JSONRPC Interface

https://github.com/0exp/jsonrpc_interface
Admin
JSONRPC Interface is an object-oriented Ruby gem implementing the JSON-RPC 2.0 protocol to validate,...
Tokens:24,469
Snippets:267
Trust Score:8.9
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install JSONRPC Interface

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Installation instructions for the gem.

```ruby
gem 'jsonrpc_interface'
```

```shell
bundle install
# --- or ---
gem install jsonrpc_interface
```

```ruby
require 'jsonrpc_interface'
```

--------------------------------

### Quick Start with JSONRPC::RPCObject

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Demonstrates creating requests, parsing responses, and handling errors using the RPCObject factory.

```ruby
require 'jsonrpc_interface'

# Create a request
request = JSONRPC::RPCObject.request(
  method: 'user.get',
  params: { id: 1 },
  id: 'req-001'
)

# Send it (serialize to JSON, transmit to server)

# Receive and parse response
response = JSONRPC::RPCObject.response(
  { id: 1, name: 'Alice' },
  request_id: 'req-001'
)

# Check success
if response.success?
  puts "Got result: #{response.result}"
end

# Handle error
error = JSONRPC::RPCObject.method_not_found_error(request_id: 'req-001')
if error.error?
  puts "Error: #{error.error[:message]}"
end
```

--------------------------------

### Define Hash Type Variations

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/types.md

Examples of flexible hash structures used for params, result, and data fields.

```ruby
{ count: 42, active: true, name: "Alice", rate: 3.14 }
```

```ruby
{ user: { id: 1, name: "Alice" }, settings: { theme: "dark" } }
```

```ruby
{ items: [1, 2, 3], tags: ["foo", "bar"] }
```

```ruby
{ data: { nested: { value: 42, tags: ["a", "b"] } }, count: 3 }
```

--------------------------------

### Handle Schema Validation Errors in Ruby

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/errors.md

Examples of triggering SmartCore::Schema::ValidationError when constructing JSONRPC requests with invalid data.

```ruby
# Missing 'method' field in request
begin
  JSONRPC::Request.new(
    jsonrpc: '2.0',
    params: {},
    id: 'req-001'
    # method is missing!
  )
rescue SmartCore::Schema::ValidationError => e
  puts "Validation error: #{e.message}"
end
```

```ruby
# Empty 'method' string
begin
  JSONRPC::Request.new(
    jsonrpc: '2.0',
    method: '',  # Empty!
    params: {},
    id: 'req-001'
  )
rescue SmartCore::Schema::ValidationError => e
  puts "Validation error: #{e.message}"
end
```

```ruby
# 'jsonrpc' must be exactly '2.0'
begin
  JSONRPC::Request.new(
    jsonrpc: '1.0',  # Wrong version!
    method: 'test',
    params: {},
    id: 'req-001'
  )
rescue SmartCore::Schema::ValidationError => e
  puts "Validation error: #{e.message}"
end
```

--------------------------------

### Run full build

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Executes the complete build pipeline including type checking, linting, and testing.

```shell
bundle exec rake
```

--------------------------------

### Create JSON-RPC Requests

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Demonstrates creating request objects using direct instantiation or the RPCObject factory.

```ruby
# Direct instantiation
request = JSONRPC::Request.new(
  jsonrpc: '2.0',
  method: 'user.create',
  params: { name: 'Alice', email: 'alice@example.com' },
  id: SecureRandom.uuid
)

# Via factory
request = JSONRPC::RPCObject.request(
  method: 'user.create',
  params: { name: 'Alice', email: 'alice@example.com' },
  id: SecureRandom.uuid
)
```

--------------------------------

### Create JSON-RPC Responses

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Demonstrates creating response objects using direct instantiation or the RPCObject factory.

```ruby
# Direct instantiation
response = JSONRPC::Response.new(
  jsonrpc: '2.0',
  result: { user_id: 42, status: 'created' },
  id: 'req-001'
)

# Via factory (returns nil if no request_id)
response = JSONRPC::RPCObject.response(
  { user_id: 42, status: 'created' },
  request_id: 'req-001'
)
```

--------------------------------

### Create JSON-RPC Notifications

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Demonstrates creating notification objects using direct instantiation or the RPCObject factory.

```ruby
# Direct instantiation
notification = JSONRPC::Notification.new(
  jsonrpc: '2.0',
  method: 'log.info',
  params: { message: 'Event occurred' }
)

# Via factory
notification = JSONRPC::RPCObject.notification(
  method: 'log.info',
  params: { message: 'Event occurred' }
)
```

--------------------------------

### Initialize JSONRPC Library

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/module-overview.md

Load the library to access all JSONRPC classes and constants under the JSONRPC namespace.

```ruby
require 'jsonrpc_interface'
# All classes and constants are now available under JSONRPC::
```

--------------------------------

### Create a Notification Instance

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/notification.md

Instantiate a new notification object with specific method and parameters.

```ruby
# Create a notification to log an event
notification = JSONRPC::Notification.new(
  jsonrpc: '2.0',
  method: 'log.event',
  params: {
    level: 'info',
    message: 'User signed in',
    user_id: 123,
    timestamp: Time.now.to_i
  }
)

puts notification.method        # => 'log.event'
puts notification.params[:level] # => 'info'
```

--------------------------------

### Accessing Library Version

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/configuration.md

Retrieves the current version string of the library.

```ruby
require 'jsonrpc_interface'

JSONRPC::VERSION
# => '0.1.0'
```

--------------------------------

### Initialize JSONRPC Request

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Shows the structure and initialization of a JSONRPC Request object.

```ruby
JSONRPC::Request
JSONRPC::Request.new(jsonrpc: '2.0', method: 'some.method', params: { some: 'params' }, id: 'sOmEiD')
JSONRPC::Request#jsonrpc (String)
JSONRPC::Request#method (String)
JSONRPC::Request#params (Hash)
JSONRPC::Request#id (String)
```

--------------------------------

### Create a Basic JSONRPC Request

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/request.md

Instantiates a new JSONRPC::Request object with required fields.

```ruby
# Create a simple request to fetch a user
request = JSONRPC::Request.new(
  jsonrpc: '2.0',
  method: 'user.get',
  params: { user_id: 42 },
  id: SecureRandom.uuid
)

puts request.method        # => 'user.get'
puts request.params        # => {:user_id=>42}
puts request.id            # => [UUID string]
```

--------------------------------

### Constructing a JSONRPC::Request

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/request.md

Initializes a new request object with required protocol version, method, parameters, and ID. Throws SmartCore::Schema::ValidationError if input parameters do not meet schema requirements.

```ruby
request = JSONRPC::Request.new(
  jsonrpc: '2.0',
  method: 'user.create',
  params: { name: 'Alice', email: 'alice@example.com' },
  id: 'req-12345'
)

request.method       # => 'user.create'
request.params       # => {:name => 'Alice', :email => 'alice@example.com'}
request.id           # => 'req-12345'
request.jsonrpc      # => '2.0'
```

--------------------------------

### Use RPCObject Factory

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/response.md

Use the factory method for a more concise way to generate response objects.

```ruby
# Factory method for convenience
user_data = { user_id: 42, name: 'Alice', email: 'alice@example.com' }
response = JSONRPC::RPCObject.response(user_data, request_id: 'req-001')

puts response.success?  # => true
puts response.error?    # => false
```

--------------------------------

### Create JSON-RPC Error Responses

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Demonstrates creating error response objects using direct instantiation or the RPCObject factory.

```ruby
# Direct instantiation
error = JSONRPC::ErrorResponse.new(
  jsonrpc: '2.0',
  error: {
    code: -32601,
    message: 'Method Not Found',
    data: {}
  },
  id: 'req-001'
)

# Via factory
error = JSONRPC::RPCObject.method_not_found_error(request_id: 'req-001')
```

--------------------------------

### JSONRPC Object Instantiation

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Direct instantiation of JSON-RPC components using class constructors.

```APIDOC
## Class Constructors

### JSONRPC::Request.new
- **jsonrpc**: String (2.0)
- **method**: String
- **params**: Hash
- **id**: String/Integer

### JSONRPC::Notification.new
- **jsonrpc**: String (2.0)
- **method**: String
- **params**: Hash

### JSONRPC::Response.new
- **jsonrpc**: String (2.0)
- **result**: Any
- **id**: String/Integer

### JSONRPC::ErrorResponse.new
- **jsonrpc**: String (2.0)
- **error**: Hash (code, message, data)
- **id**: String/Integer
```

--------------------------------

### Run code style check

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Executes RuboCop to verify adherence to project coding standards.

```shell
bundle exec rake rubocop
```

--------------------------------

### Initialize JSONRPC Response

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Shows the structure and initialization of a JSONRPC Response object.

```ruby
JSONRPC::Response
JSONRPC::Response.new(jsonrpc: '2.0', result: { some: 'result' }, id: 'sOmEiD')
JSONRPC::Response#jsonrpc (String)
JSONRPC::Response#result (Hash)
JSONRPC::Response#id (String)
```

--------------------------------

### Run tests

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Executes the RSpec test suite to verify project functionality.

```shell
bundle exec rake rspec
```

--------------------------------

### Initialize JSONRPC Notification

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Shows the structure and initialization of a JSONRPC Notification object.

```ruby
JSONRPC::Notification
JSONRPC::Notification.new(jsonrpc: '2.0', method: 'some.method', params: { some: 'params' })
JSONRPC::Notification#jsonrpc (String)
JSONRPC::Notification#method (String)
JSONRPC::Notification#params (Hash)
```

--------------------------------

### Create Request via RPCObject Factory

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/request.md

Uses the RPCObject factory method to create a request, providing helper methods like request? and notification?.

```ruby
# More convenient factory method
request = JSONRPC::RPCObject.request(
  method: 'user.create',
  params: { name: 'Bob', email: 'bob@example.com' },
  id: 'req-001'
)

puts request.request?      # => true
puts request.notification? # => false
```

--------------------------------

### Create Notification via RPCObject Factory

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/notification.md

Use the factory method for convenient creation of notification objects.

```ruby
# Factory method for convenience
notification = JSONRPC::RPCObject.notification(
  method: 'event.publish',
  params: {
    event_name: 'purchase_completed',
    order_id: 'ord-12345',
    amount: 99.99
  }
)

puts notification.notification?  # => true
puts notification.request?       # => false
```

--------------------------------

### Instantiate a new JSONRPC::Response

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/response.md

Creates a new response object with the required JSON-RPC 2.0 fields. Throws SmartCore::TypeError if the provided properties do not match the expected types.

```ruby
response = JSONRPC::Response.new(
  jsonrpc: '2.0',
  result: { user_id: 42, name: 'Alice', email: 'alice@example.com' },
  id: 'req-12345'
)

response.result   # => {:user_id => 42, :name => 'Alice', :email => 'alice@example.com'}
response.id       # => 'req-12345'
response.jsonrpc  # => '2.0'
```

--------------------------------

### Create a JSON-RPC Response

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/response.md

Instantiate a response object manually by providing the JSON-RPC version, result data, and request ID.

```ruby
# Create a response to return user data
response = JSONRPC::Response.new(
  jsonrpc: '2.0',
  result: {
    user_id: 42,
    name: 'Alice Cooper',
    email: 'alice@example.com',
    created_at: '2024-01-15T10:30:00Z'
  },
  id: 'req-001'
)

puts response.result[:name]  # => 'Alice Cooper'
puts response.id             # => 'req-001'
```

--------------------------------

### Run type validation

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Executes Steep to perform static type checking on the codebase.

```shell
bundle exec rake steep
```

--------------------------------

### Serialize JSONRPC objects to JSON

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/module-overview.md

Demonstrates how to construct JSONRPC objects using the RPCObject factory and serialize them into JSON strings.

```ruby
# Request
request = JSONRPC::RPCObject.request(
  method: 'user.get',
  params: { id: 1 },
  id: 'req-001'
)

json = {
  jsonrpc: request.jsonrpc,
  method: request.method,
  params: request.params,
  id: request.id
}.to_json
# => {"jsonrpc":"2.0","method":"user.get","params":{"id":1},"id":"req-001"}

# Response
response = JSONRPC::RPCObject.response({ user: 'Alice' }, request_id: 'req-001')

json = {
  jsonrpc: response.jsonrpc,
  result: response.result,
  id: response.id
}.to_json
# => {"jsonrpc":"2.0","result":{"user":"Alice"},"id":"req-001"}

# Error Response
error = JSONRPC::RPCObject.method_not_found_error(request_id: 'req-001')

json = {
  jsonrpc: error.jsonrpc,
  error: error.error,
  id: error.id
}.to_json
# => {"jsonrpc":"2.0","error":{"code":-32601,"message":"Method Not Found","data":{}},"id":"req-001"}
```

--------------------------------

### Define method property

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/request.md

Defines the RPC method name as a string.

```ruby
property :method, SmartCore::Types::Value::String
```

--------------------------------

### Handle Server-Side Requests

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Pattern for parsing JSON, validating structure, executing handlers, and managing errors in a server environment.

```ruby
def handle_rpc_request(request_json)
  begin
    # Parse JSON
    request_data = JSON.parse(request_json)
    
    # Create request object (validates structure)
    request = JSONRPC::Request.new(
      jsonrpc: request_data['jsonrpc'],
      method: request_data['method'],
      params: request_data['params'],
      id: request_data['id']
    )
    
    # Find and execute method
    handler = find_handler(request.method)
    unless handler
      return JSONRPC::RPCObject.method_not_found_error(request_id: request.id)
    end
    
    # Execute with error handling
    result = handler.call(request.params)
    JSONRPC::RPCObject.response(result, request_id: request.id)
    
  rescue JSON::ParserError
    JSONRPC::RPCObject.parse_error
  rescue SmartCore::Schema::ValidationError => e
    JSONRPC::RPCObject.invalid_request_error(
      { error: e.message },
      request_id: request_data&.dig('id')
    )
  rescue ArgumentError => e
    JSONRPC::RPCObject.invalid_params_error(
      { error: e.message },
      request_id: request&.id
    )
  rescue StandardError => e
    JSONRPC::RPCObject.detailed_internal_error(e, request_id: request&.id)
  end
end
```

--------------------------------

### Construct a new JSONRPC::Notification

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/notification.md

Initializes a notification object with protocol version, method name, and parameters. Validation occurs immediately upon instantiation.

```ruby
notification = JSONRPC::Notification.new(
  jsonrpc: '2.0',
  method: 'log.event',
  params: { event_type: 'login', user_id: 42 }
)

notification.method   # => 'log.event'
notification.params   # => {:event_type => 'login', :user_id => 42}
notification.jsonrpc  # => '2.0'
```

--------------------------------

### Build Server-Side Responses

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/response.md

Handle incoming requests and serialize the response object to JSON for HTTP transmission.

```ruby
require 'json'

# Simulate handling an RPC request
def handle_user_get_request(request)
  # Extract parameters from request
  user_id = request.params[:user_id]
  
  # Fetch user from database
  user = User.find(user_id)
  
  # Build response
  response = JSONRPC::RPCObject.response(
    {
      user_id: user.id,
      name: user.name,
      email: user.email
    },
    request_id: request.id
  )
  
  # Return JSON for HTTP transmission
  {
    jsonrpc: response.jsonrpc,
    result: response.result,
    id: response.id
  }.to_json
end
```

--------------------------------

### JSONRPC::Request

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/configuration.md

Constructor for creating a standard JSONRPC request object.

```APIDOC
## JSONRPC::Request.new

### Description
Creates a new JSONRPC request object.

### Parameters
- **jsonrpc** (String) - Required - JSONRPC version (must be '2.0')
- **method** (String) - Required - Method name to call
- **params** (Hash) - Required - Named parameters for method
- **id** (String) - Required - Request identifier

### Example
```ruby
request = JSONRPC::Request.new(
  jsonrpc: '2.0',
  method: 'user.create',
  params: { name: 'Alice', email: 'alice@example.com' },
  id: SecureRandom.uuid
)
```
```

--------------------------------

### Create JSONRPC Objects

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Factory methods for generating standard JSONRPC requests, notifications, and responses.

```ruby
# Create a request
request = JSONRPC::RPCObject.request(
  method: 'user.get',
  params: { id: 1 },
  id: 'req-001'
)

# Create a notification (fire-and-forget)
notification = JSONRPC::RPCObject.notification(
  method: 'log.event',
  params: { level: 'info', msg: 'Started' }
)

# Create a response
response = JSONRPC::RPCObject.response(
  { user_id: 1, name: 'Alice' },
  request_id: 'req-001'
)
```

--------------------------------

### Initialize JSONRPC Error Response

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Shows the structure and initialization of a JSONRPC Error Response object.

```ruby
JSONRPC::ErrorResponse
JSONRPC::ErrorResponse.new(jsonrpc: '2.0', method: 'some.method', params: { some: 'params' }, id: nil)
JSONRPC::ErrorResponse.new(jsonrpc: '2.0', method: 'some.method', params: { some: 'params' }, id: 'sOmEiD')
JSONRPC::ErrorResponse#jsonrpc (String)
JSONRPC::ErrorResponse#error (Hash)
JSONRPC::ErrorResponse#id (String, NilClass)

JSONRPC::ErrorResponse#error
# signature =>
{ code: Integer, message: String, data: Hash }
```

--------------------------------

### Construct a new JSONRPC::ErrorResponse

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/error-response.md

Initializes an error response object with protocol version, error details, and request ID. Throws SmartCore::Schema::ValidationError if the error hash is malformed.

```ruby
error_response = JSONRPC::ErrorResponse.new(
  jsonrpc: '2.0',
  error: {
    code: -32600,
    message: 'Invalid Request',
    data: { reason: 'Missing required field: method' }
  },
  id: 'req-12345'
)

error_response.error[:code]    # => -32600
error_response.error[:message] # => 'Invalid Request'
error_response.id              # => 'req-12345'
```

--------------------------------

### Use Factory Methods for Error Responses

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/configuration.md

Prefer built-in factory methods over manual instantiation to ensure consistent error response structures.

```ruby
# Prefer this
error = JSONRPC::RPCObject.method_not_found_error(request_id: request.id)

# Over this
error = JSONRPC::ErrorResponse.new(
  jsonrpc: '2.0',
  error: { code: -32601, message: 'Method Not Found', data: {} },
  id: request.id
)
```

--------------------------------

### Handle Client-Side Responses

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Pattern for sending requests and processing success or error responses on the client side.

```ruby
def send_rpc_request(method, params, request_id)
  # Create request
  request = JSONRPC::RPCObject.request(
    method: method,
    params: params,
    id: request_id
  )
  
  # Send to server (pseudo-code)
  response_json = http_post('/rpc', request.to_json)
  
  # Parse response
  response_data = JSON.parse(response_json)
  
  if response_data['error']
    # Handle error response
    error = JSONRPC::ErrorResponse.new(
      jsonrpc: response_data['jsonrpc'],
      error: response_data['error'],
      id: response_data['id']
    )
    
    puts "Error: #{error.error[:message]} (code: #{error.error[:code]})"
    return nil
  else
    # Handle success response
    response = JSONRPC::Response.new(
      jsonrpc: response_data['jsonrpc'],
      result: response_data['result'],
      id: response_data['id']
    )
    
    return response.result
  end
end
```

--------------------------------

### Serialize and Parse JSONRPC Objects

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Shows how to convert an RPCObject to a JSON string and parse it back into a hash.

```ruby
require 'json'

request = JSONRPC::RPCObject.request(
  method: 'user.get',
  params: { id: 1 },
  id: 'req-001'
)

# Serialize to hash and then JSON
json_data = {
  jsonrpc: request.jsonrpc,
  method: request.method,
  params: request.params,
  id: request.id
}

json_string = json_data.to_json
# => {"jsonrpc":"2.0","method":"user.get","params":{"id":1},"id":"req-001"}

# Parse back
parsed = JSON.parse(json_string)
```

--------------------------------

### Create a Method Not Found Error Response

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/rpc-object.md

Generates an error response with code -32601 when a requested RPC method is missing.

```ruby
JSONRPC::RPCObject.method_not_found_error(request_id: nil) → JSONRPC::ErrorResponse
```

```ruby
error_response = JSONRPC::RPCObject.method_not_found_error(request_id: 'req-003')
# => #<JSONRPC::ErrorResponse 
#      jsonrpc='2.0' 
#      error={code: -32601, message: 'Method Not Found', data: {}}
#      id='req-003'>
```

--------------------------------

### Define Ruby Version Requirement

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/configuration.md

Specifies the minimum Ruby version required for the library.

```ruby
spec.required_ruby_version = Gem::Requirement.new('>= 3.2')
```

--------------------------------

### JSONRPC Module Dependency Tree

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/module-overview.md

Visual representation of the core dependencies required by the JSONRPC module.

```text
JSONRPC Module
  ├── Depends on: smart_core/types
  ├── Depends on: smart_core/schema
  └── Depends on: smart_core/value-object
```

--------------------------------

### JSONRPC::Response.new

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/response.md

Constructs a new JSONRPC::Response instance with the specified protocol version, result, and request ID.

```APIDOC
## JSONRPC::Response.new

### Description
Constructs a new JSONRPC response with the specified result and request ID. Validates that the protocol version is '2.0', the result is a hash, and the ID is a string.

### Signature
`JSONRPC::Response.new(jsonrpc: String, result: Hash, id: String) -> JSONRPC::Response`

### Parameters
- **jsonrpc** (String) - Required - JSONRPC protocol version (must be '2.0')
- **result** (Hash) - Required - The return value from the RPC method
- **id** (String) - Required - The request ID for correlation

### Throws
- `SmartCore::TypeError` if property types do not match

### Example
```ruby
response = JSONRPC::Response.new(
  jsonrpc: '2.0',
  result: { user_id: 42, name: 'Alice', email: 'alice@example.com' },
  id: 'req-12345'
)
```
```

--------------------------------

### Handle Method Not Found Error

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/errors.md

Generates a method not found error when the requested RPC method is missing on the server.

```ruby
{ data: {} }  # Usually empty or contains the requested method name
```

```ruby
error_response = JSONRPC::RPCObject.method_not_found_error(request_id: 'req-002')
# => JSONRPC::ErrorResponse with code: -32601, id: 'req-002'

# Server-side usage
def handle_request(request)
  method_handler = find_method(request.method)
  
  if method_handler.nil?
    return JSONRPC::RPCObject.method_not_found_error(request_id: request.id)
  end
  
  # Continue processing...
end
```

--------------------------------

### Internal Error with Exception Details

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/error-response.md

Capture exceptions and include detailed error information in the response data.

```ruby
begin
  # Some operation that fails
  result = compute_complex_operation(data)
rescue StandardError => e
  # Create detailed error with exception information
  error_response = JSONRPC::RPCObject.detailed_internal_error(
    e,
    request_id: request.id
  )
  
  # The error response includes full exception details
  puts error_response.error[:data][:error_class]    # e.g., ZeroDivisionError
  puts error_response.error[:data][:error_message]  # e.g., 'divided by 0'
  puts error_response.error[:data][:error_backtrace] # Full backtrace array
end
```

--------------------------------

### Define JSONRPC Class Hierarchy

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/types.md

Visual representation of the inheritance structure for request, notification, and response objects using SmartCore::ValueObject and SmartCore::Schema.

```text
SmartCore::ValueObject
  ├── JSONRPC::Request
  ├── JSONRPC::Notification
  ├── JSONRPC::Response
  └── JSONRPC::ErrorResponse

SmartCore::Schema
  ├── JSONRPC::Request::Schema
  ├── JSONRPC::Notification::Schema
  └── JSONRPC::ErrorResponse::ErrorSchema
```

--------------------------------

### Generate Application Error Responses

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/errors.md

Create application errors using the default error factory or the application_error alias.

```ruby
error_response = JSONRPC::RPCObject.error(
  { reason: 'user not found', searched_id: 999 },
  request_id: 'req-007'
)
# => Uses default code -33002 and message 'Application Error'

# Or use the alias
error_response = JSONRPC::RPCObject.application_error(
  { reason: 'user not found' },
  request_id: 'req-008'
)
```

--------------------------------

### Perform Type Checking

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Methods for identifying object types and checking response status.

```ruby
# Check if object is a request or notification
if request.request?
  puts "This is a request (has ID)"
elsif request.notification?
  puts "This is a notification (no ID)"
end

# Check if response is success or error
if response.success?
  puts "Success: #{response.result}"
elsif response.error?
  puts "Error: #{response.error[:message]}"
end
```

--------------------------------

### Retrieve JSONRPC Version

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/module-overview.md

Access the current library version constant.

```ruby
JSONRPC::VERSION # => '0.1.0'
```

--------------------------------

### Create Error Response via Factory

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/error-response.md

Generate a standard error response object using the RPCObject factory methods.

```ruby
# Using RPCObject factory methods
error_response = JSONRPC::RPCObject.method_not_found_error(request_id: 'req-001')

puts error_response.error[:code]      # => -32601
puts error_response.error[:message]   # => 'Method Not Found'
puts error_response.error[:data]      # => {}
puts error_response.id                # => 'req-001'
```

--------------------------------

### Validate Incoming Requests

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/configuration.md

Wrap request instantiation in a rescue block to catch and handle schema validation errors.

```ruby
begin
  request = JSONRPC::Request.new(
    jsonrpc: request_data['jsonrpc'],
    method: request_data['method'],
    params: request_data['params'],
    id: request_data['id']
  )
rescue SmartCore::Schema::ValidationError => e
  # Return invalid request error
  JSONRPC::RPCObject.invalid_request_error(
    { validation_error: e.message }
  )
end
```

--------------------------------

### JSONRPC::Request.new

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/request.md

Constructs a new JSONRPC request object with the specified protocol version, method, parameters, and request ID.

```APIDOC
## JSONRPC::Request.new

### Description
Constructs a new JSONRPC request with the specified method, parameters, and request ID. Validates input using the JSONRPC::Request::Schema.

### Signature
`JSONRPC::Request.new(jsonrpc:, method:, params:, id:) -> JSONRPC::Request`

### Parameters
- **jsonrpc** (String) - Required - JSONRPC protocol version (must be '2.0')
- **method** (String) - Required - The RPC method name
- **params** (Hash) - Required - Named parameters for the method
- **id** (String) - Required - Request ID for correlation

### Throws
- `SmartCore::Schema::ValidationError` if validation fails

### Example
```ruby
request = JSONRPC::Request.new(
  jsonrpc: '2.0',
  method: 'user.create',
  params: { name: 'Alice', email: 'alice@example.com' },
  id: 'req-12345'
)
```
```

--------------------------------

### Build JSONRPC Request Object

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Helper method to create a request object.

```ruby
JSONRPC::RPCObject.request(
  method: 'some.method',
  params: { some: 'params' },
  request_id: SecureRandom.uuid
) # => JSONRPC::Request
```

--------------------------------

### Build JSONRPC Notification Object

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Helper method to create a notification object.

```ruby
JSONRPC::RPCObject.notification(
  method: 'some.method',
  params: { some: 'params' }
)
```

--------------------------------

### Build JSONRPC Response Object

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Helper method to create a response object.

```ruby
JSONRPC::RPCObject.response(
  { some: 'data' },
  request_id: SecureRandom.uuid
) # => JSONRPC::Response
```

--------------------------------

### Create Custom Application Error

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/rpc-object.md

Generates a custom error response with specific codes and messages, supporting the application_error alias.

```ruby
JSONRPC::RPCObject.error(
  data = {},
  code: -33_002,
  message: 'Application Error',
  request_id: nil
) → JSONRPC::ErrorResponse
```

```ruby
error_response = JSONRPC::RPCObject.error(
  { reason: 'user not found' },
  code: -33_002,
  message: 'Application Error',
  request_id: 'req-007'
)
# => #<JSONRPC::ErrorResponse 
#      jsonrpc='2.0' 
#      error={code: -33002, message: 'Application Error', data: {reason: 'user not found'}}
#      id='req-007'>

# Same as above using alias
error_response = JSONRPC::RPCObject.application_error(
  { reason: 'user not found' },
  request_id: 'req-007'
)
```

--------------------------------

### JSONRPC::RPCObject.request

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/rpc-object.md

Constructs a JSONRPC request with the specified method, parameters, and request ID.

```APIDOC
## JSONRPC::RPCObject.request

### Description
Constructs a JSONRPC request with the specified method, parameters, and request ID. The request requires a unique ID for matching responses.

### Parameters
- **jsonrpc** (String) - Optional - JSONRPC protocol version. Default: '2.0'
- **method** (String) - Required - The RPC method name.
- **params** (Hash<String|Symbol, Any>) - Required - Named parameters for the RPC method.
- **id** (String) - Required - Request ID for correlation.

### Returns
- **JSONRPC::Request**
```

--------------------------------

### Define params property

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/request.md

Defines the hash of named parameters for the RPC call.

```ruby
property :params, SmartCore::Types::Value::Hash
```

--------------------------------

### Create a Request with a Unique ID

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/configuration.md

Ensure every request includes a unique identifier, such as a UUID, to maintain traceability.

```ruby
require 'securerandom'

request = JSONRPC::Request.new(
  jsonrpc: '2.0',
  method: 'user.get',
  params: { id: 1 },
  id: SecureRandom.uuid  # Use UUID or similar unique value
)
```

--------------------------------

### Process Batch Responses

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/response.md

Map multiple requests to individual responses and serialize them into a JSON array.

```ruby
# Handle multiple requests and generate responses
requests = [
  JSONRPC::Request.new(jsonrpc: '2.0', method: 'math.add', params: { a: 1, b: 2 }, id: 'req-1'),
  JSONRPC::Request.new(jsonrpc: '2.0', method: 'math.multiply', params: { a: 5, b: 3 }, id: 'req-2'),
  JSONRPC::Request.new(jsonrpc: '2.0', method: 'math.divide', params: { a: 10, b: 2 }, id: 'req-3')
]

responses = requests.map do |request|
  result = case request.method
           when 'math.add'
             { sum: request.params[:a] + request.params[:b] }
           when 'math.multiply'
             { product: request.params[:a] * request.params[:b] }
           when 'math.divide'
             { quotient: request.params[:a] / request.params[:b] }
           end
  
  JSONRPC::RPCObject.response(result, request_id: request.id)
end

# Convert to JSON array for transmission
json_responses = responses.map { |r| {jsonrpc: r.jsonrpc, result: r.result, id: r.id} }.to_json
```

--------------------------------

### Process Batch Notifications

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/notification.md

Generate and send multiple notifications in a batch without waiting for individual responses.

```ruby
# Send multiple fire-and-forget notifications
events = [
  { method: 'log.debug', params: { msg: 'Starting process' } },
  { method: 'log.debug', params: { msg: 'Fetching data' } },
  { method: 'log.debug', params: { msg: 'Completed' } }
]

notifications = events.map do |event|
  JSONRPC::RPCObject.notification(
    method: event[:method],
    params: event[:params]
  )
end

# Send all notifications without waiting for responses
notifications.each do |notif|
  send_to_server(notif)  # pseudo-code
end
```

--------------------------------

### JSONRPC::RPCObject Factory Methods

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/module-overview.md

The RPCObject module provides factory methods to instantiate JSONRPC objects and standardized error responses.

```APIDOC
## JSONRPC::RPCObject Factory Methods

### Description
Provides factory methods for creating JSONRPC 2.0 compliant objects, including requests, notifications, and various error responses.

### Methods
- `request(jsonrpc: '2.0', method:, params:, id:)` - Creates a new JSONRPC::Request object.
- `notification(jsonrpc: '2.0', method:, params:)` - Creates a new JSONRPC::Notification object.
- `response(result = {}, request_id: nil)` - Creates a new JSONRPC::Response object.
- `error(data = {}, code: -33_002, message: 'Application Error', request_id: nil)` - Creates a new JSONRPC::ErrorResponse object.

### Error Factory Methods
- `parse_error()`
- `invalid_request_error(data = {}, request_id: nil)`
- `method_not_found_error(request_id: nil)`
- `invalid_params_error(data = {}, request_id: nil)`
- `internal_error(*error_codes, error_context: {}, request_id: nil)`
```

--------------------------------

### Check Response Status

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/response.md

Use helper methods to verify if a response indicates success or an error.

```ruby
# Utility to determine if we have a successful response
response = JSONRPC::Response.new(
  jsonrpc: '2.0',
  result: { data: 'success' },
  id: 'req-123'
)

if response.success?
  puts "Response received with result: #{response.result}"
elsif response.error?
  puts "Error occurred: #{response.result}"
end
```

--------------------------------

### Response Status Methods

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/response.md

Utility methods to check the status of a response object.

```APIDOC
## Response Status Methods

### Description
Methods to determine if a response indicates success or failure.

### Methods
- **success?** (Boolean) - Returns true if the response is successful.
- **error?** (Boolean) - Returns true if the response contains an error.
```

--------------------------------

### JSONRPC::RPCObject Error Factory Methods

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Methods for creating standard and custom JSON-RPC 2.0 ErrorResponse objects.

```APIDOC
## Error Factory Methods

### Description
Methods to generate standardized error responses for JSON-RPC 2.0 communication.

### Methods
- **JSONRPC::RPCObject.parse_error()**
- **JSONRPC::RPCObject.invalid_request_error(data, request_id)**
- **JSONRPC::RPCObject.method_not_found_error(request_id)**
- **JSONRPC::RPCObject.invalid_params_error(data, request_id)**
- **JSONRPC::RPCObject.internal_error(*codes, error_context, request_id)**
- **JSONRPC::RPCObject.jsonrpc_specification_violation_error(request_id)**
- **JSONRPC::RPCObject.error(data, code, message, request_id)**
- **JSONRPC::RPCObject.application_error(data, request_id)**
- **JSONRPC::RPCObject.detailed_internal_error(exception, request_id)**
```

--------------------------------

### Generate Method Not Found Error

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Creates an error response when the requested method does not exist.

```ruby
JSONRPC::RPCObject.method_not_found_error
JSONRPC::RPCObject.method_not_found_error(request_id: SecureRandom.uuid)

JSONRPC::ErrorResponse#error
# error hash signature =>
{ code: -32_601, message: 'Method Not Found', data: {} }
```

--------------------------------

### Require JSONRPC Interface

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Load the library into your Ruby project to access the JSONRPC module and its components.

```ruby
require 'jsonrpc_interface'
```

--------------------------------

### JSONRPC::RPCObject Factory Methods

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

The RPCObject factory provides a simplified interface for creating JSON-RPC objects without manual instantiation.

```APIDOC
## JSONRPC::RPCObject Factory Methods

### Description
Provides factory methods to generate Request, Notification, Response, and Error objects.

### Methods
- **request(method, params, id)**: Creates a new JSONRPC::Request object.
- **notification(method, params)**: Creates a new JSONRPC::Notification object.
- **response(result, request_id)**: Creates a new JSONRPC::Response object.
- **method_not_found_error(request_id)**: Creates a standard JSON-RPC Method Not Found error response.
```

--------------------------------

### JSONRPC::RPCObject.response

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/response.md

A factory method for creating response objects conveniently.

```APIDOC
## JSONRPC::RPCObject.response

### Description
Convenience factory method to generate a response object.

### Parameters
- **data** (Hash) - Required - The result data.
- **request_id** (String) - Required - The ID of the request being responded to.
```

--------------------------------

### Validate JSONRPC Request Construction

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Demonstrates handling of schema validation errors when creating a request with missing required fields.

```ruby
begin
  # Missing 'method' field
  request = JSONRPC::Request.new(
    jsonrpc: '2.0',
    params: {},
    id: 'req-001'
  )
rescue SmartCore::Schema::ValidationError => e
  puts "Validation failed: #{e.message}"
end
```

--------------------------------

### Create a JSONRPC response

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/rpc-object.md

Constructs a response object if a request_id is provided; otherwise, returns nil.

```ruby
request_id = '12345'
result = { user: 'Alice', age: 30 }
response = JSONRPC::RPCObject.response(result, request_id: request_id)
# => #<JSONRPC::Response jsonrpc='2.0' result={:user=>'Alice', :age=>30} id='12345'>

# When request_id is nil, no response is created
response = JSONRPC::RPCObject.response(result, request_id: nil)
# => nil
```

--------------------------------

### Create JSONRPC Error Responses

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/README.md

Factory methods for generating standard, custom, and exception-based error responses.

```ruby
# Standard error codes
JSONRPC::RPCObject.parse_error()
JSONRPC::RPCObject.invalid_request_error({...}, request_id: '...')
JSONRPC::RPCObject.method_not_found_error(request_id: '...')
JSONRPC::RPCObject.invalid_params_error({...}, request_id: '...')
JSONRPC::RPCObject.internal_error(*codes, error_context: {...}, request_id: '...')
JSONRPC::RPCObject.jsonrpc_specification_violation_error(request_id: '...')

# Custom errors
JSONRPC::RPCObject.error({...}, code: ..., message: '...', request_id: '...')
JSONRPC::RPCObject.application_error({...}, request_id: '...')

# Exception errors
JSONRPC::RPCObject.detailed_internal_error(exception, request_id: '...')
```

--------------------------------

### Generate Detailed Internal Error

Source: https://github.com/0exp/jsonrpc_interface/blob/main/README.md

Creates an internal error response containing detailed exception information.

```ruby
JSONRPC::RPCObject.detailed_internal_error(exception)
JSONRPC::RPCObject.detailed_internal_error(exception, request_id: SecureRandom.uuid)

JSONRPC::ErrorResponse#error
# signature =>
{
  code: -32_603,
  message: 'Internal Error',
  data: {
    error_codes: [],
    error_cotnext: {
      error_class: # => exception.class,
      error_message: # => exception.message,
      error_backtrace: # => exception.backtrace,
      error_object: # => exception
    }
  }
}
```

--------------------------------

### Handle Server-Side Errors

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/error-response.md

Implement error handling within an RPC request handler to catch exceptions and return appropriate error responses.

```ruby
def handle_rpc_request(request)
  begin
    # Try to find and execute the method
    method_handler = find_method(request.method)
    
    unless method_handler
      return JSONRPC::RPCObject.method_not_found_error(
        request_id: request.id
      )
    end
    
    # Try to execute the method
    result = method_handler.call(request.params)
    JSONRPC::RPCObject.response(result, request_id: request.id)
    
  rescue ArgumentError => e
    # Parameter validation failed
    JSONRPC::RPCObject.invalid_params_error(
      { error_message: e.message },
      request_id: request.id
    )
  rescue Exception => e
    # Unexpected server error
    JSONRPC::RPCObject.detailed_internal_error(e, request_id: request.id)
  end
end
```

--------------------------------

### Check for success status

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/response.md

Returns true for a successful response object.

```ruby
response = JSONRPC::Response.new(
  jsonrpc: '2.0',
  result: { status: 'ok', data: [1, 2, 3] },
  id: 'req-123'
)

response.success?  # => true
```

--------------------------------

### Construct JSONRPC Request

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/configuration.md

Defines the structure for a JSONRPC request object.

```ruby
JSONRPC::Request.new(
  jsonrpc: '2.0',
  method: 'string',
  params: { any: 'hash' },
  id: 'string'
)
```

```ruby
request = JSONRPC::Request.new(
  jsonrpc: '2.0',
  method: 'user.create',
  params: { name: 'Alice', email: 'alice@example.com' },
  id: SecureRandom.uuid
)
```

--------------------------------

### Handle Errors During Request Processing

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/errors.md

A robust pattern for catching and responding to various error types during RPC request execution.

```ruby
def process_rpc_request(request_json)
  begin
    # Parse request
    request_data = JSON.parse(request_json)
    request = JSONRPC::Request.new(
      jsonrpc: request_data['jsonrpc'],
      method: request_data['method'],
      params: request_data['params'],
      id: request_data['id']
    )
    
    # Process request
    result = handle_method(request.method, request.params)
    JSONRPC::RPCObject.response(result, request_id: request.id)
    
  rescue JSON::ParserError
    # JSON parsing failed
    JSONRPC::RPCObject.parse_error
    
  rescue SmartCore::Schema::ValidationError => e
    # Invalid JSONRPC structure
    JSONRPC::RPCObject.invalid_request_error(
      { validation_error: e.message },
      request_id: request_data['id'] rescue nil
    )
    
  rescue MethodNotFoundError => e
    # Method doesn't exist
    JSONRPC::RPCObject.method_not_found_error(
      request_id: request.id
    )
    
  rescue ArgumentError => e
    # Invalid parameters
    JSONRPC::RPCObject.invalid_params_error(
      { error: e.message },
      request_id: request.id
    )
    
  rescue StandardError => e
    # Unexpected server error
    JSONRPC::RPCObject.detailed_internal_error(e, request_id: request.id)
  end
end
```

--------------------------------

### JSONRPC::Notification.new

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/notification.md

Constructs a new JSONRPC notification object with the specified method and parameters.

```APIDOC
## JSONRPC::Notification.new

### Description
Constructs a new JSONRPC notification with the specified method and parameters. Unlike requests, notifications do not have an ID and do not expect a response.

### Signature
`JSONRPC::Notification.new(jsonrpc:, method:, params:) → JSONRPC::Notification`

### Parameters
- **jsonrpc** (String) - Required - JSONRPC protocol version (must be '2.0')
- **method** (String) - Required - The RPC method name
- **params** (Hash) - Required - Named parameters for the method

### Throws
- **SmartCore::Schema::ValidationError** - If validation of the input parameters fails.
```

--------------------------------

### Define JSONRPC::Request class

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/types.md

Represents a JSONRPC request object using SmartCore::ValueObject with defined properties for protocol version, method, parameters, and ID.

```ruby
class JSONRPC::Request < SmartCore::ValueObject
  property :jsonrpc, SmartCore::Types::Variadic::Enum('2.0')
  property :method, SmartCore::Types::Value::String
  property :params, SmartCore::Types::Value::Hash
  property :id, SmartCore::Types::Value::String
end
```

--------------------------------

### Create JSONRPC Error Response

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/configuration.md

Defines the method signature for generating application errors and demonstrates usage with default and custom parameters.

```ruby
JSONRPC::RPCObject.error(
  data = {},
  code: -33_002,
  message: 'Application Error',
  request_id: nil
)
```

```ruby
# With defaults
error = JSONRPC::RPCObject.error()
# => JSONRPC::ErrorResponse with code: -33002

# With custom code and message
error = JSONRPC::RPCObject.error(
  { reason: 'invalid state' },
  code: -33_001,
  message: 'Unauthorized',
  request_id: 'req-001'
)
```

--------------------------------

### Define jsonrpc property

Source: https://github.com/0exp/jsonrpc_interface/blob/main/_autodocs/api-reference/request.md

Sets the protocol version to the required '2.0' value.

```ruby
property :jsonrpc, SmartCore::Types::Variadic::Enum('2.0')
```
Tokens:
Raw