Class: X::Response

Inherits:
Object
  • Object
show all
Includes:
ResponseHeaders
Defined in:
x-core/lib/x/core/response.rb

Overview

A summary of one API response, or one object of a stream, which a client passes to its on_response hook

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(http_method:, uri:, http_response: nil, status: nil, headers: nil, body: nil) ⇒ Response

Summarize a response

Public, so that an on_response hook can be tested with a summary built from the status, headers, and body of a response, or from a Net::HTTP response, as the client builds one for each response it reads.

Examples:

Summarize a response

X::Response.new(http_method: :get, uri: URI("https://api.x.com/2/users/me"), status: 200,
  headers: {"x-rate-limit-remaining" => "74"}, body: %({"data":{"id":"1"}}))

Summarize a Net::HTTP response

X::Response.new(http_response:, http_method: :get, uri: URI("https://api.x.com/2/users/me"))

Parameters:

  • http_method (Symbol, String) —

    the HTTP method of the request, in any case, which is read as a lowercase Symbol, as an error reads it

  • uri (URI::Generic) —

    the URI of the request

  • http_response (Net::HTTPResponse, nil) (defaults to: nil) —

    the response of the transport, an escape hatch as #http_response is, whose class is not covered by the compatibility promise of 1.x, or nil for one built of the status, headers, and body, which every release of 1.x takes

  • status (Integer, nil) (defaults to: nil) —

    the status of the response, from 100 to 599, when it is not given

  • headers (Hash{String => String}, nil) (defaults to: nil) —

    the headers of the response, when it is not given

  • body (String, nil) (defaults to: nil) —

    the part of the body summarized, such as one object of a stream, or nil for all of it, which is the body of a response built of the status

Raises:

  • (ArgumentError) —

    if the HTTP response is given beside a status or headers, or neither it nor a status is given, or the status is not from 100 to 599, or the headers are not a Hash of names to values



93
94
95
96
97
98
99
 
# File 'x-core/lib/x/core/response.rb', line 93

def initialize(http_method:, uri:, http_response: nil, status: nil, headers: nil, body: nil)
  @http_method = http_method.downcase.to_sym
  @uri = uri
  @http_response = BuiltResponse.of(http_response, status:, headers:, body: (body if http_response.nil?))
  @body = body.dup&.force_encoding(Encoding::UTF_8)
  @parsed = ParsedBody.new
end

Instance Attribute Details

#http_method ⇒ Symbol (readonly)

The HTTP method of the request

Examples:

Get the HTTP method

response.http_method # => :get

Returns:

  • (Symbol) —

    the HTTP method



46
47
48
 
# File 'x-core/lib/x/core/response.rb', line 46

def http_method
  @http_method
end

#http_response ⇒ Net::HTTPResponse (readonly)

The response itself, as the client received it

It is an escape hatch, for what a summary does not read: the status is #status, the headers are #headers, and the body is #body. It is the response of the transport the client sent the request with, a Net::HTTPResponse today, or the one built of the status, headers, and body the summary was given. Its class is not covered by the compatibility promise of 1.x: a later release of 1.x may send its requests with another library, whose response this then returns.

Examples:

Read the reason phrase of the status line

response.http_response.message # => "OK"

Returns:

  • (Net::HTTPResponse) —

    the response of the transport



67
68
69
 
# File 'x-core/lib/x/core/response.rb', line 67

def http_response
  @http_response
end

#uri ⇒ URI::Generic (readonly)

The URI of the request

Examples:

Get the path of the request

response.uri.path # => "/2/users/me"

Returns:

  • (URI::Generic) —

    the request URI



53
54
55
 
# File 'x-core/lib/x/core/response.rb', line 53

def uri
  @uri
end

Instance Method Details

#body ⇒ String?

The body summarized: one streamed object, or else the whole body

It is tagged UTF-8, the encoding of the JSON the API sends. A body that is not valid UTF-8 keeps its bytes, so valid_encoding? tells it apart, and scrub replaces what is not UTF-8.

Examples:

Log the body

logger.debug(response.body)

Returns:

  • (String, nil) —

    the body, tagged UTF-8



110
 
# File 'x-core/lib/x/core/response.rb', line 110

def body = @body || http_response.body

#headers ⇒ Hash{String => String}

The headers of the response

The names are lowercase, and a field the API sent more than once is joined with a comma.

Examples:

Read how long the API took to answer

response.headers["x-response-time"]

Returns:

  • (Hash{String => String}) —

    the headers, frozen




# File 'x-core/lib/x/core/response.rb', line 32

#rate_limit ⇒ RateLimit?

The 15-minute rate limit of the endpoint, which nearly every response reports

Examples:

Slow down near the limit

sleep response.rate_limit.reset_in if response.rate_limit&.remaining&.zero?

Returns:

  • (RateLimit, nil) —

    the rate limit, or nil if the response reports none



142
 
# File 'x-core/lib/x/core/response.rb', line 142

def rate_limit = rate_limits.find { |limit| limit.type.eql?(RateLimit::RATE_LIMIT_TYPE) }

#rate_limits ⇒ Array<RateLimit>

The rate limits the response reports in its headers

Examples:

Print how many requests remain in each window

response.rate_limits.each { |limit| puts "#{limit.type}: #{limit.remaining}" }

Returns:

  • (Array<RateLimit>) —

    the 15-minute limit, and the 24-hour app and user limits when reported



134
 
# File 'x-core/lib/x/core/response.rb', line 134

def rate_limits = RateLimit.__send__(:all_from, http_response)

#resource_count ⇒ Integer

The number of resources the body holds, in data and includes together

Examples:

Total the resources a client has read

total += response.resource_count

Returns:

  • (Integer) —

    the resource count



169
 
# File 'x-core/lib/x/core/response.rb', line 169

def resource_count = resource_counts.values.sum

#resource_counts ⇒ Hash{String => Integer}

The number of resources the body holds, as data and as each kind of include

The API bills reads by the resource, but once a UTC day for each, so these count what the response returned, not what X billed for it. The body is parsed once, however many times a summary is asked what it holds, unless the summary was frozen deeply, as Ractor.make_shareable freezes one, before it was first asked, which leaves it nowhere to keep what it parsed. A body whose includes is not an object holds no includes to count.

Examples:

Count the users a lookup returned

response.resource_counts # => {"data" => 1, "posts" => 1}

Returns:

  • (Hash{String => Integer}) —

    the count of data and of each include, such as users and posts



155
156
157
158
159
160
161
 
# File 'x-core/lib/x/core/response.rb', line 155

def resource_counts
  body = parsed_body
  data = body["data"]
  counts = {"data" => Array.try_convert(data)&.size || [data].compact.size}
  Hash.try_convert(body["includes"])&.each { |key, resources| counts[key] = Array(resources).size }
  counts
end

#status ⇒ Integer

The HTTP status code

Examples:

Get the status code

response.status # => 200

Returns:

  • (Integer) —

    the status code



118
 
# File 'x-core/lib/x/core/response.rb', line 118

def status = Integer(http_response.code)

#success? ⇒ Boolean

Check whether the request succeeded

Examples:

Count the failed requests

failures += 1 unless response.success?

Returns:

  • (Boolean) —

    true for a 2xx status



126
 
# File 'x-core/lib/x/core/response.rb', line 126

def success? = http_response.is_a?(Net::HTTPSuccess)