jsonrpc-middleware 0.1.0

data/lib/jsonrpc/batch_request.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # A JSON-RPC 2.0 batch request object
+  #
+  # A batch request is an Array filled with Request objects to send several requests at once.
+  # The Server should respond with an Array containing the corresponding Response objects.
+  #
+  # @example Create a batch request with multiple requests
+  #   batch = JSONRPC::BatchRequest.new([
+  #     JSONRPC::Request.new(method: "sum", params: [1, 2, 4], id: "1"),
+  #     JSONRPC::Notification.new(method: "notify_hello", params: [7]),
+  #     JSONRPC::Request.new(method: "subtract", params: [42, 23], id: "2")
+  #   ])
+  #
+  class BatchRequest
+    include Enumerable
+
+    # The collection of request objects in this batch (may include errors)
+    # @return [Array<JSONRPC::Request, JSONRPC::Notification, JSONRPC::Error>]
+    #
+    attr_reader :requests
+
+    # Creates a new JSON-RPC 2.0 Batch Request object
+    #
+    # @param requests [Array<JSONRPC::Request, JSONRPC::Notification, JSONRPC::Error>] an array of request objects
+    #   or errors
+    # @raise [ArgumentError] if requests is not an Array
+    # @raise [ArgumentError] if requests is empty
+    # @raise [ArgumentError] if any request is not a valid Request, Notification, or Error
+    #
+    def initialize(requests)
+      validate_requests(requests)
+      @requests = requests
+    end
+
+    # Converts the batch request to a JSON-compatible Array
+    #
+    # @return [Array<Hash>] the batch request as a JSON-compatible Array
+    #
+    def to_h
+      requests.map { |item| item.respond_to?(:to_h) ? item.to_h : item }
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    # Implements the Enumerable contract by yielding each request in the batch
+    #
+    # @yield [request] Yields each request in the batch to the block
+    # @yieldparam request [JSONRPC::Request, JSONRPC::Notification, JSONRPC::Error] a request in the batch
+    # @return [Enumerator] if no block is given
+    # @return [BatchRequest] self if a block is given
+    #
+    def each(&)
+      return to_enum(:each) unless block_given?
+
+      requests.each(&)
+      self
+    end
+
+    # Returns the number of requests in the batch
+    #
+    # @return [Integer] the number of requests in the batch
+    #
+    def size
+      requests.size
+    end
+
+    # Alias for size for Array-like interface
+    alias length size
+
+    # Returns true if the batch contains no requests
+    #
+    # @return [Boolean] true if the batch is empty, false otherwise
+    #
+    def empty?
+      requests.empty?
+    end
+
+    private
+
+    # Validates that the requests is a valid array of Request/Notification/Error objects
+    #
+    # @param requests [Array] the array of requests
+    # @raise [ArgumentError] if requests is not an Array
+    # @raise [ArgumentError] if requests is empty
+    # @raise [ArgumentError] if any request is not a valid Request, Notification, or Error
+    #
+    def validate_requests(requests)
+      raise ArgumentError, 'Requests must be an Array' unless requests.is_a?(Array)
+      raise ArgumentError, 'Batch request cannot be empty' if requests.empty?
+
+      requests.each_with_index do |request, index|
+        unless request.is_a?(Request) || request.is_a?(Notification) || request.is_a?(Error)
+          raise ArgumentError, "Request at index #{index} is not a valid Request, Notification, or Error"
+        end
+      end
+    end
+  end
+end

data/lib/jsonrpc/batch_response.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # A JSON-RPC 2.0 Batch Response object
+  #
+  # A Batch Response is an Array containing Response objects, corresponding to
+  # a Batch Request. The Server should respond with one Response for each Request
+  # (except for Notifications which don't receive responses).
+  #
+  # @example Create a batch response
+  #   batch = JSONRPC::BatchResponse.new([
+  #     JSONRPC::Response.new(result: 7, id: "1"),
+  #     JSONRPC::Response.new(result: 19, id: "2"),
+  #     JSONRPC::Response.new(error: JSONRPC::Error.new(code: -32600, message: "Invalid Request"), id: nil)
+  #   ])
+  #
+  class BatchResponse
+    include Enumerable
+
+    # The collection of response objects in this batch
+    # @return [Array<JSONRPC::Response>]
+    #
+    attr_reader :responses
+
+    # Creates a new JSON-RPC 2.0 Batch Response object
+    #
+    # @param responses [Array<JSONRPC::Response>] an array of response objects
+    # @raise [ArgumentError] if responses is not an Array
+    # @raise [ArgumentError] if responses is empty
+    # @raise [ArgumentError] if any response is not a valid Response
+    #
+    def initialize(responses)
+      validate_responses(responses)
+      @responses = responses
+    end
+
+    # Converts the batch response to a JSON-compatible Array
+    #
+    # @return [Array<Hash>] the batch response as a JSON-compatible Array
+    #
+    def to_h
+      responses.map(&:to_h)
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    # Implements the Enumerable contract by yielding each response in the batch
+    #
+    # @yield [response] Yields each response in the batch to the block
+    # @yieldparam response [JSONRPC::Response] a response in the batch
+    # @return [Enumerator] if no block is given
+    # @return [BatchResponse] self if a block is given
+    #
+    def each(&)
+      return to_enum(:each) unless block_given?
+
+      responses.each(&)
+      self
+    end
+
+    def to_response
+      responses.map(&:to_response)
+    end
+
+    private
+
+    # Validates that the responses is a valid array of Response objects
+    #
+    # @param responses [Array] the array of responses
+    # @raise [ArgumentError] if responses is not an Array
+    # @raise [ArgumentError] if responses is empty
+    # @raise [ArgumentError] if any response is not a valid Response
+    #
+    def validate_responses(responses)
+      raise ArgumentError, 'Responses must be an Array' unless responses.is_a?(Array)
+      raise ArgumentError, 'Batch response cannot be empty' if responses.empty?
+
+      responses.each_with_index do |response, index|
+        raise ArgumentError, "Response at index #{index} is not a valid Response" unless response.is_a?(Response)
+      end
+    end
+  end
+end

data/lib/jsonrpc/configuration.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # Configuration class for JSON-RPC procedure management and validation.
+  # This class provides functionality to register, retrieve, and validate JSON-RPC procedures.
+  #
+  # @example Registering a procedure
+  #   JSONRPC::Configuration.instance.procedure('sum') do
+  #     params do
+  #       required(:numbers).value(:array, min_size?: 1)
+  #     end
+  #   end
+  #
+  class Configuration
+    # Represents a registered JSON-RPC procedure with its validation contract and configuration.
+    #
+    # @!attribute [r] allow_positional_arguments
+    #   @return [Boolean] whether the procedure accepts positional arguments
+    # @!attribute [r] contract
+    #   @return [Dry::Validation::Contract] the validation contract for procedure parameters
+    # @!attribute [r] parameter_name
+    #   @return [Symbol, nil] the name of the first parameter in the contract schema
+    Procedure = Data.define(:allow_positional_arguments, :contract, :parameter_name)
+
+    # @!attribute [r] validate_procedure_signatures
+    #   @return [Boolean] whether procedure signatures are validated
+    attr_reader :validate_procedure_signatures
+
+    # Initializes a new Configuration instance.
+    #
+    # @return [Configuration] a new configuration instance
+    def initialize
+      @procedures = {}
+      @validate_procedure_signatures = true
+    end
+
+    # Returns the singleton instance of the Configuration class.
+    #
+    # @return [Configuration] the singleton instance
+    def self.instance
+      @instance ||= new
+    end
+
+    # Registers a new procedure with the given method name and validation contract.
+    #
+    # @param method_name [String, Symbol] the name of the procedure
+    # @param allow_positional_arguments [Boolean] whether the procedure accepts positional arguments
+    # @yield A block that defines the validation contract using Dry::Validation DSL
+    # @return [Procedure] the registered procedure
+    def procedure(method_name, allow_positional_arguments: false, &)
+      contract_class = Class.new(Dry::Validation::Contract, &)
+      contract_class.class_eval { import_predicates_as_macros }
+      contract = contract_class.new
+
+      @procedures[method_name.to_s] = Procedure.new(
+        allow_positional_arguments:,
+        contract:,
+        parameter_name: contract.schema.key_map.keys.first&.name
+      )
+    end
+
+    # Retrieves a procedure by its method name.
+    #
+    # @param method_name [String, Symbol] the name of the procedure to retrieve
+    # @return [Procedure, nil] the procedure if found, nil otherwise
+    def get_procedure(method_name)
+      @procedures[method_name.to_s]
+    end
+
+    # Checks if a procedure with the given method name exists.
+    #
+    # @param method_name [String, Symbol] the name of the procedure to check
+    # @return [Boolean] true if the procedure exists, false otherwise
+    def procedure?(method_name)
+      @procedures.key?(method_name.to_s)
+    end
+
+    # Clears all registered procedures.
+    #
+    # @return [void]
+    def reset!
+      @procedures.clear
+    end
+  end
+end

data/lib/jsonrpc/error.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # A JSON-RPC 2.0 Error object
+  #
+  # When a rpc call encounters an error, the Response Object must contain an Error object
+  # with specific properties according to the JSON-RPC 2.0.
+  #
+  # @example Create an error
+  #   error = JSONRPC::Error.new(
+  #     code: -32600,
+  #     message: "Invalid Request",
+  #     data: { detail: "Additional information about the error" }
+  #   )
+  #
+  class Error < StandardError
+    # The request identifier (optional for notifications)
+    # @return [String, Integer, nil]
+    #
+    attr_accessor :request_id
+
+    # Error code indicating the error type
+    # @return [Integer]
+    #
+    attr_accessor :code
+
+    # Short description of the error
+    # @return [String]
+    #
+    attr_accessor :message
+
+    # Additional information about the error (optional)
+    # @return [Hash, Array, String, Number, Boolean, nil]
+    #
+    attr_accessor :data
+
+    # Creates a new JSON-RPC 2.0 Error object
+    #
+    # @param message [String] short description of the error
+    # @param code [Integer] a number indicating the error type
+    # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
+    # @param request_id [String, Integer, nil] the request identifier
+    # @raise [ArgumentError] if code is not an Integer
+    # @raise [ArgumentError] if message is not a String
+    #
+    def initialize(message, code:, data: nil, request_id: nil)
+      super(message)
+
+      validate_code(code)
+      validate_message(message)
+
+      @code = code
+      @message = message
+      @data = data
+      @request_id = request_id
+    end
+
+    # Converts the error to a JSON-compatible Hash
+    #
+    # @return [Hash] the error as a JSON-compatible Hash
+    #
+    def to_h
+      hash = { code:, message: }
+      hash[:data] = data unless data.nil?
+      hash
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    def to_response
+      Response.new(id: request_id, error: self).to_h
+    end
+
+    private
+
+    # Validates that the code is a valid Integer
+    #
+    # @param code [Integer] the error code
+    # @raise [ArgumentError] if code is not an Integer
+    #
+    def validate_code(code)
+      raise ArgumentError, 'Error code must be an Integer' unless code.is_a?(Integer)
+    end
+
+    # Validates that the message is a String
+    #
+    # @param message [String] the error message
+    # @raise [ArgumentError] if message is not a String
+    #
+    def validate_message(message)
+      raise ArgumentError, 'Error message must be a String' unless message.is_a?(String)
+    end
+  end
+end

data/lib/jsonrpc/errors/internal_error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # JSON-RPC 2.0 Internal Error (-32603)
+  #
+  # Raised when there was an internal JSON-RPC error.
+  #
+  # @example Create an internal error
+  #   error = JSONRPC::Errors::InternalError.new(data: { details: "Unexpected server error" })
+  #
+  class InternalError < Error
+    # Creates a new Internal Error with code -32603
+    #
+    # @param message [String] short description of the error
+    # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
+    # @param request_id [String, Integer, nil] the request identifier
+    #
+    def initialize(message = 'Internal JSON-RPC error.', data: nil, request_id: nil)
+      super(
+        message,
+        code: -32_603,
+        data:,
+        request_id:
+      )
+    end
+  end
+end

data/lib/jsonrpc/errors/invalid_params_error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # JSON-RPC 2.0 Invalid Params Error (-32602)
+  #
+  # Raised when invalid method parameter(s) were provided.
+  #
+  # @example Create an invalid params error
+  #   error = JSONRPC::InvalidParamsError.new(data: { details: "Expected array of integers" })
+  #
+  class InvalidParamsError < Error
+    # Creates a new Invalid Params Error with code -32602
+    #
+    # @param message [String] short description of the error
+    # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
+    # @param request_id [String, Integer, nil] the request identifier
+    #
+    def initialize(message = 'Invalid method parameter(s).', data: nil, request_id: nil)
+      super(
+        message,
+        code: -32_602,
+        data:,
+        request_id:
+      )
+    end
+  end
+end

data/lib/jsonrpc/errors/invalid_request_error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # JSON-RPC 2.0 Invalid Request Error (-32600)
+  #
+  # Raised when the JSON sent is not a valid Request object.
+  #
+  # @example Create an invalid request error
+  #   error = JSONRPC::InvalidRequestError.new(data: { details: "Method must be a string" })
+  #
+  class InvalidRequestError < Error
+    # Creates a new Invalid Request Error with code -32600
+    #
+    # @param message [String] short description of the error
+    # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
+    # @param request_id [String, Integer, nil] the request identifier
+    #
+    def initialize(
+      message = 'The JSON payload was valid JSON, but not a valid JSON-RPC Request object.',
+      data: nil,
+      request_id: nil
+    )
+      super(
+        message,
+        code: -32_600,
+        data:,
+        request_id:
+      )
+    end
+  end
+end

data/lib/jsonrpc/errors/method_not_found_error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # JSON-RPC 2.0 Method Not Found Error (-32601)
+  #
+  # Raised when the method does not exist / is not available.
+  #
+  # @example Create a method not found error
+  #   error = JSONRPC::MethodNotFound.new(data: { requested_method: "unknown_method" })
+  #
+  class MethodNotFoundError < Error
+    # Creates a new Method Not Found Error with code -32601
+    #
+    # @param message [String] short description of the error
+    # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
+    # @param request_id [String, Integer, nil] the request identifier
+    #
+    def initialize(
+      message = 'The requested RPC method does not exist or is not supported.',
+      data: nil,
+      request_id: nil
+    )
+      super(
+        message,
+        code: -32_601,
+        data:,
+        request_id:
+      )
+    end
+  end
+end

data/lib/jsonrpc/errors/parse_error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # JSON-RPC 2.0 Parse Error (-32700)
+  #
+  # Raised when invalid JSON was received by the server.
+  # An error occurred on the server while parsing the JSON text.
+  #
+  # @example Create a parse error
+  #   error = JSONRPC::ParseError.new(data: { details: "Unexpected end of input" })
+  #
+  class ParseError < Error
+    # Creates a new Parse Error with code -32700
+    #
+    # @param message [String] short description of the error
+    # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
+    #
+    def initialize(
+      message = 'Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.',
+      data: nil
+    )
+      super(
+        message,
+        code: -32_700,
+        data: data
+      )
+    end
+  end
+end

data/lib/jsonrpc/helpers.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # Framework-agnostic helpers for JSON-RPC
+  module Helpers
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class methods for registering JSON-RPC procedure handlers
+    module ClassMethods
+      def jsonrpc_method(method_name, &)
+        Configuration.instance.procedure(method_name, &)
+      end
+    end
+
+    def jsonrpc_batch? = @env.key?('jsonrpc.batch')
+    def jsonrpc_notification? = @env.key?('jsonrpc.notification')
+    def jsonrpc_request? = @env.key?('jsonrpc.request')
+
+    # Get the current JSON-RPC request object
+    def jsonrpc_batch = @env['jsonrpc.batch']
+    def jsonrpc_request = @env['jsonrpc.request']
+    def jsonrpc_notification = @env['jsonrpc.notification']
+
+    # Create a JSON-RPC response
+    def jsonrpc_response(result)
+      [200, { 'content-type' => 'application/json' }, [Response.new(id: jsonrpc_request.id, result: result).to_json]]
+    end
+
+    # Create a JSON-RPC response
+    def jsonrpc_batch_response(responses)
+      # If batch contained only notifications, responses will be empty or contain only nils
+      return [204, {}, []] if responses.compact.empty?
+
+      [200, { 'content-type' => 'application/json' }, [responses.to_json]]
+    end
+
+    def jsonrpc_notification_response
+      [204, {}, []]
+    end
+
+    # Create a JSON-RPC error response
+    def jsonrpc_error(error)
+      Response.new(id: jsonrpc_request.id, error: error).to_json
+    end
+
+    # Get the current JSON-RPC request params object
+    def jsonrpc_params
+      jsonrpc_request.params
+    end
+
+    # Create a Parse error (-32700)
+    # Used when invalid JSON was received by the server
+    def jsonrpc_parse_error(data: nil)
+      jsonrpc_error(ParseError.new(data: data))
+    end
+
+    # Create an Invalid Request error (-32600)
+    # Used when the JSON sent is not a valid Request object
+    def jsonrpc_invalid_request_error(data: nil)
+      jsonrpc_error(InvalidRequestError.new(data: data))
+    end
+
+    # Create a Method not found error (-32601)
+    # Used when the method does not exist / is not available
+    def jsonrpc_method_not_found_error(data: nil)
+      jsonrpc_error(MethodNotFoundError.new(data: data))
+    end
+
+    # Create an Invalid params error (-32602)
+    # Used when invalid method parameter(s) were received
+    def jsonrpc_invalid_params_error(data: nil)
+      jsonrpc_error(InvalidParamsError.new(data: data))
+    end
+
+    # Create an Internal error (-32603)
+    # Used for implementation-defined server errors
+    def jsonrpc_internal_error(data: nil)
+      jsonrpc_error(InternalError.new(data: data))
+    end
+  end
+end