jsonrpc-middleware 0.3.0 → 0.5.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
 
@@ -26,10 +37,29 @@ calls encoded in JSON.
 - **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
+- **Rails routing DSL**: Elegant routing DSL for Rails applications with support for namespaces and batch handling
 - **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
 
+## 🏗️ 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 +108,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 +135,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
 
@@ -145,6 +175,7 @@ rake bundle:audit:update      # Updates the bundler-audit vulnerability database
 rake clean                    # Remove any temporary products
 rake clobber                  # Remove any generated files
 rake coverage                 # Run spec with coverage
+rake examples:bundle_install  # Run bundle install on all example folders (useful after updating the gem version)
 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

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)
@@ -97,3 +95,59 @@ namespace :yard do
     puts 'Done!'
   end
 end
+
+namespace :examples do
+  desc 'Run bundle install on all example folders'
+  task :bundle_install do
+    examples_dir = File.join(Dir.pwd, 'examples')
+    
+    unless Dir.exist?(examples_dir)
+      puts 'Examples directory not found'
+      exit 1
+    end
+    
+    example_folders = Dir.glob(File.join(examples_dir, '*')).select { |path| Dir.exist?(path) }
+    
+    if example_folders.empty?
+      puts 'No example folders found'
+      return
+    end
+    
+    puts "Found #{example_folders.length} example folders:"
+    example_folders.each { |folder| puts "  - #{File.basename(folder)}" }
+    puts
+    
+    failed_folders = []
+    
+    example_folders.each do |folder|
+      gemfile_path = File.join(folder, 'Gemfile')
+      
+      unless File.exist?(gemfile_path)
+        puts "Skipping #{File.basename(folder)} - no Gemfile found"
+        next
+      end
+      
+      puts "Running bundle install in #{File.basename(folder)}..."
+      
+      Dir.chdir(folder) do
+        system('bundle install')
+        
+        unless $?.success?
+          failed_folders << File.basename(folder)
+          puts "  ✗ Failed to bundle install in #{File.basename(folder)}"
+        else
+          puts "  ✓ Successfully installed gems in #{File.basename(folder)}"
+        end
+      end
+      
+      puts
+    end
+    
+    if failed_folders.empty?
+      puts 'All example folders processed successfully!'
+    else
+      puts "Failed to process #{failed_folders.length} folders: #{failed_folders.join(', ')}"
+      exit 1
+    end
+  end
+end

data/examples/procedures.rb

@@ -52,9 +52,5 @@ JSONRPC.configure do |config|
   end
 
   # Used only to test internal server errors
-  procedure(:explode) do
-    params do
-      # No params
-    end
-  end
+  procedure(:explode)
 end

data/examples/rack/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.2.0)
+    jsonrpc-middleware (0.4.0)
       dry-validation (~> 1.11)
       zeitwerk (~> 2.7)
 

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,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.2.0)
+    jsonrpc-middleware (0.4.0)
       dry-validation (~> 1.11)
       zeitwerk (~> 2.7)
 

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.2.0)
+    jsonrpc-middleware (0.4.0)
       dry-validation (~> 1.11)
       zeitwerk (~> 2.7)
 

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/config/initializers/jsonrpc.rb

@@ -54,9 +54,5 @@ require_relative '../../../procedures'
 #   end
 #
 #   # Used only to test internal server errors
-#   procedure(:explode) do
-#     params do
-#       # No params
-#     end
-#   end
+#   procedure(:explode)
 # end

data/examples/rails-routing-dsl/README.md

@@ -0,0 +1,199 @@
+# Rails JSON-RPC Routing DSL
+
+Demonstrates using the Rails routing DSL extension to route JSON-RPC methods to different controller actions for a
+smart home control system.
+
+## Highlights
+
+Uses the `jsonrpc` routing DSL to map JSON-RPC methods to Rails controller actions with clean, readable syntax:
+
+```ruby
+class App < Rails::Application
+  # ...
+  routes.append do
+    jsonrpc '/' do
+      # Handle batch requests with a dedicated controller
+      batch to: 'batch#handle'
+
+      method 'on', to: 'main#on'
+      method 'off', to: 'main#off'
+
+      namespace 'lights' do
+        method 'on', to: 'lights#on'        # becomes lights.on
+        method 'off', to: 'lights#off'      # becomes lights.off
+      end
+
+      namespace 'climate' do
+        method 'on', to: 'climate#on'       # becomes climate.on
+        method 'off', to: 'climate#off'     # becomes climate.off
+
+        namespace 'fan' do
+          method 'on', to: 'fan#on'         # becomes climate.fan.on
+          method 'off', to: 'fan#off'       # becomes climate.fan.off
+        end
+      end
+    end
+  end
+end
+
+class MainController < ActionController::Base
+  def on
+    render jsonrpc: { device: 'main_system', status: 'on' }
+  end
+
+  def off
+    render jsonrpc: { device: 'main_system', status: 'off' }
+  end
+end
+
+class LightsController < ActionController::Base
+  def on
+    render jsonrpc: { device: 'lights', status: 'on' }
+  end
+
+  def off
+    render jsonrpc: { device: 'lights', status: 'off' }
+  end
+end
+
+class ClimateController < ActionController::Base
+  def on
+    render jsonrpc: { device: 'climate_system', status: 'on' }
+  end
+
+  def off
+    render jsonrpc: { device: 'climate_system', status: 'off' }
+  end
+end
+
+class FanController < ActionController::Base
+  def on
+    render jsonrpc: { device: 'fan', status: 'on' }
+  end
+
+  def off
+    render jsonrpc: { device: 'fan', status: 'off' }
+  end
+end
+
+class BatchController < ActionController::Base
+  def handle
+    # Process each request in the batch and collect results
+    results = jsonrpc_batch.process_each do |request_or_notification|
+      case request_or_notification.method
+      when 'on'
+        { device: 'main_system', status: 'on' }
+      when 'off'
+        { device: 'main_system', status: 'off' }
+      when 'lights.on'
+        { device: 'lights', status: 'on' }
+      when 'lights.off'
+        { device: 'lights', status: 'off' }
+      # ... handle other methods
+      end
+    end
+
+    render jsonrpc: results
+  end
+end
+```
+
+## Running
+
+```sh
+bundle exec rackup
+```
+
+## API
+
+The server implements smart home controls with these procedures:
+
+**Root Methods:**
+- `on` - Turn home automation system on
+- `off` - Turn home automation system off
+
+**Lights Namespace:**
+- `lights.on` - Turn lights on
+- `lights.off` - Turn lights off
+
+**Climate Namespace:**
+- `climate.on` - Turn climate system on
+- `climate.off` - Turn climate system off
+
+**Climate Fan Namespace:**
+- `climate.fan.on` - Turn fan on
+- `climate.fan.off` - Turn fan off
+
+**Batch Processing:**
+- Batch requests are automatically routed to the `BatchController#handle` action
+- The controller uses `jsonrpc_batch.process_each` to handle each request in the batch
+- Responses are collected and returned as an array
+
+## Example Requests
+
+Turn on the home automation system:
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "on", "params": {}, "id": 1}'
+```
+
+Turn off the home automation system:
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "off", "params": {}, "id": 2}'
+```
+
+Turn on lights:
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "lights.on", "params": {}, "id": 3}'
+```
+
+Turn off the lights:
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "lights.off", "params": {}, "id": 4}'
+```
+
+Turn on the climate system:
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "climate.on", "params": {}, "id": 5}'
+```
+
+Turn off the climate system:
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "climate.off", "params": {}, "id": 6}'
+```
+
+Turn on fan:
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "climate.fan.on", "params": {}, "id": 7}'
+```
+
+Turn off fan:
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "climate.fan.off", "params": {}, "id": 8}'
+```
+
+Batch request for evening routine:
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '[
+    {"jsonrpc": "2.0", "method": "off", "params": {}, "id": 9},
+    {"jsonrpc": "2.0", "method": "lights.off", "params": {}, "id": 10},
+    {"jsonrpc": "2.0", "method": "climate.off", "params": {}, "id": 11}
+  ]'
+```

data/examples/rails-routing-dsl/config.ru

@@ -0,0 +1,146 @@
+# 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
+
+  # Define the allowed JSON-RPC methods. Calls to methods absent from this list will return a method not found error.
+  procedure 'on'
+  procedure 'off'
+  procedure 'lights.on'
+  procedure 'lights.off'
+  procedure 'climate.on'
+  procedure 'climate.off'
+  procedure 'climate.fan.on'
+  procedure 'climate.fan.off'
+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
+    jsonrpc '/' do
+      # Handle batch requests with a dedicated controller
+      batch to: 'batch#handle'
+
+      method :on, to: 'main#on'
+      method :off, to: 'main#off'
+
+      namespace 'lights' do
+        method :on, to: 'lights#on'    # becomes lights.on
+        method :off, to: 'lights#off'  # becomes lights.off
+      end
+
+      namespace 'climate' do
+        method :on, to: 'climate#on'   # becomes climate.on
+        method :off, to: 'climate#off' # becomes climate.off
+
+        namespace 'fan' do
+          method :on, to: 'fan#on'     # becomes climate.fan.on
+          method :off, to: 'fan#off'   # becomes climate.fan.off
+        end
+      end
+    end
+  end
+end
+
+# Controller for main system operations
+class MainController < ActionController::Base
+  def on
+    render jsonrpc: { device: 'main_system', status: 'on' }
+  end
+
+  def off
+    render jsonrpc: { device: 'main_system', status: 'off' }
+  end
+end
+
+# Controller for lights operations
+class LightsController < ActionController::Base
+  def on
+    render jsonrpc: { device: 'lights', status: 'on' }
+  end
+
+  def off
+    render jsonrpc: { device: 'lights', status: 'off' }
+  end
+end
+
+# Controller for climate operations
+class ClimateController < ActionController::Base
+  def on
+    render jsonrpc: { device: 'climate_system', status: 'on' }
+  end
+
+  def off
+    render jsonrpc: { device: 'climate_system', status: 'off' }
+  end
+end
+
+# Controller for climate fan operations
+class FanController < ActionController::Base
+  def on
+    render jsonrpc: { device: 'fan', status: 'on' }
+  end
+
+  def off
+    render jsonrpc: { device: 'fan', status: 'off' }
+  end
+end
+
+# Controller for batch operations
+class BatchController < ActionController::Base
+  def handle
+    # Process each request in the batch and collect results
+    results = jsonrpc_batch.process_each do |request_or_notification|
+      result = case request_or_notification.method
+               when 'on'
+                 { device: 'main_system', status: 'on' }
+               when 'off'
+                 { device: 'main_system', status: 'off' }
+               when 'lights.on'
+                 { device: 'lights', status: 'on' }
+               when 'lights.off'
+                 { device: 'lights', status: 'off' }
+               when 'climate.on'
+                 { device: 'climate_system', status: 'on' }
+               when 'climate.off'
+                 { device: 'climate_system', status: 'off' }
+               when 'climate.fan.on'
+                 { device: 'fan', status: 'on' }
+               when 'climate.fan.off'
+                 { device: 'fan', status: 'off' }
+               else
+                 { error: 'Unknown method', method: request_or_notification.method }
+               end
+
+      result
+    end
+
+    render jsonrpc: results
+  end
+end
+
+App.initialize!
+
+run App

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

@@ -17,7 +17,7 @@ end
 
 class JsonrpcController < ActionController::Base
   # POST /
-  def echoc
+  def echo
     render jsonrpc: jsonrpc_request.params
   end
 

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

@@ -22,11 +22,7 @@ JSONRPC.configure do |config|
     end
   end
 
-  procedure(:ping) do
-    params do
-      # no params
-    end
-  end
+  procedure(:ping)
 end
 
 # Define the application

data/examples/sinatra-classic/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.2.0)
+    jsonrpc-middleware (0.4.0)
       dry-validation (~> 1.11)
       zeitwerk (~> 2.7)