clamo 0.9.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1a61a818aab987fe6d621d2f3bf642fd7993044933b0b258f2a515d896bb7a5
-  data.tar.gz: b68b313c737400cda3d739902d1d2d498a2d28344cf9cc0afc5c8b481850bcb5
+  metadata.gz: fb802891a70c42e2bb89446fd258fc7e9114ff29f64c4cc6051f819332172307
+  data.tar.gz: 10af0f3deb9d61fd068ebd9a1c6bdbc9f93aca02b8491b8c1856032338c5a56d
 SHA512:
-  metadata.gz: b2a1ac30f5f40c035d683d54a36c0164ea24dc56b8ca9af694de499862732faf22cc572029e6bfac1f05413c4d4cf56a737b9b29af96b870fcf23eee5305e756
-  data.tar.gz: ccb5a26f16ab0492e3d77e27eeed648e26b6fdcb9bda59c37a264cc3e419ba45a77bede078863e9ea18dface1f9f5c0be13a1629e6b37d4a8fb2da2f8cc291b4
+  metadata.gz: bdbb35a70e40adad88ef1c19b0247e11512d6d51a50fcba039cb74699e60ad7088b42f0ca8d7297c19d5e075100602c5ee79d1dc28f0604a6f0160c440a0db6f
+  data.tar.gz: b8a2d1c0002003468c4d4e3bbc03348d36b56e9ed13396c07653640c00cd3e924a6df45a3951a1d8c5a235bd189fd38d66418cf405f2786db3338570e8bf790a

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

@@ -1,7 +1,47 @@
 # Clamo
 
-A Ruby implementation of [JSON-RPC 2.0](https://www.jsonrpc.org/specification) designed for simplicity and compliance with the specification.
+[![CI](https://github.com/rubakas/clamo/actions/workflows/main.yml/badge.svg)](https://github.com/rubakas/clamo/actions/workflows/main.yml)
+[![Gem Version](https://badge.fury.io/rb/clamo.svg)](https://badge.fury.io/rb/clamo)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-ruby.svg)](https://www.ruby-lang.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![JSON-RPC 2.0](https://img.shields.io/badge/JSON--RPC-2.0-orange.svg)](https://www.jsonrpc.org/specification)
+
+A Ruby implementation of [JSON-RPC 2.0](https://www.jsonrpc.org/specification) designed for simplicity and compliance with the specification. Expose any Ruby module or class as a JSON-RPC service with minimal effort — just point Clamo at your object and its public methods become callable.
+
+JSON-RPC 2.0 is the transport protocol behind [MCP](https://modelcontextprotocol.io/) and [LSP](https://microsoft.github.io/language-server-protocol/) — Clamo makes it easy to build spec-compliant services in Ruby.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Usage](#basic-usage)
+  - [Batch Requests](#batch-requests)
+  - [Notifications](#notifications)
+- [Error Handling](#error-handling)
+- [Configuration](#configuration)
+  - [Error Callback](#error-callback)
+  - [Per-Call Configuration](#per-call-configuration)
+- [Advanced Features](#advanced-features)
+  - [Parallel Processing](#parallel-processing)
+  - [Building JSON-RPC Requests](#building-json-rpc-requests)
+- [Roadmap](#roadmap)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+Add to your Gemfile:
 
+```ruby
+gem "clamo"
+```
+
+Or install directly:
+
+```
+gem install clamo
+```
 
 ## Usage
 
@@ -28,41 +68,33 @@ 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
 )
 ```
 
-### Handling Different Parameter Types
-
-Clamo supports both positional (array) and named (object/hash) parameters:
+The longer names `parsed_dispatch_to_object`, `unparsed_dispatch_to_object`, and `handle` still work as deprecated aliases.
 
-```ruby
-# Positional parameters
-request = '{"jsonrpc": "2.0", "method": "add", "params": [1, 2], "id": 1}'
-
-# Named parameters
-request = '{"jsonrpc": "2.0", "method": "subtract", "params": {"a": 5, "b": 3}, "id": 2}'
-```
+Both positional (`[1, 2]`) and named (`{"a": 5, "b": 3}`) parameters are supported — they map to positional and keyword arguments on the Ruby method respectively.
 
 ### Batch Requests
 
@@ -76,7 +108,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 +123,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
 )
@@ -100,21 +132,6 @@ puts response
 # => nil
 ```
 
-### Building JSON-RPC Requests
-
-Clamo provides utilities for building JSON-RPC requests:
-
-```ruby
-request = Clamo::JSONRPC.build_request(
-  method: "add",
-  params: [1, 2],
-  id: 1
-)
-
-puts request
-# => {"jsonrpc" => "2.0", "method" => "add", "params" => [1, 2], "id" => 1}
-```
-
 ## Error Handling
 
 Clamo follows the JSON-RPC 2.0 specification for error handling:
@@ -124,24 +141,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 +159,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,16 +177,48 @@ 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
 )
 ```
 
+### Building JSON-RPC Requests
+
+Clamo provides utilities for building JSON-RPC requests:
+
+```ruby
+request = Clamo::JSONRPC.build_request(
+  method: "add",
+  params: [1, 2],
+  id: 1
+)
+
+puts request
+# => {"jsonrpc" => "2.0", "method" => "add", "params" => [1, 2], "id" => 1}
+```
+
+## Roadmap
+
+- [x] Per-call configuration
+- [ ] Method metadata caching
+- [ ] Method allowlists/denylists
+- [ ] Observability and logging
+- [ ] Profiling
+- [ ] Hooks
+- [ ] Rack helpers and framework helpers (Rails)
+- [ ] Autodoc (Markdown?)
+- [ ] Error data builder
+- [ ] Schemas
+- [ ] Method auto-prefixing (namespace to prefix)
+- [ ] Multiple objects (namespace fusion)
+- [ ] Context injection
+- [ ] More examples
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/clamo/jsonrpc.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 module Clamo
+  # Utilities for building and validating JSON-RPC 2.0 messages.
   module JSONRPC
+    # Standard JSON-RPC 2.0 error codes and messages.
     module ProtocolErrors
+      # Immutable descriptor pairing an error code with its message.
       ErrorDescriptor = Data.define(:code, :message)
 
       PARSE_ERROR       = ErrorDescriptor.new(code: -32_700, message: "Parse error")
@@ -14,22 +17,13 @@ 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
-
+      # Builds a JSON-RPC 2.0 request Hash.
+      #
+      #   Clamo::JSONRPC.build_request(method: "add", params: [1, 2], id: 1)
+      #   # => {"jsonrpc"=>"2.0", "method"=>"add", "params"=>[1, 2], "id"=>1}
+      #
+      # +method+ is required. +params+ (Array or Hash) and +id+ are optional.
+      # Omitting +id+ produces a notification.
       def build_request(**opts)
         raise ArgumentError, "method is required" unless opts.key?(:method)
 
@@ -40,10 +34,13 @@ module Clamo
           .then { |r| opts.key?(:id) ? r.merge("id" => opts[:id]) : r }
       end
 
+      # Builds a successful JSON-RPC 2.0 response Hash.
       def build_result_response(id:, result:)
         { "jsonrpc" => "2.0", "result" => result, "id" => id }
       end
 
+      # Builds a JSON-RPC 2.0 error response Hash.
+      # Requires +error:+ with +:code+ and +:message+ keys. +:data+ is optional.
       def build_error_response(**opts)
         raise ArgumentError, "error code is required" unless opts.dig(:error, :code)
         raise ArgumentError, "error message is required" unless opts.dig(:error, :message)
@@ -57,6 +54,7 @@ module Clamo
           }.reject { |k, _| k == "data" && !opts[:error].key?(:data) } }
       end
 
+      # Builds a JSON-RPC 2.0 error response from an ErrorDescriptor.
       def build_error_response_from(descriptor:, id: nil)
         build_error_response(
           id: id,
@@ -67,6 +65,7 @@ module Clamo
         )
       end
 
+      # Convenience method for a parse error (-32700) response.
       def build_error_response_parse_error
         build_error_response(
           id: nil,
@@ -77,6 +76,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,52 @@
 # frozen_string_literal: true
 
 require "json"
-require "parallel"
-require "timeout"
 
 module Clamo
+  # JSON-RPC 2.0 request dispatcher. All public methods on the target +object+
+  # become callable JSON-RPC methods.
+  #
+  # Three entry points, from highest to lowest level:
+  # - handle_json — JSON string in, JSON string out
+  # - dispatch_json — JSON string in, parsed Hash out
+  # - dispatch — parsed Hash in, parsed Hash out
+  #
+  # == Example
+  #
+  #   Clamo::Server.handle_json(
+  #     request: '{"jsonrpc":"2.0","method":"add","params":[1,2],"id":1}',
+  #     object:  MyService
+  #   )
+  #   # => '{"jsonrpc":"2.0","result":3,"id":1}'
   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
+      # Global error callback. Called with +(exception, method, params)+ whenever
+      # a dispatched method raises. Fires for both requests and notifications.
+      attr_accessor :on_error
 
-      def timeout
-        return @timeout if defined?(@timeout)
-
-        30
-      end
-
-      # JSON string in, JSON string out. Full round-trip for HTTP/socket integrations.
+      # JSON string in, JSON string out. The primary entry point for HTTP/socket
+      # integrations. Returns +nil+ for notifications (no response expected).
       #
-      #   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, **)
+      # All extra keyword arguments are forwarded to #dispatch.
+      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 Hash out. Parses the JSON and delegates
+      # to #dispatch. Returns a Hash (or Array of Hashes for batches), or +nil+
+      # for notifications.
+      #
+      #   Clamo::Server.dispatch_json(request: json_string, object: MyService)
+      #
+      # All extra keyword arguments are forwarded to #dispatch.
+      def dispatch_json(request:, object:, **)
         raise ArgumentError, "object is required" unless object
 
         begin
@@ -43,26 +55,35 @@ 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 (or Array) in, parsed response Hash out. Validates the
+      # request, resolves the method on +object+, checks parameter arity,
+      # and dispatches. Returns +nil+ for notifications.
+      #
+      #   Clamo::Server.dispatch(request: hash_or_array, object: MyService)
+      #
+      # ==== Options
+      # +on_error+:: Error callback for this call, overrides the global on_error.
+      # Extra keyword arguments are forwarded to +Parallel.map+ for batch requests.
+      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 +130,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 +156,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 +203,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 = "1.0.0"
 end

data/lib/clamo.rb

@@ -4,5 +4,10 @@ require_relative "clamo/version"
 require_relative "clamo/jsonrpc"
 require_relative "clamo/server"
 
+# Clamo is a minimal, spec-compliant JSON-RPC 2.0 server for Ruby.
+# Expose any module or class as a JSON-RPC service — public methods
+# become callable via JSON-RPC requests.
+#
+# See Clamo::Server for the main entry points.
 module Clamo
 end

metadata

@@ -1,30 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: clamo
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 1.0.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'
-description: Minimal, spec-compliant JSON-RPC 2.0 server for Ruby with request validation,
-  method dispatch, batch processing, and notification support.
+dependencies: []
+description: Minimal, spec-compliant JSON-RPC 2.0 server for Ruby. Expose any module
+  or class as a JSON-RPC service with request validation, batch processing, and notification
+  support.
 email:
 - Andriy.Tyurnikov@gmail.com
 executables: []