Class: JSONRPC::Notification

Inherits:
Object
  • Object
show all
Defined in:
lib/jsonrpc/notification.rb,
sig/jsonrpc/notification.rbs

Overview

A JSON-RPC 2.0 Notification object

Represents a method call that does not expect a response. Unlike a Request, a Notification omits the "id" field, indicating that no response should be sent.

A Notification is a Request object without an "id" member. Notifications are not confirmable by definition since they do not have a Response object.

Examples:

Create a notification with parameters

notification = JSONRPC::Notification.new(method: "update", params: [1, 2, 3, 4, 5])

Create a notification without parameters

notification = JSONRPC::Notification.new(method: "heartbeat")

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(method:, params: nil) ⇒ Notification

Creates a new JSON-RPC 2.0 Notification object

Examples:

Create a notification with array parameters

JSONRPC::Notification.new(method: "update", params: [1, 2, 3])

Create a notification with named parameters

JSONRPC::Notification.new(method: "log", params: { level: "info", message: "Hello" })

Parameters:

  • method (String) —

    the name of the method to be invoked

  • params (Hash, Array, nil) (defaults to: nil) —

    the parameters to be used during method invocation

  • method: (String)
  • params: (params_type) (defaults to: nil)

Raises:

  • (ArgumentError) —

    if method is not a String or is reserved

  • (ArgumentError) —

    if params is not a Hash, Array, or nil



71
72
73
74
75
76
77
78
79
 
# File 'lib/jsonrpc/notification.rb', line 71

def initialize(method:, params: nil)
  @jsonrpc = '2.0'

  validate_method(method)
  validate_params(params)

  @method = method
  @params = params
end

Instance Attribute Details

#jsonrpc ⇒ String (readonly)

JSON-RPC protocol version

Examples:

notification.jsonrpc # => "2.0"

Returns:

  • (String) 


31
32
33
 
# File 'lib/jsonrpc/notification.rb', line 31

def jsonrpc
  @jsonrpc
end

#method ⇒ String (readonly)

The method name to invoke

Examples:

notification.method # => "update"

Returns:

  • (String) 


42
43
44
 
# File 'lib/jsonrpc/notification.rb', line 42

def method
  @method
end

#params ⇒ Hash, ... (readonly)

Parameters to pass to the method

Examples:

notification.params # => [1, 2, 3, 4, 5]

Returns:

  • (Hash, Array, nil) 


53
54
55
 
# File 'lib/jsonrpc/notification.rb', line 53

def params
  @params
end

Instance Method Details

#to_h ⇒ Hash

Converts the notification to a JSON-compatible Hash

Examples:

notification.to_h # => { jsonrpc: "2.0", method: "update", params: [1, 2, 3] }

Returns:

  • (Hash) —

    the notification as a JSON-compatible Hash



90
91
92
93
94
95
96
97
98
 
# File 'lib/jsonrpc/notification.rb', line 90

def to_h
  hash = {
    jsonrpc: jsonrpc,
    method: method
  }

  hash[:params] = params unless params.nil?
  hash
end

#to_json ⇒ String

Converts the notification to a JSON string

Examples:

notification.to_json # => '{"jsonrpc":"2.0","method":"update","params":[1,2,3]}'

Parameters:

  • (Object)

Returns:

  • (String) —

    the notification as a JSON string



109
110
111
 
# File 'lib/jsonrpc/notification.rb', line 109

def to_json(*)
  MultiJson.dump(to_h, *)
end

#validate_method(method) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates that the method name meets JSON-RPC 2.0 requirements

Parameters:

  • method (String) —

    the method name

  • (String)

Raises:

  • (ArgumentError) —

    if method is not a String or is reserved



125
126
127
128
129
130
131
 
# File 'lib/jsonrpc/notification.rb', line 125

def validate_method(method)
  raise ArgumentError, 'Method must be a String' unless method.is_a?(String)

  return unless method.start_with?('rpc.')

  raise ArgumentError, "Method names starting with 'rpc.' are reserved"
end

#validate_params(params) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates that the params is a valid structure according to JSON-RPC 2.0

Parameters:

  • params (Hash, Array, nil) —

    the parameters

  • (params_type)

Raises:

  • (ArgumentError) —

    if params is not a Hash, Array, or nil



143
144
145
146
147
148
149
 
# File 'lib/jsonrpc/notification.rb', line 143

def validate_params(params)
  return if params.nil?

  return if params.is_a?(Hash) || params.is_a?(Array)

  raise ArgumentError, 'Params must be an Object, Array, or omitted'
end