jsonrpc-middleware 0.1.0 → 0.2.0

data/examples/sinatra-modular/app.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+require 'sinatra/json'
+require 'jsonrpc'
+
+# App is a Sinatra::Base subclass that provides JSON-RPC endpoint handling for requests and batches.
+class App < Sinatra::Base
+  set :host_authorization, permitted_hosts: []
+  set :raise_errors, true
+  set :show_exceptions, false
+
+  use JSONRPC::Middleware
+  helpers JSONRPC::Helpers
+
+  post '/' do
+    @env = env # Set the @env instance variable to use the JSONRPC helpers below
+
+    if jsonrpc_request?
+      result = handle_single(jsonrpc_request)
+      jsonrpc_response(result)
+    elsif jsonrpc_notification?
+      handle_single(jsonrpc_notification)
+      jsonrpc_notification_response
+    else
+      responses = handle_batch(jsonrpc_batch)
+      jsonrpc_batch_response(responses)
+    end
+  end
+
+  private
+
+  def handle_single(request_or_notification)
+    params = request_or_notification.params
+
+    case request_or_notification.method
+    when 'add'
+      addends = params.is_a?(Array) ? params : params['addends'] # Handle positional and named arguments
+      addends.sum
+    when 'subtract'
+      params['minuend'] - params['subtrahend']
+    when 'multiply'
+      params['multiplicand'] * params['multiplier']
+    when 'divide'
+      params['dividend'] / params['divisor']
+    when 'explode'
+      raise 'An internal error has occurred.'
+    end
+  end
+
+  def handle_batch(batch)
+    batch.flat_map do |request_or_notification|
+      result = handle_single(request_or_notification)
+      JSONRPC::Response.new(id: request_or_notification.id, result:) if request_or_notification.is_a?(JSONRPC::Request)
+    end.compact
+  end
+end

data/examples/sinatra-modular/config.ru

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require './app'
+require '../procedures'
+
+run App

data/lib/jsonrpc/batch_request.rb

@@ -17,16 +17,34 @@ module JSONRPC
     include Enumerable
 
     # The collection of request objects in this batch (may include errors)
+    #
+    # @api public
+    #
+    # @example Accessing requests in a batch
+    #   batch = JSONRPC::BatchRequest.new([request1, request2])
+    #   batch.requests # => [#<JSONRPC::Request...>, #<JSONRPC::Request...>]
+    #
     # @return [Array<JSONRPC::Request, JSONRPC::Notification, JSONRPC::Error>]
     #
     attr_reader :requests
 
     # Creates a new JSON-RPC 2.0 Batch Request object
     #
+    # @api public
+    #
+    # @example Create a batch request
+    #   requests = [
+    #     JSONRPC::Request.new(method: 'add', params: [1, 2], id: 1),
+    #     JSONRPC::Notification.new(method: 'notify', params: ['hello'])
+    #   ]
+    #   batch = JSONRPC::BatchRequest.new(requests)
+    #
     # @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)
@@ -36,21 +54,43 @@ module JSONRPC
 
     # Converts the batch request to a JSON-compatible Array
     #
+    # @api public
+    #
+    # @example Convert batch to hash
+    #   batch.to_h # => [{"jsonrpc":"2.0","method":"add","params":[1,2],"id":1}]
+    #
     # @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
 
+    # Converts the batch to JSON format
+    #
+    # @api public
+    #
+    # @example Convert batch to JSON
+    #   batch.to_json # => '[{"id":"1","method":"sum","params":[1,2,4]}]'
+    #
+    # @return [String] the JSON-formatted batch
+    #
     def to_json(*)
       to_h.to_json(*)
     end
 
     # Implements the Enumerable contract by yielding each request in the batch
     #
+    # @api public
+    #
+    # @example Iterate over requests
+    #   batch.each { |request| puts request.method }
+    #
     # @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(&)
@@ -62,17 +102,35 @@ module JSONRPC
 
     # Returns the number of requests in the batch
     #
+    # @api public
+    #
+    # @example Get batch size
+    #   batch.size # => 3
+    #
     # @return [Integer] the number of requests in the batch
     #
     def size
       requests.size
     end
 
-    # Alias for size for Array-like interface
+    # Alias for size method providing Array-like interface
+    #
+    # @api public
+    #
+    # @example Get batch length
+    #   batch.length # => 3
+    #
+    # @return [Integer] the number of requests in the batch
+    #
     alias length size
 
     # Returns true if the batch contains no requests
     #
+    # @api public
+    #
+    # @example Check if batch is empty
+    #   batch.empty? # => false
+    #
     # @return [Boolean] true if the batch is empty, false otherwise
     #
     def empty?
@@ -81,13 +139,20 @@ module JSONRPC
 
     private
 
-    # Validates that the requests is a valid array of Request/Notification/Error objects
+    # Validates the requests array
+    #
+    # @api private
     #
     # @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
     #
+    # @return [void]
+    #
     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?

data/lib/jsonrpc/batch_response.rb

@@ -18,15 +18,33 @@ module JSONRPC
     include Enumerable
 
     # The collection of response objects in this batch
+    #
+    # @api public
+    #
+    # @example Accessing responses in a batch
+    #   batch.responses # => [#<JSONRPC::Response...>, #<JSONRPC::Response...>]
+    #
     # @return [Array<JSONRPC::Response>]
     #
     attr_reader :responses
 
     # Creates a new JSON-RPC 2.0 Batch Response object
     #
+    # @api public
+    #
+    # @example Create a batch response
+    #   responses = [
+    #     JSONRPC::Response.new(result: 42, id: 1),
+    #     JSONRPC::Response.new(result: "hello", id: 2)
+    #   ]
+    #   batch = JSONRPC::BatchResponse.new(responses)
+    #
     # @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)
@@ -36,21 +54,43 @@ module JSONRPC
 
     # Converts the batch response to a JSON-compatible Array
     #
+    # @api public
+    #
+    # @example Convert batch to hash
+    #   batch.to_h # => [{"jsonrpc":"2.0","result":42,"id":1}]
+    #
     # @return [Array<Hash>] the batch response as a JSON-compatible Array
     #
     def to_h
       responses.map(&:to_h)
     end
 
+    # Converts the batch response to a JSON string
+    #
+    # @api public
+    #
+    # @example Convert batch to JSON
+    #   batch.to_json # => '[{"jsonrpc":"2.0","result":42,"id":1}]'
+    #
+    # @return [String] the JSON-formatted batch response
+    #
     def to_json(*)
       to_h.to_json(*)
     end
 
     # Implements the Enumerable contract by yielding each response in the batch
     #
+    # @api public
+    #
+    # @example Iterate over responses
+    #   batch.each { |response| puts response.result }
+    #
     # @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(&)
@@ -60,6 +100,15 @@ module JSONRPC
       self
     end
 
+    # Converts the batch response to a response format
+    #
+    # @api public
+    #
+    # @example Convert to response format
+    #   batch.to_response # => Array of response hashes
+    #
+    # @return [Array] array of response objects
+    #
     def to_response
       responses.map(&:to_response)
     end
@@ -68,11 +117,18 @@ module JSONRPC
 
     # Validates that the responses is a valid array of Response objects
     #
+    # @api private
+    #
     # @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
     #
+    # @return [void]
+    #
     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?

data/lib/jsonrpc/configuration.rb

@@ -2,7 +2,11 @@
 
 module JSONRPC
   # Configuration class for JSON-RPC procedure management and validation.
+  #
+  # @api public
+  #
   # This class provides functionality to register, retrieve, and validate JSON-RPC procedures.
+  # It acts as a central registry for method definitions and their parameter constraints.
   #
   # @example Registering a procedure
   #   JSONRPC::Configuration.instance.procedure('sum') do
@@ -12,41 +16,159 @@ module JSONRPC
   #   end
   #
   class Configuration
-    # Represents a registered JSON-RPC procedure with its validation contract and configuration.
+    # Represents a registered JSON-RPC procedure with its validation contract and configuration
+    #
+    # @api public
+    #
+    # @!method allow_positional_arguments
+    #   Indicates if the procedure accepts positional arguments
+    #   @api public
     #
-    # @!attribute [r] allow_positional_arguments
+    #   @example
+    #     procedure.allow_positional_arguments # => true
     #   @return [Boolean] whether the procedure accepts positional arguments
-    # @!attribute [r] contract
+    #
+    # @!method contract
+    #   The validation contract for procedure parameters
+    #   @api public
+    #
+    #   @example
+    #     procedure.contract # => #<Dry::Validation::Contract...>
     #   @return [Dry::Validation::Contract] the validation contract for procedure parameters
-    # @!attribute [r] parameter_name
+    #
+    # @!method parameter_name
+    #   The name of the first parameter in the contract schema
+    #   @api public
+    #
+    #   @example
+    #     procedure.parameter_name # => :numbers
     #   @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
+    # Whether to log detailed internal error information in the terminal
+    #
+    # @api public
+    #
+    # @example
+    #   config.log_internal_errors # => true
+    #
+    # @return [Boolean] whether to log internal error details
+    #
+    attr_accessor :log_internal_errors
+
+    # Whether to log validation errors during JSON-RPC request processing
+    #
+    # @api public
+    #
+    # @example
+    #   config.log_request_validation_errors # => false
+    #
+    # @return [Boolean] whether to log JSON-RPC request validation errors
+    #
+    attr_accessor :log_request_validation_errors
+
+    # Whether to render detailed internal error information in responses
+    #
+    # @api public
+    #
+    # @example
+    #   config.render_internal_errors # => true
+    #
+    # @return [Boolean] whether to log internal error details
+    #
+    attr_accessor :render_internal_errors
+
+    # Whether internal errors should be rescued and converted to JSON-RPC errors
+    #
+    # @api public
+    #
+    # @example
+    #   config.rescue_internal_errors # => true
+    #
+    # @return [Boolean] whether internal errors are rescued
+    #
+    attr_accessor :rescue_internal_errors
+
+    # Whether procedure signatures are validated
+    #
+    # @api public
+    #
+    # @example
+    #   config.validate_procedure_signatures # => true
+    #
+    # @return [Boolean] whether procedure signatures are validated
+    #
     attr_reader :validate_procedure_signatures
 
-    # Initializes a new Configuration instance.
+    # Initializes a new Configuration instance
+    #
+    # @api public
+    #
+    # @example
+    #   config = JSONRPC::Configuration.new
+    #
+    # @example With custom options
+    #   config = JSONRPC::Configuration.new(
+    #     log_request_validation_errors: true,
+    #     render_internal_errors: true
+    #   )
+    #
+    # @param log_internal_errors [Boolean] whether to log detailed internal error information in the terminal
+    # @param log_request_validation_errors [Boolean] whether to log validation errors during JSON-RPC request processing
+    # @param rescue_internal_errors [Boolean] whether internal errors should be rescued and converted to JSON-RPC errors
+    # @param render_internal_errors [Boolean] whether to render detailed internal error information in responses
+    # @param validate_procedure_signatures [Boolean] whether procedure signatures are validated
     #
     # @return [Configuration] a new configuration instance
-    def initialize
+    #
+    def initialize(
+      log_internal_errors: true,
+      log_request_validation_errors: false,
+      rescue_internal_errors: true,
+      render_internal_errors: false,
+      validate_procedure_signatures: true
+    )
       @procedures = {}
-      @validate_procedure_signatures = true
+      @log_internal_errors = log_internal_errors
+      @log_request_validation_errors = log_request_validation_errors
+      @rescue_internal_errors = rescue_internal_errors
+      @render_internal_errors = render_internal_errors
+      @validate_procedure_signatures = validate_procedure_signatures
     end
 
-    # Returns the singleton instance of the Configuration class.
+    # Returns the singleton instance of the Configuration class
+    #
+    # @api public
+    #
+    # @example
+    #   config = JSONRPC::Configuration.instance
     #
     # @return [Configuration] the singleton instance
+    #
     def self.instance
       @instance ||= new
     end
 
-    # Registers a new procedure with the given method name and validation contract.
+    # Registers a new procedure with the given method name and validation contract
+    #
+    # @api public
+    #
+    # @example Register a simple procedure
+    #   config.procedure('add') do
+    #     params do
+    #       required(:a).value(:integer)
+    #       required(:b).value(:integer)
+    #     end
+    #   end
     #
     # @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 }
@@ -59,25 +181,45 @@ module JSONRPC
       )
     end
 
-    # Retrieves a procedure by its method name.
+    # Retrieves a procedure by its method name
+    #
+    # @api public
+    #
+    # @example
+    #   procedure = config.get_procedure('add')
     #
     # @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.
+    # Checks if a procedure with the given method name exists
+    #
+    # @api public
+    #
+    # @example
+    #   config.procedure?('add') # => true
     #
     # @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.
+    # Clears all registered procedures
+    #
+    # @api public
+    #
+    # @example
+    #   config.reset!
     #
     # @return [void]
+    #
     def reset!
       @procedures.clear
     end

data/lib/jsonrpc/error.rb

@@ -3,44 +3,92 @@
 module JSONRPC
   # A JSON-RPC 2.0 Error object
   #
+  # @api public
+  #
   # 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.
+  # with specific properties according to the JSON-RPC 2.0 specification.
   #
   # @example Create an error
   #   error = JSONRPC::Error.new(
+  #     "Invalid Request",
   #     code: -32600,
-  #     message: "Invalid Request",
   #     data: { detail: "Additional information about the error" }
   #   )
   #
   class Error < StandardError
     # The request identifier (optional for notifications)
+    #
+    # @api public
+    #
+    # @example Get request ID
+    #   error.request_id # => "1"
+    #
+    # @example Set request ID
+    #   error.request_id = "2"
+    #
     # @return [String, Integer, nil]
     #
     attr_accessor :request_id
 
     # Error code indicating the error type
+    #
+    # @api public
+    #
+    # @example Get error code
+    #   error.code # => -32600
+    #
+    # @example Set error code
+    #   error.code = -32601
+    #
     # @return [Integer]
     #
     attr_accessor :code
 
     # Short description of the error
+    #
+    # @api public
+    #
+    # @example Get error message
+    #   error.message # => "Invalid Request"
+    #
+    # @example Set error message
+    #   error.message = "Method not found"
+    #
     # @return [String]
     #
     attr_accessor :message
 
     # Additional information about the error (optional)
+    #
+    # @api public
+    #
+    # @example Get error data
+    #   error.data # => { "detail" => "Additional info" }
+    #
+    # @example Set error data
+    #   error.data = { "field" => "invalid" }
+    #
     # @return [Hash, Array, String, Number, Boolean, nil]
     #
     attr_accessor :data
 
     # Creates a new JSON-RPC 2.0 Error object
     #
+    # @api public
+    #
+    # @example Create an error with code and message
+    #   error = JSONRPC::Error.new("Invalid Request", code: -32600)
+    #
+    # @example Create an error with additional data
+    #   error = JSONRPC::Error.new("Invalid params", code: -32602, data: { "field" => "missing" })
+    #
     # @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)
@@ -57,6 +105,11 @@ module JSONRPC
 
     # Converts the error to a JSON-compatible Hash
     #
+    # @api public
+    #
+    # @example Convert error to hash
+    #   error.to_h # => { code: -32600, message: "Invalid Request" }
+    #
     # @return [Hash] the error as a JSON-compatible Hash
     #
     def to_h
@@ -65,10 +118,28 @@ module JSONRPC
       hash
     end
 
+    # Converts the error to JSON
+    #
+    # @api public
+    #
+    # @example Convert error to JSON
+    #   error.to_json # => '{"code":-32600,"message":"Invalid Request"}'
+    #
+    # @return [String] the error as a JSON string
+    #
     def to_json(*)
       to_h.to_json(*)
     end
 
+    # Converts the error to a complete JSON-RPC response
+    #
+    # @api public
+    #
+    # @example Convert error to response
+    #   error.to_response # => { jsonrpc: "2.0", error: { code: -32600, message: "Invalid Request" }, id: nil }
+    #
+    # @return [Hash] a complete JSON-RPC response with this error
+    #
     def to_response
       Response.new(id: request_id, error: self).to_h
     end
@@ -77,18 +148,28 @@ module JSONRPC
 
     # Validates that the code is a valid Integer
     #
+    # @api private
+    #
     # @param code [Integer] the error code
+    #
     # @raise [ArgumentError] if code is not an Integer
     #
+    # @return [void]
+    #
     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
     #
+    # @api private
+    #
     # @param message [String] the error message
+    #
     # @raise [ArgumentError] if message is not a String
     #
+    # @return [void]
+    #
     def validate_message(message)
       raise ArgumentError, 'Error message must be a String' unless message.is_a?(String)
     end