jsonrpc-middleware 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a45b1d353d7fd1547e7e984edba9c9ed1e02669914c00294d08f259cb5bb76e6
-  data.tar.gz: 25d2b7802a03378c90e181d5e5b580489299d41a3070817d762b43063a9d68b3
+  metadata.gz: 5d8775dfa68b34e4513883b9bdbfb565a708902efe694727bb19d517d4539cd7
+  data.tar.gz: 8f087e14952785c53470895871bb175e0e48fd9aab560b9906cd17b509d6f4e2
 SHA512:
-  metadata.gz: c3a417f6096c195940c782cb313f9b4e7a5e6ef2c1c6ed994a4d23e226e7a70ba7df4b635b03c56f392983b45b1d0239f0a121c2b2982101c5ad5c47680bd7f8
-  data.tar.gz: 601bc95a7d965e6721af683765881d73ac34fc5ced0791c398b1ddc4acff054b586d0c74ab0107bf139bb177afcebc760460d96cb86896afec1394972b98b6d9
+  metadata.gz: fd7b7f8ffb647ad4e08a487307bfa58f7a2f33fbc0d5e0f248800f7ac17bc1c01cfb0c7c5d3d6804601ac7b48d5a248084ea1a39bf3c1f38fc84628776e9c7b2
+  data.tar.gz: cad4b6b454c561cc04ef2c4452722f562a9902a1c45020e709ffd793d3a2fb0fb1d1c4556a0f3867c6e30339a6fc24c58c0b38762b9aa3940eedd9c488324b09

data/CHANGELOG.md

@@ -5,10 +5,74 @@ 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.5.0] - 2025-07-22
+
+### Added
+- Rails routing DSL for elegant JSON-RPC method mapping with support for namespaces and batch handling:
+  ```ruby
+  # In routes.rb
+  jsonrpc '/' do
+    # Handle batch requests
+    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
+  ```
+- `JSONRPC::BatchConstraint` for routing JSON-RPC batch requests to dedicated controllers:
+  ```ruby
+  # Handle batch requests with custom constraint
+  post '/api', to: 'api#handle_batch', constraints: JSONRPC::BatchConstraint.new
+
+  # Or use the DSL (recommended)
+  jsonrpc '/api' do
+    batch to: 'api#handle_batch'
+  end
+  ```
+
+### Changed
+- Procedure registration now supports optional validation blocks (defaults to empty contract):
+  ```ruby
+  # Before: Always required validation block (even if empty)
+  procedure('ping') do
+    params do
+      # No params needed
+    end
+  end
+
+  # After: Optional validation block
+  procedure('ping')  # Uses empty contract by default
+
+  # Still works with validation when needed
+  procedure('add') do
+    params do
+      required(:a).value(:integer)
+      required(:b).value(:integer)
+    end
+  end
+  ```
+- Simplified example configurations by removing unnecessary empty validation blocks
+- Enhanced Rails integration with automatic DSL registration via Railtie
+
 ## [0.4.0] - 2025-07-18
 
 ### Added
-- JSONRPC::BatchRequest#process_each method for simplified batch processing
+- `JSONRPC::BatchRequest#process_each` method for simplified batch processing
 
 ## [0.3.0] - 2025-07-17
 
@@ -71,6 +135,7 @@ 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.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
 [0.2.0]: https://github.com/wilsonsilva/jsonrpc-middleware/compare/v0.1.0...v0.2.0

data/README.md

@@ -37,6 +37,7 @@ A Rack middleware implementing the JSON-RPC 2.0 protocol that integrates easily
 - **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
@@ -174,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

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

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/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/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-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)
 

data/examples/sinatra-modular/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/lib/jsonrpc/batch_request.rb

@@ -124,19 +124,6 @@ module JSONRPC
     #
     alias length size
 
-    # Returns true if the batch contains no requests
-    #
-    # @api public
-    #
-    # @example Check if batch is empty
-    #   batch.empty? # => false
-    #
-    # @return [Boolean] true if the batch is empty, false otherwise
-    #
-    def empty?
-      requests.empty?
-    end
-
     # Handles each request/notification in the batch and returns responses
     #
     # @api public

data/lib/jsonrpc/configuration.rb

@@ -162,15 +162,24 @@ module JSONRPC
     #     end
     #   end
     #
+    # @example Register a procedure without validation
+    #   config.procedure('ping')
+    #
     # @param method_name [String, Symbol] the name of the procedure
     # @param allow_positional_arguments [Boolean] whether the procedure accepts positional arguments
     #
-    # @yield A block that defines the validation contract using Dry::Validation DSL
+    # @yield [optional] A block that defines the validation contract using Dry::Validation DSL
     #
     # @return [Procedure] the registered procedure
     #
-    def procedure(method_name, allow_positional_arguments: false, &)
-      contract_class = Class.new(Dry::Validation::Contract, &)
+    def procedure(method_name, allow_positional_arguments: false, &block)
+      contract_class = if block
+                         Class.new(Dry::Validation::Contract, &block)
+                       else
+                         Class.new(Dry::Validation::Contract) do
+                           params {} # rubocop:disable Lint/EmptyBlock
+                         end
+                       end
       contract_class.class_eval { import_predicates_as_macros }
       contract = contract_class.new
 

data/lib/jsonrpc/railtie/batch_constraint.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # This constraint allows Rails routes to be matched based on JSON-RPC
+  # batch requests, enabling batch-specific routing to dedicated controllers.
+  #
+  # @example Using in Rails routes
+  #   post '/', to: 'jsonrpc#handle_batch', constraints: JSONRPC::BatchConstraint.new
+  #
+  # @api private
+  #
+  class BatchConstraint
+    # Check if the request is a JSON-RPC batch request
+    #
+    # @param request [ActionDispatch::Request] The Rails request object
+    # @return [Boolean] true if the request is a batch request, false otherwise
+    #
+    def matches?(request)
+      jsonrpc_batch = request.env['jsonrpc.batch']
+
+      # Return true if we have a batch request in the environment
+      !jsonrpc_batch.nil?
+    end
+  end
+end

data/lib/jsonrpc/railtie/mapper_extension.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # Extension module for ActionDispatch::Routing::Mapper
+  #
+  # @api private
+  #
+  module MapperExtension
+    # Define JSON-RPC routes with a DSL
+    #
+    # @param path [String] the path to handle JSON-RPC requests on
+    #
+    # @example Define JSON-RPC routes
+    #   jsonrpc '/api/v1' do
+    #     # Handle batch requests
+    #     batch to: 'batch#handle'
+    #
+    #     method 'user.create', to: 'users#create'
+    #     method 'user.get', to: 'users#show'
+    #
+    #     namespace 'posts' do
+    #       method 'create', to: 'posts#create'
+    #       method 'list', to: 'posts#index'
+    #     end
+    #   end
+    #
+    # @return [void]
+    #
+    def jsonrpc(path = '/', &)
+      dsl = JSONRPC::RoutesDsl.new(self, path)
+      dsl.instance_eval(&)
+    end
+  end
+end

data/lib/jsonrpc/railtie/method_constraint.rb

@@ -16,7 +16,7 @@ module JSONRPC
     # @param jsonrpc_method_name [String] The JSON-RPC method name to match against
     #
     def initialize(jsonrpc_method_name)
-      @jsonrpc_method_name = jsonrpc_method_name
+      @jsonrpc_method_name = jsonrpc_method_name.to_s
     end
 
     # Check if the request matches the configured method name

data/lib/jsonrpc/railtie/routes_dsl.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module JSONRPC
+  # DSL context for defining JSON-RPC routes within a jsonrpc block
+  #
+  # @example Simple method routing
+  #   jsonrpc '/api/v1' do
+  #     method 'ping', to: 'system#ping'
+  #     method 'status', to: 'system#status'
+  #   end
+  #
+  # @example Single-level namespace
+  #   jsonrpc '/api/v1' do
+  #     namespace 'users' do
+  #       method 'create', to: 'users#create'  # becomes users.create
+  #       method 'list', to: 'users#index'     # becomes users.list
+  #     end
+  #   end
+  #
+  # @example Nested namespaces (smart home control system)
+  #   jsonrpc '/' do
+  #     # Handle batch requests with 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
+  #
+  # @api private
+  #
+  class RoutesDsl
+    # Initialize a new routes DSL context
+    #
+    # @param mapper [ActionDispatch::Routing::Mapper] the Rails route mapper
+    # @param path_prefix [String] the base path for JSON-RPC requests
+    #
+    def initialize(mapper, path_prefix = '/')
+      @mapper = mapper
+      @path_prefix = path_prefix
+      @namespace_stack = []
+    end
+
+    # Define a JSON-RPC method route
+    #
+    # @param jsonrpc_method [String] the JSON-RPC method name
+    # @param to [String] the Rails controller action (e.g., 'users#create')
+    #
+    # @example Map a JSON-RPC method to controller action
+    #   method 'user.create', to: 'users#create'
+    #
+    # @example Method within a namespace
+    #   namespace 'posts' do
+    #     method 'create', to: 'posts#create'  # becomes posts.create
+    #   end
+    #
+    # @return [void]
+    #
+    def method(jsonrpc_method, to:)
+      full_method_name = build_full_method_name(jsonrpc_method)
+      constraint = JSONRPC::MethodConstraint.new(full_method_name)
+
+      @mapper.post @path_prefix, {
+        to: to,
+        constraints: constraint
+      }
+    end
+
+    # Define a route for handling JSON-RPC batch requests
+    #
+    # @param to [String] the Rails controller action (e.g., 'batches#handle')
+    #
+    # @example Map batch requests to a controller action
+    #   batch to: 'batches#handle'
+    #
+    # @return [void]
+    def batch(to:)
+      constraint = JSONRPC::BatchConstraint.new
+
+      @mapper.post @path_prefix, {
+        to: to,
+        constraints: constraint
+      }
+    end
+
+    # Create a namespace for grouping related JSON-RPC methods
+    #
+    # Namespaces can be nested to create hierarchical method names.
+    # Each level of nesting adds a dot-separated prefix to the method names.
+    #
+    # @param name [String] the namespace name
+    #
+    # @example Single-level namespace
+    #   namespace 'posts' do
+    #     method 'create', to: 'posts#create' # becomes posts.create
+    #     method 'delete', to: 'posts#delete' # becomes posts.list
+    #   end
+    #
+    # @example Nested namespaces
+    #   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
+    #
+    # @return [void]
+    #
+    def namespace(name, &)
+      @namespace_stack.push(name)
+      instance_eval(&)
+      @namespace_stack.pop
+    end
+
+    private
+
+    # Build the full method name including namespaces
+    #
+    # @param method_name [String] the base method name
+    # @return [String] the full method name with namespace prefixes
+    #
+    def build_full_method_name(method_name)
+      if @namespace_stack.any?
+        "#{@namespace_stack.join(".")}.#{method_name}"
+      else
+        method_name
+      end
+    end
+  end
+end

data/lib/jsonrpc/railtie.rb

@@ -8,6 +8,13 @@ module JSONRPC
       app.middleware.use JSONRPC::Middleware
     end
 
+    # Register the JSON-RPC routes DSL extension
+    initializer 'jsonrpc.routes_dsl' do
+      ActiveSupport.on_load(:action_controller) do
+        ActionDispatch::Routing::Mapper.include(JSONRPC::MapperExtension)
+      end
+    end
+
     initializer 'jsonrpc.renderer' do
       ActiveSupport.on_load(:action_controller) do
         Mime::Type.register 'application/json', :jsonrpc

data/lib/jsonrpc/version.rb

@@ -11,5 +11,5 @@ module JSONRPC
   #
   # @return [String] The current version number
   #
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonrpc-middleware
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Wilson Silva
@@ -45,7 +45,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".aiexclude"
+- ".aiignore"
 - ".claude/commands/document.md"
 - ".claude/commands/test.md"
 - ".claude/docs/yard.md"
@@ -80,6 +80,8 @@ files:
 - examples/rack/README.md
 - examples/rack/app.rb
 - examples/rack/config.ru
+- examples/rails-routing-dsl/README.md
+- examples/rails-routing-dsl/config.ru
 - examples/rails-single-file-routing/README.md
 - examples/rails-single-file-routing/config.ru
 - examples/rails-single-file/README.md
@@ -136,7 +138,10 @@ files:
 - lib/jsonrpc/notification.rb
 - lib/jsonrpc/parser.rb
 - lib/jsonrpc/railtie.rb
+- lib/jsonrpc/railtie/batch_constraint.rb
+- lib/jsonrpc/railtie/mapper_extension.rb
 - lib/jsonrpc/railtie/method_constraint.rb
+- lib/jsonrpc/railtie/routes_dsl.rb
 - lib/jsonrpc/request.rb
 - lib/jsonrpc/response.rb
 - lib/jsonrpc/validator.rb