jsonrpc-rails 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16369528b9adcf6bc2b66b42365e475be375d330312694626d8244f2205e9df3
-  data.tar.gz: 4eeda34cff81e732d5aac37d684c81eba9c7a66de1729a7f1f2c1c8097de21fb
+  metadata.gz: e098dc20d9c1c05b35e30788afb28d8671fb93be44b4526be851fb9d5800fa80
+  data.tar.gz: efa72ded518abf7bec6a360bad11beacde8564d426fb07829c32d1a0e390a7f3
 SHA512:
-  metadata.gz: ebefd2f90219d0dd655a9e7fc21023aa38b26de412e52102bdb6d2014a75f1975c284a417d2f353989e09360c34b56c07e42af89643e99bb3fe990db886a1039
-  data.tar.gz: 2c447976bc3b1dc7a8e9c2ffc695278bd7ec0e44bbad864f5810c16adefb901ec1212145a8d56865e4f7a59eba36b760db71e69addac2b70422f2b8276b53a7f
+  metadata.gz: a3521b7da4cd23cda88c2bde3ccbd5dc39077583f3aef93da259a865df80997f6699cd39006e5abcbd34312b55f9092b59bc148bc0e20a075310afa2ba7dd5d4
+  data.tar.gz: f42cd489ee6c10e279de3db87dcd849d0f12f8476e4535146b302f26308a1b503ae09fba4e75f9aa35dd0e9642fceb0e174ec3871b53740f5365287e62162fd6

data/README.md

@@ -54,6 +54,30 @@ config.jsonrpc_rails.validated_paths = [
 Leave the array empty (default) and the middleware is effectively off.
 Use [/.*\z/] if you really want it on everywhere.
 
+Protocol integrations can reuse the parsing, JSON-RPC validation, typed-object
+conversion, and error handling while adding their own envelope rules:
+
+```ruby
+config.middleware.use JSONRPC_Rails::Middleware::Validator,
+                      [ "/mcp" ],
+                      payload_validator: MyProtocolValidator,
+                      batch_policy: :reject
+```
+
+`payload_validator` may implement `valid?(payload)` or `call(payload)` and receives
+the decoded Hash or Array after generic JSON-RPC validation. Batches are allowed by
+default; `batch_policy: :reject` disables them.
+
+By default, matching POST requests without an `application/json` content type pass
+through untouched. Protocol endpoints that accept only JSON-RPC can reject those
+requests with HTTP 415 instead:
+
+```ruby
+config.middleware.use JSONRPC_Rails::Middleware::Validator,
+                      [ "/rpc" ],
+                      require_json_content_type: true
+```
+
 In your controllers, you can render JSON-RPC responses like so:
 
 ```ruby
@@ -100,8 +124,8 @@ You can override the default `message` or add `data` for either method by provid
 The gem automatically inserts `JSONRPC_Rails::Middleware::Validator` into your application's middleware stack. This middleware performs the following actions for incoming **POST** requests with `Content-Type: application/json`:
 
 1.  **Parses** the JSON body. Returns a JSON-RPC `Parse error (-32700)` if parsing fails.
-2.  **Validates** the structure against the JSON-RPC 2.0 specification (single or batch). It performs strict validation, ensuring `jsonrpc: "2.0"`, a string `method`, optional `params` (array/object), optional `id` (string/number/null), and **no extraneous keys**. Returns a JSON-RPC `Invalid Request (-32600)` error if validation fails. **Note:** For batch requests, if *any* individual request within the batch is structurally invalid, the entire batch is rejected with a single `Invalid Request (-32600)` error.
-3.  **Stores** the validated, parsed payload (the original Ruby Hash or Array) in `request.env[:jsonrpc]` if validation succeeds.
+2.  **Validates** request, notification, and response structures against JSON-RPC 2.0, including single and batch payloads. Extension members are accepted, while conflicting reserved envelope members are rejected. Returns a JSON-RPC `Invalid Request (-32600)` error if validation fails. **Note:** For batch payloads, if *any* message is structurally invalid, the entire batch is rejected with a single `Invalid Request (-32600)` error.
+3.  **Stores** the validated payload as a typed `JSON_RPC::Request`, `JSON_RPC::Notification`, or `JSON_RPC::Response` (or an Array of those objects) in `request.env[:jsonrpc]`.
 4.  **Passes** the request to the next middleware or your controller action.
 
 In your controller action, you can access the validated payload like this:
@@ -184,6 +208,58 @@ class MyApiController < ApplicationController
 end
 ```
 
+## Error Codes
+
+The gem implements the complete JSON-RPC 2.0 error specification. All error codes are defined in `lib/json_rpc/json_rpc_error.rb` and can be used either as numeric codes or symbols:
+
+| Code | Symbol | Name | Description |
+|------|--------|------|-------------|
+| -32700 | `:parse_error` | Parse Error | Invalid JSON was received by the server |
+| -32600 | `:invalid_request` | Invalid Request | The JSON sent is not a valid Request object |
+| -32601 | `:method_not_found` | Method Not Found | The method does not exist / is not available |
+| -32602 | `:invalid_params` | Invalid Params | Invalid method parameter(s) |
+| -32603 | `:internal_error` | Internal Error | Internal JSON-RPC error |
+| -32000 | `:server_error` | Server Error | Implementation-defined server error |
+
+### Usage Examples
+
+```ruby
+# Using numeric codes
+render jsonrpc: {}, error: -32601, id: 1
+
+# Using symbols
+render jsonrpc: {}, error: :method_not_found, id: 1
+
+# Creating error objects
+error = JSON_RPC::JsonRpcError.build(:invalid_params)
+render jsonrpc: JSON_RPC::Response.new(id: 1, error: error)
+```
+
+## JSONRPC Namespace
+
+The gem uses two main namespaces to separate core JSON-RPC functionality from Rails integration:
+
+### JSON_RPC Module (Core Specification)
+
+Contains the core JSON-RPC 2.0 specification objects:
+
+- **`JSON_RPC::Request`** - Represents a JSON-RPC request with method, params, and id
+- **`JSON_RPC::Response`** - Represents a JSON-RPC response with result or error
+- **`JSON_RPC::Notification`** - Represents a JSON-RPC notification (request without id)
+- **`JSON_RPC::JsonRpcError`** - Exception class for JSON-RPC errors with standard error codes
+- **`JSON_RPC::Parser`** - Utility for converting hashes to typed JSON-RPC objects
+
+### JSONRPC_Rails Module (Rails Integration)
+
+Contains Rails-specific integration components:
+
+- **`JSONRPC_Rails::Railtie`** - Rails initialization, middleware setup, and renderer registration
+- **`JSONRPC_Rails::Middleware::Validator`** - Rack middleware for validating JSON-RPC requests
+- **`JSONRPC_Rails::ControllerHelpers`** - Helper methods like `jsonrpc_params` and `jsonrpc_params_batch?`
+- **`JSONRPC_Rails::VERSION`** - Current gem version
+
+This separation ensures clean architecture where core JSON-RPC logic is independent of Rails, while Rails-specific features are properly isolated.
+
 ## Testing
 
 A dummy Rails application is included within the gem (located in `test/dummy`) to facilitate testing. You can run the tests from the **project root directory** by executing:

data/lib/jsonrpc_rails/middleware/validator.rb

@@ -2,6 +2,8 @@
 
 require "json"
 require "active_support/json"
+require "rack/media_type"
+require "stringio"
 
 module JSONRPC_Rails
   module Middleware
@@ -14,54 +16,75 @@ module JSONRPC_Rails
     # IDs or empty batches no longer raise before we can return a proper
     # -32600 “Invalid Request”.
     class Validator
-      CONTENT_TYPE     = "application/json"
-      ENV_PAYLOAD_KEY  = :jsonrpc
+      CONTENT_TYPE = "application/json"
+      ENV_PAYLOAD_KEY = :jsonrpc
+      BATCH_POLICIES = %i[allow reject].freeze
+      RESERVED_MEMBERS = %w[jsonrpc method params id result error].freeze
 
       # @param app [#call]
       # @param paths [Array<String, Regexp, Proc>] paths to validate
-      def initialize(app, paths = nil)
-        @app   = app
+      # @param payload_validator [#valid?, #call, nil] optional protocol validator
+      # @param batch_policy [Symbol] either :allow or :reject
+      # @param require_json_content_type [Boolean] reject matching POST requests
+      #   that do not use application/json instead of passing them downstream
+      def initialize(app, paths = nil, payload_validator: nil, batch_policy: :allow,
+                     require_json_content_type: false)
+        unless BATCH_POLICIES.include?(batch_policy)
+          raise ArgumentError, "batch_policy must be one of: #{BATCH_POLICIES.join(", ")}"
+        end
+
+        @app = app
         @paths = Array(paths || Rails.configuration.jsonrpc_rails.validated_paths)
+        @payload_validator = payload_validator
+        @batch_policy = batch_policy
+        @require_json_content_type = require_json_content_type
       end
 
       # Rack entry point
       def call(env)
         return @app.call(env) unless validate_path?(env["PATH_INFO"])
-        return @app.call(env) unless env["REQUEST_METHOD"] == "POST" &&
-                                     env["CONTENT_TYPE"]&.start_with?(CONTENT_TYPE)
+        return @app.call(env) unless env["REQUEST_METHOD"] == "POST"
 
-        body = env["rack.input"].read
-        env["rack.input"].rewind
+        unless json_content_type?(env["CONTENT_TYPE"])
+          return @app.call(env) unless @require_json_content_type
 
-        raw_payload = parse_json(body)
+          return jsonrpc_error_response(
+            :server_error,
+            status: 415,
+            message: "Unsupported Media Type: Content-Type must be application/json"
+          )
+        end
 
-        unless raw_payload.is_a?(Hash) || raw_payload.is_a?(Array)
-          id = extract_id_from_raw_payload(raw_payload)
-          return jsonrpc_error_response(:invalid_request, id: id)
+        body = env["rack.input"].read
+        # Replace consumed input with fresh StringIO for downstream middleware
+        # This is Rack 3.0+ compatible and works with all input stream types
+        env["rack.input"] = StringIO.new(body)
+
+        begin
+          raw_payload = ActiveSupport::JSON.decode(body)
+        rescue ActiveSupport::JSON.parse_error
+          return jsonrpc_error_response(:parse_error)
         end
 
-        validity, = if raw_payload.is_a?(Array)
-                      validate_batch(raw_payload)
-        else
-                      validate_single(raw_payload)
+        unless raw_payload.is_a?(Hash) || raw_payload.is_a?(Array)
+          return jsonrpc_error_response(:invalid_request)
         end
-        return validity unless validity == :valid
 
-        env[ENV_PAYLOAD_KEY] = convert_to_objects(raw_payload)
+        return invalid_request_response(raw_payload) unless valid_batch_policy?(raw_payload)
+        return invalid_request_response(raw_payload) unless valid_payload_structure?(raw_payload)
+        return invalid_request_response(raw_payload) unless valid_protocol_payload?(raw_payload)
+
+        begin
+          env[ENV_PAYLOAD_KEY] = convert_to_objects(raw_payload)
+        rescue JSON_RPC::JsonRpcError, ArgumentError, TypeError
+          return invalid_request_response(raw_payload)
+        end
 
         @app.call(env)
       end
 
       private
 
-      def parse_json(body)
-        return nil if body.nil? || body.strip.empty?
-
-        ActiveSupport::JSON.decode(body)
-      rescue ActiveSupport::JSON.parse_error
-        nil
-      end
-
       def validate_path?(path)
         return false if @paths.empty?
 
@@ -75,35 +98,86 @@ module JSONRPC_Rails
         end
       end
 
+      def json_content_type?(content_type)
+        media_type = Rack::MediaType.type(content_type)&.strip
+        media_type&.casecmp?(CONTENT_TYPE) || false
+      end
+
       # -------------------- structure validation --------------------------------
 
-      def validate_single_structure(obj)
+      def valid_payload_structure?(payload)
+        if payload.is_a?(Array)
+          !payload.empty? && payload.all? { |message| valid_message_structure?(message) }
+        else
+          valid_message_structure?(payload)
+        end
+      end
+
+      def valid_message_structure?(obj)
         return false unless obj.is_a?(Hash)
         return false unless obj["jsonrpc"] == "2.0"
-        return false unless obj["method"].is_a?(String)
 
-        return false if obj.key?("params") && !obj["params"].is_a?(Array) && !obj["params"].is_a?(Hash)
+        if obj.key?("method")
+          valid_call_structure?(obj)
+        elsif obj.key?("result") || obj.key?("error")
+          valid_response_structure?(obj)
+        else
+          false
+        end
+      end
 
-        return false if obj.key?("id") && ![ String, Integer, NilClass ].include?(obj["id"].class)
+      def valid_call_structure?(obj)
+        return false unless obj["method"].is_a?(String)
+        return false unless valid_params?(obj)
+        return false if obj.key?("id") && !valid_id?(obj["id"])
 
-        allowed = %w[jsonrpc method params id]
-        (obj.keys - allowed).empty?
+        no_conflicting_members?(obj, %w[jsonrpc method params id])
       end
 
-      def validate_single(obj)
-        if validate_single_structure(obj)
-          [ :valid, obj["id"] ]
+      def valid_response_structure?(obj)
+        return false unless obj.key?("id") && valid_id?(obj["id"])
+        return false if obj.key?("result") == obj.key?("error")
+
+        if obj.key?("result")
+          no_conflicting_members?(obj, %w[jsonrpc id result])
         else
-          id = obj.is_a?(Hash) ? obj["id"] : nil
-          [ jsonrpc_error_response(:invalid_request, id: id), id ]
+          valid_error_structure?(obj["error"]) &&
+            no_conflicting_members?(obj, %w[jsonrpc id error])
         end
       end
 
-      def validate_batch(batch)
-        return [ jsonrpc_error_response(:invalid_request), nil ] unless batch.is_a?(Array) && !batch.empty?
+      def valid_error_structure?(error)
+        return false unless error.is_a?(Hash)
+        return false unless error["code"].is_a?(Integer)
+        return false unless error["message"].is_a?(String)
+
+        true
+      end
+
+      def no_conflicting_members?(obj, allowed_members)
+        (obj.keys & (RESERVED_MEMBERS - allowed_members)).empty?
+      end
+
+      def valid_params?(obj)
+        !obj.key?("params") || obj["params"].is_a?(Array) || obj["params"].is_a?(Hash)
+      end
+
+      def valid_id?(id)
+        id.is_a?(String) || id.is_a?(Numeric) || id.nil?
+      end
+
+      def valid_batch_policy?(payload)
+        !payload.is_a?(Array) || @batch_policy == :allow
+      end
+
+      def valid_protocol_payload?(payload)
+        return true unless @payload_validator
 
-        invalid = batch.find { |el| !validate_single_structure(el) }
-        invalid ? [ jsonrpc_error_response(:invalid_request), nil ] : [ :valid, nil ]
+        if @payload_validator.respond_to?(:valid?)
+          @payload_validator.valid?(payload)
+        else
+          @payload_validator.call(payload)
+        end
       end
 
       # ------------------ conversion to typed objects ---------------------------
@@ -123,21 +197,26 @@ module JSONRPC_Rails
 
       # @param error_sym [Symbol]
       # @param status    [Integer]
-      # @param id       [String, Integer, nil]
+      # @param id       [String, Numeric, nil]
+      # @param message  [String, nil]
       # @return [Array] Rack triplet
-      def jsonrpc_error_response(error_sym, status: 400, id: nil)
-        error_obj = JSON_RPC::JsonRpcError.build(error_sym)
+      def jsonrpc_error_response(error_sym, status: 400, id: nil, message: nil)
+        error_obj = JSON_RPC::JsonRpcError.build(error_sym, message: message)
         payload   = JSON_RPC::Response.new(id: id, error: error_obj).to_json
 
-        [ status, { "Content-Type" => CONTENT_TYPE }, [ payload ] ]
+        [ status, { "content-type" => CONTENT_TYPE }, [ payload ] ]
+      end
+
+      def invalid_request_response(raw_payload)
+        jsonrpc_error_response(:invalid_request, id: extract_id_from_raw_payload(raw_payload))
       end
 
       # Extract ID from raw payload if possible
       def extract_id_from_raw_payload(raw)
         return nil unless raw.is_a?(Hash)
-        raw["id"]
-      rescue
-        nil
+
+        id = raw["id"]
+        id if valid_id?(id)
       end
     end
   end

data/lib/jsonrpc_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONRPC_Rails
-  VERSION = "0.5.3"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonrpc-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -67,7 +67,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A Railtie-based gem that brings JSON-RPC 2.0 support to your Rails application.
 test_files: []