jsonrpc-middleware 0.4.0 → 0.6.0

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

@@ -10,6 +10,10 @@ Uses constraints to route JSON-RPC requests to different Rails controller action
 class App < Rails::Application
   # ...
   routes.append do
+    # Handle batch requests
+    post '/', to: 'jsonrpc#ping_or_echo', constraints: JSONRPC::BatchConstraint.new
+
+    # Handle individual method requests
     post '/', to: 'jsonrpc#echo', constraints: JSONRPC::MethodConstraint.new('echo')
     post '/', to: 'jsonrpc#ping', constraints: JSONRPC::MethodConstraint.new('ping')
   end
@@ -17,7 +21,7 @@ end
 
 class JsonrpcController < ActionController::Base
   # POST /
-  def echoc
+  def echo
     render jsonrpc: jsonrpc_request.params
   end
 
@@ -25,6 +29,20 @@ class JsonrpcController < ActionController::Base
   def ping
     render jsonrpc: 'pong'
   end
+
+  # POST /
+  def ping_or_echo
+    results = jsonrpc_batch.process_each do |request_or_notification|
+      case request_or_notification.method
+      when 'echo'
+        request_or_notification.params
+      when 'ping'
+        'pong'
+      end
+    end
+
+    render jsonrpc: results
+  end
 end
 ```
 
@@ -36,18 +54,35 @@ bundle exec rackup
 
 ## API
 
-The server implements an echo API with these procedures:
+The server implements these procedures:
 
 - `echo` - Returns the input message
-- `ping` - Returns "pong"
+- `ping` - Returns `'pong'`
 
 ## Example Requests
 
+Echo request:
 ```sh
 curl -X POST http://localhost:9292 \
   -H "Content-Type: application/json" \
   -d '{"jsonrpc": "2.0", "method": "echo", "params": {"message": "Hello, World!"}, "id": 1}'
+```
+
+Ping request:
+```sh
+curl -X POST http://localhost:9292 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "ping", "params": {}, "id": 2}'
+```
+
+Batch request with multiple methods:
+```sh
+# Batch request with multiple methods
 curl -X POST http://localhost:9292 \
   -H "Content-Type: application/json" \
-  -d '{"jsonrpc": "2.0""method": "ping", "params": {}, "id": 2}'
+  -d '[
+    {"jsonrpc": "2.0", "method": "echo", "params": {"message": "Hello from batch!"}, "id": 1},
+    {"jsonrpc": "2.0", "method": "ping", "params": {}, "id": 2},
+    {"jsonrpc": "2.0", "method": "echo", "params": {"message": "Another echo"}, "id": 3}
+  ]'
 ```

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
@@ -41,6 +37,10 @@ class App < Rails::Application
   config.hosts.clear
 
   routes.append do
+    # Handle batch requests
+    post '/', to: 'jsonrpc#ping_or_echo', constraints: JSONRPC::BatchConstraint.new
+
+    # Handle individual method requests
     post '/', to: 'jsonrpc#echo', constraints: JSONRPC::MethodConstraint.new('echo')
     post '/', to: 'jsonrpc#ping', constraints: JSONRPC::MethodConstraint.new('ping')
   end
@@ -55,6 +55,19 @@ class JsonrpcController < ActionController::Base
   def ping
     render jsonrpc: 'pong'
   end
+
+  def ping_or_echo
+    results = jsonrpc_batch.process_each do |request_or_notification|
+      case request_or_notification.method
+      when 'echo'
+        request_or_notification.params
+      when 'ping'
+        'pong'
+      end
+    end
+
+    render jsonrpc: results
+  end
 end
 
 App.initialize!

data/examples/sinatra-classic/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.2.0)
+    jsonrpc-middleware (0.5.0)
       dry-validation (~> 1.11)
+      multi_json (~> 1.17)
       zeitwerk (~> 2.7)
 
 GEM
@@ -47,7 +48,7 @@ GEM
       dry-schema (~> 1.14)
       zeitwerk (~> 2.6)
     logger (1.7.0)
-    multi_json (1.16.0)
+    multi_json (1.17.0)
     mustermann (3.0.3)
       ruby2_keywords (~> 0.0.1)
     nio4r (2.7.4)

data/examples/sinatra-modular/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: ../..
   specs:
-    jsonrpc-middleware (0.2.0)
+    jsonrpc-middleware (0.5.0)
       dry-validation (~> 1.11)
+      multi_json (~> 1.17)
       zeitwerk (~> 2.7)
 
 GEM
@@ -47,7 +48,7 @@ GEM
       dry-schema (~> 1.14)
       zeitwerk (~> 2.6)
     logger (1.7.0)
-    multi_json (1.16.0)
+    multi_json (1.17.0)
     mustermann (3.0.3)
       ruby2_keywords (~> 0.0.1)
     nio4r (2.7.4)

data/lib/jsonrpc/batch_request.rb

@@ -75,7 +75,7 @@ module JSONRPC
     # @return [String] the JSON-formatted batch
     #
     def to_json(*)
-      to_h.to_json(*)
+      MultiJson.dump(to_h, *)
     end
 
     # Implements the Enumerable contract by yielding each request in the batch
@@ -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/batch_response.rb

@@ -75,7 +75,7 @@ module JSONRPC
     # @return [String] the JSON-formatted batch response
     #
     def to_json(*)
-      to_h.to_json(*)
+      MultiJson.dump(to_h, *)
     end
 
     # Implements the Enumerable contract by yielding each response in the batch

data/lib/jsonrpc/configuration.rb

@@ -101,6 +101,19 @@ module JSONRPC
     #
     attr_reader :validate_procedure_signatures
 
+    # JSON adapter to use (optional)
+    #
+    # @api public
+    #
+    # @example
+    #   config.json_adapter = :oj
+    #
+    # @return [Symbol, nil] the JSON adapter to use
+    #
+    def json_adapter=(adapter)
+      MultiJson.use(adapter)
+    end
+
     # Initializes a new Configuration instance
     #
     # @api public
@@ -162,15 +175,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/error.rb

@@ -128,7 +128,7 @@ module JSONRPC
     # @return [String] the error as a JSON string
     #
     def to_json(*)
-      to_h.to_json(*)
+      MultiJson.dump(to_h, *)
     end
 
     # Converts the error to a complete JSON-RPC response

data/lib/jsonrpc/middleware.rb

@@ -324,7 +324,7 @@ module JSONRPC
 
       return [] unless status == 200 && !body.empty?
 
-      app_responses = JSON.parse(body.join)
+      app_responses = MultiJson.load(body.join)
       app_responses.map do |resp|
         Response.new(id: resp['id'], result: resp['result'], error: resp['error'])
       end
@@ -359,7 +359,8 @@ module JSONRPC
     # @return [Array] Rack response tuple [status, headers, body]
     #
     def json_response(status, body)
-      [status, { 'content-type' => 'application/json' }, [body.is_a?(String) ? body : JSON.generate(body)]]
+      json_body = body.is_a?(String) ? body : MultiJson.dump(body)
+      [status, { 'content-type' => 'application/json' }, [json_body]]
     end
 
     # Reads and returns the request body from the Rack environment

data/lib/jsonrpc/notification.rb

@@ -108,7 +108,7 @@ module JSONRPC
     # @return [String] the notification as a JSON string
     #
     def to_json(*)
-      to_h.to_json(*)
+      MultiJson.dump(to_h, *)
     end
 
     private

data/lib/jsonrpc/parser.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'json'
-
 module JSONRPC
   # JSON-RPC 2.0 Parser for converting raw JSON into JSONRPC objects
   #
@@ -37,17 +35,21 @@ module JSONRPC
     # @raise [InvalidRequestError] if the request structure is invalid
     #
     def parse(json)
-      begin
-        data = JSON.parse(json)
-      rescue JSON::ParserError => e
-        raise ParseError.new(data: { details: e.message })
-      end
+      data = MultiJson.load(json)
 
       if data.is_a?(Array)
         parse_batch(data)
       else
         parse_single(data)
       end
+    rescue MultiJson::ParseError => e
+      raise ParseError.new(
+        data: {
+          details: e.message,
+          adapter: MultiJson.adapter.name,
+          input_preview: json[0..100]
+        }
+      )
     end
 
     private

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