jsonrpc-middleware 0.6.0 → 0.7.0

data/examples/rails/Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.5.0)
+    jsonrpc-middleware (0.6.0)
       dry-struct (~> 1.8)
       dry-validation (~> 1.11)
-      multi_json (~> 1.17)
+      multi_json (~> 1.20)
       zeitwerk (~> 2.7)
 
 GEM
@@ -156,8 +156,11 @@ GEM
       net-smtp
     marcel (1.0.4)
     mini_mime (1.1.5)
-    minitest (5.25.5)
-    multi_json (1.17.0)
+    mini_portile2 (2.8.9)
+    minitest (6.0.2)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    multi_json (1.21.1)
     net-imap (0.5.9)
       date
       net-protocol
@@ -168,11 +171,15 @@ GEM
     net-smtp (0.5.1)
       net-protocol
     nio4r (2.7.4)
+    nokogiri (1.18.8)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
     nokogiri (1.18.8-arm64-darwin)
       racc (~> 1.4)
     pp (0.6.2)
       prettyprint
     prettyprint (0.2.0)
+    prism (1.9.0)
     psych (5.2.6)
       date
       stringio
@@ -246,4 +253,4 @@ DEPENDENCIES
   rails (~> 8.0.2)
 
 BUNDLED WITH
-   2.7.0
+  4.0.8

data/examples/rails/config/initializers/jsonrpc.rb

@@ -16,7 +16,7 @@ require_relative '../../../procedures'
 #     end
 #
 #     rule(:addends) do
-#       key.failure('must contain at least one addend') if value.empty?
+#       key.failure('must contain at least two addends') if value.size < 2
 #     end
 #   end
 #

data/examples/rails-routing-dsl/config.ru

@@ -65,7 +65,7 @@ class App < Rails::Application
 end
 
 # Controller for main system operations
-class MainController < ActionController::Base
+class MainController < ApplicationController
   def on
     render jsonrpc: { device: 'main_system', status: 'on' }
   end
@@ -76,7 +76,7 @@ class MainController < ActionController::Base
 end
 
 # Controller for lights operations
-class LightsController < ActionController::Base
+class LightsController < ApplicationController
   def on
     render jsonrpc: { device: 'lights', status: 'on' }
   end
@@ -87,7 +87,7 @@ class LightsController < ActionController::Base
 end
 
 # Controller for climate operations
-class ClimateController < ActionController::Base
+class ClimateController < ApplicationController
   def on
     render jsonrpc: { device: 'climate_system', status: 'on' }
   end
@@ -98,7 +98,7 @@ class ClimateController < ActionController::Base
 end
 
 # Controller for climate fan operations
-class FanController < ActionController::Base
+class FanController < ApplicationController
   def on
     render jsonrpc: { device: 'fan', status: 'on' }
   end
@@ -109,7 +109,7 @@ class FanController < ActionController::Base
 end
 
 # Controller for batch operations
-class BatchController < ActionController::Base
+class BatchController < ApplicationController
   def handle
     # Process each request in the batch and collect results
     results = jsonrpc_batch.process_each do |request_or_notification|

data/examples/rails-single-file/config.ru

@@ -40,7 +40,7 @@ class App < Rails::Application
 end
 
 # Define the JSONRPC controller
-class JsonrpcController < ActionController::Base
+class JsonrpcController < ApplicationController
   def handle
     if jsonrpc_request?
       result = handle_single(jsonrpc_request)

data/examples/rails-single-file-routing/config.ru

@@ -47,7 +47,7 @@ class App < Rails::Application
 end
 
 # Define the JSONRPC controller
-class JsonrpcController < ActionController::Base
+class JsonrpcController < ApplicationController
   def echo
     render jsonrpc: jsonrpc_request.params
   end

data/examples/sinatra-classic/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.5.0)
+    jsonrpc-middleware (0.6.0)
+      dry-struct (~> 1.8)
       dry-validation (~> 1.11)
-      multi_json (~> 1.17)
+      multi_json (~> 1.20)
       zeitwerk (~> 2.7)
 
 GEM
@@ -34,6 +35,11 @@ GEM
       dry-logic (~> 1.5)
       dry-types (~> 1.8)
       zeitwerk (~> 2.6)
+    dry-struct (1.8.0)
+      dry-core (~> 1.1)
+      dry-types (~> 1.8, >= 1.8.2)
+      ice_nine (~> 0.11)
+      zeitwerk (~> 2.6)
     dry-types (1.8.3)
       bigdecimal (~> 3.0)
       concurrent-ruby (~> 1.0)
@@ -47,8 +53,9 @@ GEM
       dry-initializer (~> 3.2)
       dry-schema (~> 1.14)
       zeitwerk (~> 2.6)
+    ice_nine (0.11.2)
     logger (1.7.0)
-    multi_json (1.17.0)
+    multi_json (1.21.1)
     mustermann (3.0.3)
       ruby2_keywords (~> 0.0.1)
     nio4r (2.7.4)
@@ -93,4 +100,4 @@ DEPENDENCIES
   sinatra-contrib
 
 BUNDLED WITH
-   2.7.0
+  4.0.8

data/examples/sinatra-modular/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.5.0)
+    jsonrpc-middleware (0.6.0)
+      dry-struct (~> 1.8)
       dry-validation (~> 1.11)
-      multi_json (~> 1.17)
+      multi_json (~> 1.20)
       zeitwerk (~> 2.7)
 
 GEM
@@ -34,6 +35,11 @@ GEM
       dry-logic (~> 1.5)
       dry-types (~> 1.8)
       zeitwerk (~> 2.6)
+    dry-struct (1.8.0)
+      dry-core (~> 1.1)
+      dry-types (~> 1.8, >= 1.8.2)
+      ice_nine (~> 0.11)
+      zeitwerk (~> 2.6)
     dry-types (1.8.3)
       bigdecimal (~> 3.0)
       concurrent-ruby (~> 1.0)
@@ -47,8 +53,9 @@ GEM
       dry-initializer (~> 3.2)
       dry-schema (~> 1.14)
       zeitwerk (~> 2.6)
+    ice_nine (0.11.2)
     logger (1.7.0)
-    multi_json (1.17.0)
+    multi_json (1.21.1)
     mustermann (3.0.3)
       ruby2_keywords (~> 0.0.1)
     nio4r (2.7.4)
@@ -93,4 +100,4 @@ DEPENDENCIES
   sinatra-contrib
 
 BUNDLED WITH
-   2.7.0
+  4.0.8

data/lib/jsonrpc/batch_request.rb

@@ -6,6 +6,8 @@ module JSONRPC
   # 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.
   #
+  # @api public
+  #
   # @example Create a batch request with multiple requests
   #   batch = JSONRPC::BatchRequest.new([
   #     JSONRPC::Request.new(method: "sum", params: [1, 2, 4], id: "1"),
@@ -39,14 +41,13 @@ module JSONRPC
     #   ]
     #   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
     #
+    # @param requests [Array<JSONRPC::Request, JSONRPC::Notification, JSONRPC::Error>] an array of request objects
+    #   or errors
+    #
     def initialize(requests)
       validate_requests(requests)
       @requests = requests
@@ -109,9 +110,7 @@ module JSONRPC
     #
     # @return [Integer] the number of requests in the batch
     #
-    def size
-      requests.size
-    end
+    def size = requests.size
 
     # Alias for size method providing Array-like interface
     #
@@ -162,14 +161,12 @@ module JSONRPC
     #
     # @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
     #
+    # @param requests [Array] the array of requests
+    #
     # @return [void]
     #
     def validate_requests(requests)

data/lib/jsonrpc/batch_response.rb

@@ -7,6 +7,8 @@ module JSONRPC
   # a Batch Request. The Server should respond with one Response for each Request
   # (except for Notifications which don't receive responses).
   #
+  # @api public
+  #
   # @example Create a batch response
   #   batch = JSONRPC::BatchResponse.new([
   #     JSONRPC::Response.new(result: 7, id: "1"),
@@ -39,14 +41,12 @@ module JSONRPC
     #   ]
     #   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
     #
+    # @param responses [Array<JSONRPC::Response>] an array of response objects
+    #
     def initialize(responses)
       validate_responses(responses)
       @responses = responses
@@ -119,14 +119,12 @@ module JSONRPC
     #
     # @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
     #
+    # @param responses [Array] the array of responses
+    #
     # @return [void]
     #
     def validate_responses(responses)

data/lib/jsonrpc/configuration.rb

@@ -20,32 +20,52 @@ module JSONRPC
     #
     # @api public
     #
-    # @!method allow_positional_arguments
+    # @!attribute [r] allow_positional_arguments
     #   Indicates if the procedure accepts positional arguments
+    #
     #   @api public
     #
     #   @example
     #     procedure.allow_positional_arguments # => true
+    #
     #   @return [Boolean] whether the procedure accepts positional arguments
     #
-    # @!method contract
+    # @!attribute [r] 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
     #
-    # @!method parameter_name
+    # @!attribute [r] 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)
 
+    # The logger instance used for error and diagnostic output
+    #
+    # @api public
+    #
+    # @example Using the default logger
+    #   config.logger # => #<Logger:...>
+    #
+    # @example Setting a custom logger
+    #   config.logger = Logger.new('log/jsonrpc.log')
+    #
+    # @return [Logger] the logger instance
+    #
+    attr_accessor :logger
+
     # Whether to log detailed internal error information in the terminal
     #
     # @api public
@@ -108,6 +128,8 @@ module JSONRPC
     # @example
     #   config.json_adapter = :oj
     #
+    # @param adapter [Symbol, nil] the JSON adapter to use
+    #
     # @return [Symbol, nil] the JSON adapter to use
     #
     def json_adapter=(adapter)
@@ -127,6 +149,7 @@ module JSONRPC
     #     render_internal_errors: true
     #   )
     #
+    # @param logger [Logger] the logger instance for error and diagnostic output
     # @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
@@ -136,6 +159,7 @@ module JSONRPC
     # @return [Configuration] a new configuration instance
     #
     def initialize(
+      logger: Logger.new($stdout, progname: 'JSONRPC'),
       log_internal_errors: true,
       log_request_validation_errors: false,
       rescue_internal_errors: true,
@@ -143,6 +167,7 @@ module JSONRPC
       validate_procedure_signatures: true
     )
       @procedures = {}
+      @logger = logger
       @log_internal_errors = log_internal_errors
       @log_request_validation_errors = log_request_validation_errors
       @rescue_internal_errors = rescue_internal_errors
@@ -180,8 +205,9 @@ module JSONRPC
     #
     # @param method_name [String, Symbol] the name of the procedure
     # @param allow_positional_arguments [Boolean] whether the procedure accepts positional arguments
+    # @param block [Proc, nil] an optional block that defines the validation contract using Dry::Validation DSL
     #
-    # @yield [optional] A block that defines the validation contract using Dry::Validation DSL
+    # @yield A block that defines the validation contract using Dry::Validation DSL
     #
     # @return [Procedure] the registered procedure
     #

data/lib/jsonrpc/error.rb

@@ -82,15 +82,14 @@ module JSONRPC
     # @example Create an error with additional data
     #   error = JSONRPC::Error.new("Invalid params", code: -32602, data: { "field" => "missing" })
     #
+    # @raise [ArgumentError] if code is not an Integer
+    # @raise [ArgumentError] if message is not a String
+    #
     # @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)
 
@@ -150,10 +149,10 @@ module JSONRPC
     #
     # @api private
     #
-    # @param code [Integer] the error code
-    #
     # @raise [ArgumentError] if code is not an Integer
     #
+    # @param code [Integer] the error code
+    #
     # @return [void]
     #
     def validate_code(code)
@@ -164,10 +163,10 @@ module JSONRPC
     #
     # @api private
     #
-    # @param message [String] the error message
-    #
     # @raise [ArgumentError] if message is not a String
     #
+    # @param message [String] the error message
+    #
     # @return [void]
     #
     def validate_message(message)

data/lib/jsonrpc/errors/internal_error.rb

@@ -5,6 +5,8 @@ module JSONRPC
   #
   # Raised when there was an internal JSON-RPC error.
   #
+  # @api public
+  #
   # @example Create an internal error
   #   error = JSONRPC::Errors::InternalError.new(data: { details: 'Unexpected server error' })
   #

data/lib/jsonrpc/errors/invalid_params_error.rb

@@ -5,6 +5,8 @@ module JSONRPC
   #
   # Raised when invalid method parameter(s) were provided.
   #
+  # @api public
+  #
   # @example Create an invalid params error
   #   error = JSONRPC::InvalidParamsError.new(data: { details: "Expected array of integers" })
   #

data/lib/jsonrpc/errors/invalid_request_error.rb

@@ -5,6 +5,8 @@ module JSONRPC
   #
   # Raised when the JSON sent is not a valid Request object.
   #
+  # @api public
+  #
   # @example Create an invalid request error
   #   error = JSONRPC::InvalidRequestError.new(data: { details: "Method must be a string" })
   #

data/lib/jsonrpc/errors/method_not_found_error.rb

@@ -5,6 +5,8 @@ module JSONRPC
   #
   # Raised when the method does not exist / is not available.
   #
+  # @api public
+  #
   # @example Create a method not found error
   #   error = JSONRPC::MethodNotFound.new(data: { requested_method: "unknown_method" })
   #

data/lib/jsonrpc/errors/parse_error.rb

@@ -6,6 +6,8 @@ module JSONRPC
   # Raised when invalid JSON was received by the server.
   # An error occurred on the server while parsing the JSON text.
   #
+  # @api public
+  #
   # @example Create a parse error
   #   error = JSONRPC::ParseError.new(data: { details: "Unexpected end of input" })
   #

data/lib/jsonrpc/helpers.rb

@@ -2,6 +2,9 @@
 
 module JSONRPC
   # Framework-agnostic helpers for JSON-RPC
+  #
+  # @api public
+  #
   module Helpers
     # Extends the including class with ClassMethods when module is included
     #
@@ -21,6 +24,9 @@ module JSONRPC
     end
 
     # Class methods for registering JSON-RPC procedure handlers
+    #
+    # @api public
+    #
     module ClassMethods
       # Registers a JSON-RPC procedure with the given method name
       #

data/lib/jsonrpc/middleware.rb

@@ -41,13 +41,15 @@ module JSONRPC
     # @option options [String] :path ('/') The path to handle JSON-RPC requests on
     # @option options [Boolean] :rescue_internal_errors (nil) Override config rescue_internal_errors
     # @option options [Boolean] :log_internal_errors (true) Override config log_internal_errors
+    # @option options [Logger] :logger (nil) Override config logger
     #
     def initialize(app, options = {})
       @app = app
-      @parser = Parser.new
-      @validator = Validator.new
       @path = options.fetch(:path, DEFAULT_PATH)
       @config = JSONRPC.configuration
+      @logger = options.fetch(:logger, @config.logger)
+      @parser = Parser.new
+      @validator = Validator.new(logger: @logger)
       @log_internal_errors = options.fetch(:log_internal_errors, @config.log_internal_errors)
       @rescue_internal_errors = options.fetch(:rescue_internal_errors, @config.rescue_internal_errors)
     end
@@ -89,10 +91,10 @@ module JSONRPC
     #
     # @api private
     #
-    # @return [Array] Rack response tuple
-    #
     # @raise [StandardError] Catches all errors and converts to Internal Error response
     #
+    # @return [Array] Rack response tuple
+    #
     def handle_jsonrpc_request
       parsed_request = parse_request
       return parsed_request if parsed_request.is_a?(Array) # Early return for parse errors
@@ -122,12 +124,11 @@ module JSONRPC
     #
     # @api private
     #
-    # @return [Request, Notification, BatchRequest, Array] Parsed request or error response
-    #
     # @raise [ParseError] When JSON parsing fails
-    #
     # @raise [InvalidRequestError] When request structure is invalid
     #
+    # @return [Request, Notification, BatchRequest, Array] Parsed request or error response
+    #
     def parse_request
       body = read_request_body
       parsed = @parser.parse(body)
@@ -259,7 +260,7 @@ module JSONRPC
     # @return [Array<Request, Notification>] Array of valid requests
     #
     def collect_valid_requests(batch_request)
-      batch_request.requests.reject { |item| item.is_a?(Error) }
+      batch_request.requests.grep_v(Error)
     end
 
     # Builds ordered array of responses maintaining request order for batch processing
@@ -378,7 +379,7 @@ module JSONRPC
       body_content
     end
 
-    # Logs internal errors to stdout with full backtrace
+    # Logs internal errors with full backtrace using the configured logger
     #
     # @api private
     #
@@ -390,8 +391,8 @@ module JSONRPC
     # @return [void]
     #
     def log_internal_error(error)
-      puts "Internal error: #{error.message}"
-      puts error.backtrace.join("\n")
+      @logger.error("Internal error: #{error.message}")
+      @logger.error(error.backtrace.join("\n"))
     end
   end
 end

data/lib/jsonrpc/notification.rb

@@ -62,13 +62,12 @@ module JSONRPC
     # @example Create a notification with named parameters
     #   JSONRPC::Notification.new(method: "log", params: { level: "info", message: "Hello" })
     #
-    # @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
     #
+    # @param method [String] the name of the method to be invoked
+    # @param params [Hash, Array, nil] the parameters to be used during method invocation
+    #
     def initialize(method:, params: nil)
       @jsonrpc = '2.0'
 
@@ -117,10 +116,10 @@ module JSONRPC
     #
     # @api private
     #
-    # @param method [String] the method name
-    #
     # @raise [ArgumentError] if method is not a String or is reserved
     #
+    # @param method [String] the method name
+    #
     # @return [void]
     #
     def validate_method(method)
@@ -135,10 +134,10 @@ module JSONRPC
     #
     # @api private
     #
-    # @param params [Hash, Array, nil] the parameters
-    #
     # @raise [ArgumentError] if params is not a Hash, Array, or nil
     #
+    # @param params [Hash, Array, nil] the parameters
+    #
     # @return [void]
     #
     def validate_params(params)