jsonrpc-middleware 0.1.0

data/lib/jsonrpc/middleware.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'rack'
+
+module JSONRPC
+  # Middleware for JSON-RPC compliance
+  class Middleware
+    DEFAULT_PATH = '/'
+
+    def initialize(app, options = {})
+      @app = app
+      @parser = Parser.new
+      @validator = Validator.new
+      @path = options.fetch(:path, DEFAULT_PATH)
+    end
+
+    def call(env)
+      @req = Rack::Request.new(env)
+
+      if jsonrpc_request?
+        handle_jsonrpc_request
+      else
+        @app.call(env)
+      end
+    end
+
+    private
+
+    def jsonrpc_request?
+      @req.path == @path && @req.post?
+    end
+
+    def handle_jsonrpc_request
+      parsed_request = parse_request
+      return parsed_request if parsed_request.is_a?(Array) # Early return for parse errors
+
+      validation_result = validate_request(parsed_request)
+      return validation_result if validation_result.is_a?(Array) # Early return for validation errors
+
+      # Set parsed request in environment and call app
+      store_request_in_env(parsed_request)
+      @app.call(@req.env)
+    rescue StandardError
+      error = InternalError.new(request_id: parsed_request.is_a?(Request) ? parsed_request.id : nil)
+      @req.env['jsonrpc.error'] = error
+      json_response(200, error.to_response)
+    end
+
+    def parse_request
+      body = read_request_body
+      parsed = @parser.parse(body)
+
+      # Handle batch requests with parse errors separately
+      return handle_mixed_batch_errors(parsed) if parsed.is_a?(BatchRequest) && parse_errors?(parsed)
+
+      parsed
+    rescue ParseError, InvalidRequestError => e
+      @req.env['jsonrpc.error'] = e
+      json_response(200, e.to_response)
+    end
+
+    def validate_request(parsed_request)
+      validation_errors = @validator.validate(parsed_request)
+
+      case validation_errors
+      when Array
+        handle_batch_validation_errors(parsed_request, validation_errors)
+      when Error
+        json_response(200, validation_errors.to_response)
+      when nil
+        nil # No errors, continue processing
+      end
+    end
+
+    def store_request_in_env(parsed_request)
+      case parsed_request
+      when Request
+        @req.env['jsonrpc.request'] = parsed_request
+      when Notification
+        @req.env['jsonrpc.notification'] = parsed_request
+      when BatchRequest
+        @req.env['jsonrpc.batch'] = parsed_request
+      end
+    end
+
+    # Batch handling methods
+
+    def parse_errors?(batch_request)
+      batch_request.requests.any?(Error)
+    end
+
+    def handle_mixed_batch_errors(batch_request)
+      error_responses = collect_parse_error_responses(batch_request)
+      valid_requests = collect_valid_requests(batch_request)
+
+      if valid_requests.any?
+        success_responses = process_valid_batch_requests(valid_requests)
+        error_responses.concat(success_responses)
+      end
+
+      json_response(200, BatchResponse.new(error_responses).to_h)
+    end
+
+    def handle_batch_validation_errors(batch_request, validation_errors)
+      responses = build_ordered_responses(batch_request, validation_errors)
+      valid_requests, indices = extract_valid_requests(batch_request, validation_errors)
+
+      if valid_requests.any?
+        success_responses = process_valid_batch_requests(valid_requests)
+        merge_success_responses(responses, success_responses, indices)
+      end
+
+      json_response(200, BatchResponse.new(responses.compact).to_h)
+    end
+
+    def collect_parse_error_responses(batch_request)
+      batch_request.requests.filter_map do |item|
+        Response.new(id: item.request_id, error: item) if item.is_a?(Error)
+      end
+    end
+
+    def collect_valid_requests(batch_request)
+      batch_request.requests.reject { |item| item.is_a?(Error) }
+    end
+
+    def build_ordered_responses(batch_request, validation_errors)
+      responses = Array.new(batch_request.requests.size)
+
+      batch_request.requests.each_with_index do |request, index|
+        responses[index] = Response.new(id: request.id, error: validation_errors[index]) if validation_errors[index]
+      end
+
+      responses
+    end
+
+    def extract_valid_requests(batch_request, validation_errors)
+      valid_requests = []
+      valid_indices = []
+
+      batch_request.requests.each_with_index do |request, index|
+        unless validation_errors[index]
+          valid_requests << request
+          valid_indices << index
+        end
+      end
+
+      [valid_requests, valid_indices]
+    end
+
+    def process_valid_batch_requests(valid_requests)
+      valid_batch = BatchRequest.new(valid_requests)
+
+      # For mixed error scenarios, validate the remaining requests
+      validation_errors = @validator.validate(valid_batch)
+      return [] if validation_errors
+
+      @req.env['jsonrpc.batch'] = valid_batch
+      status, _headers, body = @app.call(@req.env)
+
+      return [] unless status == 200 && !body.empty?
+
+      app_responses = JSON.parse(body.join)
+      app_responses.map do |resp|
+        Response.new(id: resp['id'], result: resp['result'], error: resp['error'])
+      end
+    end
+
+    def merge_success_responses(responses, success_responses, valid_indices)
+      success_responses.each_with_index do |response, app_index|
+        original_index = valid_indices[app_index]
+        responses[original_index] = response
+      end
+    end
+
+    # Utility methods
+
+    def json_response(status, body)
+      [status, { 'content-type' => 'application/json' }, [body.is_a?(String) ? body : JSON.generate(body)]]
+    end
+
+    def read_request_body
+      body = @req.env[Rack::RACK_INPUT]
+      return unless body
+
+      body_content = body.read
+      body.rewind if body.respond_to?(:rewind)
+      body_content
+    end
+  end
+end

data/lib/jsonrpc/notification.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # A JSON-RPC 2.0 Notification object
+  #
+  # A Notification is a Request object without an "id" member.
+  # Notifications are not confirmable by definition since they do not have a Response object.
+  #
+  # @example Create a notification with parameters
+  #   notification = JSONRPC::Notification.new(method: "update", params: [1, 2, 3, 4, 5])
+  #
+  # @example Create a notification without parameters
+  #   notification = JSONRPC::Notification.new(method: "heartbeat")
+  #
+  class Notification
+    # JSON-RPC protocol version
+    # @return [String]
+    #
+    attr_reader :jsonrpc
+
+    # The method name to invoke
+    # @return [String]
+    #
+    attr_reader :method
+
+    # Parameters to pass to the method
+    # @return [Hash, Array, nil]
+    #
+    attr_reader :params
+
+    # Creates a new JSON-RPC 2.0 Notification object
+    #
+    # @param method [String] the name of the method to be invoked
+    # @param params [Hash, Array, nil] the parameters to be used during method invocation
+    # @raise [ArgumentError] if method is not a String or is reserved
+    # @raise [ArgumentError] if params is not a Hash, Array, or nil
+    #
+    def initialize(method:, params: nil)
+      @jsonrpc = '2.0'
+
+      validate_method(method)
+      validate_params(params)
+
+      @method = method
+      @params = params
+    end
+
+    # Converts the notification to a JSON-compatible Hash
+    #
+    # @return [Hash] the notification as a JSON-compatible Hash
+    #
+    def to_h
+      hash = {
+        jsonrpc: jsonrpc,
+        method: method
+      }
+
+      hash[:params] = params unless params.nil?
+      hash
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    private
+
+    # Validates that the method name meets JSON-RPC 2.0 requirements
+    #
+    # @param method [String] the method name
+    # @raise [ArgumentError] if method is not a String or is reserved
+    #
+    def validate_method(method)
+      raise ArgumentError, 'Method must be a String' unless method.is_a?(String)
+
+      return unless method.start_with?('rpc.')
+
+      raise ArgumentError, "Method names starting with 'rpc.' are reserved"
+    end
+
+    # Validates that the params is a valid structure according to JSON-RPC 2.0
+    #
+    # @param params [Hash, Array, nil] the parameters
+    # @raise [ArgumentError] if params is not a Hash, Array, or nil
+    #
+    def validate_params(params)
+      return if params.nil?
+
+      return if params.is_a?(Hash) || params.is_a?(Array)
+
+      raise ArgumentError, 'Params must be an Object, Array, or omitted'
+    end
+  end
+end

data/lib/jsonrpc/parser.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module JSONRPC
+  # JSON-RPC 2.0 Parser for converting raw JSON into JSONRPC objects
+  #
+  # The Parser handles converting raw JSON strings into appropriate JSONRPC objects
+  # based on the JSON-RPC 2.0 protocol specification.
+  #
+  # @example Parse a request
+  #   parser = JSONRPC::Parser.new
+  #   request = parser.parse('{"jsonrpc":"2.0","method":"subtract","params":[42,23],"id":1}')
+  #
+  # @example JSONRPC::Parse a batch request
+  #   parser = JSONRPC::Parser.new
+  #   batch = parser.parse('[{"jsonrpc":"2.0","method":"sum","params":[1,2],"id":"1"},
+  #                         {"jsonrpc":"2.0","method":"notify_hello","params":[7]}]')
+  #
+  class Parser
+    # Parse a JSON-RPC 2.0 message
+    #
+    # @param json [String] the JSON-RPC 2.0 message
+    #
+    # @return [Request, Notification, BatchRequest] the parsed object
+    #
+    # @raise [ParseError] if the JSON is invalid
+    # @raise [InvalidRequestError] if the request structure is invalid
+    #
+    def parse(json)
+      begin
+        data = JSON.parse(json)
+      rescue JSON::ParserError => e
+        raise ParseError.new(data: { details: e.message })
+      end
+
+      if data.is_a?(Array)
+        parse_batch(data)
+      else
+        parse_single(data)
+      end
+    end
+
+    private
+
+    # Parse a single JSON-RPC 2.0 message
+    #
+    # @param data [Hash] the parsed JSON data
+    # @return [Request, Notification, Error] the parsed request, notification, or error
+    #
+    def parse_single(data)
+      validate_jsonrpc_version(data)
+      validate_request_structure(data)
+
+      method = data['method']
+      params = data['params']
+
+      if data.key?('id')
+        Request.new(method: method, params: params, id: data['id'])
+      else
+        Notification.new(method: method, params: params)
+      end
+    rescue ArgumentError => e
+      request_id = data.is_a?(Hash) ? data['id'] : nil
+      raise InvalidRequestError.new(data: { details: e.message }, request_id: request_id)
+    end
+
+    # Parse a batch JSON-RPC 2.0 message
+    #
+    # @param data [Array] the array of request data
+    # @return [BatchRequest] the batch request
+    # @raise [InvalidRequestError] if the batch is empty
+    #
+    def parse_batch(data)
+      raise InvalidRequestError.new(data: { details: 'Batch request cannot be empty' }) if data.empty?
+
+      items = []
+
+      data.each_with_index do |item, index|
+        parsed_item = parse_single_for_batch(item)
+        items << parsed_item
+      rescue InvalidRequestError => e
+        # For batch processing, we want to include the error in the results
+        # rather than stopping the entire batch processing
+        error_with_index = InvalidRequestError.new(
+          data: { index: index, details: e.data&.fetch(:details, nil) },
+          request_id: e.request_id
+        )
+        items << error_with_index
+      end
+
+      BatchRequest.new(items)
+    end
+
+    # Parse a single item within a batch, allowing errors to be captured
+    #
+    # @param data [Hash] the parsed JSON data for a single item
+    # @return [Request, Notification] the parsed request or notification
+    # @raise [InvalidRequestError] if the request structure is invalid
+    #
+    def parse_single_for_batch(data)
+      validate_jsonrpc_version(data)
+      validate_request_structure(data)
+
+      method = data['method']
+      params = data['params']
+
+      if data.key?('id')
+        Request.new(method: method, params: params, id: data['id'])
+      else
+        Notification.new(method: method, params: params)
+      end
+    rescue ArgumentError => e
+      request_id = data.is_a?(Hash) ? data['id'] : nil
+      raise InvalidRequestError.new(data: { details: e.message }, request_id: request_id)
+    end
+
+    # Validate the JSON-RPC 2.0 version
+    #
+    # @param data [Hash] the request data
+    # @raise [InvalidRequestError] if the version is missing or invalid
+    #
+    def validate_jsonrpc_version(data)
+      raise InvalidRequestError.new(data: { details: 'Request must be an object' }) unless data.is_a?(Hash)
+
+      jsonrpc = data['jsonrpc']
+
+      # Get request ID from the data
+      request_id = data['id']
+
+      if jsonrpc.nil?
+        raise InvalidRequestError.new(data: { details: "Missing 'jsonrpc' property" },
+                                      request_id: request_id)
+      end
+
+      return if jsonrpc == '2.0'
+
+      raise InvalidRequestError.new(data: { details: "Invalid JSON-RPC version, must be '2.0'" },
+                                    request_id: request_id)
+    end
+
+    # Validate the request structure according to JSON-RPC 2.0 specification
+    #
+    # @param data [Hash] the request data
+    # @raise [InvalidRequestError] if the request structure is invalid
+    #
+    def validate_request_structure(data)
+      method = data['method']
+
+      # Get ID for possible errors
+      id = data['id']
+
+      raise InvalidRequestError.new(data: { details: "Missing 'method' property" }, request_id: id) if method.nil?
+
+      unless method.is_a?(String)
+        raise InvalidRequestError.new(data: { details: 'Method must be a string' }, request_id: id)
+      end
+
+      params = data['params']
+
+      unless params.nil? || params.is_a?(Array) || params.is_a?(Hash)
+        raise InvalidRequestError.new(data: { details: 'Params must be an object, array, or omitted' }, request_id: id)
+      end
+
+      id = data['id']
+      unless id.nil? || id.is_a?(String) || id.is_a?(Integer) || id.nil?
+        raise InvalidRequestError.new(
+          data: { details: 'ID must be a string, number, null, or omitted' },
+          request_id: id
+        )
+      end
+
+      nil unless id.is_a?(Integer)
+    end
+  end
+end

data/lib/jsonrpc/request.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # A JSON-RPC 2.0 Request object
+  #
+  # @example Create a request with positional parameters
+  #   request = JSONRPC::Request.new(method: "subtract", params: [42, 23], id: 1)
+  #
+  # @example Create a request with named parameters
+  #   request = JSONRPC::Request.new(method: "subtract", params: {minuend: 42, subtrahend: 23}, id: 3)
+  #
+  class Request
+    # JSON-RPC protocol version
+    # @return [String]
+    #
+    attr_reader :jsonrpc
+
+    # The method name to invoke
+    # @return [String]
+    #
+    attr_reader :method
+
+    # Parameters to pass to the method
+    # @return [Hash, Array, nil]
+    #
+    attr_reader :params
+
+    # The request identifier
+    # @return [String, Integer, nil]
+    #
+    attr_reader :id
+
+    # Creates a new JSON-RPC 2.0 Request object
+    #
+    # @param method [String] the name of the method to be invoked
+    # @param params [Hash, Array, nil] the parameters to be used during method invocation
+    # @param id [String, Integer, nil] the request identifier
+    # @raise [ArgumentError] if method is not a String or is reserved
+    # @raise [ArgumentError] if params is not a Hash, Array, or nil
+    # @raise [ArgumentError] if id is not a String, Integer, or nil
+    #
+    def initialize(method:, id:, params: nil)
+      @jsonrpc = '2.0'
+
+      validate_method(method)
+      validate_params(params)
+      validate_id(id)
+
+      @method = method
+      @params = params
+      @id = id
+    end
+
+    # Converts the request to a JSON-compatible Hash
+    #
+    # @return [Hash] the request as a JSON-compatible Hash
+    #
+    def to_h
+      hash = {
+        jsonrpc: jsonrpc,
+        method: method,
+        id: id
+      }
+
+      hash[:params] = params unless params.nil?
+      hash
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    private
+
+    # Validates that the method name meets JSON-RPC 2.0 requirements
+    #
+    # @param method [String] the method name
+    # @raise [ArgumentError] if method is not a String or is reserved
+    #
+    def validate_method(method)
+      raise ArgumentError, 'Method must be a String' unless method.is_a?(String)
+
+      return unless method.start_with?('rpc.')
+
+      raise ArgumentError, "Method names starting with 'rpc.' are reserved"
+    end
+
+    # Validates that the params is a valid structure according to JSON-RPC 2.0
+    #
+    # @param params [Hash, Array, nil] the parameters
+    # @raise [ArgumentError] if params is not a Hash, Array, or nil
+    #
+    def validate_params(params)
+      return if params.nil?
+
+      return if params.is_a?(Hash) || params.is_a?(Array)
+
+      raise ArgumentError, 'Params must be an Object, Array, or omitted'
+    end
+
+    # Validates that the id meets JSON-RPC 2.0 requirements
+    #
+    # @param id [String, Integer, nil] the request identifier
+    # @raise [ArgumentError] if id is not a String, Integer, or nil
+    #
+    def validate_id(id)
+      return if id.nil?
+
+      raise ArgumentError, 'ID must be a String, Integer, or nil' unless id.is_a?(String) || id.is_a?(Integer)
+    end
+  end
+end

data/lib/jsonrpc/response.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # A JSON-RPC 2.0 Response object
+  #
+  # When a rpc call is made, the Server must reply with a Response, except for notifications.
+  # A Response object can contain either a result (for success) or an error (for failure),
+  # but never both.
+  #
+  # @example Create a successful response
+  #   response = JSONRPC::Response.new(result: 19, id: 1)
+  #
+  # @example Create an error response
+  #   error = JSONRPC::Error.new(code: -32601, message: "Method not found")
+  #   response = JSONRPC::Response.new(error: error, id: 1)
+  #
+  class Response
+    # JSON-RPC protocol version
+    # @return [String]
+    #
+    attr_reader :jsonrpc
+
+    # The result of the method invocation (for success)
+    # @return [Object, nil]
+    #
+    attr_reader :result
+
+    # The error object (for failure)
+    # @return [JSONRPC::Error, nil]
+    #
+    attr_reader :error
+
+    # The request identifier
+    # @return [String, Integer, nil]
+    #
+    attr_reader :id
+
+    # Creates a new JSON-RPC 2.0 Response object
+    #
+    # @param result [Object, nil] the result of the method invocation (for success)
+    # @param error [JSONRPC::Error, nil] the error object (for failure)
+    # @param id [String, Integer, nil] the request identifier
+    # @raise [ArgumentError] if both result and error are present or both are nil
+    # @raise [ArgumentError] if error is present but not a JSONRPC::Error
+    # @raise [ArgumentError] if id is not a String, Integer, or nil
+    #
+    def initialize(id:, result: nil, error: nil)
+      @jsonrpc = '2.0'
+
+      validate_result_and_error(result, error)
+      validate_id(id)
+
+      @result = result
+      @error = error
+      @id = id
+    end
+
+    # Checks if the response is successful
+    #
+    # @return [Boolean] true if the response contains a result, false if it contains an error
+    #
+    def success?
+      !@result.nil?
+    end
+
+    # Checks if the response is an error
+    #
+    # @return [Boolean] true if the response contains an error, false if it contains a result
+    #
+    def error?
+      !@error.nil?
+    end
+
+    # Converts the response to a JSON-compatible Hash
+    #
+    # @return [Hash] the response as a JSON-compatible Hash
+    #
+    def to_h
+      hash = {
+        jsonrpc: jsonrpc,
+        id: id
+      }
+
+      if success?
+        hash[:result] = result
+      else
+        hash[:error] = error.to_h
+      end
+
+      hash
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    private
+
+    # Validates that exactly one of result or error is present
+    #
+    # @param result [Object, nil] the result
+    # @param error [JSONRPC::Error, nil] the error
+    # @raise [ArgumentError] if both result and error are present or both are nil
+    # @raise [ArgumentError] if error is present but not a JSONRPC::Error
+    #
+    def validate_result_and_error(result, error)
+      raise ArgumentError, 'Either result or error must be present' if result.nil? && error.nil?
+
+      raise ArgumentError, 'Response cannot contain both result and error' if !result.nil? && !error.nil?
+
+      return unless !error.nil? && !error.is_a?(Error)
+
+      raise ArgumentError, 'Error must be a JSONRPC::Error'
+    end
+
+    # Validates that the id meets JSON-RPC 2.0 requirements
+    #
+    # @param id [String, Integer, nil] the request identifier
+    # @raise [ArgumentError] if id is not a String, Integer, or nil
+    #
+    def validate_id(id)
+      return if id.nil?
+
+      raise ArgumentError, 'ID must be a String, Integer, or nil' unless id.is_a?(String) || id.is_a?(Integer)
+    end
+  end
+end