jsonrpc-middleware 0.1.0 → 0.2.0

data/lib/jsonrpc/middleware.rb

@@ -3,17 +3,66 @@
 require 'rack'
 
 module JSONRPC
-  # Middleware for JSON-RPC compliance
+  # Rack middleware for handling JSON-RPC 2.0 requests
+  #
+  # @api public
+  #
+  # This middleware intercepts HTTP POST requests at a specified path and processes them
+  # as JSON-RPC 2.0 messages. It handles parsing, validation, and error responses according
+  # to the JSON-RPC 2.0 specification.
+  #
+  # @example Basic usage
+  #   use JSONRPC::Middleware
+  #
+  # @example Custom path
+  #   use JSONRPC::Middleware, path: '/api/v1/rpc'
+  #
   class Middleware
+    # Default path for JSON-RPC requests
+    #
+    # @api public
+    #
+    # @return [String] The default path '/'
+    #
     DEFAULT_PATH = '/'
 
+    # Initializes the JSON-RPC middleware
+    #
+    # @api public
+    #
+    # @example Basic initialization
+    #   middleware = JSONRPC::Middleware.new(app)
+    #
+    # @example With custom path
+    #   middleware = JSONRPC::Middleware.new(app, path: '/api/jsonrpc')
+    #
+    # @param app [#call] The Rack application to wrap
+    # @param options [Hash] Configuration options
+    # @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
+    #
     def initialize(app, options = {})
       @app = app
       @parser = Parser.new
       @validator = Validator.new
       @path = options.fetch(:path, DEFAULT_PATH)
+      @config = JSONRPC.configuration
+      @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
 
+    # Rack application call method
+    #
+    # @api public
+    #
+    # @example Processing a request
+    #   status, headers, body = middleware.call(env)
+    #
+    # @param env [Hash] The Rack environment
+    #
+    # @return [Array] Rack response tuple [status, headers, body]
+    #
     def call(env)
       @req = Rack::Request.new(env)
 
@@ -26,26 +75,59 @@ module JSONRPC
 
     private
 
+    # Determines if the current request should be handled as JSON-RPC
+    #
+    # @api private
+    #
+    # @return [Boolean] true if the request matches the configured path and is a POST request
+    #
     def jsonrpc_request?
       @req.path == @path && @req.post?
     end
 
+    # Handles a JSON-RPC request through the complete processing pipeline
+    #
+    # @api private
+    #
+    # @return [Array] Rack response tuple
+    #
+    # @raise [StandardError] Catches all errors and converts to Internal Error response
+    #
     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
+      if @config.validate_procedure_signatures
+        validation_result = validate_request(parsed_request)
+        return validation_result if validation_result.is_a?(Array) # Early return for validation errors
+      end
 
       # 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)
+    rescue StandardError => e
+      log_internal_error(e) if @log_internal_errors
+
+      data = {}
+      data = { class: e.class.name, message: e.message, backtrace: e.backtrace } if @config.render_internal_errors
+      error = InternalError.new(request_id: parsed_request.is_a?(Request) ? parsed_request.id : nil, data:)
       @req.env['jsonrpc.error'] = error
+
+      raise e unless @rescue_internal_errors
+
       json_response(200, error.to_response)
     end
 
+    # Parses the request body into JSON-RPC objects
+    #
+    # @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
+    #
     def parse_request
       body = read_request_body
       parsed = @parser.parse(body)
@@ -59,6 +141,14 @@ module JSONRPC
       json_response(200, e.to_response)
     end
 
+    # Validates the parsed request using registered procedure definitions
+    #
+    # @api private
+    #
+    # @param parsed_request [Request, Notification, BatchRequest] The parsed request to validate
+    #
+    # @return [Array, nil] Validation error response or nil if valid
+    #
     def validate_request(parsed_request)
       validation_errors = @validator.validate(parsed_request)
 
@@ -72,6 +162,14 @@ module JSONRPC
       end
     end
 
+    # Stores the parsed request in the Rack environment for downstream processing
+    #
+    # @api private
+    #
+    # @param parsed_request [Request, Notification, BatchRequest] The request to store
+    #
+    # @return [void]
+    #
     def store_request_in_env(parsed_request)
       case parsed_request
       when Request
@@ -85,10 +183,26 @@ module JSONRPC
 
     # Batch handling methods
 
+    # Checks if any requests in a batch contain parse errors
+    #
+    # @api private
+    #
+    # @param batch_request [BatchRequest] The batch request to check
+    #
+    # @return [Boolean] true if any request is an Error object
+    #
     def parse_errors?(batch_request)
       batch_request.requests.any?(Error)
     end
 
+    # Handles batch requests that contain a mix of parse errors and valid requests
+    #
+    # @api private
+    #
+    # @param batch_request [BatchRequest] The batch request containing mixed errors
+    #
+    # @return [Array] Rack response tuple with error and success responses
+    #
     def handle_mixed_batch_errors(batch_request)
       error_responses = collect_parse_error_responses(batch_request)
       valid_requests = collect_valid_requests(batch_request)
@@ -101,6 +215,15 @@ module JSONRPC
       json_response(200, BatchResponse.new(error_responses).to_h)
     end
 
+    # Handles batch requests with validation errors by building appropriate responses
+    #
+    # @api private
+    #
+    # @param batch_request [BatchRequest] The batch request with validation errors
+    # @param validation_errors [Array] Array of validation errors corresponding to each request
+    #
+    # @return [Array] Rack response tuple with mixed error and success responses
+    #
     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)
@@ -113,16 +236,41 @@ module JSONRPC
       json_response(200, BatchResponse.new(responses.compact).to_h)
     end
 
+    # Collects error responses from parse errors in a batch request
+    #
+    # @api private
+    #
+    # @param batch_request [BatchRequest] The batch request to process
+    #
+    # @return [Array<Response>] Array of error responses
+    #
     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
 
+    # Collects valid (non-error) requests from a batch request
+    #
+    # @api private
+    #
+    # @param batch_request [BatchRequest] The batch request to process
+    #
+    # @return [Array<Request, Notification>] Array of valid requests
+    #
     def collect_valid_requests(batch_request)
       batch_request.requests.reject { |item| item.is_a?(Error) }
     end
 
+    # Builds ordered array of responses maintaining request order for batch processing
+    #
+    # @api private
+    #
+    # @param batch_request [BatchRequest] The original batch request
+    # @param validation_errors [Array] Array of validation errors corresponding to each request
+    #
+    # @return [Array<Response, nil>] Array of responses with nil for valid requests
+    #
     def build_ordered_responses(batch_request, validation_errors)
       responses = Array.new(batch_request.requests.size)
 
@@ -133,6 +281,15 @@ module JSONRPC
       responses
     end
 
+    # Extracts valid requests and their indices from a batch with validation errors
+    #
+    # @api private
+    #
+    # @param batch_request [BatchRequest] The batch request to process
+    # @param validation_errors [Array] Array of validation errors
+    #
+    # @return [Array<Array<Request>, Array<Integer>>] Valid requests and their original indices
+    #
     def extract_valid_requests(batch_request, validation_errors)
       valid_requests = []
       valid_indices = []
@@ -147,6 +304,14 @@ module JSONRPC
       [valid_requests, valid_indices]
     end
 
+    # Processes valid batch requests by delegating to the application
+    #
+    # @api private
+    #
+    # @param valid_requests [Array<Request, Notification>] Valid requests to process
+    #
+    # @return [Array<Response>] Array of successful responses from the application
+    #
     def process_valid_batch_requests(valid_requests)
       valid_batch = BatchRequest.new(valid_requests)
 
@@ -165,6 +330,16 @@ module JSONRPC
       end
     end
 
+    # Merges successful responses into their original positions
+    #
+    # @api private
+    #
+    # @param responses [Array<Response, nil>] Array of responses with error responses and nils
+    # @param success_responses [Array<Response>] Successful responses from the application
+    # @param valid_indices [Array<Integer>] Original indices of the valid requests
+    #
+    # @return [void]
+    #
     def merge_success_responses(responses, success_responses, valid_indices)
       success_responses.each_with_index do |response, app_index|
         original_index = valid_indices[app_index]
@@ -174,10 +349,25 @@ module JSONRPC
 
     # Utility methods
 
+    # Creates a JSON HTTP response
+    #
+    # @api private
+    #
+    # @param status [Integer] HTTP status code
+    # @param body [Hash, String] Response body to serialize as JSON
+    #
+    # @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)]]
     end
 
+    # Reads and returns the request body from the Rack environment
+    #
+    # @api private
+    #
+    # @return [String, nil] The request body content or nil if no body
+    #
     def read_request_body
       body = @req.env[Rack::RACK_INPUT]
       return unless body
@@ -186,5 +376,21 @@ module JSONRPC
       body.rewind if body.respond_to?(:rewind)
       body_content
     end
+
+    # Logs internal errors to stdout with full backtrace
+    #
+    # @api private
+    #
+    # @example Log an internal error
+    #   log_internal_error(StandardError.new("Something went wrong"))
+    #
+    # @param error [Exception] The error to log
+    #
+    # @return [void]
+    #
+    def log_internal_error(error)
+      puts "Internal error: #{error.message}"
+      puts error.backtrace.join("\n")
+    end
   end
 end

data/lib/jsonrpc/notification.rb

@@ -3,6 +3,12 @@
 module JSONRPC
   # A JSON-RPC 2.0 Notification object
   #
+  # @api public
+  #
+  # Represents a method call that does not expect a response. Unlike a
+  # Request, a Notification omits the "id" field, indicating that no
+  # response should be sent.
+  #
   # A Notification is a Request object without an "id" member.
   # Notifications are not confirmable by definition since they do not have a Response object.
   #
@@ -14,25 +20,53 @@ module JSONRPC
   #
   class Notification
     # JSON-RPC protocol version
+    #
+    # @api public
+    #
+    # @example
+    #   notification.jsonrpc # => "2.0"
+    #
     # @return [String]
     #
     attr_reader :jsonrpc
 
     # The method name to invoke
+    #
+    # @api public
+    #
+    # @example
+    #   notification.method # => "update"
+    #
     # @return [String]
     #
     attr_reader :method
 
     # Parameters to pass to the method
+    #
+    # @api public
+    #
+    # @example
+    #   notification.params # => [1, 2, 3, 4, 5]
+    #
     # @return [Hash, Array, nil]
     #
     attr_reader :params
 
     # Creates a new JSON-RPC 2.0 Notification object
     #
+    # @api public
+    #
+    # @example Create a notification with array parameters
+    #   JSONRPC::Notification.new(method: "update", params: [1, 2, 3])
+    #
+    # @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
     #
     def initialize(method:, params: nil)
@@ -47,6 +81,11 @@ module JSONRPC
 
     # Converts the notification to a JSON-compatible Hash
     #
+    # @api public
+    #
+    # @example
+    #   notification.to_h # => { jsonrpc: "2.0", method: "update", params: [1, 2, 3] }
+    #
     # @return [Hash] the notification as a JSON-compatible Hash
     #
     def to_h
@@ -59,6 +98,15 @@ module JSONRPC
       hash
     end
 
+    # Converts the notification to a JSON string
+    #
+    # @api public
+    #
+    # @example
+    #   notification.to_json # => '{"jsonrpc":"2.0","method":"update","params":[1,2,3]}'
+    #
+    # @return [String] the notification as a JSON string
+    #
     def to_json(*)
       to_h.to_json(*)
     end
@@ -67,9 +115,14 @@ module JSONRPC
 
     # Validates that the method name meets JSON-RPC 2.0 requirements
     #
+    # @api private
+    #
     # @param method [String] the method name
+    #
     # @raise [ArgumentError] if method is not a String or is reserved
     #
+    # @return [void]
+    #
     def validate_method(method)
       raise ArgumentError, 'Method must be a String' unless method.is_a?(String)
 
@@ -80,9 +133,14 @@ module JSONRPC
 
     # Validates that the params is a valid structure according to JSON-RPC 2.0
     #
+    # @api private
+    #
     # @param params [Hash, Array, nil] the parameters
+    #
     # @raise [ArgumentError] if params is not a Hash, Array, or nil
     #
+    # @return [void]
+    #
     def validate_params(params)
       return if params.nil?
 

data/lib/jsonrpc/parser.rb

@@ -20,11 +20,20 @@ module JSONRPC
   class Parser
     # Parse a JSON-RPC 2.0 message
     #
+    # @api public
+    #
+    # @example Parse a single request
+    #   parser.parse('{"jsonrpc":"2.0","method":"subtract","params":[42,23],"id":1}')
+    #
+    # @example Parse a batch request
+    #   parser.parse('[{"jsonrpc":"2.0","method":"sum","params":[1,2],"id":"1"}]')
+    #
     # @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)
@@ -45,7 +54,10 @@ module JSONRPC
 
     # Parse a single JSON-RPC 2.0 message
     #
+    # @api private
+    #
     # @param data [Hash] the parsed JSON data
+    #
     # @return [Request, Notification, Error] the parsed request, notification, or error
     #
     def parse_single(data)
@@ -67,8 +79,12 @@ module JSONRPC
 
     # Parse a batch JSON-RPC 2.0 message
     #
+    # @api private
+    #
     # @param data [Array] the array of request data
+    #
     # @return [BatchRequest] the batch request
+    #
     # @raise [InvalidRequestError] if the batch is empty
     #
     def parse_batch(data)
@@ -94,8 +110,12 @@ module JSONRPC
 
     # Parse a single item within a batch, allowing errors to be captured
     #
+    # @api private
+    #
     # @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)
@@ -117,9 +137,14 @@ module JSONRPC
 
     # Validate the JSON-RPC 2.0 version
     #
+    # @api private
+    #
     # @param data [Hash] the request data
+    #
     # @raise [InvalidRequestError] if the version is missing or invalid
     #
+    # @return [void]
+    #
     def validate_jsonrpc_version(data)
       raise InvalidRequestError.new(data: { details: 'Request must be an object' }) unless data.is_a?(Hash)
 
@@ -141,9 +166,14 @@ module JSONRPC
 
     # Validate the request structure according to JSON-RPC 2.0 specification
     #
+    # @api private
+    #
     # @param data [Hash] the request data
+    #
     # @raise [InvalidRequestError] if the request structure is invalid
     #
+    # @return [void]
+    #
     def validate_request_structure(data)
       method = data['method']
 

data/lib/jsonrpc/railtie.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # @api private
+  class Railtie < ::Rails::Railtie
+    initializer 'jsonrpc.middleware' do |app|
+      app.middleware.use JSONRPC::Middleware
+    end
+
+    initializer 'jsonrpc.renderer' do
+      ActiveSupport.on_load(:action_controller) do
+        Mime::Type.register 'application/json', :jsonrpc
+
+        ActionController::Renderers.add :jsonrpc do |result_data, _options|
+          self.content_type ||= Mime[:jsonrpc]
+
+          # Handle different types of JSON-RPC responses
+          if jsonrpc_request?
+            # Single request - create response with ID and result
+            self.status = 200
+            self.response_body = JSONRPC::Response.new(id: jsonrpc_request.id, result: result_data).to_json
+          elsif jsonrpc_batch?
+            # Batch request - result_data should be an array of responses
+            if result_data.compact.empty?
+              # Batch contained only notifications
+              self.status = 204
+              self.response_body = ''
+              ''
+            else
+              result_data.to_json
+            end
+          elsif jsonrpc_notification?
+            # Notification - no response body
+            self.status = 204
+            self.response_body = ''
+            ''
+          else
+            # Fallback - treat as regular JSON-RPC response
+            result_data.to_json
+          end
+        end
+      end
+    end
+
+    # Hook into the controller loading process
+    initializer 'jsonrpc.include_controller_extensions', after: 'action_controller.set_configs' do
+      ActiveSupport.on_load(:action_controller_base) do
+        include JSONRPC::Helpers
+      end
+
+      # Also include in API controllers if you're using Rails API mode
+      ActiveSupport.on_load(:action_controller_api) do
+        include JSONRPC::Helpers
+      end
+    end
+  end
+end