clamo 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c91f68aa4a88440e10a75a4ae3f138df400c10fd698b2d2b8c72990dc7e25f1
-  data.tar.gz: bef5052025e0714e0297b20d95d1b90dfed7fce4e30a2fecd24cff9e8a84913c
+  metadata.gz: 410f469e07b16f8273149b1eded89c94692a91c8b41cd7c47642e897ca8d97fb
+  data.tar.gz: 2d6be4be393cfd70d5bf22109943b7735de5ca0abe93b65a888fe1a372640faa
 SHA512:
-  metadata.gz: 96fa52c9f35c408c60a6827fa7886ee35fcea05af69fc6dde54aca497f0347c8de76bfd163fdb6bb4595f498fe9b55e9059e32d7212f997ec43cf5e77fafafef
-  data.tar.gz: a7519eeba5bfd4074ada39cea72a03afa03cfc22809b53034eaf06c48d8a94a1122e136a6cf7b9452a27fb2f0ca54d9507db91a7bf498073b5f25e76cee74f45
+  metadata.gz: 385175b28fea11461b35a98860a6b8099bd9c88bc8dfef4f2603dc911a3d9e1709b51343d2b22ebb524ffc82aa03de7d8886a50b078c258d5fe28ec897a17296
+  data.tar.gz: 0c37f0971e24855610a91c8687d8e55ff32a03accf1effc73b6a1090118b46e3d78ffd9f0a7531418aa97a3154969bf7fb4d2dd0da9dc0cfe1b2b7aa94778cda

data/.rubocop.yml

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

data/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.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,32 @@ 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
+
+Notifications don't return responses, so errors during notification dispatch are silent by default. Use `on_error` to capture them:
+
+```ruby
+Clamo::Server.on_error = ->(exception, method, params) {
+  Rails.logger.error("#{method} failed: #{exception.message}")
+}
+```
+
 ## 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,6 +2,7 @@
 
 require "json"
 require "parallel"
+require "timeout"
 
 module Clamo
   module Server
@@ -14,6 +15,19 @@ module Clamo
       #
       attr_accessor :on_error
 
+      # Maximum seconds allowed for a single method dispatch. Defaults to 30.
+      # Set to nil to disable.
+      #
+      #   Clamo::Server.timeout = 10
+      #
+      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.
       #
       #   Clamo::Server.handle(request: body, object: MyService)
@@ -40,6 +54,8 @@ module Clamo
       end
 
       def parsed_dispatch_to_object(request:, object:, **opts)
+        raise ArgumentError, "object is required" unless object
+
         response_for(request: request, object: object, **opts) do |method, params|
           dispatch_to_ruby(object: object, method: method, params: params)
         end
@@ -53,13 +69,15 @@ module Clamo
 
       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
 
+      # 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:, **, &block)
         case request
         when Array
@@ -89,6 +107,11 @@ module Clamo
           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)
+          return result ? [result] : nil
+        end
+
         result = Parallel.map(request, **opts) do |item|
           response_for_single_request(request: item, object: object, block: block)
         end.compact
@@ -105,6 +128,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
 
@@ -113,7 +139,7 @@ module Clamo
       end
 
       def dispatch_notification(request, block)
-        block.yield request["method"], request["params"]
+        with_timeout { block.yield request["method"], request["params"] }
         nil
       rescue StandardError => e
         on_error&.call(e, request["method"], request["params"])
@@ -123,7 +149,16 @@ module Clamo
       def dispatch_request(request, block)
         JSONRPC.build_result_response(
           id: request["id"],
-          result: block.yield(request["method"], request["params"])
+          result: with_timeout { block.yield(request["method"], request["params"]) }
+        )
+      rescue Timeout::Error
+        JSONRPC.build_error_response(
+          id: request["id"],
+          error: {
+            code: JSONRPC::ProtocolErrors::SERVER_ERROR.code,
+            message: JSONRPC::ProtocolErrors::SERVER_ERROR.message,
+            data: "Request timed out"
+          }
         )
       rescue StandardError => e
         JSONRPC.build_error_response(
@@ -135,6 +170,14 @@ module Clamo
           }
         )
       end
+
+      def with_timeout(&block)
+        if timeout
+          Timeout.timeout(timeout, &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.7.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.7.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