jsonrpc-rails 0.5.4 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c170f3b4c1b8b5d8903fc6202f317d98340c0939dae84117c062009f4128de3
-  data.tar.gz: 047dfecbe033df5e49a41a03d4c471452953358cb41bc95c0e2add3b9666ff81
+  metadata.gz: e098dc20d9c1c05b35e30788afb28d8671fb93be44b4526be851fb9d5800fa80
+  data.tar.gz: efa72ded518abf7bec6a360bad11beacde8564d426fb07829c32d1a0e390a7f3
 SHA512:
-  metadata.gz: 2346088ba624f426d7f26df3f1d3d46faec883d2b45ef929ccd53e4bb1085132e8c0d2491b0f322ade4592ef0ffc182b0e39f15c795a490c7f0e4d2a2a646de1
-  data.tar.gz: c76d9df6e6b1e5c7eab1498ac9cf4a544f00c796cab13ae487ff302ac77a500ed488bd920ce9f010391de96430ee888fa68d3388f898646ebd82045e9d919dfd
+  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:

data/lib/jsonrpc_rails/middleware/validator.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "active_support/json"
+require "rack/media_type"
 require "stringio"
 
 module JSONRPC_Rails
@@ -15,56 +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"
+
+        unless json_content_type?(env["CONTENT_TYPE"])
+          return @app.call(env) unless @require_json_content_type
+
+          return jsonrpc_error_response(
+            :server_error,
+            status: 415,
+            message: "Unsupported Media Type: Content-Type must be application/json"
+          )
+        end
 
         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)
 
-        raw_payload = parse_json(body)
+        begin
+          raw_payload = ActiveSupport::JSON.decode(body)
+        rescue ActiveSupport::JSON.parse_error
+          return jsonrpc_error_response(:parse_error)
+        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)
+          return jsonrpc_error_response(:invalid_request)
         end
 
-        validity, = if raw_payload.is_a?(Array)
-                      validate_batch(raw_payload)
-        else
-                      validate_single(raw_payload)
-        end
-        return validity unless validity == :valid
+        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)
 
-        env[ENV_PAYLOAD_KEY] = convert_to_objects(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?
 
@@ -78,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 ---------------------------
@@ -126,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 ] ]
       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.4"
+  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.4
+  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: []