jsonrpc-middleware 0.1.0 → 0.2.0

data/lib/jsonrpc/request.rb

@@ -3,40 +3,76 @@
 module JSONRPC
   # A JSON-RPC 2.0 Request object
   #
+  # @api public
+  #
+  # Represents a call to a specific method with optional parameters and an identifier.
+  #
   # @example Create a request with positional parameters
   #   request = JSONRPC::Request.new(method: "subtract", params: [42, 23], id: 1)
   #
   # @example Create a request with named parameters
-  #   request = JSONRPC::Request.new(method: "subtract", params: {minuend: 42, subtrahend: 23}, id: 3)
+  #   request = JSONRPC::Request.new(method: "subtract", params: { minuend: 42, subtrahend: 23 }, id: 3)
   #
   class Request
     # JSON-RPC protocol version
+    #
+    # @api public
+    #
+    # @example
+    #   request.jsonrpc # => "2.0"
+    #
     # @return [String]
     #
     attr_reader :jsonrpc
 
     # The method name to invoke
+    #
+    # @api public
+    #
+    # @example
+    #   request.method # => "subtract"
+    #
     # @return [String]
     #
     attr_reader :method
 
     # Parameters to pass to the method
+    #
+    # @api public
+    #
+    # @example
+    #   request.params # => { "minuend": 42, "subtrahend": 23 }
+    #
     # @return [Hash, Array, nil]
     #
     attr_reader :params
 
     # The request identifier
+    #
+    # @api public
+    #
+    # @example
+    #   request.id # => 1
+    #
     # @return [String, Integer, nil]
     #
     attr_reader :id
 
     # Creates a new JSON-RPC 2.0 Request object
     #
+    # @api public
+    #
+    # @example Create a request with positional parameters
+    #   JSONRPC::Request.new(method: "subtract", params: [42, 23], id: 1)
+    #
     # @param method [String] the name of the method to be invoked
     # @param params [Hash, Array, nil] the parameters to be used during method invocation
     # @param id [String, Integer, nil] the request identifier
+    #
     # @raise [ArgumentError] if method is not a String or is reserved
+    #
     # @raise [ArgumentError] if params is not a Hash, Array, or nil
+    #
     # @raise [ArgumentError] if id is not a String, Integer, or nil
     #
     def initialize(method:, id:, params: nil)
@@ -53,6 +89,12 @@ module JSONRPC
 
     # Converts the request to a JSON-compatible Hash
     #
+    # @api public
+    #
+    # @example
+    #   request.to_h
+    #   # => { jsonrpc: "2.0", method: "subtract", params: [42, 23], id: 1 }
+    #
     # @return [Hash] the request as a JSON-compatible Hash
     #
     def to_h
@@ -66,6 +108,16 @@ module JSONRPC
       hash
     end
 
+    # Converts the request to a JSON string
+    #
+    # @api public
+    #
+    # @example
+    #   request.to_json
+    #   # => '{"jsonrpc":"2.0","method":"subtract","params":[42,23],"id":1}'
+    #
+    # @return [String] the request as a JSON string
+    #
     def to_json(*)
       to_h.to_json(*)
     end
@@ -74,9 +126,14 @@ module JSONRPC
 
     # Validates that the method name meets JSON-RPC 2.0 requirements
     #
+    # @api private
+    #
     # @param method [String] the method name
+    #
     # @raise [ArgumentError] if method is not a String or is reserved
     #
+    # @return [void]
+    #
     def validate_method(method)
       raise ArgumentError, 'Method must be a String' unless method.is_a?(String)
 
@@ -87,9 +144,14 @@ module JSONRPC
 
     # Validates that the params is a valid structure according to JSON-RPC 2.0
     #
+    # @api private
+    #
     # @param params [Hash, Array, nil] the parameters
+    #
     # @raise [ArgumentError] if params is not a Hash, Array, or nil
     #
+    # @return [void]
+    #
     def validate_params(params)
       return if params.nil?
 
@@ -100,9 +162,14 @@ module JSONRPC
 
     # Validates that the id meets JSON-RPC 2.0 requirements
     #
+    # @api private
+    #
     # @param id [String, Integer, nil] the request identifier
+    #
     # @raise [ArgumentError] if id is not a String, Integer, or nil
     #
+    # @return [void]
+    #
     def validate_id(id)
       return if id.nil?
 

data/lib/jsonrpc/response.rb

@@ -3,6 +3,11 @@
 module JSONRPC
   # A JSON-RPC 2.0 Response object
   #
+  # @api public
+  #
+  # Represents the outcome of a method invocation, either containing a result for
+  # successful calls or an error for failed ones. This follows the JSON-RPC 2.0 specification.
+  #
   # When a rpc call is made, the Server must reply with a Response, except for notifications.
   # A Response object can contain either a result (for success) or an error (for failure),
   # but never both.
@@ -16,32 +21,68 @@ module JSONRPC
   #
   class Response
     # JSON-RPC protocol version
+    #
+    # @api public
+    #
+    # @example
+    #   response.jsonrpc # => "2.0"
+    #
     # @return [String]
     #
     attr_reader :jsonrpc
 
     # The result of the method invocation (for success)
+    #
+    # @api public
+    #
+    # @example
+    #   response.result # => 42
+    #
     # @return [Object, nil]
     #
     attr_reader :result
 
     # The error object (for failure)
+    #
+    # @api public
+    #
+    # @example
+    #   response.error # => #<JSONRPC::Error...>
+    #
     # @return [JSONRPC::Error, nil]
     #
     attr_reader :error
 
     # The request identifier
+    #
+    # @api public
+    #
+    # @example
+    #   response.id # => 1
+    #
     # @return [String, Integer, nil]
     #
     attr_reader :id
 
     # Creates a new JSON-RPC 2.0 Response object
     #
+    # @api public
+    #
+    # @example Create a successful response
+    #   JSONRPC::Response.new(id: 1, result: 42)
+    #
+    # @example Create an error response
+    #   error = JSONRPC::Error.new("Method not found", code: -32601)
+    #   JSONRPC::Response.new(id: 1, error: error)
+    #
     # @param result [Object, nil] the result of the method invocation (for success)
     # @param error [JSONRPC::Error, nil] the error object (for failure)
     # @param id [String, Integer, nil] the request identifier
+    #
     # @raise [ArgumentError] if both result and error are present or both are nil
+    #
     # @raise [ArgumentError] if error is present but not a JSONRPC::Error
+    #
     # @raise [ArgumentError] if id is not a String, Integer, or nil
     #
     def initialize(id:, result: nil, error: nil)
@@ -57,6 +98,11 @@ module JSONRPC
 
     # Checks if the response is successful
     #
+    # @api public
+    #
+    # @example
+    #   response.success? # => true
+    #
     # @return [Boolean] true if the response contains a result, false if it contains an error
     #
     def success?
@@ -65,6 +111,11 @@ module JSONRPC
 
     # Checks if the response is an error
     #
+    # @api public
+    #
+    # @example
+    #   response.error? # => false
+    #
     # @return [Boolean] true if the response contains an error, false if it contains a result
     #
     def error?
@@ -73,6 +124,11 @@ module JSONRPC
 
     # Converts the response to a JSON-compatible Hash
     #
+    # @api public
+    #
+    # @example
+    #   response.to_h # => { jsonrpc: "2.0", result: 42, id: 1 }
+    #
     # @return [Hash] the response as a JSON-compatible Hash
     #
     def to_h
@@ -90,6 +146,15 @@ module JSONRPC
       hash
     end
 
+    # Converts the response to a JSON string
+    #
+    # @api public
+    #
+    # @example
+    #   response.to_json # => '{"jsonrpc":"2.0","result":42,"id":1}'
+    #
+    # @return [String] the response as a JSON string
+    #
     def to_json(*)
       to_h.to_json(*)
     end
@@ -98,11 +163,17 @@ module JSONRPC
 
     # Validates that exactly one of result or error is present
     #
+    # @api private
+    #
     # @param result [Object, nil] the result
     # @param error [JSONRPC::Error, nil] the error
+    #
     # @raise [ArgumentError] if both result and error are present or both are nil
+    #
     # @raise [ArgumentError] if error is present but not a JSONRPC::Error
     #
+    # @return [void]
+    #
     def validate_result_and_error(result, error)
       raise ArgumentError, 'Either result or error must be present' if result.nil? && error.nil?
 
@@ -115,9 +186,14 @@ module JSONRPC
 
     # Validates that the id meets JSON-RPC 2.0 requirements
     #
+    # @api private
+    #
     # @param id [String, Integer, nil] the request identifier
+    #
     # @raise [ArgumentError] if id is not a String, Integer, or nil
     #
+    # @return [void]
+    #
     def validate_id(id)
       return if id.nil?
 

data/lib/jsonrpc/validator.rb

@@ -1,11 +1,21 @@
 # frozen_string_literal: true
 
 module JSONRPC
-  # Validates JSON-RPC 2.0 requests and notifications.
+  # Validates JSON-RPC 2.0 requests, notifications and batches
+  #
+  # @api public
+  #
+  # The Validator handles parameter validation for JSON-RPC requests by checking
+  # method signatures against registered procedure definitions using Dry::Validation contracts.
+  #
+  # @example Validate a single request
+  #   validator = JSONRPC::Validator.new
+  #   error = validator.validate(request)
+  #
   class Validator
-    # Validates a single request, notification or a batch of requests and/or notifications.
+    # Validates a single request, notification or a batch
     #
-    # @param [JSONRPC::BatchRequest, JSONRPC::Request, JSONRPC::Notification] batch_or_request
+    # @api public
     #
     # @example Validate a single request
     #   validator = JSONRPC::Validator.new
@@ -15,7 +25,9 @@ module JSONRPC
     #   validator = JSONRPC::Validator.new
     #   errors = validator.validate(batch)
     #
-    # @return [JSONRPC::Error, Array<JSONRPC::Error>, nil]
+    # @param batch_or_request [JSONRPC::BatchRequest, JSONRPC::Request, JSONRPC::Notification] the object to validate
+    #
+    # @return [JSONRPC::Error, Array<JSONRPC::Error>, nil] error(s) if validation fails, nil if successful
     #
     def validate(batch_or_request)
       case batch_or_request
@@ -28,6 +40,14 @@ module JSONRPC
 
     private
 
+    # Validates a batch of requests/notifications
+    #
+    # @api private
+    #
+    # @param batch [BatchRequest] the batch to validate
+    #
+    # @return [Array<Error>, nil] array of errors or nil if all valid
+    #
     def validate_batch_params(batch)
       errors = batch.map { |req| validate_request_params(req) }
 
@@ -36,7 +56,14 @@ module JSONRPC
       errors.any? ? errors : nil
     end
 
-    # @param [Request, Notification] request_or_notification
+    # Validates a single request or notification
+    #
+    # @api private
+    #
+    # @param request_or_notification [Request, Notification] the request to validate
+    #
+    # @return [Error, nil] error if validation fails, nil if successful
+    #
     def validate_request_params(request_or_notification)
       config = JSONRPC.configuration
 
@@ -72,7 +99,7 @@ module JSONRPC
 
       nil
     rescue StandardError => e
-      if ENV['DEBUG_RACK'] == 'true'
+      if JSONRPC.configuration.log_request_validation_errors
         puts "Validation error: #{e.message}"
         puts e.backtrace.join("\n")
       end
@@ -80,6 +107,15 @@ module JSONRPC
       InternalError.new(request_id: extract_request_id(request_or_notification))
     end
 
+    # Prepares parameters for validation based on procedure configuration
+    #
+    # @api private
+    #
+    # @param request [Request, Notification] the request
+    # @param procedure [Configuration::Procedure] the procedure configuration
+    #
+    # @return [Hash, InvalidParamsError] prepared params or error
+    #
     def prepare_params_for_validation(request, procedure)
       if procedure.allow_positional_arguments
         handle_positional_arguments(request, procedure)
@@ -88,6 +124,15 @@ module JSONRPC
       end
     end
 
+    # Handles validation for procedures that allow positional arguments
+    #
+    # @api private
+    #
+    # @param request_or_notification [Request, Notification] the request
+    # @param procedure [Configuration::Procedure] the procedure configuration
+    #
+    # @return [Hash, InvalidParamsError] prepared params or error
+    #
     def handle_positional_arguments(request_or_notification, procedure)
       case request_or_notification.params
       when Array
@@ -112,6 +157,14 @@ module JSONRPC
       end
     end
 
+    # Handles validation for procedures that only accept named arguments
+    #
+    # @api private
+    #
+    # @param request_or_notification [Request, Notification] the request
+    #
+    # @return [Hash, InvalidParamsError] prepared params or error
+    #
     def handle_named_arguments(request_or_notification)
       case request_or_notification.params
       when Hash
@@ -128,6 +181,14 @@ module JSONRPC
       end
     end
 
+    # Extracts the request ID from a request or notification
+    #
+    # @api private
+    #
+    # @param request_or_notification [Request, Notification] the request
+    #
+    # @return [String, Integer, nil] the request ID or nil for notifications
+    #
     def extract_request_id(request_or_notification)
       case request_or_notification
       when Request

data/lib/jsonrpc/version.rb

@@ -1,5 +1,15 @@
 # frozen_string_literal: true
 
+# Encapsulates all the gem's logic for JSON-RPC 2.0 protocol handling
+#
+# @api public
+#
 module JSONRPC
-  VERSION = '0.1.0'
+  # The version of the gem
+  #
+  # @api public
+  #
+  # @return [String] The current version number
+  #
+  VERSION = '0.2.0'
 end

data/lib/jsonrpc.rb

@@ -5,12 +5,60 @@ require 'dry-validation'
 
 Dry::Validation.load_extensions(:predicates_as_macros)
 
-# Encapsulates all the gem's logic
+# JSON-RPC 2.0 middleware implementation for Ruby
+#
+# @api public
+#
+# This module provides a complete implementation of the JSON-RPC 2.0 specification
+# as Rack middleware. It handles parsing, validation, and error handling for
+# JSON-RPC requests, notifications, and batch operations.
+#
+# @example Basic configuration
+#   JSONRPC.configure do
+#     procedure('add') do
+#       params do
+#         required(:a).value(:integer)
+#         required(:b).value(:integer)
+#       end
+#     end
+#   end
+#
+# @example Using the middleware
+#   use JSONRPC::Middleware, path: '/api/v1/rpc'
+#
 module JSONRPC
+  # Configures the JSON-RPC middleware with procedure definitions
+  #
+  # @api public
+  #
+  # @example Configure procedures
+  #   JSONRPC.configure do
+  #     procedure('subtract') do
+  #       params do
+  #         required(:minuend).value(:integer)
+  #         required(:subtrahend).value(:integer)
+  #       end
+  #     end
+  #   end
+  #
+  # @yield Block containing procedure definitions using the Configuration DSL
+  #
+  # @return [void]
+  #
   def self.configure(&)
     Configuration.instance.instance_eval(&)
   end
 
+  # Returns the current JSON-RPC configuration instance
+  #
+  # @api public
+  #
+  # @example Access configuration
+  #   config = JSONRPC.configuration
+  #   config.procedure?('add') # => true/false
+  #
+  # @return [Configuration] The singleton configuration instance
+  #
   def self.configuration
     Configuration.instance
   end
@@ -20,6 +68,10 @@ loader = Zeitwerk::Loader.for_gem
 loader.log! if ENV['DEBUG_ZEITWERK'] == 'true'
 loader.enable_reloading
 loader.collapse("#{__dir__}/jsonrpc/errors")
+loader.ignore("#{__dir__}/jsonrpc/railtie.rb")
 loader.inflector.inflect('jsonrpc' => 'JSONRPC')
 loader.setup
 loader.eager_load
+
+# Only load Rails integration if Rails is available
+require_relative 'jsonrpc/railtie' if defined?(Rails)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonrpc-middleware
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Wilson Silva
@@ -45,14 +45,19 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".aiexclude"
+- ".claude/commands/document.md"
+- ".claude/docs/yard.md"
 - ".claude/settings.local.json"
 - ".editorconfig"
+- ".env.example"
 - ".overcommit.yml"
 - ".rspec"
 - ".rubocop.yml"
 - ".tool-versions"
 - ".yardstick.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Guardfile
 - LICENSE.txt
@@ -60,17 +65,59 @@ files:
 - Rakefile
 - Steepfile
 - docs/JSON-RPC-2.0-Specification.md
+- examples/README.md
 - examples/procedures.rb
 - examples/rack-echo/Gemfile
 - examples/rack-echo/Gemfile.lock
 - examples/rack-echo/README.md
 - examples/rack-echo/app.rb
 - examples/rack-echo/config.ru
+- examples/rack-single-file/README.md
+- examples/rack-single-file/config.ru
 - examples/rack/Gemfile
 - examples/rack/Gemfile.lock
 - examples/rack/README.md
 - examples/rack/app.rb
 - examples/rack/config.ru
+- examples/rails-single-file/config.ru
+- examples/rails/.gitignore
+- examples/rails/.ruby-version
+- examples/rails/Gemfile
+- examples/rails/Gemfile.lock
+- examples/rails/README.md
+- examples/rails/Rakefile
+- examples/rails/app/controllers/application_controller.rb
+- examples/rails/app/controllers/jsonrpc_controller.rb
+- examples/rails/bin/dev
+- examples/rails/bin/rails
+- examples/rails/bin/rake
+- examples/rails/bin/setup
+- examples/rails/config.ru
+- examples/rails/config/application.rb
+- examples/rails/config/boot.rb
+- examples/rails/config/credentials.yml.enc
+- examples/rails/config/environment.rb
+- examples/rails/config/environments/development.rb
+- examples/rails/config/environments/production.rb
+- examples/rails/config/environments/test.rb
+- examples/rails/config/initializers/cors.rb
+- examples/rails/config/initializers/filter_parameter_logging.rb
+- examples/rails/config/initializers/inflections.rb
+- examples/rails/config/initializers/jsonrpc.rb
+- examples/rails/config/locales/en.yml
+- examples/rails/config/puma.rb
+- examples/rails/config/routes.rb
+- examples/rails/public/robots.txt
+- examples/sinatra-classic/Gemfile
+- examples/sinatra-classic/Gemfile.lock
+- examples/sinatra-classic/README.md
+- examples/sinatra-classic/app.rb
+- examples/sinatra-classic/config.ru
+- examples/sinatra-modular/Gemfile
+- examples/sinatra-modular/Gemfile.lock
+- examples/sinatra-modular/README.md
+- examples/sinatra-modular/app.rb
+- examples/sinatra-modular/config.ru
 - lib/jsonrpc.rb
 - lib/jsonrpc/batch_request.rb
 - lib/jsonrpc/batch_response.rb
@@ -85,6 +132,7 @@ files:
 - lib/jsonrpc/middleware.rb
 - lib/jsonrpc/notification.rb
 - lib/jsonrpc/parser.rb
+- lib/jsonrpc/railtie.rb
 - lib/jsonrpc/request.rb
 - lib/jsonrpc/response.rb
 - lib/jsonrpc/validator.rb