Class: JSONRPC::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/jsonrpc/configuration.rb

Overview

Configuration class for JSON-RPC procedure management and validation.

This class provides functionality to register, retrieve, and validate JSON-RPC procedures. It acts as a central registry for method definitions and their parameter constraints.

Examples:

Registering a procedure

JSONRPC::Configuration.instance.procedure('sum') do
  params do
    required(:numbers).value(:array, min_size?: 1)
  end
end

Defined Under Namespace

Classes: Procedure

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(logger: Logger.new($stdout, progname: 'JSONRPC'), log_internal_errors: true, log_request_validation_errors: false, rescue_internal_errors: true, render_internal_errors: false, validate_procedure_signatures: true) ⇒ Configuration

Initializes a new Configuration instance

Examples:

config = JSONRPC::Configuration.new

With custom options

config = JSONRPC::Configuration.new(
  log_request_validation_errors: true,
  render_internal_errors: true
)

Parameters:

  • logger (Logger) (defaults to: Logger.new($stdout, progname: 'JSONRPC')) —

    the logger instance for error and diagnostic output

  • log_internal_errors (Boolean) (defaults to: true) —

    whether to log detailed internal error information in the terminal

  • log_request_validation_errors (Boolean) (defaults to: false) —

    whether to log validation errors during JSON-RPC request processing

  • rescue_internal_errors (Boolean) (defaults to: true) —

    whether internal errors should be rescued and converted to JSON-RPC errors

  • render_internal_errors (Boolean) (defaults to: false) —

    whether to render detailed internal error information in responses

  • validate_procedure_signatures (Boolean) (defaults to: true) —

    whether procedure signatures are validated



161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/jsonrpc/configuration.rb', line 161

def initialize(
  logger: Logger.new($stdout, progname: 'JSONRPC'),
  log_internal_errors: true,
  log_request_validation_errors: false,
  rescue_internal_errors: true,
  render_internal_errors: false,
  validate_procedure_signatures: true
)
  @procedures = {}
  @logger = logger
  @log_internal_errors = log_internal_errors
  @log_request_validation_errors = log_request_validation_errors
  @rescue_internal_errors = rescue_internal_errors
  @render_internal_errors = render_internal_errors
  @validate_procedure_signatures = validate_procedure_signatures
end

Instance Attribute Details

#allow_positional_arguments ⇒ Boolean (readonly)

Indicates if the procedure accepts positional arguments

Examples:

procedure.allow_positional_arguments # => true

Returns:

  • (Boolean) —

    whether the procedure accepts positional arguments



53
 
# File 'lib/jsonrpc/configuration.rb', line 53

Procedure = Data.define(:allow_positional_arguments, :contract, :parameter_name)

#contract ⇒ Dry::Validation::Contract (readonly)

The validation contract for procedure parameters

Examples:

procedure.contract # => #<Dry::Validation::Contract...>

Returns:

  • (Dry::Validation::Contract) —

    the validation contract for procedure parameters



53
 
# File 'lib/jsonrpc/configuration.rb', line 53

Procedure = Data.define(:allow_positional_arguments, :contract, :parameter_name)

#log_internal_errors ⇒ Boolean

Whether to log detailed internal error information in the terminal

Examples:

config.log_internal_errors # => true

Returns:

  • (Boolean) —

    whether to log internal error details



78
79
80
 
# File 'lib/jsonrpc/configuration.rb', line 78

def log_internal_errors
  @log_internal_errors
end

#log_request_validation_errors ⇒ Boolean

Whether to log validation errors during JSON-RPC request processing

Examples:

config.log_request_validation_errors # => false

Returns:

  • (Boolean) —

    whether to log JSON-RPC request validation errors



89
90
91
 
# File 'lib/jsonrpc/configuration.rb', line 89

def log_request_validation_errors
  @log_request_validation_errors
end

#logger ⇒ Logger

The logger instance used for error and diagnostic output

Examples:

Using the default logger

config.logger # => #<Logger:...>

Setting a custom logger

config.logger = Logger.new('log/jsonrpc.log')

Returns:

  • (Logger) —

    the logger instance



67
68
69
 
# File 'lib/jsonrpc/configuration.rb', line 67

def logger
  @logger
end

#parameter_name ⇒ Symbol? (readonly)

The name of the first parameter in the contract schema

Examples:

procedure.parameter_name # => :numbers

Returns:

  • (Symbol, nil) —

    the name of the first parameter in the contract schema



53
 
# File 'lib/jsonrpc/configuration.rb', line 53

Procedure = Data.define(:allow_positional_arguments, :contract, :parameter_name)

#render_internal_errors ⇒ Boolean

Whether to render detailed internal error information in responses

Examples:

config.render_internal_errors # => true

Returns:

  • (Boolean) —

    whether to log internal error details



100
101
102
 
# File 'lib/jsonrpc/configuration.rb', line 100

def render_internal_errors
  @render_internal_errors
end

#rescue_internal_errors ⇒ Boolean

Whether internal errors should be rescued and converted to JSON-RPC errors

Examples:

config.rescue_internal_errors # => true

Returns:

  • (Boolean) —

    whether internal errors are rescued



111
112
113
 
# File 'lib/jsonrpc/configuration.rb', line 111

def rescue_internal_errors
  @rescue_internal_errors
end

#validate_procedure_signatures ⇒ Boolean (readonly)

Whether procedure signatures are validated

Examples:

config.validate_procedure_signatures # => true

Returns:

  • (Boolean) —

    whether procedure signatures are validated



122
123
124
 
# File 'lib/jsonrpc/configuration.rb', line 122

def validate_procedure_signatures
  @validate_procedure_signatures
end

Class Method Details

.instance ⇒ Configuration

Returns the singleton instance of the Configuration class

Examples:

config = JSONRPC::Configuration.instance

Returns:



187
188
189
 
# File 'lib/jsonrpc/configuration.rb', line 187

def self.instance
  @instance ||= new
end

Instance Method Details

#get_procedure(method_name) ⇒ Procedure?

Retrieves a procedure by its method name

Examples:

procedure = config.get_procedure('add')

Parameters:

  • method_name (String, Symbol) —

    the name of the procedure to retrieve

Returns:

  • (Procedure, nil) —

    the procedure if found, nil otherwise



243
244
245
 
# File 'lib/jsonrpc/configuration.rb', line 243

def get_procedure(method_name)
  @procedures[method_name.to_s]
end

#json_adapter=(adapter) ⇒ Symbol?

JSON adapter to use (optional)

Examples:

config.json_adapter = :oj

Parameters:

  • adapter (Symbol, nil) —

    the JSON adapter to use

Returns:

  • (Symbol, nil) —

    the JSON adapter to use



135
136
137
 
# File 'lib/jsonrpc/configuration.rb', line 135

def json_adapter=(adapter)
  MultiJson.use(adapter)
end

#procedure(method_name, allow_positional_arguments: false, &block) { ... } ⇒ Procedure

Registers a new procedure with the given method name and validation contract

Examples:

Register a simple procedure

config.procedure('add') do
  params do
    required(:a).value(:integer)
    required(:b).value(:integer)
  end
end

Register a procedure without validation

config.procedure('ping')

Parameters:

  • method_name (String, Symbol) —

    the name of the procedure

  • allow_positional_arguments (Boolean) (defaults to: false) —

    whether the procedure accepts positional arguments

  • block (Proc, nil) —

    an optional block that defines the validation contract using Dry::Validation DSL

Yields:

  • A block that defines the validation contract using Dry::Validation DSL

Returns:



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/jsonrpc/configuration.rb', line 214

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

  @procedures[method_name.to_s] = Procedure.new(
    allow_positional_arguments:,
    contract:,
    parameter_name: contract.schema.key_map.keys.first&.name
  )
end

#procedure?(method_name) ⇒ Boolean

Checks if a procedure with the given method name exists

Examples:

config.procedure?('add') # => true

Parameters:

  • method_name (String, Symbol) —

    the name of the procedure to check

Returns:

  • (Boolean) —

    true if the procedure exists, false otherwise



258
259
260
 
# File 'lib/jsonrpc/configuration.rb', line 258

def procedure?(method_name)
  @procedures.key?(method_name.to_s)
end

#reset! ⇒ void

This method returns an undefined value.

Clears all registered procedures

Examples:

config.reset!


271
272
273
 
# File 'lib/jsonrpc/configuration.rb', line 271

def reset!
  @procedures.clear
end