Class: HTTPX::Response

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Callbacks, _Reader, _ToS, ResponsePatternMatchExtensions, _Response
Defined in:
lib/httpx/response.rb,
sig/response.rbs

Overview

Defines a HTTP response is handled internally, with a few properties exposed as attributes.

It delegates the following methods to the corresponding HTTPX::Request:

  • HTTPX::Request#uri
  • HTTPX::Request#peer_address

It implements (indirectly, via the body) the IO write protocol to internally buffer payloads.

It implements the IO reader protocol in order for users to buffer/stream it, acts as an enumerable (of payload chunks).

Defined Under Namespace

Classes: Body, Buffer

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from ResponsePatternMatchExtensions

#deconstruct, #deconstruct_keys

Methods included from Callbacks

#callbacks, #callbacks_for?, #emit, #on, #once

Constructor Details

#initialize(request, status, version, headers) ⇒ Response

inits the instance with the corresponding request to this response, an the response HTTP status, version and HTTPX::Headers instance of headers.

Parameters:

  • request (Request)
  • status (String, Integer)
  • version (String)
  • (headers, nil) 


63
64
65
66
67
68
69
70
71
72
 
# File 'lib/httpx/response.rb', line 63

def initialize(request, status, version, headers)
  @request = request
  @options = request.options
  @version = version
  @status = Integer(status)
  @headers = @options.headers_class.new(headers)
  @body = @options.response_body_class.new(self, @options)
  @finished = complete?
  @content_type = @content_length = nil
end

Instance Attribute Details

#body ⇒ Body (readonly)

a HTTPX::Response::Body object wrapping the response body. The following methods are delegated to it:

  • HTTPX::Response::Body#to_s
  • HTTPX::Response::Body#to_str
  • HTTPX::Response::Body#read
  • HTTPX::Response::Body#copy_to
  • HTTPX::Response::Body#close

Returns:



39
40
41
 
# File 'lib/httpx/response.rb', line 39

def body
  @body
end

#headers ⇒ Headers (readonly)

an HTTPX::Headers object containing the response HTTP headers.

Returns:



30
31
32
 
# File 'lib/httpx/response.rb', line 30

def headers
  @headers
end

#status ⇒ Integer (readonly)

the HTTP response status code

Returns:

  • (Integer) 


27
28
29
 
# File 'lib/httpx/response.rb', line 27

def status
  @status
end

#version ⇒ String (readonly)

The HTTP protocol version used to fetch the response.

Returns:

  • (String) 


42
43
44
 
# File 'lib/httpx/response.rb', line 42

def version
  @version
end

Instance Method Details

#<<(data) ⇒ Object

writes data chunk into the response body.



95
96
97
 
# File 'lib/httpx/response.rb', line 95

def <<(data)
  @body.write(data)
end

#bodyless? ⇒ Boolean

returns whether the response contains body payload.

Returns:

  • (Boolean) 


127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/httpx/response.rb', line 127

def bodyless?
  @request.verb == "HEAD" ||
    @status < 200 || # informational response
    @status == 204 ||
    @status == 205 ||
    @status == 304 || begin
      content_length = @headers["content-length"]
      return false if content_length.nil?

      content_length == "0"
    end
end

#close ⇒ void

This method returns an undefined value.

closes the respective @request and @body.



83
84
85
86
 
# File 'lib/httpx/response.rb', line 83

def close
  @request.close
  @body.close
end

#complete? ⇒ Boolean

Returns:

  • (Boolean) 


140
141
142
 
# File 'lib/httpx/response.rb', line 140

def complete?
  bodyless? || (@request.verb == "CONNECT" && @status == 200)
end

#content_length ⇒ Integer?

returns the response content length as advertised in the HTTP Content-Length header value.

Returns:

  • (Integer, nil) 


108
109
110
111
112
 
# File 'lib/httpx/response.rb', line 108

def content_length
  return @content_length if defined?(@content_length)

  @content_length = @headers["content-length"]&.to_i
end

#content_type ⇒ ContentType

returns the HTTPX::ContentType for the response, as per what's declared in the content-type header.

response.content_type #=> #<HTTPX::ContentType:xxx @header_value="text/plain">
response.content_type.mime_type #=> "text/plain"

Returns:



103
104
105
 
# File 'lib/httpx/response.rb', line 103

def content_type
  @content_type ||= ContentType.new(@headers["content-type"])
end

#copy_to ⇒ void

This method returns an undefined value.

Parameters:

  • destination (_ToPath, _Writer) 


33
 
# File 'sig/response.rbs', line 33

def copy_to: (_ToPath | _Writer destination) -> void

#decode(transcoder, *args) ⇒ Object

decodes the response payload using the given transcoder, which implements the decoding logic.

transcoder must implement the internal transcoder API, i.e. respond to decode(HTTPX::Response response), which returns a decoder which responds to call(HTTPX::Response response, **kwargs)

Parameters:

Returns:

  • (Object)

Raises:



203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/httpx/response.rb', line 203

def decode(transcoder, *args)
  # TODO: check if content-type is a valid format, i.e. "application/json" for json parsing

  decoder = transcoder.decode(self)

  raise Error, "no decoder available for \"#{transcoder}\"" unless decoder

  @body.rewind

  decoder.call(self, *args)
end

#error ⇒ Object

returns an instance of HTTPX::HTTPError if the response has a 4xx or 5xx status code, or nothing.

ok_response.error #=> nil
not_found_response.error #=> HTTPX::HTTPError instance, status 404


159
160
161
162
163
 
# File 'lib/httpx/response.rb', line 159

def error
  return if @status < 400

  HTTPError.new(self)
end

#finish! ⇒ Object

marks the response as finished, freezes the headers.



120
121
122
123
124
 
# File 'lib/httpx/response.rb', line 120

def finish!
  @finished = true
  @headers.freeze
  @request.connection = nil
end

#finished? ⇒ Boolean

returns whether the response has been fully fetched.

Returns:

  • (Boolean) 


115
116
117
 
# File 'lib/httpx/response.rb', line 115

def finished?
  @finished
end

#form ⇒ Hash[String, untyped]

decodes the response payload into a ruby object if the payload is valid "application/x-www-urlencoded" or "multipart/form-data".

Returns:

  • (Hash[String, untyped]) 


185
186
187
 
# File 'lib/httpx/response.rb', line 185

def form
  decode(Transcoder::Form)
end

#initialize_dup(orig) ⇒ Object

dupped initialization



75
76
77
78
79
80
 
# File 'lib/httpx/response.rb', line 75

def initialize_dup(orig)
  super
  # if a response gets dupped, the body handle must also get dupped to prevent
  # two responses from using the same file handle to read.
  @body = orig.body.dup
end

#inspect ⇒ Object

simplecov:disable



145
146
147
148
149
150
151
 
# File 'lib/httpx/response.rb', line 145

def inspect
  "#<#{self.class}:#{object_id} " \
    "HTTP/#{version} " \
    "@status=#{@status} " \
    "@headers=#{@headers} " \
    "@body=#{@body.bytesize}>"
end

#json(*args) ⇒ Object

decodes the response payload into a ruby object if the payload is valid json.

response.json #≈> { "foo" => "bar" } for "{\"foo\":\"bar\"}" payload
response.json(symbolize_names: true) #≈> { foo: "bar" } for "{\"foo\":\"bar\"}" payload

Parameters:

  • opts (JSON::options)

Returns:

  • (Object) 


179
180
181
 
# File 'lib/httpx/response.rb', line 179

def json(*args)
  decode(Transcoder::JSON, *args)
end

#merge_headers(h) ⇒ void

This method returns an undefined value.

merges headers defined in h into the response headers.

Parameters:

  • (_Each[[String, headers_value]]) 


89
90
91
92
 
# File 'lib/httpx/response.rb', line 89

def merge_headers(h)
  @headers = @headers.merge(h)
  @content_type = @content_length = nil
end

#peer_address ⇒ String, ...

Returns:

  • (String, IPAddr, nil) 


39
 
# File 'sig/response.rbs', line 39

def peer_address: () -> (String | IPAddr)?

#raise_for_status ⇒ Object

it raises the exception returned by error, or itself otherwise.

ok_response.raise_for_status #=> ok_response
not_found_response.raise_for_status #=> raises HTTPX::HTTPError exception


169
170
171
172
173
 
# File 'lib/httpx/response.rb', line 169

def raise_for_status
  return self unless (err = error)

  raise err
end

#uri ⇒ URI::Generic

Returns:

  • (URI::Generic) 


37
 
# File 'sig/response.rbs', line 37

def uri: () -> URI::Generic

#xml ⇒ Object 



189
190
191
192
193
194
195
 
# File 'lib/httpx/response.rb', line 189

def xml
  # TODO: remove at next major version.
  warn "DEPRECATION WARNING: calling `.#{__method__}` on plain HTTPX responses is deprecated. " \
       "Use HTTPX.plugin(:xml) sessions and call `.#{__method__}` in its responses instead."
  require "httpx/plugins/xml"
  decode(Plugins::XML::Transcoder)
end