jsonrpc-middleware 0.5.0 → 0.7.0

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
@@ -75,7 +76,7 @@ module JSONRPC
     # @return [String] the JSON-formatted batch
     #
     def to_json(*)
-      to_h.to_json(*)
+      MultiJson.dump(to_h, *)
     end
 
     # Implements the Enumerable contract by yielding each request in the batch
@@ -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
@@ -75,7 +75,7 @@ module JSONRPC
     # @return [String] the JSON-formatted batch response
     #
     def to_json(*)
-      to_h.to_json(*)
+      MultiJson.dump(to_h, *)
     end
 
     # Implements the Enumerable contract by yielding each response in the batch
@@ -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
@@ -101,6 +121,21 @@ module JSONRPC
     #
     attr_reader :validate_procedure_signatures
 
+    # JSON adapter to use (optional)
+    #
+    # @api public
+    #
+    # @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)
+      MultiJson.use(adapter)
+    end
+
     # Initializes a new Configuration instance
     #
     # @api public
@@ -114,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
@@ -123,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,
@@ -130,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
@@ -167,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)
 
@@ -128,7 +127,7 @@ module JSONRPC
     # @return [String] the error as a JSON string
     #
     def to_json(*)
-      to_h.to_json(*)
+      MultiJson.dump(to_h, *)
     end
 
     # Converts the error to a complete JSON-RPC response
@@ -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
@@ -324,7 +325,7 @@ module JSONRPC
 
       return [] unless status == 200 && !body.empty?
 
-      app_responses = JSON.parse(body.join)
+      app_responses = MultiJson.load(body.join)
       app_responses.map do |resp|
         Response.new(id: resp['id'], result: resp['result'], error: resp['error'])
       end
@@ -359,7 +360,8 @@ module JSONRPC
     # @return [Array] Rack response tuple [status, headers, body]
     #
     def json_response(status, body)
-      [status, { 'content-type' => 'application/json' }, [body.is_a?(String) ? body : JSON.generate(body)]]
+      json_body = body.is_a?(String) ? body : MultiJson.dump(body)
+      [status, { 'content-type' => 'application/json' }, [json_body]]
     end
 
     # Reads and returns the request body from the Rack environment
@@ -377,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
     #
@@ -389,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'
 
@@ -108,7 +107,7 @@ module JSONRPC
     # @return [String] the notification as a JSON string
     #
     def to_json(*)
-      to_h.to_json(*)
+      MultiJson.dump(to_h, *)
     end
 
     private
@@ -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)

data/lib/jsonrpc/parser.rb

@@ -1,13 +1,13 @@
 # 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.
   #
+  # @api public
+  #
   # @example Parse a request
   #   parser = JSONRPC::Parser.new
   #   request = parser.parse('{"jsonrpc":"2.0","method":"subtract","params":[42,23],"id":1}')
@@ -28,26 +28,29 @@ module JSONRPC
     # @example Parse a batch request
     #   parser.parse('[{"jsonrpc":"2.0","method":"sum","params":[1,2],"id":"1"}]')
     #
+    # @raise [ParseError] if the JSON is invalid
+    # @raise [InvalidRequestError] if the request structure is invalid
+    #
     # @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
+      data = MultiJson.load(json)
 
       if data.is_a?(Array)
         parse_batch(data)
       else
         parse_single(data)
       end
+    rescue MultiJson::ParseError => e
+      raise ParseError.new(
+        data: {
+          details: e.message,
+          adapter: MultiJson.adapter.name,
+          input_preview: json[0..100]
+        }
+      )
     end
 
     private
@@ -81,12 +84,12 @@ module JSONRPC
     #
     # @api private
     #
+    # @raise [InvalidRequestError] if the batch is empty
+    #
     # @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?
 
@@ -112,12 +115,12 @@ module JSONRPC
     #
     # @api private
     #
+    # @raise [InvalidRequestError] if the request structure is invalid
+    #
     # @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)
@@ -139,10 +142,10 @@ module JSONRPC
     #
     # @api private
     #
-    # @param data [Hash] the request data
-    #
     # @raise [InvalidRequestError] if the version is missing or invalid
     #
+    # @param data [Hash] the request data
+    #
     # @return [void]
     #
     def validate_jsonrpc_version(data)
@@ -168,10 +171,10 @@ module JSONRPC
     #
     # @api private
     #
-    # @param data [Hash] the request data
-    #
     # @raise [InvalidRequestError] if the request structure is invalid
     #
+    # @param data [Hash] the request data
+    #
     # @return [void]
     #
     def validate_request_structure(data)

data/lib/jsonrpc/railtie/batch_constraint.rb

@@ -13,6 +13,7 @@ module JSONRPC
     # Check if the request is a JSON-RPC batch request
     #
     # @param request [ActionDispatch::Request] The Rails request object
+    #
     # @return [Boolean] true if the request is a batch request, false otherwise
     #
     def matches?(request)

data/lib/jsonrpc/railtie/mapper_extension.rb

@@ -8,8 +8,6 @@ module JSONRPC
   module MapperExtension
     # Define JSON-RPC routes with a DSL
     #
-    # @param path [String] the path to handle JSON-RPC requests on
-    #
     # @example Define JSON-RPC routes
     #   jsonrpc '/api/v1' do
     #     # Handle batch requests
@@ -24,6 +22,8 @@ module JSONRPC
     #     end
     #   end
     #
+    # @param path [String] the path to handle JSON-RPC requests on
+    #
     # @return [void]
     #
     def jsonrpc(path = '/', &)

data/lib/jsonrpc/railtie/method_constraint.rb

@@ -22,6 +22,7 @@ module JSONRPC
     # Check if the request matches the configured method name
     #
     # @param request [ActionDispatch::Request] The Rails request object
+    #
     # @return [Boolean] true if the JSON-RPC method matches, false otherwise
     #
     def matches?(request)
@@ -31,5 +32,13 @@ module JSONRPC
 
       jsonrpc_request.method == @jsonrpc_method_name
     end
+
+    # Returns a string representation of the constraint
+    #
+    # @return [String] A string showing the configured JSON-RPC method name
+    #
+    def to_s
+      "#<JSONRPC::MethodConstraint method=\"#{@jsonrpc_method_name}\">"
+    end
   end
 end