ultimate_json_rpc 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 57a4e2297d9a88e829782f6ba971a4d358cf342cf608e85cdd45b4532f1d5cc5
+  data.tar.gz: 561c9b24aaf6369bc54429592ac5a3d3ef21577eba4df66591badbbca6f4f274
+SHA512:
+  metadata.gz: a66e18a36696028d540dfdeffbf3136b2b413fd0c326ffc0ca4878b5c24eb96c19820f765491739ebc0d9a33076d68856e54f9808364e3615a9ed754f2106ca5
+  data.tar.gz: 26f3451b0dc98ea82c04051a415efa68cf7d26131718ad051cf1842e898cb9a8b86b00ce3fe6685d3d191c4d5e9d61147727076abf41d3e3bf1a6238f8247b59

data/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+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/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-03-20
+
+### Added
+- `TCP#port` accessor for discovering the bound port at runtime
+
+### Changed
+- Gem renamed from `reclamo` to `ultimate_json_rpc` (module `Reclamo` → `UltimateJsonRpc`)
+- `InvalidParams` error data is now gated by `expose_errors` (same as `InvalidRequest` and `ArgumentError`). `InvalidParams` is a protocol-level schema check, not an application validation error — use `ApplicationError` for business rule violations.
+
+### Fixed
+- `Server#freeze` is now idempotent — calling freeze on an already-frozen server no longer raises `FrozenError`
+- RBS type signatures now correctly reflect Core/Extras/Transport namespace structure
+- RBS `Server` class no longer declares conditional `include` for extras
+- Recorder `max_exchanges:` and TCP `MAX_LINE_BYTES` added to RBS type signatures
+- `Docs#escape_cell` now escapes newlines in Markdown table cells
+- Flaky profiler test with timing-dependent percentile assertion
+- Batch-too-large error now uses standard `"Invalid Request"` message with reason in `data` field (JSON-RPC 2.0 conformance)
+
+## [0.3.0] - 2026-03-18
+
+### Added
+- Method-level middleware: `server.use(only: ["admin.*"])` and `server.use(except: ["ping"])` to scope middleware to specific methods or namespaces, with glob pattern support
+- `UltimateJsonRpc::Transport::Rack` built-in Rack adapter: Content-Type handling, 200/204/405 responses, `require "ultimate_json_rpc/transport/rack"` to opt in
+- Test assertion helpers: `assert_rpc_success`, `assert_rpc_error`, `assert_rpc_notification` in `ultimate_json_rpc/test_helpers`
+- `UltimateJsonRpc::Transport::Stdio` adapter: newline-delimited JSON-RPC over stdin/stdout with signal handling, `require "ultimate_json_rpc/transport/stdio"`
+- Return type annotations: `returns:` keyword on `expose_method` and `returns:` hash on `expose`, appears in `rpc.discover`
+- OpenRPC 1.3.2 schema: `rpc.discover` now returns a full OpenRPC document with `openrpc` version, `info` object, and `result` contentDescriptors
+- Instrumentation hooks: `server.on(:request)`, `on(:response)`, `on(:error)` for read-only lifecycle observability with duration timing
+- Request timeout: `Server.new(timeout: 5)` wraps dispatch in `Timeout.timeout`, returns `-32001 Request timeout` on expiry
+- `RequestTimeout` error class and `REQUEST_TIMEOUT` (-32001) constant
+- Method deprecation markers: `deprecated: true` or `deprecated: "Use v2"` on `expose_method` and `expose`, appears in `rpc.discover`
+- Parameter validation: `params_schema:` on `expose_method` and `expose` for type and enum validation before dispatch, returns `-32602 Invalid params` on mismatch, schemas appear in `rpc.discover` param descriptors
+- Concurrent batch execution: `Server.new(concurrent_batches: true)` processes batch items in parallel using threads
+- Error catalog: `server.register_error(code, name, description)` registers application error codes that appear in `rpc.discover` under `components.errors`
+- Custom JSON serializer: `Server.new(json: Oj)` to swap JSON encoder/decoder, any object responding to `parse` and `generate`
+- Method-level authorization: `server.authorize("admin.*") { |req| req.context[:role] == :admin }` with glob patterns and custom error codes
+- Structured logging: `require "ultimate_json_rpc/extras/logging"` provides `UltimateJsonRpc::Extras::Logging.new(server, logger)` for logger-agnostic observability
+- Request/response recorder: `require "ultimate_json_rpc/extras/recorder"` provides `UltimateJsonRpc::Extras::Recorder.new(server)` capturing exchanges for replay testing, with optional JSONL file output
+- MCP (Model Context Protocol) adapter: `require "ultimate_json_rpc/extras/mcp"` provides `UltimateJsonRpc::Extras::MCP.new(server)` for AI tool integration over stdio, mapping methods to MCP tools with schema support
+- Rate limiting: `require "ultimate_json_rpc/extras/rate_limit"` provides `UltimateJsonRpc::Extras::RateLimiter.new(server, max:, period:)` with sliding window, per-caller keying, and per-method scoping
+- Per-method profiling: `require "ultimate_json_rpc/extras/profiler"` provides `UltimateJsonRpc::Extras::Profiler.new(server)` collecting count, min/max/avg, and p50/p95/p99 per method
+- TCP server adapter: `require "ultimate_json_rpc/transport/tcp"` provides `UltimateJsonRpc::Transport::TCP.new(server, port: 4000)` for newline-delimited JSON-RPC over TCP with multi-client threading
+- API documentation generation: `require "ultimate_json_rpc/extras/docs"` provides `UltimateJsonRpc::Extras::Docs.new(server).to_markdown` generating Markdown from OpenRPC schema
+- Usage examples: `examples/` directory with runnable patterns for Rack, MCP, multi-namespace/versioning, error handling, and testing
+- WebSocket adapter: `require "ultimate_json_rpc/transport/websocket"` provides `UltimateJsonRpc::Transport::WebSocket` for JSON-RPC over WebSockets with any Rack-compatible library
+
+### Fixed
+- MCP `inputSchema` now always included for zero-parameter tools (MCP spec compliance)
+- `handle_parsed` no longer crashes with `TypeError` on Symbol-keyed hashes
+
+### Changed
+- `rpc.discover` output restructured: service metadata moved to `info` object (`name` → `info.title`), method `returns` → `result` in OpenRPC contentDescriptor format
+
+## [0.2.0] - 2026-03-18
+
+### Added
+- `InvalidParams` error class for explicit -32602 errors from user code
+- `expose_method` accepts callable objects (Method, Proc, lambda) as first argument
+- `Server#empty?` and `Handler#empty?` convenience methods
+- Callable validation: `expose_method` checks that callable responds to `#call`
+
+### Changed
+- `MethodNotFound` now has a descriptive Ruby exception message ("Method not found: name")
+- `ApplicationError` validates that error code is an Integer
+- Request params and id are frozen after construction for immutability
+- `ServerError` uses `between?` for range validation (consistency)
+
+## [0.1.0] - 2025-05-01
+
+### Added
+- Initial release
+- JSON-RPC 2.0 server with `expose`, `expose_method`, and middleware support
+- `rpc.discover` built-in introspection
+- Batch request handling
+- `Server#freeze` for thread-safe immutability
+- `Server#call` alias and `#to_proc` for Rack-like usage
+- `only:`/`except:` method filtering
+- Method descriptions via `descriptions:` option
+- Service metadata via `name:` and `version:` options

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 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

@@ -0,0 +1,478 @@
+# UltimateJsonRpc
+
+[![CI](https://github.com/rubakas/ultimate_json_rpc/actions/workflows/main.yml/badge.svg)](https://github.com/rubakas/ultimate_json_rpc/actions/workflows/main.yml)
+
+Network-agnostic JSON-RPC 2.0 server that exposes Ruby modules, classes, and instances as callable RPC endpoints. UltimateJsonRpc handles JSON-RPC message parsing, method dispatch, and response serialization — transport (HTTP, WebSocket, stdio, TCP, etc.) is the caller's responsibility.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ultimate_json_rpc"
+```
+
+## Usage
+
+```ruby
+require "ultimate_json_rpc"
+
+# Define your service
+module Calculator
+  def self.add(a, b) = a + b
+  def self.divide(a, b) = a.to_f / b
+end
+
+# Create a server and expose objects
+server = UltimateJsonRpc::Server.new(name: "My API", version: "1.0")
+server.expose(Calculator, descriptions: { add: "Add two numbers" })
+server.expose(some_instance, namespace: "greeter")
+
+# Handle a JSON-RPC request string, get a JSON-RPC response string
+request = '{"jsonrpc":"2.0","method":"add","params":[2,3],"id":1}'
+response = server.handle(request)
+# => '{"jsonrpc":"2.0","result":5,"id":1}'
+```
+
+### Expose individual methods
+
+```ruby
+server.expose_method("double", description: "Double a number") { |n| n * 2 }
+server.expose_method("greet") { |name:, greeting: "Hello"| "#{greeting}, #{name}!" }
+```
+
+### Chainable API
+
+All setup methods return `self`, and the server is callable via `to_proc`:
+
+```ruby
+server = UltimateJsonRpc::Server.new
+  .expose(Calculator, namespace: "calc")
+  .expose_method("ping") { "pong" }
+  .use { |req, next_call| next_call.call }
+
+# Use to_proc for mapping over requests
+responses = json_requests.map(&server)
+```
+
+### Return type annotations
+
+Declare return types for discovery metadata (purely informational, no runtime enforcement):
+
+```ruby
+server.expose_method("add", returns: { "type" => "number" }) { |a, b| a + b }
+server.expose(Calculator, returns: { add: { "type" => "number" } })
+```
+
+### Service discovery
+
+Built-in `rpc.discover` returns an [OpenRPC](https://open-rpc.org/) 1.3.2-compatible document:
+
+```ruby
+request = '{"jsonrpc":"2.0","method":"rpc.discover","id":1}'
+server.handle(request)
+# => '{"jsonrpc":"2.0","result":{"openrpc":"1.3.2","info":{"title":"My API","version":"1.0"},"methods":[...]},"id":1}'
+```
+
+### Middleware
+
+Add cross-cutting concerns like logging, auth, or rate limiting:
+
+```ruby
+server.use do |request, next_call|
+  puts "Calling #{request.method_name}"
+  result = next_call.call
+  puts "Done"
+  result
+end
+
+# Reject unauthorized calls
+server.use do |request, next_call|
+  raise UltimateJsonRpc::ApplicationError.new(code: 403, message: "Forbidden") unless authorized?(request)
+
+  next_call.call
+end
+```
+
+Middleware runs in registration order (first registered = outermost wrapper).
+
+#### Scoped middleware
+
+Target specific methods or namespaces with `only:` / `except:`, supporting glob patterns:
+
+```ruby
+# Only run for admin namespace methods
+server.use(only: ["admin.*"]) do |request, next_call|
+  raise UltimateJsonRpc::ApplicationError.new(code: 403, message: "Forbidden") unless admin?(request)
+  next_call.call
+end
+
+# Run for everything except health checks
+server.use(except: ["ping", "health"]) do |request, next_call|
+  log(request)
+  next_call.call
+end
+```
+
+Middleware can pass data to handlers via `request.context`:
+
+```ruby
+server.use do |request, next_call|
+  request.context[:user] = authenticate(request)
+  next_call.call
+end
+```
+
+### Instrumentation hooks
+
+Read-only lifecycle hooks for observability — they can't alter responses or swallow errors:
+
+```ruby
+server.on(:request)  { |request| puts "→ #{request.method_name}" }
+server.on(:response) { |request, result, duration| puts "← #{request.method_name} (#{duration}s)" }
+server.on(:error)    { |request, error, duration| log_error(error, method: request.method_name) }
+```
+
+Hook errors are rescued and logged via `Kernel.warn`, never breaking dispatch.
+
+### Custom JSON serializer
+
+Swap the JSON encoder/decoder (defaults to stdlib `JSON`):
+
+```ruby
+require "oj"
+Oj.mimic_JSON
+server = UltimateJsonRpc::Server.new(json: Oj)
+```
+
+Any object responding to `parse(string)` and `generate(object)` works.
+
+### Concurrent batches
+
+Opt-in parallel processing for batch requests:
+
+```ruby
+server = UltimateJsonRpc::Server.new(concurrent_batches: true)
+# Batch items are processed in parallel using threads
+# Respects max_batch_size and request timeout
+```
+
+### Request timeout
+
+Set a per-server timeout (in seconds) to prevent slow handlers from blocking:
+
+```ruby
+server = UltimateJsonRpc::Server.new(timeout: 5)
+# Handlers exceeding 5 seconds receive a -32001 "Request timeout" error
+```
+
+### Parameter validation
+
+Declare parameter schemas to validate incoming params before dispatch:
+
+```ruby
+server.expose_method("add", params_schema: {
+  a: { "type" => "number" },
+  b: { "type" => "number" }
+}) { |a, b| a + b }
+
+server.expose(Calculator, params_schema: {
+  add: { left: { "type" => "number" }, right: { "type" => "number" } }
+})
+```
+
+Supported JSON Schema keywords: `type` (`string`, `number`, `integer`, `boolean`, `array`, `object`, `null`) and `enum`. On mismatch, returns `-32602 Invalid params` with a descriptive message. Schemas also appear in `rpc.discover` output.
+
+### Method deprecation
+
+Mark methods as deprecated in discovery metadata (purely informational, no runtime enforcement):
+
+```ruby
+server.expose_method("old_add", deprecated: true) { |a, b| a + b }
+server.expose_method("old_multiply", deprecated: "Use multiply_v2 instead") { |a, b| a * b }
+server.expose(Calculator, deprecated: { add: "Use add_v2" })
+```
+
+Deprecated methods still work normally but appear flagged in `rpc.discover` output.
+
+### Per-method profiling
+
+Collect per-method timing statistics:
+
+```ruby
+require "ultimate_json_rpc/extras/profiler"
+
+profiler = UltimateJsonRpc::Extras::Profiler.new(server)
+# ... handle requests ...
+profiler["add"]  # => {count: 150, min: 0.0001, max: 0.05, avg: 0.002, p50: ..., p95: ..., p99: ...}
+profiler.stats   # => all methods
+profiler.reset   # clear data
+```
+
+### Structured logging
+
+Logger-agnostic observability:
+
+```ruby
+require "ultimate_json_rpc/extras/logging"
+
+UltimateJsonRpc::Extras::Logging.new(server, Logger.new($stdout))           # logs at INFO by default
+UltimateJsonRpc::Extras::Logging.new(server, Rails.logger, level: :debug)   # custom level
+```
+
+Successful responses log at the specified level; errors always log at ERROR.
+
+### Rate limiting
+
+Sliding-window rate limiting with per-caller keying:
+
+```ruby
+require "ultimate_json_rpc/extras/rate_limit"
+
+UltimateJsonRpc::Extras::RateLimiter.new(server, max: 100, period: 60)                        # 100 req/min global
+UltimateJsonRpc::Extras::RateLimiter.new(server, max: 10, period: 60, only: ["expensive.*"])  # per-method
+UltimateJsonRpc::Extras::RateLimiter.new(server, max: 50, period: 60, key: :api_key)         # per-caller via context
+```
+
+### Authorization
+
+Declarative access control with glob patterns:
+
+```ruby
+server.authorize("admin.*") { |req| req.context[:role] == :admin }
+server.authorize("users.delete", code: 1001, message: "Insufficient permissions") do |req|
+  req.context[:permissions]&.include?("delete")
+end
+```
+
+Returns `ApplicationError` (code 403 by default) when the block returns falsy.
+
+### Error catalog
+
+Register application-specific error codes for discovery:
+
+```ruby
+server.register_error(code: 42, message: "InsufficientFunds", description: "Account balance too low")
+server.register_error(code: 43, message: "AccountLocked")
+```
+
+Registered errors appear in `rpc.discover` under `components.errors`, so consumers know which error codes to expect.
+
+### Error handling
+
+Raise `ApplicationError` for custom error codes, or `ServerError` for implementation-defined errors:
+
+```ruby
+raise UltimateJsonRpc::ApplicationError.new(code: 42, message: "Custom error", data: { "detail" => "info" })
+raise UltimateJsonRpc::ServerError.new(code: -32_001, message: "Server shutting down")
+```
+
+Ruby's `ArgumentError` automatically maps to JSON-RPC Invalid params (`-32602`). All other exceptions become Internal error (`-32603`).
+
+### Error visibility
+
+By default, internal error details (exception messages) are hidden from clients:
+
+```ruby
+server = UltimateJsonRpc::Server.new                    # expose_errors: false (default)
+# Internal errors return generic "Internal server error" in the data field
+
+server = UltimateJsonRpc::Server.new(expose_errors: true)
+# Internal errors include the actual exception message in the data field
+```
+
+`ApplicationError`, `ServerError`, and `MethodNotFound` always expose their details regardless of this setting, since those are intentionally raised by your code.
+
+Protocol-level errors (`InvalidRequest`, `InvalidParams`, `ArgumentError`, and unhandled exceptions) are gated by `expose_errors`. `InvalidParams` is a JSON-RPC schema check (type mismatch, enum violation) — for application-level business validation, raise `ApplicationError` instead.
+
+### Freezing
+
+Lock the server after setup to prevent accidental modifications:
+
+```ruby
+server.freeze  # expose, expose_method, use will now raise FrozenError
+server.handle(request)  # still works
+```
+
+### Features
+
+- **JSON-RPC 2.0** compliant (requests, notifications, batch requests)
+- **Expose modules** — singleton methods become RPC methods
+- **Expose instances** — public methods become RPC methods
+- **Expose blocks** — `server.expose_method("name") { ... }` for standalone methods
+- **Namespacing** — `server.expose(obj, namespace: "ns")` makes methods callable as `ns.method_name`
+- **Method filtering** — `server.expose(obj, only: [:add])` or `except: [:internal]`
+- **Method descriptions** — `descriptions:` hash or `description:` keyword for discovery
+- **Return type annotations** — `returns:` hash or keyword for discovery metadata
+- **Service metadata** — `name:` and `version:` appear in `rpc.discover` responses
+- **Positional and keyword params** — arrays map to positional args, objects map to keyword args
+- **Service discovery** — built-in `rpc.discover` returns OpenRPC 1.3.2-compatible schema
+- **Middleware** — `server.use { |request, next_call| ... }` for cross-cutting concerns
+- **Scoped middleware** — `only:` / `except:` with glob patterns to target specific methods or namespaces
+- **Instrumentation hooks** — `on(:request)`, `on(:response)`, `on(:error)` for read-only observability
+- **Parameter validation** — `params_schema:` with JSON Schema types and enum constraints
+- **Request timeout** — `Server.new(timeout: 5)` prevents slow handlers from blocking
+- **Method deprecation** — mark methods as deprecated in discovery metadata
+- **Error catalog** — `register_error` documents app error codes in `rpc.discover`
+- **Authorization** — `authorize("admin.*") { |req| ... }` for declarative access control
+- **Error handling** — standard JSON-RPC error codes, `ApplicationError`, and `ServerError`
+- **Error visibility** — `expose_errors: true` to include exception messages in error responses
+- **Rate limiting** — sliding-window `rate_limit(max:, period:)` with per-caller keying
+- **Security** — dangerous methods (eval, system, exec, etc.) are automatically blocked
+- **Chainable API** — all setup methods return `self`
+- **Callable** — `to_proc` enables `requests.map(&server)`
+- **Rack adapter** — `UltimateJsonRpc::Transport::Rack.new(server)` for instant HTTP deployment
+- **MCP adapter** — `UltimateJsonRpc::Extras::MCP.new(server).run` for AI tool integration (Claude, Cursor, etc.)
+- **stdio adapter** — `UltimateJsonRpc::Transport::Stdio.new(server).run` for CLI/MCP-style integrations
+- **Test helpers** — `rpc_call`, `assert_rpc_success`, `assert_rpc_error` for cleaner tests
+- **Concurrent batches** — `concurrent_batches: true` processes batch items in parallel
+- **Custom JSON** — `json: Oj` to swap the JSON encoder/decoder
+- **Batch size limit** — `max_batch_size: 100` (default) prevents oversized batch requests
+- **Freezable** — `server.freeze` locks configuration after setup
+
+### Transport examples
+
+UltimateJsonRpc is transport-agnostic. Here are common setups:
+
+#### Rack (HTTP)
+
+Use the built-in Rack adapter:
+
+```ruby
+# config.ru
+require "ultimate_json_rpc"
+require "ultimate_json_rpc/transport/rack"
+
+server = UltimateJsonRpc::Server.new(name: "My API")
+server.expose(Calculator)
+
+run UltimateJsonRpc::Transport::Rack.new(server)
+```
+
+`UltimateJsonRpc::Transport::Rack` handles Content-Type, returns 200 for responses, 204 for notifications, and 405 for non-POST requests.
+
+#### MCP (Model Context Protocol)
+
+Expose methods as AI tools via MCP:
+
+```ruby
+require "ultimate_json_rpc/extras/mcp"
+
+server = UltimateJsonRpc::Server.new(name: "My Tools", version: "1.0")
+server.expose(Calculator, descriptions: { add: "Add two numbers" })
+
+UltimateJsonRpc::Extras::MCP.new(server).run
+```
+
+`UltimateJsonRpc::Extras::MCP` handles the MCP lifecycle (`initialize`, `tools/list`, `tools/call`), maps methods to tool definitions with input schemas, and runs over stdio for integration with Claude, Cursor, and other AI tools.
+
+#### WebSocket
+
+Use the WebSocket adapter with any Rack-compatible library (e.g., `faye-websocket`):
+
+```ruby
+require "ultimate_json_rpc/transport/websocket"
+
+ws_handler = UltimateJsonRpc::Transport::WebSocket.new(server)
+
+# In your Rack app:
+ws = Faye::WebSocket.new(env)
+ws_handler.call(env, ws)
+```
+
+See `examples/websocket_server.ru` for a complete runnable example.
+
+#### TCP
+
+Use the built-in TCP adapter for internal microservices:
+
+```ruby
+require "ultimate_json_rpc/transport/tcp"
+
+server = UltimateJsonRpc::Server.new
+server.expose(Calculator)
+
+UltimateJsonRpc::Transport::TCP.new(server, port: 4000).run
+```
+
+`UltimateJsonRpc::Transport::TCP` accepts newline-delimited JSON-RPC over TCP, handles multiple concurrent clients via threads, and supports `SIGINT`/`SIGTERM` for graceful shutdown.
+
+#### stdio
+
+Use the built-in stdio adapter:
+
+```ruby
+require "ultimate_json_rpc"
+require "ultimate_json_rpc/transport/stdio"
+
+server = UltimateJsonRpc::Server.new
+server.expose(Calculator)
+
+UltimateJsonRpc::Transport::Stdio.new(server).run
+```
+
+`UltimateJsonRpc::Transport::Stdio` reads newline-delimited JSON-RPC from stdin, writes responses to stdout, skips empty lines, and handles `SIGINT`/`SIGTERM` for graceful shutdown.
+
+### Pre-parsed input
+
+If you've already parsed the JSON (e.g. from a WebSocket frame), use `handle_parsed` to skip the parse step:
+
+```ruby
+data = JSON.parse(raw_json)
+response = server.handle_parsed(data)
+```
+
+### Request/response recording
+
+Capture exchanges for replay and regression testing:
+
+```ruby
+require "ultimate_json_rpc/extras/recorder"
+
+recorder = UltimateJsonRpc::Extras::Recorder.new(server)
+server.handle(request_json)
+recorder.exchanges  # => [{"method" => "add", "params" => [2, 3], "result" => 5, "duration" => 0.001}]
+
+# Write JSONL to a file
+recorder = UltimateJsonRpc::Extras::Recorder.new(server, output: File.open("exchanges.jsonl", "a"))
+```
+
+### Test helpers
+
+UltimateJsonRpc ships with optional test helpers for cleaner assertions:
+
+```ruby
+require "ultimate_json_rpc/extras/test_helpers"
+
+class MyTest < Minitest::Test
+  include UltimateJsonRpc::Extras::TestHelpers
+
+  def test_addition
+    response = rpc_call(server, "add", params: [2, 3])
+    assert_rpc_success response, 5
+  end
+
+  def test_method_not_found
+    response = rpc_call(server, "nonexistent")
+    assert_rpc_error response, code: -32_601
+  end
+
+  def test_notification
+    assert_rpc_notification server, "add", params: [1, 2]
+  end
+end
+```
+
+## Development
+
+```bash
+bin/setup       # Install dependencies
+rake test       # Run tests
+rake rubocop    # Run linter
+rake            # Run both
+bin/console     # Interactive console
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rubakas/ultimate_json_rpc.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/examples/error_handling.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Error handling patterns
+#
+# Run: ruby examples/error_handling.rb
+
+require "ultimate_json_rpc"
+require "ultimate_json_rpc/extras/logging"
+require "json"
+require "logger"
+
+module BankService
+  def self.transfer(from:, to:, amount:)
+    raise UltimateJsonRpc::Core::ApplicationError.new(code: 1001, message: "Insufficient funds", data: { balance: 50 }) if amount > 100
+    raise UltimateJsonRpc::Core::ApplicationError.new(code: 1002, message: "Account frozen") if from == "frozen"
+
+    { from:, to:, amount:, status: "completed" }
+  end
+end
+
+server = UltimateJsonRpc::Server.new(name: "Bank API", version: "1.0", expose_errors: true)
+server.expose(BankService, descriptions: { transfer: "Transfer money between accounts" })
+server.register_error(code: 1001, message: "InsufficientFunds", description: "Account balance too low for transfer")
+server.register_error(code: 1002, message: "AccountFrozen", description: "Account is frozen and cannot transact")
+UltimateJsonRpc::Extras::Logging.new(server, Logger.new($stdout, level: :info))
+
+# Successful transfer
+puts "=== Successful transfer ==="
+puts server.handle(JSON.generate({
+  "jsonrpc" => "2.0", "method" => "transfer",
+  "params" => { "from" => "alice", "to" => "bob", "amount" => 50 }, "id" => 1
+}))
+
+# Application error — insufficient funds
+puts "\n=== Insufficient funds ==="
+puts server.handle(JSON.generate({
+  "jsonrpc" => "2.0", "method" => "transfer",
+  "params" => { "from" => "alice", "to" => "bob", "amount" => 200 }, "id" => 2
+}))
+
+# Application error — frozen account
+puts "\n=== Frozen account ==="
+puts server.handle(JSON.generate({
+  "jsonrpc" => "2.0", "method" => "transfer",
+  "params" => { "from" => "frozen", "to" => "bob", "amount" => 10 }, "id" => 3
+}))
+
+# Method not found
+puts "\n=== Method not found ==="
+puts server.handle(JSON.generate({ "jsonrpc" => "2.0", "method" => "withdraw", "id" => 4 }))