jsonrpc-middleware 0.3.0 → 0.5.0

data/examples/sinatra-classic/app.rb

@@ -45,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,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/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

@@ -124,17 +124,36 @@ module JSONRPC
     #
     alias length size
 
-    # Returns true if the batch contains no requests
+    # Handles each request/notification in the batch and returns responses
     #
     # @api public
     #
-    # @example Check if batch is empty
-    #   batch.empty? # => false
+    # @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
     #
-    # @return [Boolean] true if the batch is empty, false otherwise
+    # @yield [request_or_notification] Yields each request/notification in the batch
     #
-    def empty?
-      requests.empty?
+    # @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

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.3.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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Wilson Silva
@@ -37,16 +37,17 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.7'
-description: Implements the JSON-RPC 2.0 protocol, enabling standardized remote procedure
-  calls encoded in JSON.
+description: A Rack middleware implementing the JSON-RPC 2.0 protocol that integrates
+  easily with all Rack-based applications (Rails, Sinatra, Hanami, etc).
 email:
 - wilson.dsigns@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".aiexclude"
+- ".aiignore"
 - ".claude/commands/document.md"
+- ".claude/commands/test.md"
 - ".claude/docs/yard.md"
 - ".claude/settings.local.json"
 - ".editorconfig"
@@ -79,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
@@ -135,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
@@ -167,5 +173,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.7.0
 specification_version: 4
-summary: Implementation of the JSON-RPC protocol.
+summary: Rack middleware implementing the JSON-RPC 2.0 protocol.
 test_files: []