clamo 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c91f68aa4a88440e10a75a4ae3f138df400c10fd698b2d2b8c72990dc7e25f1
-  data.tar.gz: bef5052025e0714e0297b20d95d1b90dfed7fce4e30a2fecd24cff9e8a84913c
+  metadata.gz: 97084b2761bd6af3549fd2444f981da0a23ce6f1ebbc740f4c2fb237e90ee1fe
+  data.tar.gz: dde0cc4f7187bc58aeb2d1be4169f3cc6331d4008c7a10539317cb80e2a68480
 SHA512:
-  metadata.gz: 96fa52c9f35c408c60a6827fa7886ee35fcea05af69fc6dde54aca497f0347c8de76bfd163fdb6bb4595f498fe9b55e9059e32d7212f997ec43cf5e77fafafef
-  data.tar.gz: a7519eeba5bfd4074ada39cea72a03afa03cfc22809b53034eaf06c48d8a94a1122e136a6cf7b9452a27fb2f0ca54d9507db91a7bf498073b5f25e76cee74f45
+  metadata.gz: 18a87542a9340025ff18f60594ae32e941bca85f4f268c2dd99ca207dc2c4296c74f2809531e7e43034f27219b4d43fec4f380f61def8e37af6477fa979c273e
+  data.tar.gz: 976d81d554ff643ddfcbbaa5185094fda802657b5adee586d60e7c31e7aee27b0f6f141263f23dc8ebbc4d7b0a288beb3e1dc78a41b4209c18c266f2c64931a8

data/.rubocop.yml

@@ -5,6 +5,15 @@ AllCops:
 Metrics/MethodLength:
   Enabled: false
 
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
 Style/Documentation:
   Enabled: false
 

data/CHANGELOG.md

@@ -4,6 +4,45 @@ 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.8.0] - 2026-03-14
+
+### Added
+
+- `before_dispatch` and `after_dispatch` hooks — run around every method call (requests and notifications). Raise in `before_dispatch` to halt execution; `after_dispatch` fires only on success with `(method, params, result)`.
+- Per-call configuration — `timeout`, `on_error`, `before_dispatch`, and `after_dispatch` can be passed as keyword arguments to `handle`, `unparsed_dispatch_to_object`, and `parsed_dispatch_to_object`, overriding module-level defaults.
+- `Clamo::Server::Config` — immutable `Data` struct that snapshots configuration at the start of each dispatch, eliminating race conditions from concurrent mutations to module-level settings.
+
+### Changed
+
+- Internal error responses no longer include `e.message` in the `data` field, preventing leakage of internal details to clients. Exceptions are routed through `on_error` instead.
+- `parsed_dispatch_to_object` normalizes request keys to strings at the boundary, fixing silent dispatch failures when callers pass symbol-key hashes.
+- `on_error` is now called for request dispatch errors (previously only for notification errors).
+- Test suite expanded to 95 tests / 138 assertions.
+
+## [0.7.0] - 2026-03-14
+
+### Added
+
+- `Clamo::Server.timeout` — per-dispatch timeout with 30-second default; returns `-32000 Server error` on timeout for requests, calls `on_error` for notifications. Set to `nil` to disable.
+- MIT LICENSE file and `spec.license` in gemspec
+- Indifferent key access in JSONRPC validators (symbol and string keys both accepted)
+- Tests for string ids, arity mismatch, single-item batches, and handle+timeout (77 tests / 105 assertions)
+
+### Changed
+
+- `proper_pragma?`, `proper_method?`, `proper_id_if_any?` moved from public to private API on `Clamo::JSONRPC`
+- Notifications with invalid params type now return `nil` instead of an error response (spec compliance)
+- `parsed_dispatch_to_object` now validates `object:` argument (raises `ArgumentError` if nil)
+- Single-item batches skip `Parallel.map` overhead
+- Gemspec description expanded (no longer identical to summary)
+- README updated with `Server.handle`, `timeout`, and `on_error` documentation
+
+### Removed
+
+- `Clamo::Error` base exception class (unused)
+- `sig/clamo.rbs` type signatures (misleadingly incomplete)
+- Dead `else` branch in `dispatch_to_ruby`
+
 ## [0.6.0] - 2026-03-14
 
 ### Added

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Andriy Tyurnikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -26,15 +26,30 @@ module MyService
   end
 end
 
-# Handle a JSON-RPC request
-request_body = '{"jsonrpc": "2.0", "method": "add", "params": [1, 2], "id": 1}'
-response = Clamo::Server.unparsed_dispatch_to_object(
-  request: request_body,
+# 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(
+  request: '{"jsonrpc": "2.0", "method": "add", "params": [1, 2], "id": 1}',
   object: MyService
 )
+# => '{"jsonrpc":"2.0","result":3,"id":1}'
+```
 
-puts response
+If you need the parsed hash instead of a JSON string, use the lower-level methods:
+
+```ruby
+# From a JSON string
+response = Clamo::Server.unparsed_dispatch_to_object(
+  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(
+  request: { "jsonrpc" => "2.0", "method" => "add", "params" => [1, 2], "id" => 1 },
+  object: MyService
+)
 ```
 
 ### Handling Different Parameter Types
@@ -113,11 +128,63 @@ Clamo follows the JSON-RPC 2.0 specification for error handling:
 | -32603     | Internal error   | Internal JSON-RPC error                              |
 | -32000     | Server error     | Reserved for implementation-defined server errors    |
 
+## Configuration
+
+### Timeout
+
+Every method dispatch is wrapped in a timeout. The default is 30 seconds. Timed-out requests return a `-32000 Server error` response.
+
+```ruby
+Clamo::Server.timeout = 10  # seconds
+Clamo::Server.timeout = nil # disable timeout
+```
+
+### 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:
+
+```ruby
+Clamo::Server.on_error = ->(exception, method, params) {
+  Rails.logger.error("#{method} failed: #{exception.message}")
+}
+```
+
+### 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:
+
+```ruby
+Clamo::Server.handle(
+  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) }
+)
+```
+
+Per-call config is snapshotted at the start of each dispatch, so concurrent mutations to module-level settings cannot affect in-flight requests.
+
 ## Advanced Features
 
 ### Parallel Processing
 
-Batch requests are processed in parallel using the [parallel](https://github.com/grosser/parallel) gem. You can pass options to `Parallel.map` via the `parsed_dispatch_to_object` method:
+Batch requests are processed in parallel using the [parallel](https://github.com/grosser/parallel) gem. You can pass options to `Parallel.map`:
 
 ```ruby
 Clamo::Server.parsed_dispatch_to_object(

data/lib/clamo/jsonrpc.rb

@@ -14,27 +14,10 @@ module Clamo
     end
 
     class << self
-      def proper_pragma?(request)
-        request["jsonrpc"] == "2.0"
-      end
-
-      def proper_method?(request)
-        request["method"].is_a?(String)
-      end
-
-      def proper_id_if_any?(request)
-        if request.key?("id")
-          request["id"].is_a?(String) ||
-            request["id"].is_a?(Integer) ||
-            request["id"].is_a?(NilClass)
-        else
-          true
-        end
-      end
-
       def proper_params_if_any?(request)
-        if request.key?("params")
-          request["params"].is_a?(Array) || request["params"].is_a?(Hash)
+        if key_indifferent?(request, "params")
+          params = fetch_indifferent(request, "params")
+          params.is_a?(Array) || params.is_a?(Hash)
         else
           true
         end
@@ -96,11 +79,36 @@ module Clamo
 
       private
 
+      def proper_pragma?(request)
+        fetch_indifferent(request, "jsonrpc") == "2.0"
+      end
+
+      def proper_method?(request)
+        fetch_indifferent(request, "method").is_a?(String)
+      end
+
+      def proper_id_if_any?(request)
+        if key_indifferent?(request, "id")
+          id = fetch_indifferent(request, "id")
+          id.is_a?(String) || id.is_a?(Integer) || id.is_a?(NilClass)
+        else
+          true
+        end
+      end
+
       def validate_params_type!(params)
         return if params.is_a?(Array) || params.is_a?(Hash)
 
         raise ArgumentError, "params must be an Array or Hash"
       end
+
+      def fetch_indifferent(hash, key)
+        hash.fetch(key.to_s) { hash.fetch(key.to_sym, nil) }
+      end
+
+      def key_indifferent?(hash, key)
+        hash.key?(key.to_s) || hash.key?(key.to_sym)
+      end
     end
   end
 end

data/lib/clamo/server.rb

@@ -2,17 +2,24 @@
 
 require "json"
 require "parallel"
+require "timeout"
 
 module Clamo
   module Server
+    Config = Data.define(:timeout, :on_error, :before_dispatch, :after_dispatch)
+
     class << self
-      # Global error callback for notification failures.
-      # This is module-level state shared across all callers.
-      # Set to any callable (lambda, method, proc) that accepts (exception, method, params).
-      #
-      #   Clamo::Server.on_error = ->(e, method, params) { Rails.logger.error(e) }
-      #
-      attr_accessor :on_error
+      # 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
 
       # JSON string in, JSON string out. Full round-trip for HTTP/socket integrations.
       #
@@ -39,39 +46,60 @@ module Clamo
         parsed_dispatch_to_object(request: parsed, object: object, **)
       end
 
-      def parsed_dispatch_to_object(request:, object:, **opts)
-        response_for(request: request, object: object, **opts) do |method, params|
+      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)
+        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)
+
+        response_for(request: request, object: object, config: config, **opts) do |method, params|
           dispatch_to_ruby(object: object, method: method, params: params)
         end
       end
 
       private
 
+      def normalize_request_keys(request)
+        case request
+        when Hash  then request.transform_keys(&:to_s)
+        when Array then request.map { |r| r.is_a?(Hash) ? r.transform_keys(&:to_s) : r }
+        else request
+        end
+      end
+
       def method_known?(object:, method:)
         object.public_methods(false).map(&:to_sym).include?(method.to_sym)
       end
 
       def dispatch_to_ruby(object:, method:, params:)
         case params
-        when Array     then object.public_send(method.to_sym, *params)
-        when Hash      then object.public_send(method.to_sym, **params.transform_keys(&:to_sym))
-        when NilClass  then object.public_send(method.to_sym)
-        else raise ArgumentError, "Unsupported params type: #{params.class}"
+        when Array    then object.public_send(method.to_sym, *params)
+        when Hash     then object.public_send(method.to_sym, **params.transform_keys(&:to_sym))
+        when NilClass then object.public_send(method.to_sym)
         end
       end
 
-      def response_for(request:, object:, **, &block)
+      # Extra keyword arguments (**) are forwarded to response_for_batch only,
+      # where they become options for Parallel.map (e.g., in_processes: 4).
+      # For single requests they are silently ignored.
+      def response_for(request:, object:, config:, **, &block)
         case request
         when Array
-          response_for_batch(request: request, object: object, block: block, **)
+          response_for_batch(request: request, object: object, block: block, config: config, **)
         when Hash
-          response_for_single_request(request: request, object: object, block: block)
+          response_for_single_request(request: request, object: object, block: block, config: config)
         else
           JSONRPC.build_error_response_from(id: nil, descriptor: JSONRPC::ProtocolErrors::INVALID_REQUEST)
         end
       end
 
-      def response_for_single_request(request:, object:, block:)
+      def response_for_single_request(request:, object:, block:, config:)
         error = validate_request_structure(request)
         return error if error
 
@@ -79,18 +107,23 @@ module Clamo
           return request.key?("id") ? method_not_found_error(request) : nil
         end
 
-        return dispatch_notification(request, block) unless request.key?("id")
+        return dispatch_notification(request, block, config) unless request.key?("id")
 
-        dispatch_request(request, block)
+        dispatch_request(request, block, config)
       end
 
-      def response_for_batch(request:, object:, block:, **opts)
+      def response_for_batch(request:, object:, block:, config:, **opts)
         if request.empty?
           return JSONRPC.build_error_response_from(id: nil, descriptor: JSONRPC::ProtocolErrors::INVALID_REQUEST)
         end
 
+        if request.size == 1
+          result = response_for_single_request(request: request.first, object: object, block: block, config: config)
+          return result ? [result] : nil
+        end
+
         result = Parallel.map(request, **opts) do |item|
-          response_for_single_request(request: item, object: object, block: block)
+          response_for_single_request(request: item, object: object, block: block, config: config)
         end.compact
         result.empty? ? nil : result
       end
@@ -105,6 +138,9 @@ module Clamo
 
         return if JSONRPC.proper_params_if_any?(request)
 
+        # 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: JSONRPC::ProtocolErrors::INVALID_PARAMS)
       end
 
@@ -112,29 +148,50 @@ module Clamo
         JSONRPC.build_error_response_from(id: request["id"], descriptor: JSONRPC::ProtocolErrors::METHOD_NOT_FOUND)
       end
 
-      def dispatch_notification(request, block)
-        block.yield request["method"], request["params"]
+      def dispatch_notification(request, block, config)
+        method = request["method"]
+        params = request["params"]
+        config.before_dispatch&.call(method, params)
+        with_timeout(config.timeout) { block.yield(method, params) }
+        config.after_dispatch&.call(method, params, nil)
         nil
       rescue StandardError => e
-        on_error&.call(e, request["method"], request["params"])
+        config.on_error&.call(e, method, params)
         nil
       end
 
-      def dispatch_request(request, block)
-        JSONRPC.build_result_response(
-          id: request["id"],
-          result: block.yield(request["method"], request["params"])
-        )
+      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)
+        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)
+      end
+
+      def timeout_error(request)
         JSONRPC.build_error_response(
           id: request["id"],
           error: {
-            code: JSONRPC::ProtocolErrors::INTERNAL_ERROR.code,
-            message: JSONRPC::ProtocolErrors::INTERNAL_ERROR.message,
-            data: e.message
+            code: JSONRPC::ProtocolErrors::SERVER_ERROR.code,
+            message: JSONRPC::ProtocolErrors::SERVER_ERROR.message,
+            data: "Request timed out"
           }
         )
       end
+
+      def with_timeout(seconds, &block)
+        if seconds
+          Timeout.timeout(seconds, &block)
+        else
+          block.call
+        end
+      end
     end
   end
 end

data/lib/clamo/version.rb

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

data/lib/clamo.rb

@@ -5,5 +5,4 @@ require_relative "clamo/jsonrpc"
 require_relative "clamo/server"
 
 module Clamo
-  class Error < StandardError; end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clamo
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Andriy Tyurnikov
@@ -23,7 +23,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.27'
-description: JSON-RPC 2.0 server toolkit for Ruby
+description: Minimal, spec-compliant JSON-RPC 2.0 server for Ruby with request validation,
+  method dispatch, batch processing, and notification support.
 email:
 - Andriy.Tyurnikov@gmail.com
 executables: []
@@ -32,15 +33,16 @@ extra_rdoc_files: []
 files:
 - ".rubocop.yml"
 - CHANGELOG.md
+- LICENSE
 - README.md
 - Rakefile
 - lib/clamo.rb
 - lib/clamo/jsonrpc.rb
 - lib/clamo/server.rb
 - lib/clamo/version.rb
-- sig/clamo.rbs
 homepage: https://github.com/rubakas/clamo
-licenses: []
+licenses:
+- MIT
 metadata:
   homepage_uri: https://github.com/rubakas/clamo
   source_code_uri: https://github.com/rubakas/clamo

data/sig/clamo.rbs

@@ -1,4 +0,0 @@
-module Clamo
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end