jsonrpc-middleware 0.2.0 → 0.4.0

data/README.md

@@ -1,12 +1,23 @@
-# JSONRPC::Middleware
+<p align="center">
+  <a href="https://jsonrpc-middleware.com" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="./.github/images/logo-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="./.github/images/logo-light.svg">
+      <img alt="JSON-RPC Middleware Logo" src="./.github/images/logo-light.svg" width="600" height="120" style="max-width: 100%;">
+    </picture>
+  </a>
+</p>
+
+<div align="center">
 
 [![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/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.
+</div>
+
+A Rack middleware implementing the JSON-RPC 2.0 protocol that integrates easily with all Rack-based applications (Rails, Sinatra, Hanami, etc).
 
 ## Table of contents
 
@@ -30,6 +41,24 @@ calls encoded in JSON.
 - **Request validation**: Define request parameter specifications and validations
 - **Helpers**: Convenient helper methods to simplify request and response processing
 
+## 🏗️ 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
+```
+
 ## 📦 Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -78,31 +107,26 @@ class App
     @env = env
 
     if jsonrpc_request?
-      result = handle_single(jsonrpc_request)
-      jsonrpc_response(result)
+      sum = add(jsonrpc_request.params)
+      jsonrpc_response(sum)
     elsif jsonrpc_notification?
-      handle_single(jsonrpc_notification)
+      add(jsonrpc_notification.params)
       jsonrpc_notification_response
     else
-      responses = handle_batch(jsonrpc_batch)
-      jsonrpc_batch_response(responses)
+      results = add_in_batches(jsonrpc_batch)
+      jsonrpc_batch_response(results)
     end
   end
 
   private
 
-  def handle_single(request_or_notification)
-    params = request_or_notification.params
-
+  def add(params)
     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)
-      JSONRPC::Response.new(id: request_or_notification.id, result:) if request_or_notification.is_a?(JSONRPC::Request)
-    end.compact
+  def add_in_batches(batch)
+    batch.process_each { |request_or_notification| add(request_or_notification.params) }
   end
 end
 
@@ -110,9 +134,14 @@ use JSONRPC::Middleware
 run App.new
 ```
 
-This will give you a fully-featured JSON-RPC server.
+This will give you a fully-featured JSON-RPC server, capable of:
+- Handling JSON-RPC requests, notifications __and batches__
+- Validating the allowed JSON-RPC methods (e.g. allow only `add`)
+- Validating the JSON-RPC method parameters (e.g. allow only non-empty arrays of numbers)
+- Accept positional and named parameters (`params: [5, 5]`, `params: { addends: [5, 5] }`)
+- Respond successfully or erroneously, according to the specification
 
-For more advanced setups, check the [examples](https://github.com/wilsonsilva/jsonrpc-middleware/blob/main/examples/README.md).
+For more advanced setups, or other frameworks such as Rails or Sinatra, check the [examples](https://github.com/wilsonsilva/jsonrpc-middleware/blob/main/examples/README.md).
 
 ## 📚 Documentation
 

data/Rakefile

@@ -14,9 +14,7 @@ yardstick_options = YAML.load_file('.yardstick.yml')
 
 Bundler::Audit::Task.new
 RSpec::Core::RakeTask.new(:spec)
-RuboCop::RakeTask.new do |task|
-  task.requires << 'rubocop-yard'
-end
+RuboCop::RakeTask.new
 YARD::Rake::YardocTask.new
 YardJunk::Rake.define_task
 Yardstick::Rake::Measurement.new(:yardstick_measure, yardstick_options)

data/examples/README.md

@@ -7,8 +7,9 @@ This directory contains example implementations of JSON-RPC servers using the js
 - [**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**](./rails/) - Calculator server using Rails
 - [**rails-single-file**](./rails-single-file/) - Echo server using Rails with bundler/inline
+- [**rails-single-file-routing**](./rails-single-file-routing/) - Echo server using Rails with method-specific routing
 - [**sinatra-classic**](./sinatra-classic/) - Calculator server using classic Sinatra
 - [**sinatra-modular**](./sinatra-modular/) - Calculator server using modular Sinatra
 

data/examples/rack/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.1.0)
+    jsonrpc-middleware (0.3.0)
       dry-validation (~> 1.11)
       zeitwerk (~> 2.7)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    bigdecimal (3.1.9)
+    bigdecimal (3.2.2)
     concurrent-ruby (1.3.5)
     dry-configurable (1.3.0)
       dry-core (~> 1.1)
@@ -32,7 +32,7 @@ GEM
       dry-logic (~> 1.5)
       dry-types (~> 1.8)
       zeitwerk (~> 2.6)
-    dry-types (1.8.2)
+    dry-types (1.8.3)
       bigdecimal (~> 3.0)
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.0)
@@ -49,10 +49,10 @@ GEM
     nio4r (2.7.4)
     puma (6.6.0)
       nio4r (~> 2.0)
-    rack (3.1.14)
+    rack (3.1.16)
     rackup (2.2.1)
       rack (>= 3)
-    zeitwerk (2.7.2)
+    zeitwerk (2.7.3)
 
 PLATFORMS
   arm64-darwin-24
@@ -65,4 +65,4 @@ DEPENDENCIES
   rackup
 
 BUNDLED WITH
-   2.6.8
+   2.7.0

data/examples/rack/app.rb

@@ -40,9 +40,6 @@ class App
   end
 
   def handle_batch(batch)
-    batch.flat_map do |request_or_notification|
-      result = handle_single(request_or_notification)
-      JSONRPC::Response.new(id: request_or_notification.id, result:) if request_or_notification.is_a?(JSONRPC::Request)
-    end.compact
+    batch.process_each { |request_or_notification| handle_single(request_or_notification) }
   end
 end

data/examples/rack-echo/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.1.0)
+    jsonrpc-middleware (0.2.0)
       dry-validation (~> 1.11)
       zeitwerk (~> 2.7)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    bigdecimal (3.1.9)
+    bigdecimal (3.2.2)
     concurrent-ruby (1.3.5)
     dry-configurable (1.3.0)
       dry-core (~> 1.1)
@@ -32,7 +32,7 @@ GEM
       dry-logic (~> 1.5)
       dry-types (~> 1.8)
       zeitwerk (~> 2.6)
-    dry-types (1.8.2)
+    dry-types (1.8.3)
       bigdecimal (~> 3.0)
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.0)
@@ -49,10 +49,10 @@ GEM
     nio4r (2.7.4)
     puma (6.6.0)
       nio4r (~> 2.0)
-    rack (3.1.14)
+    rack (3.1.16)
     rackup (2.2.1)
       rack (>= 3)
-    zeitwerk (2.7.2)
+    zeitwerk (2.7.3)
 
 PLATFORMS
   arm64-darwin-24
@@ -65,4 +65,4 @@ DEPENDENCIES
   rackup
 
 BUNDLED WITH
-   2.6.8
+   2.7.0

data/examples/rack-echo/app.rb

@@ -27,10 +27,7 @@ class App
   end
 
   def handle_batch(batch)
-    batch.flat_map do |request_or_notification|
-      result = handle_single(request_or_notification)
-      JSONRPC::Response.new(id: request_or_notification.id, result:) if request_or_notification.is_a?(JSONRPC::Request)
-    end.compact
+    batch.process_each { |request_or_notification| handle_single(request_or_notification) }
   end
 end
 

data/examples/rack-single-file/config.ru

@@ -43,10 +43,7 @@ class App
   def handle_single(request_or_notification) = request_or_notification.params
 
   def handle_batch(batch)
-    batch.flat_map do |request_or_notification|
-      result = handle_single(request_or_notification)
-      JSONRPC::Response.new(id: request_or_notification.id, result:) if request_or_notification.is_a?(JSONRPC::Request)
-    end.compact
+    batch.process_each { |request_or_notification| handle_single(request_or_notification) }
   end
 end
 

data/examples/rails/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.1.0)
+    jsonrpc-middleware (0.2.0)
       dry-validation (~> 1.11)
       zeitwerk (~> 2.7)
 
@@ -126,13 +126,13 @@ GEM
       dry-initializer (~> 3.2)
       dry-schema (~> 1.14)
       zeitwerk (~> 2.6)
-    erb (5.0.1)
+    erb (5.0.2)
     erubi (1.13.1)
     globalid (1.2.1)
       activesupport (>= 6.1)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
-    io-console (0.8.0)
+    io-console (0.8.1)
     irb (1.15.2)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
@@ -258,4 +258,4 @@ DEPENDENCIES
   rails (~> 8.0.2)
 
 BUNDLED WITH
-   2.6.9
+   2.7.0

data/examples/rails/app/controllers/jsonrpc_controller.rb

@@ -36,9 +36,6 @@ class JsonrpcController < ApplicationController
   end
 
   def handle_batch(batch)
-    batch.flat_map do |request_or_notification|
-      result = handle_single(request_or_notification)
-      JSONRPC::Response.new(id: request_or_notification.id, result:) if request_or_notification.is_a?(JSONRPC::Request)
-    end.compact
+    batch.process_each { |request_or_notification| handle_single(request_or_notification) }
   end
 end

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

@@ -0,0 +1,23 @@
+# Rails Single File
+
+An echo server using Rails with bundler/inline in a single file.
+
+## Running
+
+```sh
+bundle exec rackup
+```
+
+## API
+
+The server implements an echo API with this 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}'
+```

data/examples/rails-single-file/config.ru

@@ -59,10 +59,7 @@ class JsonrpcController < ActionController::Base
   def handle_single(request_or_notification) = request_or_notification.params
 
   def handle_batch(batch)
-    batch.flat_map do |request_or_notification|
-      result = handle_single(request_or_notification)
-      JSONRPC::Response.new(id: request_or_notification.id, result:) if request_or_notification.is_a?(JSONRPC::Request)
-    end.compact
+    batch.process_each { |request_or_notification| handle_single(request_or_notification) }
   end
 end
 

data/examples/rails-single-file-routing/README.md

@@ -0,0 +1,53 @@
+# Rails Single File Routing
+
+Demonstrates routing JSON-RPC methods to different Rails controller actions.
+
+## Highlights
+
+Uses constraints to route JSON-RPC requests to different Rails controller actions:
+
+```ruby
+class App < Rails::Application
+  # ...
+  routes.append do
+    post '/', to: 'jsonrpc#echo', constraints: JSONRPC::MethodConstraint.new('echo')
+    post '/', to: 'jsonrpc#ping', constraints: JSONRPC::MethodConstraint.new('ping')
+  end
+end
+
+class JsonrpcController < ActionController::Base
+  # POST /
+  def echoc
+    render jsonrpc: jsonrpc_request.params
+  end
+
+  # POST /
+  def ping
+    render jsonrpc: 'pong'
+  end
+end
+```
+
+## Running
+
+```sh
+bundle exec rackup
+```
+
+## API
+
+The server implements an echo API with these procedures:
+
+- `echo` - Returns the input message
+- `ping` - Returns "pong"
+
+## 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}'
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0""method": "ping", "params": {}, "id": 2}'
+```

data/examples/rails-single-file-routing/config.ru

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+gemfile(true) do
+  source 'https://rubygems.org'
+
+  gem 'rails', '~> 8.0.2'
+  gem 'puma', '~> 6.6.0'
+  gem 'jsonrpc-middleware', path: '../../', require: 'jsonrpc'
+end
+
+require 'rails'
+require 'action_controller/railtie'
+
+JSONRPC.configure do |config|
+  config.rescue_internal_errors = true # set to +false+ if you want to raise JSONRPC::InternalError manually
+
+  procedure(:echo) do
+    params do
+      required(:message).filled(:string)
+    end
+  end
+
+  procedure(:ping) do
+    params do
+      # no params
+    end
+  end
+end
+
+# Define the application
+class App < Rails::Application
+  config.root = __dir__
+  config.cache_classes = true
+  config.eager_load = true
+  config.active_support.deprecation = :stderr
+  config.consider_all_requests_local = true
+  config.active_support.to_time_preserves_timezone = :zone
+  config.logger = nil
+  config.hosts.clear
+
+  routes.append do
+    post '/', to: 'jsonrpc#echo', constraints: JSONRPC::MethodConstraint.new('echo')
+    post '/', to: 'jsonrpc#ping', constraints: JSONRPC::MethodConstraint.new('ping')
+  end
+end
+
+# Define the JSONRPC controller
+class JsonrpcController < ActionController::Base
+  def echo
+    render jsonrpc: jsonrpc_request.params
+  end
+
+  def ping
+    render jsonrpc: 'pong'
+  end
+end
+
+App.initialize!
+
+run App

data/examples/sinatra-classic/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.1.0)
+    jsonrpc-middleware (0.2.0)
       dry-validation (~> 1.11)
       zeitwerk (~> 2.7)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    base64 (0.2.0)
+    base64 (0.3.0)
     bigdecimal (3.2.2)
     concurrent-ruby (1.3.5)
     dry-configurable (1.3.0)
@@ -47,18 +47,18 @@ GEM
       dry-schema (~> 1.14)
       zeitwerk (~> 2.6)
     logger (1.7.0)
-    multi_json (1.15.0)
+    multi_json (1.16.0)
     mustermann (3.0.3)
       ruby2_keywords (~> 0.0.1)
     nio4r (2.7.4)
     puma (6.6.0)
       nio4r (~> 2.0)
-    rack (3.1.13)
+    rack (3.1.16)
     rack-protection (4.1.1)
       base64 (>= 0.1.0)
       logger (>= 1.6.0)
       rack (>= 3.0.0, < 4)
-    rack-session (2.1.0)
+    rack-session (2.1.1)
       base64 (>= 0.1.0)
       rack (>= 3.0.0)
     rackup (2.2.1)
@@ -77,8 +77,8 @@ GEM
       rack-protection (= 4.1.1)
       sinatra (= 4.1.1)
       tilt (~> 2.0)
-    tilt (2.6.0)
-    zeitwerk (2.7.2)
+    tilt (2.6.1)
+    zeitwerk (2.7.3)
 
 PLATFORMS
   arm64-darwin-24
@@ -92,4 +92,4 @@ DEPENDENCIES
   sinatra-contrib
 
 BUNDLED WITH
-   2.6.8
+   2.7.0

data/examples/sinatra-classic/app.rb

@@ -26,8 +26,6 @@ post '/' do
   end
 end
 
-private
-
 def handle_single(request_or_notification)
   params = request_or_notification.params
 
@@ -47,8 +45,5 @@ def handle_single(request_or_notification)
 end
 
 def handle_batch(batch)
-  batch.flat_map do |request_or_notification|
-    result = handle_single(request_or_notification)
-    JSONRPC::Response.new(id: request_or_notification.id, result:) if request_or_notification.is_a?(JSONRPC::Request)
-  end.compact
+  batch.process_each { |request_or_notification| handle_single(request_or_notification) }
 end

data/examples/sinatra-modular/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.1.0)
+    jsonrpc-middleware (0.2.0)
       dry-validation (~> 1.11)
       zeitwerk (~> 2.7)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    base64 (0.2.0)
+    base64 (0.3.0)
     bigdecimal (3.2.2)
     concurrent-ruby (1.3.5)
     dry-configurable (1.3.0)
@@ -47,18 +47,18 @@ GEM
       dry-schema (~> 1.14)
       zeitwerk (~> 2.6)
     logger (1.7.0)
-    multi_json (1.15.0)
+    multi_json (1.16.0)
     mustermann (3.0.3)
       ruby2_keywords (~> 0.0.1)
     nio4r (2.7.4)
     puma (6.6.0)
       nio4r (~> 2.0)
-    rack (3.1.13)
+    rack (3.1.16)
     rack-protection (4.1.1)
       base64 (>= 0.1.0)
       logger (>= 1.6.0)
       rack (>= 3.0.0, < 4)
-    rack-session (2.1.0)
+    rack-session (2.1.1)
       base64 (>= 0.1.0)
       rack (>= 3.0.0)
     rackup (2.2.1)
@@ -77,8 +77,8 @@ GEM
       rack-protection (= 4.1.1)
       sinatra (= 4.1.1)
       tilt (~> 2.0)
-    tilt (2.6.0)
-    zeitwerk (2.7.2)
+    tilt (2.6.1)
+    zeitwerk (2.7.3)
 
 PLATFORMS
   arm64-darwin-24
@@ -92,4 +92,4 @@ DEPENDENCIES
   sinatra-contrib
 
 BUNDLED WITH
-   2.6.8
+   2.7.0

data/examples/sinatra-modular/app.rb

@@ -49,9 +49,6 @@ class App < Sinatra::Base
   end
 
   def handle_batch(batch)
-    batch.flat_map do |request_or_notification|
-      result = handle_single(request_or_notification)
-      JSONRPC::Response.new(id: request_or_notification.id, result:) if request_or_notification.is_a?(JSONRPC::Request)
-    end.compact
+    batch.process_each { |request_or_notification| handle_single(request_or_notification) }
   end
 end

data/lib/jsonrpc/batch_request.rb

@@ -137,6 +137,38 @@ module JSONRPC
       requests.empty?
     end
 
+    # Handles each request/notification in the batch and returns responses
+    #
+    # @api public
+    #
+    # @example Handle batch with a block
+    #   batch.process_each do |request_or_notification|
+    #     # Process the request/notification
+    #     result = some_processing(request_or_notification.params)
+    #     result
+    #   end
+    #
+    # @yield [request_or_notification] Yields each request/notification in the batch
+    #
+    # @yieldparam request_or_notification [JSONRPC::Request, JSONRPC::Notification] a request or notification
+    #   in the batch
+    #
+    # @yieldreturn [Object] the result of processing the request. Notifications yield no results.
+    #
+    # @return [Array<JSONRPC::Response>] responses for requests only (notifications return no response)
+    #
+    def process_each
+      raise ArgumentError, 'Block required' unless block_given?
+
+      flat_map do |request_or_notification|
+        result = yield(request_or_notification)
+
+        if request_or_notification.is_a?(JSONRPC::Request)
+          JSONRPC::Response.new(id: request_or_notification.id, result:)
+        end
+      end.compact
+    end
+
     private
 
     # Validates the requests array

data/lib/jsonrpc/railtie/method_constraint.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # This constraint allows Rails routes to be matched based on the JSON-RPC
+  # method name in the request, enabling method-specific routing.
+  #
+  # @example Using in Rails routes
+  #   post '/', to: 'jsonrpc#echo', constraints: JSONRPC::Railtie::MethodConstraint.new('echo')
+  #   post '/', to: 'jsonrpc#ping', constraints: JSONRPC::Railtie::MethodConstraint.new('ping')
+  #
+  # @api private
+  #
+  class MethodConstraint
+    # Initialize a new method constraint
+    #
+    # @param jsonrpc_method_name [String] The JSON-RPC method name to match against
+    #
+    def initialize(jsonrpc_method_name)
+      @jsonrpc_method_name = jsonrpc_method_name
+    end
+
+    # Check if the request matches the configured method name
+    #
+    # @param request [ActionDispatch::Request] The Rails request object
+    # @return [Boolean] true if the JSON-RPC method matches, false otherwise
+    #
+    def matches?(request)
+      jsonrpc_request = request.env['jsonrpc.request']
+
+      return false unless jsonrpc_request
+
+      jsonrpc_request.method == @jsonrpc_method_name
+    end
+  end
+end

data/lib/jsonrpc/railtie.rb

@@ -3,6 +3,7 @@
 module JSONRPC
   # @api private
   class Railtie < ::Rails::Railtie
+    # Rails routing constraint for matching JSON-RPC method names
     initializer 'jsonrpc.middleware' do |app|
       app.middleware.use JSONRPC::Middleware
     end