jsonrpc-middleware 0.5.0 → 0.7.0

data/AGENTS.md

@@ -0,0 +1,142 @@
+# AGENTS.md
+
+This file provides guidance to AI agents when working with code in this repository.
+
+## Development Commands
+
+### Testing
+- `bundle exec rspec` - Run all tests
+- `bundle exec rspec spec/path/to/spec.rb` - Run specific test file
+- `bundle exec rake coverage` - Run tests with test coverage and write a LLM-friendly report in `coverage/report.md`
+
+### Code Quality
+- `bundle exec rake qa` - Complete quality check (tests, linting, security, docs)
+- `bundle exec rubocop` - Run Ruby linter
+- `bundle exec rubocop --autocorrect` - Auto-fix safe Ruby style issues
+- `bundle exec rubocop --autocorrect-all` - Auto-fix all Ruby style issues
+- `bundle exec steep check` - Run type checking with Steep/RBS
+
+### Security & Dependencies
+- `bundle exec rake bundle:audit:check` - Check for vulnerable dependencies
+- `bundle exec rake bundle:audit:update` - Update vulnerability database
+
+### Documentation
+- `bundle exec rake yard` - Generate YARD documentation
+- `bundle exec rake yard:format` - Format YARD comments in code
+- `bundle exec rake yard:lint` - Lint YARD comments for issues
+
+### Build & Release
+- `bundle exec rake build` - Build gem package
+- `bundle exec rake install` - Install gem locally
+- `bin/console` - Interactive console with gem loaded
+
+### Containerized development (cloud agents)
+
+A ready-to-develop container is defined by `Dockerfile` and `.devcontainer/devcontainer.json`
+(Ruby 4.0.5 + the full dev toolchain). Cloud agent platforms / Codespaces consume the
+devcontainer directly. Locally:
+
+- `docker build -t jsonrpc-middleware-dev .`
+- `docker run --rm -it -v "$PWD":/app jsonrpc-middleware-dev bash`
+- Inside the container: `bundle exec rake qa`, `bundle exec rspec`, `bundle exec steep check`.
+
+To run an example app on Linux, first add Linux platforms to that example's lockfile:
+`cd examples/<name> && bundle lock --add-platform x86_64-linux aarch64-linux && bundle install`.
+
+## Architecture Overview
+
+### Core Components
+
+**JSONRPC Module** (`lib/jsonrpc.rb`)
+- Main entry point with configuration DSL
+- Uses Zeitwerk for autoloading with specific inflection rules
+- Singleton Configuration pattern for procedure definitions
+
+**Middleware** (`lib/jsonrpc/middleware.rb`)
+- Rack middleware implementing JSON-RPC 2.0 specification
+- Handles parsing, validation, and error responses
+- Supports single requests, notifications, and batch operations
+- Complex batch processing with mixed error/success handling
+
+**Parser** (`lib/jsonrpc/parser.rb`)
+- Converts JSON strings into Request/Notification/BatchRequest objects
+- Handles malformed JSON and invalid request structures
+
+**Validator** (`lib/jsonrpc/validator.rb`)
+- Validates requests against procedure definitions using dry-validation
+- Supports both positional and named parameters
+- Handles method existence and parameter validation
+
+**Helpers** (`lib/jsonrpc/helpers.rb`)
+- Framework-agnostic helper methods for apps
+- Provides convenience methods for checking request types
+- Response generation helpers for different scenarios
+
+### Request/Response Objects
+- `Request` - Standard JSON-RPC request with id
+- `Notification` - Request without id (no response expected)
+- `BatchRequest` - Collection of requests/notifications
+- `Response` - JSON-RPC response with result or error
+- `BatchResponse` - Collection of responses
+
+### Error System
+Structured error hierarchy in `lib/jsonrpc/errors/`:
+- `ParseError` (-32700) - Invalid JSON
+- `InvalidRequestError` (-32600) - Invalid request object
+- `MethodNotFoundError` (-32601) - Method not found
+- `InvalidParamsError` (-32602) - Invalid parameters
+- `InternalError` (-32603) - Server error
+
+### Configuration DSL
+```ruby
+JSONRPC.configure do
+  procedure('method_name') do
+    params do
+      required(:param).value(:type)
+    end
+
+    rule(:param) do
+      # Custom validation rules
+    end
+  end
+end
+```
+
+## Type System
+
+The project uses RBS (Ruby Type Signatures) with Steep for type checking:
+- Type definitions in `sig/` directory
+- Run `bundle exec steep check` for type validation
+- Generate types with `bundle exec typeprof FILENAME`
+
+### Third-party RBS signatures (RBS collection)
+
+Signatures for third-party gems are managed with the RBS collection:
+- `rbs_collection.yaml` declares the requested gems (activesupport, dry-struct,
+  dry-validation, multi_json, zeitwerk) and the `ruby/gem_rbs_collection` source.
+- `rbs_collection.lock.yaml` pins the resolved versions and revisions (committed).
+- `bundle exec rbs collection install` downloads them into `.gem_rbs_collection/`
+  (gitignored). Run this after cloning, before `bundle exec steep check`.
+- `bundle exec rbs collection update` re-resolves and refreshes the lock file when
+  adding a gem to `rbs_collection.yaml` or bumping sources.
+
+Steep loads the collection automatically via the lock file. A few gems still have
+hand-written stubs in `sig/` (e.g. `sig/zeitwerk.rbs`, `sig/multi_json.rbs`) where the
+collection's coverage is incomplete for this project's usage.
+
+## Examples
+
+Comprehensive examples in `examples/` directory showing integration with:
+- Pure Rack applications
+- Sinatra (classic and modular)
+- Single-file applications with bundler/inline
+
+Each example implements calculator operations (add, subtract, multiply, divide) demonstrating different usage patterns.
+
+## Testing Strategy
+
+- RSpec with comprehensive test coverage
+- Factory Bot for test data generation
+- Rack::Test for middleware testing
+- SimpleCov for coverage reporting with multiple formatters
+- Examples include both unit and integration tests

data/CHANGELOG.md

@@ -5,6 +5,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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-06-01
+
+### Added
+- Configurable `Logger` support for JSON-RPC components
+  - `JSONRPC.configuration.logger` (defaults to `Logger.new($stdout, progname: 'JSONRPC')`)
+  - `JSONRPC::Middleware` accepts a `:logger` option and uses it for internal-error and validation logging
+- Development container support (`.devcontainer`, `Dockerfile`, `.dockerignore`)
+
+### Changed
+- Updated Ruby to v4.0.5
+- Updated Bundler to v4.0.8
+- Updated runtime dependencies
+  - `multi_json` to `~> 1.21` (removed the local `JSON::Ext::Generator::State#except` workaround now that the upstream fix has shipped)
+  - `zeitwerk` to `~> 2.8`
+- Replaced the README architecture diagram (Mermaid) with an inline SVG
+- Replaced yardstick/yard-junk with yard-lint for documentation linting
+- Achieved 100% test coverage
+
+## [0.6.0] - 2025-09-17
+
+### Added
+- MultiJson support for improved JSON performance and flexibility
+  - Configuration option to select JSON adapter (`JSONRPC.configuration.json_adapter`)
+  - Enhanced error handling with adapter and input preview details
+  - Better performance through optimized JSON parsing
+- Enhanced examples
+  - Batch JSON-RPC request handling in Rails single-file routing example
+  - Smart home control API example using Rails routing DSL
+  - Updated documentation with batch request usage examples
+
+### Changed
+- Replaced JSON gem with MultiJson throughout the codebase
+  - All JSON parsing now uses MultiJson for better adapter support
+  - Updated documentation to mention optimized JSON handling
+- Refactored Request and Response classes to use dry-struct
+  - Simplified class definitions with automatic type checking
+  - Reduced code complexity while maintaining functionality
+- Enhanced Rails integration
+  - Improved example applications with better error handling
+  - Updated Gemfile.lock files across all examples
+
 ## [0.5.0] - 2025-07-22
 
 ### Added
@@ -135,6 +176,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Helper methods for request and response processing
 - Examples for basic and advanced usage scenarios
 
+[0.7.0]: https://github.com/wilsonsilva/jsonrpc-middleware/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/wilsonsilva/jsonrpc-middleware/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/wilsonsilva/jsonrpc-middleware/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/wilsonsilva/jsonrpc-middleware/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/wilsonsilva/jsonrpc-middleware/compare/v0.2.0...v0.3.0

data/CLAUDE.md

@@ -1,114 +1,3 @@
-# CLAUDE.md
+# Claude Code Instructions
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Development Commands
-
-### Testing
-- `bundle exec rspec` - Run all tests
-- `bundle exec rspec spec/path/to/spec.rb` - Run specific test file
-- `rake coverage` - Run tests with coverage report (opens in browser)
-
-### Code Quality
-- `bundle exec rake qa` - Complete quality check (tests, linting, security, docs)
-- `bundle exec rubocop` - Run Ruby linter
-- `bundle exec rubocop --autocorrect` - Auto-fix safe Ruby style issues  
-- `bundle exec rubocop --autocorrect-all` - Auto-fix all Ruby style issues
-- `bundle exec steep check` - Run type checking with Steep/RBS
-
-### Security & Dependencies
-- `bundle exec rake bundle:audit:check` - Check for vulnerable dependencies
-- `bundle exec rake bundle:audit:update` - Update vulnerability database
-
-### Documentation
-- `bundle exec rake yard` - Generate YARD documentation
-- `bundle exec rake yard:format` - Format YARD comments in code
-- `bundle exec rake verify_measurements` - Verify 100% documentation coverage
-
-### Build & Release
-- `bundle exec rake build` - Build gem package
-- `bundle exec rake install` - Install gem locally
-- `bin/console` - Interactive console with gem loaded
-
-## Architecture Overview
-
-### Core Components
-
-**JSONRPC Module** (`lib/jsonrpc.rb`)
-- Main entry point with configuration DSL
-- Uses Zeitwerk for autoloading with specific inflection rules
-- Singleton Configuration pattern for procedure definitions
-
-**Middleware** (`lib/jsonrpc/middleware.rb`)
-- Rack middleware implementing JSON-RPC 2.0 specification
-- Handles parsing, validation, and error responses
-- Supports single requests, notifications, and batch operations
-- Complex batch processing with mixed error/success handling
-
-**Parser** (`lib/jsonrpc/parser.rb`)
-- Converts JSON strings into Request/Notification/BatchRequest objects
-- Handles malformed JSON and invalid request structures
-
-**Validator** (`lib/jsonrpc/validator.rb`)
-- Validates requests against procedure definitions using dry-validation
-- Supports both positional and named parameters
-- Handles method existence and parameter validation
-
-**Helpers** (`lib/jsonrpc/helpers.rb`)
-- Framework-agnostic helper methods for apps
-- Provides convenience methods for checking request types
-- Response generation helpers for different scenarios
-
-### Request/Response Objects
-- `Request` - Standard JSON-RPC request with id
-- `Notification` - Request without id (no response expected)
-- `BatchRequest` - Collection of requests/notifications
-- `Response` - JSON-RPC response with result or error
-- `BatchResponse` - Collection of responses
-
-### Error System
-Structured error hierarchy in `lib/jsonrpc/errors/`:
-- `ParseError` (-32700) - Invalid JSON
-- `InvalidRequestError` (-32600) - Invalid request object
-- `MethodNotFoundError` (-32601) - Method not found
-- `InvalidParamsError` (-32602) - Invalid parameters
-- `InternalError` (-32603) - Server error
-
-### Configuration DSL
-```ruby
-JSONRPC.configure do
-  procedure('method_name') do
-    params do
-      required(:param).value(:type)
-    end
-    
-    rule(:param) do
-      # Custom validation rules
-    end
-  end
-end
-```
-
-## Type System
-
-The project uses RBS (Ruby Type Signatures) with Steep for type checking:
-- Type definitions in `sig/` directory
-- Run `bundle exec steep check` for type validation
-- Generate types with `bundle exec typeprof FILENAME`
-
-## Examples
-
-Comprehensive examples in `examples/` directory showing integration with:
-- Pure Rack applications
-- Sinatra (classic and modular)
-- Single-file applications with bundler/inline
-
-Each example implements calculator operations (add, subtract, multiply, divide) demonstrating different usage patterns.
-
-## Testing Strategy
-
-- RSpec with comprehensive test coverage
-- Factory Bot for test data generation
-- Rack::Test for middleware testing
-- SimpleCov for coverage reporting with multiple formatters
-- Examples include both unit and integration tests
+See [AGENTS.md](./AGENTS.md) for all contribution guidelines.

data/Dockerfile

@@ -0,0 +1,144 @@
+# syntax=docker/dockerfile:1
+#
+# Development image for the jsonrpc-middleware gem.
+# ============================================================================
+# This image is a *development environment* for AI agents (and humans) who work
+# ON the gem — not a *production runtime* that ships the gem to end users.
+#
+# That single fact inverts most of the usual Docker advice:
+#   - We do NOT use a multi-stage build or a distroless final stage. The whole
+#     point is to keep the full toolchain available — compilers, git, and every
+#     development gem (RSpec, RuboCop, Steep, YARD, bundler-audit, Guard, ...) —
+#     so an agent can run the test/lint/type-check/audit suite and rebuild or
+#     install native gems on demand. Slimming those away would defeat the image.
+#   - Optimising for a tiny final image is therefore a non-goal; optimising for
+#     "everything an agent needs is already here and reproducible" is the goal.
+# ============================================================================
+
+# Why this exact base:
+#   - ruby:4.0.5  -> `.tool-versions` pins Ruby 4.0.5 as the repo's canonical
+#     version (CI runs on it too). The gemspec only requires `>= 3.4.0`, but the
+#     container must match the pinned version to faithfully reproduce CI results
+#     — otherwise an agent could see green/red locally that disagrees with CI.
+#   - -slim       -> Debian-slim: small, but still glibc + `apt`. We deliberately
+#     avoid Alpine here: Alpine's musl libc forces many native gems to recompile
+#     from source (slower builds) and occasionally behaves differently from the
+#     glibc CI environment. Debian-slim keeps us byte-for-byte closer to CI while
+#     letting us add only the few build packages we actually need.
+FROM ruby:4.0.5-slim
+
+# System packages. Each line below earns its place — nothing here is "just in
+# case", because every package widens the image and the attack surface:
+#   build-essential, pkg-config  Compile native gem extensions when a gem has no
+#                                precompiled platform build (or an agent adds one
+#                                later). Most deps resolve to precompiled gems,
+#                                but the toolchain must be present so `bundle
+#                                install` never dead-ends.
+#   git                          Required for THREE distinct reasons:
+#                                  1. `yard-lint` is sourced from GitHub in the
+#                                     Gemfile (`github: 'mensfeld/yard-lint'`),
+#                                     so bundler git-clones it during install.
+#                                  2. `overcommit --install` (run by bin/setup in
+#                                     the devcontainer) writes git hooks.
+#                                  3. The gemspec calls `git ls-files` to build
+#                                     its file list.
+#   libyaml-dev                  Psych (Ruby's YAML) links against libyaml; tools
+#                                and configs throughout the stack parse YAML.
+#   curl, ca-certificates        TLS roots + a fetch tool for rubygems.org and
+#                                the bundler-audit advisory database.
+# `--no-install-recommends` skips suggested extras; deleting the apt lists in the
+# same layer keeps this layer from carrying ~tens of MB of package indexes.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      build-essential \
+      ca-certificates \
+      curl \
+      git \
+      libyaml-dev \
+      pkg-config \
+ && rm -rf /var/lib/apt/lists/*
+
+# Pin bundler to the version recorded in Gemfile.lock's `BUNDLED WITH` (4.0.8).
+# Bundler is sensitive to this: a mismatched bundler can re-resolve or warn, which
+# undermines the whole point of a locked, reproducible dependency set. Matching it
+# keeps installs identical to what a contributor (and CI) get.
+RUN gem install bundler -v 4.0.8
+
+# Build/runtime environment:
+#   BUNDLE_JOBS=4   Install gems in parallel — meaningfully faster on multi-core
+#                   cloud builders.
+#   BUNDLE_RETRY=3  Retry a gem fetch up to 3x; absorbs transient network blips
+#                   that would otherwise fail an unattended cloud build.
+#   LANG=C.UTF-8    Slim images ship with no locale, so Ruby's default external
+#                   encoding would be US-ASCII and choke on non-ASCII I/O. Force
+#                   UTF-8 to avoid Encoding errors in tooling and specs.
+ENV BUNDLE_JOBS=4 \
+    BUNDLE_RETRY=3 \
+    LANG=C.UTF-8
+
+# Conventional, stable workdir. The devcontainer bind-mounts the live repo here
+# (see .devcontainer/devcontainer.json -> workspaceFolder/workspaceMount).
+WORKDIR /app
+
+# Run as a non-root user (security: containers should not run as root). UID/GID
+# 1000 is chosen on purpose — it's the first non-root user on most Linux hosts
+# and CI runners, so files created in a bind-mounted workspace get sane, non-root
+# ownership on the host instead of being owned by root.
+RUN groupadd --gid 1000 dev \
+ && useradd --uid 1000 --gid 1000 --create-home --shell /bin/bash dev
+
+# --- Dependency layer --------------------------------------------------------
+# Copy ONLY the dependency manifests before the source so this (expensive) layer
+# is cached and re-runs only when dependencies change — not on every code edit.
+#
+# Why the gemspec AND lib/jsonrpc/version.rb are needed here: the Gemfile's
+# `gemspec` directive evaluates jsonrpc-middleware.gemspec at install time, and
+# that file `require_relative`s lib/jsonrpc/version.rb (for `spec.version`). Both
+# must be present or `bundle install` fails before it ever reads the lock.
+# (The gemspec also runs `git ls-files`; with .git excluded via .dockerignore it
+# simply returns an empty file list — harmless, because the *dependencies* come
+# from the `add_dependency` lines, not from `spec.files`.)
+COPY Gemfile Gemfile.lock jsonrpc-middleware.gemspec ./
+COPY lib/jsonrpc/version.rb lib/jsonrpc/version.rb
+
+# Why add Linux platforms: the committed Gemfile.lock was generated on macOS and
+# historically listed only `arm64-darwin`. Bundler refuses to install for a
+# platform the lock doesn't name, so a Linux build would fail outright. Adding
+# x86_64-linux + aarch64-linux makes it resolve on both Intel and ARM Linux
+# (cloud runners and Docker on Apple silicon). These platforms are now also
+# committed to the repo's lockfile, so in normal builds this command is a no-op
+# — it stays here defensively so the image still builds from an older checkout.
+#
+# Gems install into the base image's GEM_HOME (/usr/local/bundle), which lives
+# OUTSIDE /app. That is deliberate and important: the devcontainer bind-mounts
+# the host repo over /app at runtime, which would shadow anything installed under
+# /app — but gems in /usr/local/bundle survive the mount, so the container is
+# ready to run the toolchain the instant it starts.
+RUN bundle lock --add-platform x86_64-linux aarch64-linux \
+ && bundle install
+
+# --- Source layer ------------------------------------------------------------
+# Bake a full copy of the repo so the image is usable standalone (e.g. plain
+# `docker run ... bundle exec rspec`). When used as a devcontainer, the live
+# bind-mount overlays this copy with the contributor's working tree.
+COPY . .
+
+# Hand ownership of both the workspace and the gem cache to the non-root user.
+# Chowning /usr/local/bundle is essential, not cosmetic: gems were installed as
+# root above, and without this the `dev` user could not install additional gems
+# at runtime (e.g. `bundle exec rake examples:bundle_install`) without sudo.
+RUN chown -R dev:dev /app /usr/local/bundle
+USER dev
+
+# Documentation only — EXPOSE does not publish ports. It records the ports the
+# example apps use, so an agent that boots one to manually verify behaviour knows
+# where to look: rack/sinatra examples listen on 9292, the Rails example on 3000.
+EXPOSE 9292 3000
+
+# Deliberately no HEALTHCHECK: this container runs dev commands, it does not serve
+# traffic, so there is no endpoint or process to health-check.
+
+# Default to an interactive shell for ad-hoc development. The devcontainer
+# overrides this with its own keep-alive command, so this CMD only matters for
+# direct `docker run` usage.
+CMD ["bash"]

data/README.md

@@ -41,24 +41,19 @@ A Rack middleware implementing the JSON-RPC 2.0 protocol that integrates easily
 - **Error handling**: Comprehensive error handling with standard JSON-RPC error responses
 - **Request validation**: Define request parameter specifications and validations
 - **Helpers**: Convenient helper methods to simplify request and response processing
+- **Optimized JSON handling**: Uses MultiJSON to automatically select the fastest available JSON library
 
 ## 🏗️ Architecture
 
 The gem integrates seamlessly into your Rack-based application:
 
-```mermaid
-block-beta
-  columns 4
-
-  App["Your app"]:4
-  Rails:1 Sinatra:1 RackApp["Other Rack-compatible framework"]:2
-  Middleware["JSON-RPC Middleware"]:4
-  Rack["Rack"]:4
-  HTTP["HTTP"]:4
-
-  classDef middlewareStyle fill:#ff6b6b,stroke:#d63031,stroke-width:2px,color:#fff
-  class Middleware middlewareStyle
-```
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./.github/images/architecture-diagram-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="./.github/images/architecture-diagram-light.svg">
+    <img alt="Architecture Diagram" src="./.github/images/architecture-diagram-light.svg" width="800" height="400" style="max-width: 100%;">
+  </picture>
+</p>
 
 ## 📦 Installation
 
@@ -96,7 +91,7 @@ JSONRPC.configure do
     end
 
     rule(:addends) do
-      key.failure('must contain at least one addend') if value.empty?
+      key.failure('must contain at least two addends') if value.size < 2
     end
   end
 end
@@ -184,11 +179,9 @@ rake rubocop                  # Run RuboCop
 rake rubocop:autocorrect      # Autocorrect RuboCop offenses (only when it's safe)
 rake rubocop:autocorrect_all  # Autocorrect RuboCop offenses (safe and unsafe)
 rake spec                     # Run RSpec code examples
-rake verify_measurements      # Verify that yardstick coverage is at least 100%
 rake yard                     # Generate YARD Documentation
 rake yard:format              # Format YARD documentation
-rake yard:junk                # Check the junk in your YARD Documentation
-rake yardstick_measure        # Measure docs in lib/**/*.rb with yardstick
+rake yard:lint                # Lint YARD documentation
 ```
 
 ### 🧪 Type checking