jsonrpc-middleware 0.1.0 → 0.2.0

data/.claude/settings.local.json

@@ -2,7 +2,8 @@
   "permissions": {
     "allow": [
       "Bash(bundle exec rspec:*)",
-      "Bash(bundle exec rubocop:*)"
+      "Bash(bundle exec rubocop:*)",
+      "Bash(bundle exec rake:*)"
     ]
   },
   "enableAllProjectMcpServers": false

data/.env.example

@@ -0,0 +1,5 @@
+# Whether the code coverage is displayed in the terminal after the test run
+COVERAGE=false
+
+# Enable debug mode for Zeitwerk autoloader (shows file loading activity)
+DEBUG_ZEITWERK=false

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2025-07-10
+
+### Added
+- Rails support via Railtie for automatic middleware registration
+- Configuration options for logging, internal error handling, and error rendering
+- Complete YARD documentation for all public APIs
+- Rails application examples (single-file and full application)
+- Sinatra application examples (classic and modular styles)
+- Pure Rack application examples
+- AI development guidelines for Claude Code, Copilot, and Cursor
+
+### Changed
+- Enhanced helper methods with improved framework-agnostic support
+- Improved error handling with configurable logging capabilities
+- Updated development dependencies for better compatibility
+
+### Fixed
+- Method parameter handling in Rack examples
+
 ## [0.1.0] - 2025-06-14
 
 ### Added
@@ -33,5 +52,6 @@ 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
 
-[Unreleased]: https://github.com/wilsonsilva/jsonrpc-middleware/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/wilsonsilva/jsonrpc-middleware/releases/tag/v0.1.0
+[Unreleased]: https://github.com/wilsonsilva/jsonrpc-middleware/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/wilsonsilva/jsonrpc-middleware/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/wilsonsilva/jsonrpc-middleware/compare/745b5a...v0.1.0

data/CLAUDE.md

@@ -0,0 +1,114 @@
+# CLAUDE.md
+
+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

data/README.md

@@ -1,9 +1,9 @@
-# JSONRPC::Middleware - Ruby JSON-RPC Implementation
+# JSONRPC::Middleware
 
 [![Gem Version](https://badge.fury.io/rb/jsonrpc-middleware.svg)](https://badge.fury.io/rb/jsonrpc-middleware)
 ![Build](https://github.com/wilsonsilva/jsonrpc-middleware/actions/workflows/main.yml/badge.svg)
-[![Maintainability](https://qlty.sh/badges/73ebc4bb-d1db-4b5b-9a7c-a4acd59dfe69/maintainability.svg)](https://qlty.sh/gh/wilsonsilva/projects/jsonrpc-middleware)
-[![Code Coverage](https://qlty.sh/badges/73ebc4bb-d1db-4b5b-9a7c-a4acd59dfe69/test_coverage.svg)](https://qlty.sh/gh/wilsonsilva/projects/jsonrpc-middleware)
+[![Maintainability](https://qlty.sh/badges/a275de81-94e3-45af-9469-523aa5345871/maintainability.svg)](https://qlty.sh/gh/wilsonsilva/projects/jsonrpc-middleware)
+[![Code Coverage](https://qlty.sh/badges/a275de81-94e3-45af-9469-523aa5345871/test_coverage.svg)](https://qlty.sh/gh/wilsonsilva/projects/jsonrpc-middleware)
 
 A Ruby implementation of the JSON-RPC protocol, enabling standardized communication between systems via remote procedure
 calls encoded in JSON.
@@ -13,63 +13,52 @@ calls encoded in JSON.
 - [Key features](#-key-features)
 - [Installation](#-installation)
 - [Quickstart](#-quickstart)
+- [Examples](#-examples)
 - [Documentation](#-documentation)
 - [Development](#-development)
-  * [Type checking](#type-checking)
+  * [Type checking](#-type-checking)
 - [Contributing](#-contributing)
 - [License](#-license)
 - [Code of Conduct](#-code-of-conduct)
 
 ## 🔑 Key features
 
-- **Complete JSON-RPC 2.0 Implementation**: Fully implements the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification)
-- **Rack Middleware integration**: Seamlessly integrates with Rack applications
-- **Advanced request validation**: Define request parameter specifications and validations using `Dry::Validation`
+- **Spec-compliant**: Fully implements the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification)
+- **Rack middleware integration**: Seamlessly integrates with Rack applications (Rails, Sinatra, Hanami, etc)
 - **Support for all request types**: Handles single requests, notifications, and batch requests
-- **Parameter validation**: Supports both positional and named arguments with customizable validation rules
 - **Error handling**: Comprehensive error handling with standard JSON-RPC error responses
-- **Helper methods**: Convenient helper methods to simplify request and response processing
-- **Type checking**: Ruby type checking support via RBS definitions
+- **Request validation**: Define request parameter specifications and validations
+- **Helpers**: Convenient helper methods to simplify request and response processing
 
 ## 📦 Installation
 
-Install the gem by executing:
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add jsonrpc-middleware
+
+If bundler is not being used to manage dependencies, install the gem by executing:
 
     $ gem install jsonrpc-middleware
 
 ## ⚡️ Quickstart
 
-### Basic Setup with Rack
+Create a file called `config.ru` and run `bundle exec rackup`:
 
 ```ruby
-# Gemfile
-source 'https://rubygems.org'
-gem 'jsonrpc-middleware'
-gem 'rack'
-```
-
-```ruby
-# config.ru
-require 'jsonrpc'
-require_relative 'app'
-
-# Use the middleware
-use JSONRPC::Middleware
+# frozen_string_literal: true
 
-# Your application
-run App.new
-```
+require 'bundler/inline'
 
-### Define Your JSON-RPC Procedures
+gemfile do
+  source 'https://rubygems.org'
 
-Define your available procedures with validation rules:
-
-```ruby
-# procedures.rb
-require 'jsonrpc'
+  gem 'jsonrpc-middleware', require: 'jsonrpc'
+  gem 'puma'
+  gem 'rack'
+  gem 'rackup'
+end
 
 JSONRPC.configure do
-  # Define a procedure that accepts both positional and named arguments
   procedure(:add, allow_positional_arguments: true) do
     params do
       required(:addends).filled(:array)
@@ -80,37 +69,21 @@ JSONRPC.configure do
       key.failure('must contain at least one addend') if value.empty?
     end
   end
-
-  # Define a procedure with named arguments only
-  procedure(:subtract) do
-    params do
-      required(:minuend).filled(:integer)
-      required(:subtrahend).filled(:integer)
-    end
-  end
 end
-```
-
-### Create Your Application
 
-```ruby
-# app.rb
 class App
   include JSONRPC::Helpers
 
   def call(env)
-    @env = env # Set the env instance variable to use JSONRPC helpers
+    @env = env
 
     if jsonrpc_request?
-      # Handle a standard JSON-RPC request
       result = handle_single(jsonrpc_request)
       jsonrpc_response(result)
     elsif jsonrpc_notification?
-      # Handle a notification (no response needed)
       handle_single(jsonrpc_notification)
       jsonrpc_notification_response
     else
-      # Handle batch requests
       responses = handle_batch(jsonrpc_batch)
       jsonrpc_batch_response(responses)
     end
@@ -121,68 +94,34 @@ class App
   def handle_single(request_or_notification)
     params = request_or_notification.params
 
-    case request_or_notification.method
-    when 'add'
-      # Handle both positional and named arguments
-      addends = params.is_a?(Array) ? params : params['addends']
-      addends.sum
-    when 'subtract'
-      params['minuend'] - params['subtrahend']
-    end
+    addends = params.is_a?(Array) ? params : params['addends'] # Handle positional and named arguments
+    addends.sum
   end
 
   def handle_batch(batch)
     batch.flat_map do |request_or_notification|
       result = handle_single(request_or_notification)
-      # Only create responses for requests, not notifications
-      JSONRPC::Response.new(id: request_or_notification.id, result: result) if request_or_notification.is_a?(JSONRPC::Request)
+      JSONRPC::Response.new(id: request_or_notification.id, result:) if request_or_notification.is_a?(JSONRPC::Request)
     end.compact
   end
 end
-```
 
-### Example Requests
-
-Here are example JSON-RPC requests you can make to your application:
-
-```json
-// Standard request with named params
-{
-  "jsonrpc": "2.0",
-  "method": "subtract",
-  "params": {
-    "minuend": 42,
-    "subtrahend": 23
-  },
-  "id": 1
-}
-
-// Request with positional params (if allowed)
-{
-  "jsonrpc": "2.0",
-  "method": "add",
-  "params": [1, 2, 3, 4, 5],
-  "id": 2
-}
-
-// Notification (no response)
-{
-  "jsonrpc": "2.0",
-  "method": "add",
-  "params": {"addends": [1, 2, 3]}
-}
-
-// Batch request
-[
-  {"jsonrpc": "2.0", "method": "add", "params": {"addends": [1, 2]}, "id": 1},
-  {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 10, "subtrahend": 5}, "id": 2}
-]
+use JSONRPC::Middleware
+run App.new
 ```
 
+This will give you a fully-featured JSON-RPC server.
+
+For more advanced setups, check the [examples](https://github.com/wilsonsilva/jsonrpc-middleware/blob/main/examples/README.md).
+
 ## 📚 Documentation
 
 - [YARD documentation](https://rubydoc.info/gems/jsonrpc-middleware)
 
+## 📜 Examples
+
+Examples for the most common Rack-based applications, including Rails and Sinatra can be found [here](https://github.com/wilsonsilva/jsonrpc-middleware/blob/main/examples/README.md)
+
 ## 🔨 Development
 
 After checking out the repo, run `bin/setup` to install dependencies.
@@ -200,7 +139,7 @@ Rake tasks to test, lint and audit the gem for security vulnerabilities and docu
 
 ```
 rake build                    # Build jsonrpc-middleware.gem into the pkg directory
-rake build:checksum           # Generate SHA512 checksum if jsonrpc-middleware.gem into the checksums directory
+rake build:checksum           # Generate SHA512 checksum of jsonrpc-middleware.gem into the checksums directory
 rake bundle:audit:check       # Checks the Gemfile.lock for insecure dependencies
 rake bundle:audit:update      # Updates the bundler-audit vulnerability database
 rake clean                    # Remove any temporary products
@@ -209,18 +148,19 @@ rake coverage                 # Run spec with coverage
 rake install                  # Build and install jsonrpc-middleware.gem into system gems
 rake install:local            # Build and install jsonrpc-middleware.gem into system gems without network access
 rake qa                       # Test, lint and perform security and documentation audits
-rake release[remote]          # Create a tag, build and push jsonrpc-middleware.gem to rubygems.org
+rake release[remote]          # Create tag v0.1.0 and build and push jsonrpc-middleware-0.1.0.gem to rubygems.org
 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
 ```
 
-### Type checking
+### 🧪 Type checking
 
 This gem leverages [RBS](https://github.com/ruby/rbs), a language to describe the structure of Ruby programs. It is
 used to provide type checking and autocompletion in your editor. Run `bundle exec typeprof FILENAME` to generate

data/Rakefile

@@ -20,7 +20,7 @@ end
 YARD::Rake::YardocTask.new
 YardJunk::Rake.define_task
 Yardstick::Rake::Measurement.new(:yardstick_measure, yardstick_options)
-Yardstick::Rake::Verify.new
+Yardstick::Rake::Verify.new(:verify_measurements, yardstick_options)
 
 task default: %i[spec rubocop]
 
@@ -39,3 +39,61 @@ end
 
 desc 'Test, lint and perform security and documentation audits'
 task qa: %w[spec rubocop yard:junk verify_measurements bundle:audit]
+
+namespace :yard do
+  desc 'Format YARD documentation'
+  task :format do
+    require 'fileutils'
+
+    ruby_files = Dir.glob(File.join(Dir.pwd, 'lib', '**', '*.rb'))
+
+    puts "Found #{ruby_files.length} Ruby files in lib directory"
+    puts
+
+    ruby_files.each do |file_path|
+      puts "Processing #{file_path}..."
+
+      content = File.read(file_path)
+      lines = content.split("\n")
+      result = []
+
+      lines.each_with_index do |line, index|
+        result << line
+
+        current_is_yard = line.strip.match?(/^\s*#\s*@\w+/)
+        next_line_exists = index + 1 < lines.length
+
+        # Process YARD tag spacing
+        next unless current_is_yard && next_line_exists
+
+        next_line = lines[index + 1]
+
+        next unless next_line.strip.match?(/^\s*#\s*@\w+/)
+
+        current_tag = line.strip.match(/^\s*#\s*@(\w+)/)[1]
+        next_tag = next_line.strip.match(/^\s*#\s*@(\w+)/)[1]
+
+        groupable = %w[param option]
+        should_group = groupable.include?(current_tag) && groupable.include?(next_tag)
+
+        # Add blank line between different tag types
+        unless should_group
+          indentation = line.match(/^(\s*)/)[1]
+          result << "#{indentation}#"
+        end
+      end
+
+      formatted_content = "#{result.join("\n")}\n"
+
+      if content == formatted_content
+        puts '  - No changes needed'
+      else
+        File.write(file_path, formatted_content)
+        puts '  ✓ Updated'
+      end
+    end
+
+    puts
+    puts 'Done!'
+  end
+end

data/examples/README.md

@@ -0,0 +1,37 @@
+# Examples
+
+This directory contains example implementations of JSON-RPC servers using the jsonrpc-middleware gem with different Ruby web frameworks.
+
+## Examples
+
+- [**rack-echo**](./rack-echo/) - Echo server using Rack with helpers
+- [**rack-single-file**](./rack-single-file/) - Minimal single-file example with bundler/inline
+- [**rack**](./rack/) - Calculator server using pure Rack
+- [**rails**](./rails-single-file/) - Calculator server using Rails
+- [**rails-single-file**](./rails-single-file/) - Echo server using Rails with bundler/inline
+- [**sinatra-classic**](./sinatra-classic/) - Calculator server using classic Sinatra
+- [**sinatra-modular**](./sinatra-modular/) - Calculator server using modular Sinatra
+
+## Common Procedures
+
+Most examples implement a calculator API with these procedures:
+
+- `add` - Add numbers (supports both positional and named arguments)
+- `subtract` - Subtract two numbers
+- `multiply` - Multiply two numbers
+- `divide` - Divide two numbers
+- `explode` - Test procedure that throws an error
+
+The echo examples implement:
+
+- `echo` - Returns the input message
+
+## Running Examples
+
+Each example directory contains its own README with specific instructions. Generally:
+
+```sh
+cd <example-directory>
+bundle install  # if Gemfile present
+bundle exec rackup  # or ruby app.rb for Sinatra classic
+```

data/examples/procedures.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
-JSONRPC.configure do
+JSONRPC.configure do |config|
+  config.log_internal_errors = true           # Log internal error backtraces (default: true)
+  config.log_request_validation_errors = true # Log JSON-RPC request validation errors (default: false)
+  config.render_internal_errors = true        # Render detailed internal error information in responses (default: true)
+  config.rescue_internal_errors = true        # Handle and serialize internal errors (default: true)
+
   # Allow positional and named arguments
   procedure(:add, allow_positional_arguments: true) do
     params do

data/examples/rack/README.md

@@ -1,7 +1,32 @@
-# Rack
+# Rack Calculator
+
+A JSON-RPC calculator server using pure Rack with JSONRPC helpers.
 
 ## Running
 
 ```sh
+bundle install
 bundle exec rackup
 ```
+
+## API
+
+The server implements a calculator with these procedures:
+
+- `add` - Add numbers (supports both positional and named arguments)
+- `subtract` - Subtract two numbers  
+- `multiply` - Multiply two numbers
+- `divide` - Divide two numbers
+- `explode` - Test procedure that throws an error
+
+## Example Requests
+
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "add", "params": {"addends": [1, 2, 3]}, "id": 1}'
+
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "divide", "params": {"dividend": 20, "divisor": 4}, "id": 4}'
+```

data/examples/rack/app.rb

@@ -26,7 +26,7 @@ class App
 
     case request_or_notification.method
     when 'add'
-      addends = params.is_a?(Array) ? params : { addends: params } # Handle positional and named arguments
+      addends = params.is_a?(Array) ? params : params['addends'] # Handle positional and named arguments
       addends.sum
     when 'subtract'
       params['minuend'] - params['subtrahend']

data/examples/rack-echo/README.md

@@ -1,7 +1,29 @@
-# Rack
+# Rack Echo Server
+
+A simple JSON-RPC echo server using Rack with JSONRPC helpers.
 
 ## Running
 
 ```sh
+bundle install
 bundle exec rackup
 ```
+
+## API
+
+The server implements a single procedure:
+
+- `echo` - Returns the input message
+
+## Example Requests
+
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "echo", "params": {"message": "Hello, world!"}, "id": 1}'
+
+# Notification (no response)
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "echo", "params": {"message": "Hello, world!"}}'
+```

data/examples/rack-single-file/README.md

@@ -0,0 +1,37 @@
+# Rack Single File Echo Server
+
+A minimal single-file JSON-RPC echo server using bundler/inline for dependencies.
+
+## Running
+
+```sh
+rackup
+```
+
+## API
+
+The server implements a single procedure:
+
+- `echo` - Returns the input message
+
+## Features
+
+- Uses `bundler/inline` to define dependencies inline
+- Self-contained in a single `config.ru` file
+- Supports single requests, notifications, and batch requests
+
+## Example Requests
+
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "echo", "params": {"message": "Hello!"}, "id": 1}'
+
+# Batch request
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '[
+    {"jsonrpc": "2.0", "method": "echo", "params": {"message": "ping"}, "id": 1},
+    {"jsonrpc": "2.0", "method": "echo", "params": {"message": "pong"}}
+  ]'
+```