jsonrpc-middleware 0.1.0 → 0.3.0

data/lib/jsonrpc/error.rb

@@ -3,44 +3,92 @@
 module JSONRPC
   # A JSON-RPC 2.0 Error object
   #
+  # @api public
+  #
   # When a rpc call encounters an error, the Response Object must contain an Error object
-  # with specific properties according to the JSON-RPC 2.0.
+  # with specific properties according to the JSON-RPC 2.0 specification.
   #
   # @example Create an error
   #   error = JSONRPC::Error.new(
+  #     "Invalid Request",
   #     code: -32600,
-  #     message: "Invalid Request",
   #     data: { detail: "Additional information about the error" }
   #   )
   #
   class Error < StandardError
     # The request identifier (optional for notifications)
+    #
+    # @api public
+    #
+    # @example Get request ID
+    #   error.request_id # => "1"
+    #
+    # @example Set request ID
+    #   error.request_id = "2"
+    #
     # @return [String, Integer, nil]
     #
     attr_accessor :request_id
 
     # Error code indicating the error type
+    #
+    # @api public
+    #
+    # @example Get error code
+    #   error.code # => -32600
+    #
+    # @example Set error code
+    #   error.code = -32601
+    #
     # @return [Integer]
     #
     attr_accessor :code
 
     # Short description of the error
+    #
+    # @api public
+    #
+    # @example Get error message
+    #   error.message # => "Invalid Request"
+    #
+    # @example Set error message
+    #   error.message = "Method not found"
+    #
     # @return [String]
     #
     attr_accessor :message
 
     # Additional information about the error (optional)
+    #
+    # @api public
+    #
+    # @example Get error data
+    #   error.data # => { "detail" => "Additional info" }
+    #
+    # @example Set error data
+    #   error.data = { "field" => "invalid" }
+    #
     # @return [Hash, Array, String, Number, Boolean, nil]
     #
     attr_accessor :data
 
     # Creates a new JSON-RPC 2.0 Error object
     #
+    # @api public
+    #
+    # @example Create an error with code and message
+    #   error = JSONRPC::Error.new("Invalid Request", code: -32600)
+    #
+    # @example Create an error with additional data
+    #   error = JSONRPC::Error.new("Invalid params", code: -32602, data: { "field" => "missing" })
+    #
     # @param message [String] short description of the error
     # @param code [Integer] a number indicating the error type
     # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
     # @param request_id [String, Integer, nil] the request identifier
+    #
     # @raise [ArgumentError] if code is not an Integer
+    #
     # @raise [ArgumentError] if message is not a String
     #
     def initialize(message, code:, data: nil, request_id: nil)
@@ -57,6 +105,11 @@ module JSONRPC
 
     # Converts the error to a JSON-compatible Hash
     #
+    # @api public
+    #
+    # @example Convert error to hash
+    #   error.to_h # => { code: -32600, message: "Invalid Request" }
+    #
     # @return [Hash] the error as a JSON-compatible Hash
     #
     def to_h
@@ -65,10 +118,28 @@ module JSONRPC
       hash
     end
 
+    # Converts the error to JSON
+    #
+    # @api public
+    #
+    # @example Convert error to JSON
+    #   error.to_json # => '{"code":-32600,"message":"Invalid Request"}'
+    #
+    # @return [String] the error as a JSON string
+    #
     def to_json(*)
       to_h.to_json(*)
     end
 
+    # Converts the error to a complete JSON-RPC response
+    #
+    # @api public
+    #
+    # @example Convert error to response
+    #   error.to_response # => { jsonrpc: "2.0", error: { code: -32600, message: "Invalid Request" }, id: nil }
+    #
+    # @return [Hash] a complete JSON-RPC response with this error
+    #
     def to_response
       Response.new(id: request_id, error: self).to_h
     end
@@ -77,18 +148,28 @@ module JSONRPC
 
     # Validates that the code is a valid Integer
     #
+    # @api private
+    #
     # @param code [Integer] the error code
+    #
     # @raise [ArgumentError] if code is not an Integer
     #
+    # @return [void]
+    #
     def validate_code(code)
       raise ArgumentError, 'Error code must be an Integer' unless code.is_a?(Integer)
     end
 
     # Validates that the message is a String
     #
+    # @api private
+    #
     # @param message [String] the error message
+    #
     # @raise [ArgumentError] if message is not a String
     #
+    # @return [void]
+    #
     def validate_message(message)
       raise ArgumentError, 'Error message must be a String' unless message.is_a?(String)
     end

data/lib/jsonrpc/errors/internal_error.rb

@@ -6,16 +6,28 @@ module JSONRPC
   # Raised when there was an internal JSON-RPC error.
   #
   # @example Create an internal error
-  #   error = JSONRPC::Errors::InternalError.new(data: { details: "Unexpected server error" })
+  #   error = JSONRPC::Errors::InternalError.new(data: { details: 'Unexpected server error' })
   #
   class InternalError < Error
     # Creates a new Internal Error with code -32603
     #
+    # @api public
+    #
+    # @example Create an internal error
+    #   error = JSONRPC::InternalError.new
+    #
+    # @example Create an internal error with exception details
+    #   error = JSONRPC::InternalError.new(data: { exception: "NoMethodError" }, request_id: 1)
+    #
     # @param message [String] short description of the error
     # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
     # @param request_id [String, Integer, nil] the request identifier
     #
-    def initialize(message = 'Internal JSON-RPC error.', data: nil, request_id: nil)
+    def initialize(
+      message = 'Internal JSON-RPC error.',
+      data: nil,
+      request_id: nil
+    )
       super(
         message,
         code: -32_603,

data/lib/jsonrpc/errors/invalid_params_error.rb

@@ -11,11 +11,23 @@ module JSONRPC
   class InvalidParamsError < Error
     # Creates a new Invalid Params Error with code -32602
     #
+    # @api public
+    #
+    # @example Create an invalid params error
+    #   error = JSONRPC::InvalidParamsError.new
+    #
+    # @example Create an invalid params error with validation details
+    #   error = JSONRPC::InvalidParamsError.new(data: { errors: ["param a is required"] })
+    #
     # @param message [String] short description of the error
     # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
     # @param request_id [String, Integer, nil] the request identifier
     #
-    def initialize(message = 'Invalid method parameter(s).', data: nil, request_id: nil)
+    def initialize(
+      message = 'Invalid method parameter(s).',
+      data: nil,
+      request_id: nil
+    )
       super(
         message,
         code: -32_602,

data/lib/jsonrpc/errors/invalid_request_error.rb

@@ -11,6 +11,14 @@ module JSONRPC
   class InvalidRequestError < Error
     # Creates a new Invalid Request Error with code -32600
     #
+    # @api public
+    #
+    # @example Create an invalid request error
+    #   error = JSONRPC::InvalidRequestError.new
+    #
+    # @example Create an invalid request error with custom data
+    #   error = JSONRPC::InvalidRequestError.new(data: { field: "missing jsonrpc" })
+    #
     # @param message [String] short description of the error
     # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
     # @param request_id [String, Integer, nil] the request identifier

data/lib/jsonrpc/errors/method_not_found_error.rb

@@ -11,6 +11,14 @@ module JSONRPC
   class MethodNotFoundError < Error
     # Creates a new Method Not Found Error with code -32601
     #
+    # @api public
+    #
+    # @example Create a method not found error
+    #   error = JSONRPC::MethodNotFoundError.new
+    #
+    # @example Create a method not found error with method name
+    #   error = JSONRPC::MethodNotFoundError.new(data: { method: "unknown_method" })
+    #
     # @param message [String] short description of the error
     # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
     # @param request_id [String, Integer, nil] the request identifier

data/lib/jsonrpc/errors/parse_error.rb

@@ -12,6 +12,14 @@ module JSONRPC
   class ParseError < Error
     # Creates a new Parse Error with code -32700
     #
+    # @api public
+    #
+    # @example Create a parse error with default message
+    #   error = JSONRPC::ParseError.new
+    #
+    # @example Create a parse error with custom data
+    #   error = JSONRPC::ParseError.new(data: { detail: "Unexpected end of input" })
+    #
     # @param message [String] short description of the error
     # @param data [Hash, Array, String, Number, Boolean, nil] additional error information
     #

data/lib/jsonrpc/helpers.rb

@@ -3,32 +3,140 @@
 module JSONRPC
   # Framework-agnostic helpers for JSON-RPC
   module Helpers
+    # Extends the including class with ClassMethods when module is included
+    #
+    # @api public
+    #
+    # @example Include helpers in a class
+    #   class MyController
+    #     include JSONRPC::Helpers
+    #   end
+    #
+    # @param base [Class] The class including this module
+    #
+    # @return [void]
+    #
     def self.included(base)
       base.extend(ClassMethods)
     end
 
     # Class methods for registering JSON-RPC procedure handlers
     module ClassMethods
+      # Registers a JSON-RPC procedure with the given method name
+      #
+      # @api public
+      #
+      # @example Register a procedure
+      #   jsonrpc_method('add') do
+      #     params do
+      #       required(:a).value(:integer)
+      #       required(:b).value(:integer)
+      #     end
+      #   end
+      #
+      # @param method_name [String, Symbol] the name of the method
+      #
+      # @yield Block containing the procedure definition
+      #
+      # @return [Configuration::Procedure] the registered procedure
+      #
       def jsonrpc_method(method_name, &)
         Configuration.instance.procedure(method_name, &)
       end
     end
 
-    def jsonrpc_batch? = @env.key?('jsonrpc.batch')
-    def jsonrpc_notification? = @env.key?('jsonrpc.notification')
-    def jsonrpc_request? = @env.key?('jsonrpc.request')
+    # Checks if the current request is a batch request
+    #
+    # @api public
+    #
+    # @example Check if request is batch
+    #   jsonrpc_batch? # => true/false
+    #
+    # @return [Boolean] true if current request is a batch
+    #
+    def jsonrpc_batch? = env.key?('jsonrpc.batch')
 
-    # Get the current JSON-RPC request object
-    def jsonrpc_batch = @env['jsonrpc.batch']
-    def jsonrpc_request = @env['jsonrpc.request']
-    def jsonrpc_notification = @env['jsonrpc.notification']
+    # Checks if the current request is a notification
+    #
+    # @api public
+    #
+    # @example Check if request is notification
+    #   jsonrpc_notification? # => true/false
+    #
+    # @return [Boolean] true if current request is a notification
+    #
+    def jsonrpc_notification? = env.key?('jsonrpc.notification')
 
-    # Create a JSON-RPC response
+    # Checks if the current request is a regular request
+    #
+    # @api public
+    #
+    # @example Check if request is regular request
+    #   jsonrpc_request? # => true/false
+    #
+    # @return [Boolean] true if current request is a regular request
+    #
+    def jsonrpc_request? = env.key?('jsonrpc.request')
+
+    # Gets the current JSON-RPC batch request object
+    #
+    # @api public
+    #
+    # @example Get current batch
+    #   batch = jsonrpc_batch
+    #
+    # @return [BatchRequest, nil] the current batch request or nil
+    #
+    def jsonrpc_batch = env['jsonrpc.batch']
+
+    # Gets the current JSON-RPC request object
+    #
+    # @api public
+    #
+    # @example Get current request
+    #   request = jsonrpc_request
+    #
+    # @return [Request, nil] the current request or nil
+    #
+    def jsonrpc_request = env['jsonrpc.request']
+
+    # Gets the current JSON-RPC notification object
+    #
+    # @api public
+    #
+    # @example Get current notification
+    #   notification = jsonrpc_notification
+    #
+    # @return [Notification, nil] the current notification or nil
+    #
+    def jsonrpc_notification = env['jsonrpc.notification']
+
+    # Creates a JSON-RPC response
+    #
+    # @api public
+    #
+    # @example Create a successful response
+    #   jsonrpc_response(42) # => [200, headers, body]
+    #
+    # @param result [Object] the result to return
+    #
+    # @return [Array] Rack response tuple
+    #
     def jsonrpc_response(result)
       [200, { 'content-type' => 'application/json' }, [Response.new(id: jsonrpc_request.id, result: result).to_json]]
     end
 
-    # Create a JSON-RPC response
+    # Creates a JSON-RPC batch response
+    #
+    # @api public
+    #
+    # @example Create a batch response
+    #   jsonrpc_batch_response([response1, response2]) # => [200, headers, body]
+    #
+    # @param responses [Array] array of responses
+    #
+    # @return [Array] Rack response tuple
+    #
     def jsonrpc_batch_response(responses)
       # If batch contained only notifications, responses will be empty or contain only nils
       return [204, {}, []] if responses.compact.empty?
@@ -36,48 +144,131 @@ module JSONRPC
       [200, { 'content-type' => 'application/json' }, [responses.to_json]]
     end
 
+    # Creates a response for a notification (no content)
+    #
+    # @api public
+    #
+    # @example Create notification response
+    #   jsonrpc_notification_response # => [204, {}, []]
+    #
+    # @return [Array] Rack response tuple with 204 status
+    #
     def jsonrpc_notification_response
       [204, {}, []]
     end
 
-    # Create a JSON-RPC error response
+    # Creates a JSON-RPC error response
+    #
+    # @api public
+    #
+    # @example Create error response
+    #   error = JSONRPC::Error.new(code: -32600, message: "Invalid Request")
+    #   jsonrpc_error(error) # => JSON string
+    #
+    # @param error [Error] the error object
+    #
+    # @return [String] JSON-formatted error response
+    #
     def jsonrpc_error(error)
       Response.new(id: jsonrpc_request.id, error: error).to_json
     end
 
-    # Get the current JSON-RPC request params object
+    # Gets the current JSON-RPC request params object
+    #
+    # @api public
+    #
+    # @example Get request parameters
+    #   params = jsonrpc_params # => [1, 2, 3] or {"a": 1, "b": 2}
+    #
+    # @return [Array, Hash, nil] the request parameters
+    #
     def jsonrpc_params
       jsonrpc_request.params
     end
 
-    # Create a Parse error (-32700)
-    # Used when invalid JSON was received by the server
+    # Creates a Parse error (-32700) for invalid JSON
+    #
+    # @api public
+    #
+    # @example Create parse error
+    #   jsonrpc_parse_error # => JSON error response
+    #
+    # @param data [Object, nil] additional error data
+    #
+    # @return [String] JSON-formatted error response
+    #
     def jsonrpc_parse_error(data: nil)
       jsonrpc_error(ParseError.new(data: data))
     end
 
-    # Create an Invalid Request error (-32600)
-    # Used when the JSON sent is not a valid Request object
+    # Creates an Invalid Request error (-32600) for invalid Request objects
+    #
+    # @api public
+    #
+    # @example Create invalid request error
+    #   jsonrpc_invalid_request_error # => JSON error response
+    #
+    # @param data [Object, nil] additional error data
+    #
+    # @return [String] JSON-formatted error response
+    #
     def jsonrpc_invalid_request_error(data: nil)
       jsonrpc_error(InvalidRequestError.new(data: data))
     end
 
-    # Create a Method not found error (-32601)
-    # Used when the method does not exist / is not available
+    # Creates a Method not found error (-32601) for missing methods
+    #
+    # @api public
+    #
+    # @example Create method not found error
+    #   jsonrpc_method_not_found_error # => JSON error response
+    #
+    # @param data [Object, nil] additional error data
+    #
+    # @return [String] JSON-formatted error response
+    #
     def jsonrpc_method_not_found_error(data: nil)
       jsonrpc_error(MethodNotFoundError.new(data: data))
     end
 
-    # Create an Invalid params error (-32602)
-    # Used when invalid method parameter(s) were received
+    # Creates an Invalid params error (-32602) for invalid parameters
+    #
+    # @api public
+    #
+    # @example Create invalid params error
+    #   jsonrpc_invalid_params_error # => JSON error response
+    #
+    # @param data [Object, nil] additional error data
+    #
+    # @return [String] JSON-formatted error response
+    #
     def jsonrpc_invalid_params_error(data: nil)
       jsonrpc_error(InvalidParamsError.new(data: data))
     end
 
-    # Create an Internal error (-32603)
-    # Used for implementation-defined server errors
+    # Creates an Internal error (-32603) for server errors
+    #
+    # @api public
+    #
+    # @example Create internal error
+    #   jsonrpc_internal_error # => JSON error response
+    #
+    # @param data [Object, nil] additional error data
+    #
+    # @return [String] JSON-formatted error response
+    #
     def jsonrpc_internal_error(data: nil)
       jsonrpc_error(InternalError.new(data: data))
     end
+
+    # Gets the Rack environment hash from @env or the Rails Request
+    #
+    # @api private
+    #
+    # @return [Hash] the Rack environment hash
+    #
+    def env
+      @env ||= request.env
+    end
   end
 end