clamo 0.9.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1a61a818aab987fe6d621d2f3bf642fd7993044933b0b258f2a515d896bb7a5
-  data.tar.gz: b68b313c737400cda3d739902d1d2d498a2d28344cf9cc0afc5c8b481850bcb5
+  metadata.gz: 7596405122290bf9bce3c04760bbb5e03eef24f8e5e6b3c6e99105c8faa7d14e
+  data.tar.gz: 219e2f1f54ffd99c03dcde0c18508d24625904daa2aa65f5c7c1aabbfacee11c
 SHA512:
-  metadata.gz: b2a1ac30f5f40c035d683d54a36c0164ea24dc56b8ca9af694de499862732faf22cc572029e6bfac1f05413c4d4cf56a737b9b29af96b870fcf23eee5305e756
-  data.tar.gz: ccb5a26f16ab0492e3d77e27eeed648e26b6fdcb9bda59c37a264cc3e419ba45a77bede078863e9ea18dface1f9f5c0be13a1629e6b37d4a8fb2da2f8cc291b4
+  metadata.gz: 7d6a2c1407df2fc1427a7c95500d07f4873660c2322bcd4ae1a4f642550e89d6a723e7854f2126404f985446432a8e59e2690873d28ff25b218e1f01e260898a
+  data.tar.gz: eb941c6f05333536695f9f3d6531de593b592653b17c6fb5a10e18c5cca693c6cb2fe3e922a25f17c5a1bf3d90fae8b518674b14fc78b7b2926deff1f3d7223b

data/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.12.0] - 2026-03-14
+
+### Changed
+
+- Extracted `error_for` helper to centralize notification-aware error responses, replacing scattered `request.key?("id") ? error : nil` pattern.
+- Split `validate_request_structure` into envelope validation and `validate_params_type`, making the single-request pipeline a clear 5-stage chain.
+- Removed `method_not_found_error` and `arity_mismatch_error` one-liner wrappers (replaced by `error_for` calls).
+
+### Added
+
+- `server_error_response` test helper, completing the error response helper set.
+- Test for arity-mismatch notification returning nil.
+
+## [0.11.0] - 2026-03-14
+
+### Changed
+
+- **Breaking:** `dispatch` is now the canonical name for `parsed_dispatch_to_object`. The old name remains as a deprecated alias.
+- **Breaking:** `dispatch_json` is now the canonical name for `unparsed_dispatch_to_object`. The old name remains as a deprecated alias.
+- **Breaking:** `handle_json` is now the canonical name for `handle`. The old name remains as a deprecated alias.
+
+## [0.10.0] - 2026-03-14
+
+### Removed
+
+- **Breaking:** `timeout` configuration and `Timeout.timeout` wrapping — Ruby's `Timeout.timeout` is unsafe (can fire during `ensure`, IO, or lock acquisition). Callers who need timeouts should wrap dispatch externally.
+- **Breaking:** `before_dispatch` and `after_dispatch` hooks — callers can wrap `dispatch` calls directly for the same effect with less coupling.
+- `parallel` as a runtime dependency — it is now loaded on demand. Batch requests fall back to sequential `map` when the gem is not installed.
+
+### Added
+
+- **Arity validation** — parameter count and keyword names are checked against the Ruby method signature before dispatch. Mismatches return `-32602 Invalid params` instead of the previous `-32603 Internal error`.
+- `Clamo::Server.dispatch` — alias for `parsed_dispatch_to_object`.
+- `Clamo::Server.dispatch_json` — alias for `unparsed_dispatch_to_object`.
+- Concurrency tests for thread-safe dispatch.
+
+### Changed
+
+- `Config` simplified to `Data.define(:on_error)` (was `Data.define(:timeout, :on_error, :before_dispatch, :after_dispatch)`).
+- `parsed_dispatch_to_object` signature reduced to `(request:, object:, on_error:, **opts)`.
+
 ## [0.9.0] - 2026-03-14
 
 ### Changed

data/README.md

@@ -28,30 +28,32 @@ end
 
 # JSON string in, JSON string out — the primary entry point for HTTP/socket integrations.
 # Returns nil for notifications (no response expected).
-json_response = Clamo::Server.handle(
+json_response = Clamo::Server.handle_json(
   request: '{"jsonrpc": "2.0", "method": "add", "params": [1, 2], "id": 1}',
   object: MyService
 )
 # => '{"jsonrpc":"2.0","result":3,"id":1}'
 ```
 
-If you need the parsed hash instead of a JSON string, use the lower-level methods:
+If you need the parsed hash instead of a JSON string, use the lower-level methods directly or via their shorter aliases:
 
 ```ruby
 # From a JSON string
-response = Clamo::Server.unparsed_dispatch_to_object(
+response = Clamo::Server.dispatch_json(
   request: '{"jsonrpc": "2.0", "method": "add", "params": [1, 2], "id": 1}',
   object: MyService
 )
 # => {"jsonrpc" => "2.0", "result" => 3, "id" => 1}
 
 # From a pre-parsed hash
-response = Clamo::Server.parsed_dispatch_to_object(
+response = Clamo::Server.dispatch(
   request: { "jsonrpc" => "2.0", "method" => "add", "params" => [1, 2], "id" => 1 },
   object: MyService
 )
 ```
 
+The longer names `parsed_dispatch_to_object`, `unparsed_dispatch_to_object`, and `handle` still work as deprecated aliases.
+
 ### Handling Different Parameter Types
 
 Clamo supports both positional (array) and named (object/hash) parameters:
@@ -76,7 +78,7 @@ batch_request = <<~JSON
 ]
 JSON
 
-batch_response = Clamo::Server.unparsed_dispatch_to_object(
+batch_response = Clamo::Server.dispatch_json(
   request: batch_request,
   object: MyService
 )
@@ -91,7 +93,7 @@ Notifications are requests without an ID field. They don't produce a response:
 
 ```ruby
 notification = '{"jsonrpc": "2.0", "method": "add", "params": [1, 2]}'
-response = Clamo::Server.unparsed_dispatch_to_object(
+response = Clamo::Server.dispatch_json(
   request: notification,
   object: MyService
 )
@@ -124,24 +126,17 @@ Clamo follows the JSON-RPC 2.0 specification for error handling:
 | -32700     | Parse error      | Invalid JSON was received                            |
 | -32600     | Invalid request  | The JSON sent is not a valid Request object          |
 | -32601     | Method not found | The method does not exist / is not available         |
-| -32602     | Invalid params   | Invalid method parameter(s)                          |
+| -32602     | Invalid params   | Invalid method parameter(s) or arity mismatch        |
 | -32603     | Internal error   | Internal JSON-RPC error                              |
-| -32000     | Server error     | Reserved for implementation-defined server errors    |
-
-## Configuration
-
-### Timeout
+| -32000     | Server error     | Exception raised by dispatched method                |
 
-Every method dispatch is wrapped in a timeout. The default is 30 seconds. Timed-out requests return a `-32000 Server error` response.
+Parameter arity is validated before dispatch. If the number of positional arguments or keyword arguments doesn't match the Ruby method signature, a `-32602 Invalid params` error is returned.
 
-```ruby
-Clamo::Server.timeout = 10  # seconds
-Clamo::Server.timeout = nil # disable timeout
-```
+## Configuration
 
 ### Error Callback
 
-Errors during dispatch are reported through `on_error`. Notifications are silent by default (no response is sent); requests return a generic `-32603 Internal error` without leaking exception details. Use `on_error` to capture the full exception for logging:
+Errors during dispatch are reported through `on_error`, which is called for both requests and notifications. Notifications are silent by default (no response is sent to the client, but `on_error` still fires); requests return a generic `-32000 Server error` without leaking exception details. Use `on_error` to capture the full exception for logging:
 
 ```ruby
 Clamo::Server.on_error = ->(exception, method, params) {
@@ -149,32 +144,15 @@ Clamo::Server.on_error = ->(exception, method, params) {
 }
 ```
 
-### Dispatch Hooks
-
-`before_dispatch` and `after_dispatch` run around every method call (requests and notifications). Raise in `before_dispatch` to halt execution:
-
-```ruby
-Clamo::Server.before_dispatch = ->(method, params) {
-  raise "unauthorized" unless allowed?(method)
-}
-
-Clamo::Server.after_dispatch = ->(method, params, result) {
-  Rails.logger.info("#{method} completed")
-}
-```
-
 ### Per-Call Configuration
 
-All configuration options can be overridden per-call. Module-level settings serve as defaults:
+Configuration can be overridden per-call. Module-level settings serve as defaults:
 
 ```ruby
-Clamo::Server.handle(
+Clamo::Server.handle_json(
   request: body,
   object: MyService,
-  timeout: 5,
-  on_error: ->(e, method, params) { MyLogger.error(e) },
-  before_dispatch: ->(method, params) { authorize!(method) },
-  after_dispatch: ->(method, params, result) { track(method) }
+  on_error: ->(e, method, params) { MyLogger.error(e) }
 )
 ```
 
@@ -184,10 +162,10 @@ Per-call config is snapshotted at the start of each dispatch, so concurrent muta
 
 ### Parallel Processing
 
-Batch requests are processed in parallel using the [parallel](https://github.com/grosser/parallel) gem. You can pass options to `Parallel.map`:
+Batch requests are processed in parallel when the [parallel](https://github.com/grosser/parallel) gem is available. If `parallel` is not installed, batches fall back to sequential processing. You can pass options to `Parallel.map`:
 
 ```ruby
-Clamo::Server.parsed_dispatch_to_object(
+Clamo::Server.dispatch(
   request: batch_request,
   object: MyService,
   in_processes: 4  # Parallel processing option

data/lib/clamo/jsonrpc.rb

@@ -14,22 +14,6 @@ module Clamo
     end
 
     class << self
-      def proper_params_if_any?(request)
-        if key_indifferent?(request, "params")
-          params = fetch_indifferent(request, "params")
-          params.is_a?(Array) || params.is_a?(Hash)
-        else
-          true
-        end
-      end
-
-      def valid_request?(request)
-        request.is_a?(Hash) &&
-          proper_pragma?(request) &&
-          proper_method?(request) &&
-          proper_id_if_any?(request)
-      end
-
       def build_request(**opts)
         raise ArgumentError, "method is required" unless opts.key?(:method)
 
@@ -77,6 +61,24 @@ module Clamo
         )
       end
 
+      # Used internally by Clamo::Server — not part of the public API.
+      def proper_params_if_any?(request)
+        if key_indifferent?(request, "params")
+          params = fetch_indifferent(request, "params")
+          params.is_a?(Array) || params.is_a?(Hash)
+        else
+          true
+        end
+      end
+
+      # Used internally by Clamo::Server — not part of the public API.
+      def valid_request?(request)
+        request.is_a?(Hash) &&
+          proper_pragma?(request) &&
+          proper_method?(request) &&
+          proper_id_if_any?(request)
+      end
+
       private
 
       def proper_pragma?(request)

data/lib/clamo/server.rb

@@ -1,40 +1,30 @@
 # frozen_string_literal: true
 
 require "json"
-require "parallel"
-require "timeout"
 
 module Clamo
   module Server
-    Config = Data.define(:timeout, :on_error, :before_dispatch, :after_dispatch)
+    Config = Data.define(:on_error)
 
     class << self
-      # Module-level defaults. These are snapshotted at the start of each
-      # dispatch call, so mutations mid-request do not affect in-flight work.
-      # All four can be overridden per-call via keyword arguments.
-      attr_accessor :on_error, :before_dispatch, :after_dispatch
-      attr_writer :timeout
-
-      def timeout
-        return @timeout if defined?(@timeout)
-
-        30
-      end
+      attr_accessor :on_error
 
       # JSON string in, JSON string out. Full round-trip for HTTP/socket integrations.
       #
-      #   Clamo::Server.handle(request: body, object: MyService)
+      #   Clamo::Server.handle_json(request: body, object: MyService)
       #
-      def handle(request:, object:, **)
-        response = unparsed_dispatch_to_object(request: request, object: object, **)
+      def handle_json(request:, object:, **)
+        response = dispatch_json(request: request, object: object, **)
         response&.to_json
       end
 
-      # Clamo::Server.unparsed_dispatch_to_object(
-      #   request:  request_body,
-      #   object:   MyModule
-      # )
-      def unparsed_dispatch_to_object(request:, object:, **)
+      alias handle handle_json
+
+      # JSON string in, parsed response out.
+      #
+      #   Clamo::Server.dispatch_json(request: json_string, object: MyModule)
+      #
+      def dispatch_json(request:, object:, **)
         raise ArgumentError, "object is required" unless object
 
         begin
@@ -43,26 +33,30 @@ module Clamo
           return JSONRPC.build_error_response_parse_error
         end
 
-        parsed_dispatch_to_object(request: parsed, object: object, **)
+        dispatch(request: parsed, object: object, **)
       end
 
-      def parsed_dispatch_to_object(request:, object:,
-                                    timeout: self.timeout,
-                                    on_error: self.on_error,
-                                    before_dispatch: self.before_dispatch,
-                                    after_dispatch: self.after_dispatch,
-                                    **opts)
+      alias unparsed_dispatch_to_object dispatch_json
+
+      # Parsed hash in, parsed response out.
+      #
+      #   Clamo::Server.dispatch(request: hash_or_array, object: MyModule)
+      #
+      def dispatch(request:, object:,
+                   on_error: self.on_error,
+                   **opts)
         raise ArgumentError, "object is required" unless object
 
         request = normalize_request_keys(request)
-        config = Config.new(timeout: timeout, on_error: on_error,
-                            before_dispatch: before_dispatch, after_dispatch: after_dispatch)
+        config = Config.new(on_error: on_error)
 
         response_for(request: request, object: object, config: config, **opts) do |method, params|
           dispatch_to_ruby(object: object, method: method, params: params)
         end
       end
 
+      alias parsed_dispatch_to_object dispatch
+
       private
 
       def normalize_request_keys(request)
@@ -109,8 +103,15 @@ module Clamo
         error = validate_request_structure(request)
         return error if error
 
+        error = validate_params_type(request)
+        return error if error
+
         unless method_known?(object: object, method: request["method"])
-          return request.key?("id") ? method_not_found_error(request) : nil
+          return error_for(request, JSONRPC::ProtocolErrors::METHOD_NOT_FOUND)
+        end
+
+        unless params_match_arity?(object: object, method: request["method"], params: request["params"])
+          return error_for(request, JSONRPC::ProtocolErrors::INVALID_PARAMS)
         end
 
         return dispatch_notification(request, block, config) unless request.key?("id")
@@ -128,38 +129,44 @@ module Clamo
           return result ? [result] : nil
         end
 
-        result = Parallel.map(request, **opts) do |item|
+        result = map_batch(request, **opts) do |item|
           response_for_single_request(request: item, object: object, block: block, config: config)
         end.compact
         result.empty? ? nil : result
       end
 
-      def validate_request_structure(request)
-        unless JSONRPC.valid_request?(request)
-          return JSONRPC.build_error_response_from(
-            id: request.is_a?(Hash) ? request["id"] : nil,
-            descriptor: JSONRPC::ProtocolErrors::INVALID_REQUEST
-          )
-        end
+      def map_batch(items, **, &)
+        require "parallel"
+        Parallel.map(items, **, &)
+      rescue LoadError
+        items.map(&)
+      end
 
-        return if JSONRPC.proper_params_if_any?(request)
+      def error_for(request, descriptor)
+        return unless request.key?("id")
 
-        # Notifications must never produce a response, even for invalid params
-        return nil unless request.key?("id")
+        JSONRPC.build_error_response_from(id: request["id"], descriptor: descriptor)
+      end
 
-        JSONRPC.build_error_response_from(id: request["id"], descriptor: JSONRPC::ProtocolErrors::INVALID_PARAMS)
+      def validate_request_structure(request)
+        return if JSONRPC.valid_request?(request)
+
+        JSONRPC.build_error_response_from(
+          id: request.is_a?(Hash) ? request["id"] : nil,
+          descriptor: JSONRPC::ProtocolErrors::INVALID_REQUEST
+        )
       end
 
-      def method_not_found_error(request)
-        JSONRPC.build_error_response_from(id: request["id"], descriptor: JSONRPC::ProtocolErrors::METHOD_NOT_FOUND)
+      def validate_params_type(request)
+        return if JSONRPC.proper_params_if_any?(request)
+
+        error_for(request, JSONRPC::ProtocolErrors::INVALID_PARAMS)
       end
 
       def dispatch_notification(request, block, config)
         method = request["method"]
         params = request["params"]
-        config.before_dispatch&.call(method, params)
-        result = with_timeout(config.timeout) { block.yield(method, params) }
-        config.after_dispatch&.call(method, params, result)
+        block.yield(method, params)
         nil
       rescue StandardError => e
         config.on_error&.call(e, method, params)
@@ -169,35 +176,59 @@ module Clamo
       def dispatch_request(request, block, config)
         method = request["method"]
         params = request["params"]
-        config.before_dispatch&.call(method, params)
-        result = with_timeout(config.timeout) { block.yield(method, params) }
-        config.after_dispatch&.call(method, params, result)
+        result = block.yield(method, params)
         JSONRPC.build_result_response(id: request["id"], result: result)
-      rescue Timeout::Error
-        timeout_error(request)
       rescue StandardError => e
         config.on_error&.call(e, method, params)
-        JSONRPC.build_error_response_from(id: request["id"], descriptor: JSONRPC::ProtocolErrors::INTERNAL_ERROR)
+        JSONRPC.build_error_response_from(id: request["id"], descriptor: JSONRPC::ProtocolErrors::SERVER_ERROR)
       end
 
-      def timeout_error(request)
-        JSONRPC.build_error_response(
-          id: request["id"],
-          error: {
-            code: JSONRPC::ProtocolErrors::SERVER_ERROR.code,
-            message: JSONRPC::ProtocolErrors::SERVER_ERROR.message,
-            data: "Request timed out"
-          }
-        )
-      end
+      def params_match_arity?(object:, method:, params:)
+        ruby_method = resolve_method(object, method)
+        return true unless ruby_method
 
-      def with_timeout(seconds, &block)
-        if seconds
-          Timeout.timeout(seconds, &block)
-        else
-          block.call
+        parameters = ruby_method.parameters
+
+        case params
+        when Array then array_params_match?(parameters, params.size)
+        when Hash  then hash_params_match?(parameters, params.keys.map(&:to_sym))
+        when nil   then nil_params_match?(parameters)
+        else true
         end
       end
+
+      def resolve_method(object, method_name)
+        object.method(method_name.to_sym)
+      rescue NameError
+        nil
+      end
+
+      def array_params_match?(parameters, count)
+        by_type = parameters.group_by(&:first)
+
+        return false if by_type.key?(:keyreq)
+        return true if by_type.key?(:rest)
+
+        required = by_type.fetch(:req, []).size
+        count.between?(required, required + by_type.fetch(:opt, []).size)
+      end
+
+      def hash_params_match?(parameters, keys)
+        by_type = parameters.group_by(&:first)
+        required = by_type.fetch(:keyreq, []).map(&:last)
+        allowed = required + by_type.fetch(:key, []).map(&:last)
+
+        return false if by_type.key?(:req)
+        return false unless (required - keys).empty?
+
+        by_type.key?(:keyrest) || (keys - allowed).empty?
+      end
+
+      def nil_params_match?(parameters)
+        by_type = parameters.group_by(&:first)
+
+        by_type.fetch(:req, []).empty? && !by_type.key?(:keyreq)
+      end
     end
   end
 end

data/lib/clamo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clamo
-  VERSION = "0.9.0"
+  VERSION = "0.12.0"
 end

metadata

@@ -1,28 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clamo
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Andriy Tyurnikov
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: parallel
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.27'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.27'
+dependencies: []
 description: Minimal, spec-compliant JSON-RPC 2.0 server for Ruby with request validation,
   method dispatch, batch processing, and notification support.
 email: