Class: JSONRPC::BatchRequest

Inherits:
Object
  • Object
show all
Includes:
Enumerable, Enumerable[Request
Defined in:
lib/jsonrpc/batch_request.rb,
sig/jsonrpc/batch_request.rbs

Overview

A JSON-RPC 2.0 batch request object

A batch request is an Array filled with Request objects to send several requests at once. The Server should respond with an Array containing the corresponding Response objects.

Examples:

Create a batch request with multiple requests

batch = JSONRPC::BatchRequest.new([
  JSONRPC::Request.new(method: "sum", params: [1, 2, 4], id: "1"),
  JSONRPC::Notification.new(method: "notify_hello", params: [7]),
  JSONRPC::Request.new(method: "subtract", params: [42, 23], id: "2")
])

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(requests) ⇒ BatchRequest

Creates a new JSON-RPC 2.0 Batch Request object

Examples:

Create a batch request

requests = [
  JSONRPC::Request.new(method: 'add', params: [1, 2], id: 1),
  JSONRPC::Notification.new(method: 'notify', params: ['hello'])
]
batch = JSONRPC::BatchRequest.new(requests)

Parameters:

Raises:

  • (ArgumentError) —

    if requests is not an Array

  • (ArgumentError) —

    if requests is empty

  • (ArgumentError) —

    if any request is not a valid Request, Notification, or Error



51
52
53
54
 
# File 'lib/jsonrpc/batch_request.rb', line 51

def initialize(requests)
  validate_requests(requests)
  @requests = requests
end

Instance Attribute Details

#requests ⇒ Array<JSONRPC::Request, JSONRPC::Notification, JSONRPC::Error> (readonly)

The collection of request objects in this batch (may include errors)

Examples:

Accessing requests in a batch

batch = JSONRPC::BatchRequest.new([request1, request2])
batch.requests # => [#<JSONRPC::Request...>, #<JSONRPC::Request...>]

Returns:



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

def requests
  @requests
end

Instance Method Details

#each ⇒ self #each ⇒ Enumerator[Request | Notification | Error, self]

Implements the Enumerable contract by yielding each request in the batch

Examples:

Iterate over requests

batch.each { |request| puts request.method }

Overloads:

Yields:

  • (request) —

    Yields each request in the batch to the block

Yield Parameters:

Returns:

  • (Enumerator) —

    if no block is given

  • (BatchRequest) —

    self if a block is given



97
98
99
100
101
102
 
# File 'lib/jsonrpc/batch_request.rb', line 97

def each(&)
  return to_enum(:each) unless block_given?

  requests.each(&)
  self
end

#process_each {|request_or_notification| ... } ⇒ Array<JSONRPC::Response>

Handles each request/notification in the batch and returns responses

Examples:

Handle batch with a block

batch.process_each do |request_or_notification|
  # Process the request/notification
  result = some_processing(request_or_notification.params)
  result
end

Yields:

  • (request_or_notification) —

    Yields each request/notification in the batch

Yield Parameters:

Yield Returns:

  • (Object) —

    the result of processing the request. Notifications yield no results.

Returns:

  • (Array<JSONRPC::Response>) —

    responses for requests only (notifications return no response)

Raises:

  • (ArgumentError) 


146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/jsonrpc/batch_request.rb', line 146

def process_each
  raise ArgumentError, 'Block required' unless block_given?

  flat_map do |request_or_notification|
    result = yield(request_or_notification)

    if request_or_notification.is_a?(JSONRPC::Request)
      JSONRPC::Response.new(id: request_or_notification.id, result:)
    end
  end.compact
end

#size ⇒ Integer Also known as: length

Returns the number of requests in the batch

Examples:

Get batch size

batch.size # => 3

Returns:

  • (Integer) —

    the number of requests in the batch



113
 
# File 'lib/jsonrpc/batch_request.rb', line 113

def size = requests.size

#to_h ⇒ Array<Hash>

Converts the batch request to a JSON-compatible Array

Examples:

Convert batch to hash

batch.to_h # => [{"jsonrpc":"2.0","method":"add","params":[1,2],"id":1}]

Returns:

  • (Array<Hash>) —

    the batch request as a JSON-compatible Array



65
66
67
 
# File 'lib/jsonrpc/batch_request.rb', line 65

def to_h
  requests.map { |item| item.respond_to?(:to_h) ? item.to_h : item }
end

#to_json ⇒ String

Converts the batch to JSON format

Examples:

Convert batch to JSON

batch.to_json # => '[{"id":"1","method":"sum","params":[1,2,4]}]'

Parameters:

  • (Object)

Returns:

  • (String) —

    the JSON-formatted batch



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

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

#validate_requests(requests) ⇒ 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 the requests array

Parameters:

  • requests (Array) —

    the array of requests

  • (Array[untyped])

Raises:

  • (ArgumentError) —

    if requests is not an Array

  • (ArgumentError) —

    if requests is empty

  • (ArgumentError) —

    if any request is not a valid Request, Notification, or Error



172
173
174
175
176
177
178
179
180
181
 
# File 'lib/jsonrpc/batch_request.rb', line 172

def validate_requests(requests)
  raise ArgumentError, 'Requests must be an Array' unless requests.is_a?(Array)
  raise ArgumentError, 'Batch request cannot be empty' if requests.empty?

  requests.each_with_index do |request, index|
    unless request.is_a?(Request) || request.is_a?(Notification) || request.is_a?(Error)
      raise ArgumentError, "Request at index #{index} is not a valid Request, Notification, or Error"
    end
  end
end