Class: Gem::Net::HTTPResponse

Inherits:
Object
  • Object
show all
Includes:
HTTPHeader
Defined in:
lib/rubygems/vendor/net-http/lib/net/http/response.rb,
lib/rubygems/vendor/net-http/lib/net/http/responses.rb

Overview

This class is the base class for Gem::Net::HTTP response classes.

About the Examples

:include: doc/net-http/examples.rdoc

Returned Responses

Method Gem::Net::HTTP.get_response returns an instance of one of the subclasses of Gem::Net::HTTPResponse:

Gem::Net::HTTP.get_response(uri)
# => #<Gem::Net::HTTPOK 200 OK readbody=true>
Gem::Net::HTTP.get_response(hostname, '/nosuch')
# => #<Gem::Net::HTTPNotFound 404 Not Found readbody=true>

As does method Gem::Net::HTTP#request:

req = Gem::Net::HTTP::Get.new(uri)
Gem::Net::HTTP.start(hostname) do |http|
  http.request(req)
end # => #<Gem::Net::HTTPOK 200 OK readbody=true>

Class Gem::Net::HTTPResponse includes module Gem::Net::HTTPHeader, which provides access to response header values via (among others):

  • Hash-like method [].

  • Specific reader methods, such as content_type.

Examples:

res = Gem::Net::HTTP.get_response(uri) # => #<Gem::Net::HTTPOK 200 OK readbody=true>
res['Content-Type']               # => "text/html; charset=UTF-8"
res.content_type                  # => "text/html"

Response Subclasses

Class Gem::Net::HTTPResponse has a subclass for each HTTP status code. You can look up the response class for a given code:

Gem::Net::HTTPResponse::CODE_TO_OBJ['200'] # => Gem::Net::HTTPOK
Gem::Net::HTTPResponse::CODE_TO_OBJ['400'] # => Gem::Net::HTTPBadRequest
Gem::Net::HTTPResponse::CODE_TO_OBJ['404'] # => Gem::Net::HTTPNotFound

And you can retrieve the status code for a response object:

Gem::Net::HTTP.get_response(uri).code                 # => "200"
Gem::Net::HTTP.get_response(hostname, '/nosuch').code # => "404"

The response subclasses (indentation shows class hierarchy):

  • Gem::Net::HTTPUnknownResponse (for unhandled HTTP extensions).

  • Gem::Net::HTTPInformation:

    • Gem::Net::HTTPContinue (100)

    • Gem::Net::HTTPSwitchProtocol (101)

    • Gem::Net::HTTPProcessing (102)

    • Gem::Net::HTTPEarlyHints (103)

  • Gem::Net::HTTPSuccess:

    • Gem::Net::HTTPOK (200)

    • Gem::Net::HTTPCreated (201)

    • Gem::Net::HTTPAccepted (202)

    • Gem::Net::HTTPNonAuthoritativeInformation (203)

    • Gem::Net::HTTPNoContent (204)

    • Gem::Net::HTTPResetContent (205)

    • Gem::Net::HTTPPartialContent (206)

    • Gem::Net::HTTPMultiStatus (207)

    • Gem::Net::HTTPAlreadyReported (208)

    • Gem::Net::HTTPIMUsed (226)

  • Gem::Net::HTTPRedirection:

    • Gem::Net::HTTPMultipleChoices (300)

    • Gem::Net::HTTPMovedPermanently (301)

    • Gem::Net::HTTPFound (302)

    • Gem::Net::HTTPSeeOther (303)

    • Gem::Net::HTTPNotModified (304)

    • Gem::Net::HTTPUseProxy (305)

    • Gem::Net::HTTPTemporaryRedirect (307)

    • Gem::Net::HTTPPermanentRedirect (308)

  • Gem::Net::HTTPClientError:

    • Gem::Net::HTTPBadRequest (400)

    • Gem::Net::HTTPUnauthorized (401)

    • Gem::Net::HTTPPaymentRequired (402)

    • Gem::Net::HTTPForbidden (403)

    • Gem::Net::HTTPNotFound (404)

    • Gem::Net::HTTPMethodNotAllowed (405)

    • Gem::Net::HTTPNotAcceptable (406)

    • Gem::Net::HTTPProxyAuthenticationRequired (407)

    • Gem::Net::HTTPRequestTimeOut (408)

    • Gem::Net::HTTPConflict (409)

    • Gem::Net::HTTPGone (410)

    • Gem::Net::HTTPLengthRequired (411)

    • Gem::Net::HTTPPreconditionFailed (412)

    • Gem::Net::HTTPRequestEntityTooLarge (413)

    • Gem::Net::HTTPRequestURITooLong (414)

    • Gem::Net::HTTPUnsupportedMediaType (415)

    • Gem::Net::HTTPRequestedRangeNotSatisfiable (416)

    • Gem::Net::HTTPExpectationFailed (417)

    • Gem::Net::HTTPMisdirectedRequest (421)

    • Gem::Net::HTTPUnprocessableEntity (422)

    • Gem::Net::HTTPLocked (423)

    • Gem::Net::HTTPFailedDependency (424)

    • Gem::Net::HTTPUpgradeRequired (426)

    • Gem::Net::HTTPPreconditionRequired (428)

    • Gem::Net::HTTPTooManyRequests (429)

    • Gem::Net::HTTPRequestHeaderFieldsTooLarge (431)

    • Gem::Net::HTTPUnavailableForLegalReasons (451)

  • Gem::Net::HTTPServerError:

    • Gem::Net::HTTPInternalServerError (500)

    • Gem::Net::HTTPNotImplemented (501)

    • Gem::Net::HTTPBadGateway (502)

    • Gem::Net::HTTPServiceUnavailable (503)

    • Gem::Net::HTTPGatewayTimeOut (504)

    • Gem::Net::HTTPVersionNotSupported (505)

    • Gem::Net::HTTPVariantAlsoNegotiates (506)

    • Gem::Net::HTTPInsufficientStorage (507)

    • Gem::Net::HTTPLoopDetected (508)

    • Gem::Net::HTTPNotExtended (510)

    • Gem::Net::HTTPNetworkAuthenticationRequired (511)

There is also the Gem::Net::HTTPBadResponse exception which is raised when there is a protocol error.

Defined Under Namespace

Classes: Inflater

Constant Summary collapse

CODE_CLASS_TO_OBJ = 
{
  '1' => Gem::Net::HTTPInformation,
  '2' => Gem::Net::HTTPSuccess,
  '3' => Gem::Net::HTTPRedirection,
  '4' => Gem::Net::HTTPClientError,
  '5' => Gem::Net::HTTPServerError
}
CODE_TO_OBJ = 
{
  '100' => Gem::Net::HTTPContinue,
  '101' => Gem::Net::HTTPSwitchProtocol,
  '102' => Gem::Net::HTTPProcessing,
  '103' => Gem::Net::HTTPEarlyHints,

  '200' => Gem::Net::HTTPOK,
  '201' => Gem::Net::HTTPCreated,
  '202' => Gem::Net::HTTPAccepted,
  '203' => Gem::Net::HTTPNonAuthoritativeInformation,
  '204' => Gem::Net::HTTPNoContent,
  '205' => Gem::Net::HTTPResetContent,
  '206' => Gem::Net::HTTPPartialContent,
  '207' => Gem::Net::HTTPMultiStatus,
  '208' => Gem::Net::HTTPAlreadyReported,
  '226' => Gem::Net::HTTPIMUsed,

  '300' => Gem::Net::HTTPMultipleChoices,
  '301' => Gem::Net::HTTPMovedPermanently,
  '302' => Gem::Net::HTTPFound,
  '303' => Gem::Net::HTTPSeeOther,
  '304' => Gem::Net::HTTPNotModified,
  '305' => Gem::Net::HTTPUseProxy,
  '307' => Gem::Net::HTTPTemporaryRedirect,
  '308' => Gem::Net::HTTPPermanentRedirect,

  '400' => Gem::Net::HTTPBadRequest,
  '401' => Gem::Net::HTTPUnauthorized,
  '402' => Gem::Net::HTTPPaymentRequired,
  '403' => Gem::Net::HTTPForbidden,
  '404' => Gem::Net::HTTPNotFound,
  '405' => Gem::Net::HTTPMethodNotAllowed,
  '406' => Gem::Net::HTTPNotAcceptable,
  '407' => Gem::Net::HTTPProxyAuthenticationRequired,
  '408' => Gem::Net::HTTPRequestTimeout,
  '409' => Gem::Net::HTTPConflict,
  '410' => Gem::Net::HTTPGone,
  '411' => Gem::Net::HTTPLengthRequired,
  '412' => Gem::Net::HTTPPreconditionFailed,
  '413' => Gem::Net::HTTPPayloadTooLarge,
  '414' => Gem::Net::HTTPURITooLong,
  '415' => Gem::Net::HTTPUnsupportedMediaType,
  '416' => Gem::Net::HTTPRangeNotSatisfiable,
  '417' => Gem::Net::HTTPExpectationFailed,
  '421' => Gem::Net::HTTPMisdirectedRequest,
  '422' => Gem::Net::HTTPUnprocessableEntity,
  '423' => Gem::Net::HTTPLocked,
  '424' => Gem::Net::HTTPFailedDependency,
  '426' => Gem::Net::HTTPUpgradeRequired,
  '428' => Gem::Net::HTTPPreconditionRequired,
  '429' => Gem::Net::HTTPTooManyRequests,
  '431' => Gem::Net::HTTPRequestHeaderFieldsTooLarge,
  '451' => Gem::Net::HTTPUnavailableForLegalReasons,

  '500' => Gem::Net::HTTPInternalServerError,
  '501' => Gem::Net::HTTPNotImplemented,
  '502' => Gem::Net::HTTPBadGateway,
  '503' => Gem::Net::HTTPServiceUnavailable,
  '504' => Gem::Net::HTTPGatewayTimeout,
  '505' => Gem::Net::HTTPVersionNotSupported,
  '506' => Gem::Net::HTTPVariantAlsoNegotiates,
  '507' => Gem::Net::HTTPInsufficientStorage,
  '508' => Gem::Net::HTTPLoopDetected,
  '510' => Gem::Net::HTTPNotExtended,
  '511' => Gem::Net::HTTPNetworkAuthenticationRequired,
}

Constants included from HTTPHeader

Gem::Net::HTTPHeader::MAX_FIELD_LENGTH, Gem::Net::HTTPHeader::MAX_KEY_LENGTH

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from HTTPHeader

#[], #[]=, #add_field, #basic_auth, #chunked?, #connection_close?, #connection_keep_alive?, #content_length, #content_length=, #content_range, #content_type, #delete, #each_capitalized, #each_capitalized_name, #each_header, #each_name, #each_value, #fetch, #get_fields, #initialize_http_header, #key?, #main_type, #proxy_basic_auth, #range, #range_length, #set_content_type, #set_form, #set_form_data, #set_range, #size, #sub_type, #to_hash, #type_params

Constructor Details

#initialize(httpv, code, msg) ⇒ HTTPResponse

:nodoc: internal use only



194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 194

def initialize(httpv, code, msg)   #:nodoc: internal use only
  @http_version = httpv
  @code         = code
  @message      = msg
  initialize_http_header nil
  @body = nil
  @read = false
  @uri  = nil
  @decode_content = false
  @body_encoding = false
  @ignore_eof = true
end

Instance Attribute Details

#body_encoding ⇒ Object

Returns the value set by body_encoding=, or false if none; see #body_encoding=.



229
230
231
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 229

def body_encoding
  @body_encoding
end

#code ⇒ Object (readonly)

The HTTP result code string. For example, ‘302’. You can also determine the response type by examining which response subclass the response object is an instance of.



213
214
215
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 213

def code
  @code
end

#decode_content ⇒ Object

Set to true automatically when the request did not contain an Accept-Encoding header from the user.



225
226
227
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 225

def decode_content
  @decode_content
end

#http_version ⇒ Object (readonly)

The HTTP version supported by the server.



208
209
210
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 208

def http_version
  @http_version
end

#ignore_eof ⇒ Object

Whether to ignore EOF when reading bodies with a specified Content-Length header.



260
261
262
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 260

def ignore_eof
  @ignore_eof
end

#message ⇒ Object (readonly) Also known as: msg

The HTTP result message sent by the server. For example, ‘Not Found’.



216
217
218
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 216

def message
  @message
end

#uri ⇒ Object

The Gem::URI used to fetch this response. The response Gem::URI is only available if a Gem::URI was used to create the request.



221
222
223
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 221

def uri
  @uri
end

Class Method Details

.body_permitted? ⇒ Boolean

true if the response has a body.

Returns:

  • (Boolean) 


138
139
140
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 138

def body_permitted?
  self::HAS_BODY
end

.exception_type ⇒ Object

:nodoc: internal use only



142
143
144
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 142

def exception_type   # :nodoc: internal use only
  self::EXCEPTION_TYPE
end

.read_new(sock) ⇒ Object

:nodoc: internal use only



146
147
148
149
150
151
152
153
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 146

def read_new(sock)   #:nodoc: internal use only
  httpv, code, msg = read_status_line(sock)
  res = response_class(code).new(httpv, code, msg)
  each_response_header(sock) do |k,v|
    res.add_field k, v
  end
  res
end

Instance Method Details

#body ⇒ Object Also known as: entity

Returns the string response body; note that repeated calls for the unmodified body return a cached string:

path = '/todos/1'
Gem::Net::HTTP.start(hostname) do |http|
  res = http.get(path)
  p res.body
  p http.head(path).body # No body.
end

Output:

"{\n  \"userId\": 1,\n  \"id\": 1,\n  \"title\": \"delectus aut autem\",\n  \"completed\": false\n}"
nil



400
401
402
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 400

def body
  read_body()
end

#body=(value) ⇒ Object

Sets the body of the response to the given value.



405
406
407
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 405

def body=(value)
  @body = value
end

#code_type ⇒ Object

response <-> exception relationship



270
271
272
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 270

def code_type   #:nodoc:
  self.class
end

#error! ⇒ Object

:nodoc:

Raises:



274
275
276
277
278
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 274

def error!   #:nodoc:
  message = @code
  message = "#{message} #{@message.dump}" if @message
  raise error_type().new(message, self)
end

#error_type ⇒ Object

:nodoc:



280
281
282
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 280

def error_type   #:nodoc:
  self.class::EXCEPTION_TYPE
end

#header ⇒ Object

:nodoc:



302
303
304
305
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 302

def header   #:nodoc:
  warn "Gem::Net::HTTPResponse#header is obsolete", uplevel: 1 if $VERBOSE
  self
end

#inspect ⇒ Object 



262
263
264
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 262

def inspect
  "#<#{self.class} #{@code} #{@message} readbody=#{@read}>"
end

#read_body(dest = nil, &block) ⇒ Object

Gets the entity body returned by the remote HTTP server.

If a block is given, the body is passed to the block, and the body is provided in fragments, as it is read in from the socket.

If dest argument is given, response is read into that variable, with dest#<< method (it could be String or IO, or any other object responding to <<).

Calling this method a second or subsequent time for the same HTTPResponse object will return the value already read.

http.request_get('/index.html') {|res|
  puts res.read_body
}

http.request_get('/index.html') {|res|
  p res.read_body.object_id   # 538149362
  p res.read_body.object_id   # 538149362
}

# using iterator
http.request_get('/index.html') {|res|
  res.read_body do |segment|
    print segment
  end
}



355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 355

def read_body(dest = nil, &block)
  if @read
    raise IOError, "#{self.class}\#read_body called twice" if dest or block
    return @body
  end
  to = procdest(dest, block)
  stream_check
  if @body_exist
    read_body_0 to
    @body = to
  else
    @body = nil
  end
  @read = true
  return if @body.nil?

  case enc = @body_encoding
  when Encoding, false, nil
    # Encoding: force given encoding
    # false/nil: do not force encoding
  else
    # other value: detect encoding from body
    enc = detect_encoding(@body)
  end

  @body.force_encoding(enc) if enc

  @body
end

#read_header ⇒ Object

:nodoc:



307
308
309
310
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 307

def read_header   #:nodoc:
  warn "Gem::Net::HTTPResponse#read_header is obsolete", uplevel: 1 if $VERBOSE
  self
end

#reading_body(sock, reqmethodallowbody) ⇒ Object

body



316
317
318
319
320
321
322
323
324
325
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 316

def reading_body(sock, reqmethodallowbody)  #:nodoc: internal use only
  @socket = sock
  @body_exist = reqmethodallowbody && self.class.body_permitted?
  begin
    yield
    self.body   # ensure to read body
  ensure
    @socket = nil
  end
end

#response ⇒ Object

header (for backward compatibility only; DO NOT USE)



297
298
299
300
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 297

def response   #:nodoc:
  warn "Gem::Net::HTTPResponse#response is obsolete", uplevel: 1 if $VERBOSE
  self
end

#value ⇒ Object

Raises an HTTP error if the response is not 2xx (success).



285
286
287
 
# File 'lib/rubygems/vendor/net-http/lib/net/http/response.rb', line 285

def value
  error! unless self.kind_of?(Gem::Net::HTTPSuccess)
end