clamo 0.12.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7596405122290bf9bce3c04760bbb5e03eef24f8e5e6b3c6e99105c8faa7d14e
-  data.tar.gz: 219e2f1f54ffd99c03dcde0c18508d24625904daa2aa65f5c7c1aabbfacee11c
+  metadata.gz: fb802891a70c42e2bb89446fd258fc7e9114ff29f64c4cc6051f819332172307
+  data.tar.gz: 10af0f3deb9d61fd068ebd9a1c6bdbc9f93aca02b8491b8c1856032338c5a56d
 SHA512:
-  metadata.gz: 7d6a2c1407df2fc1427a7c95500d07f4873660c2322bcd4ae1a4f642550e89d6a723e7854f2126404f985446432a8e59e2690873d28ff25b218e1f01e260898a
-  data.tar.gz: eb941c6f05333536695f9f3d6531de593b592653b17c6fb5a10e18c5cca693c6cb2fe3e922a25f17c5a1bf3d90fae8b518674b14fc78b7b2926deff1f3d7223b
+  metadata.gz: bdbb35a70e40adad88ef1c19b0247e11512d6d51a50fcba039cb74699e60ad7088b42f0ca8d7297c19d5e075100602c5ee79d1dc28f0604a6f0160c440a0db6f
+  data.tar.gz: b8a2d1c0002003468c4d4e3bbc03348d36b56e9ed13396c07653640c00cd3e924a6df45a3951a1d8c5a235bd189fd38d66418cf405f2786db3338570e8bf790a

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
 
@@ -54,17 +94,7 @@ response = Clamo::Server.dispatch(
 
 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:
-
-```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
 
@@ -102,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:
@@ -172,6 +187,38 @@ Clamo::Server.dispatch(
 )
 ```
 
+### 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,6 +17,13 @@ module Clamo
     end
 
     class << self
+      # 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)
 
@@ -24,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)
@@ -41,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,
@@ -51,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,

data/lib/clamo/server.rb

@@ -3,16 +3,35 @@
 require "json"
 
 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(:on_error)
 
     class << self
+      # Global error callback. Called with +(exception, method, params)+ whenever
+      # a dispatched method raises. Fires for both requests and notifications.
       attr_accessor :on_error
 
-      # 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_json(request: body, object: MyService)
       #
+      # All extra keyword arguments are forwarded to #dispatch.
       def handle_json(request:, object:, **)
         response = dispatch_json(request: request, object: object, **)
         response&.to_json
@@ -20,10 +39,13 @@ module Clamo
 
       alias handle handle_json
 
-      # JSON string in, parsed response out.
+      # 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: MyModule)
+      #   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
 
@@ -38,10 +60,15 @@ module Clamo
 
       alias unparsed_dispatch_to_object dispatch_json
 
-      # Parsed hash in, parsed response out.
+      # 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: MyModule)
+      #   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)

data/lib/clamo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clamo
-  VERSION = "0.12.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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clamo
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Andriy Tyurnikov
@@ -9,8 +9,9 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Minimal, spec-compliant JSON-RPC 2.0 server for Ruby with request validation,
-  method dispatch, batch processing, and notification support.
+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: []