class Gem::Net::HTTPResponse

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

About the Examples

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):

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

Constants

CODE_CLASS_TO_OBJ
CODE_TO_OBJ

Attributes

body_encoding[R]

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

code[R]

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.

decode_content[RW]

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

http_version[R]

The HTTP version supported by the server.

ignore_eof[RW]

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

message[R]

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

msg[R]

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

uri[R]

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

Public Class Methods

body_permitted?() click to toggle source

true if the response has a body.

# File rubygems/net-http/lib/net/http/response.rb, line 138
def body_permitted?
  self::HAS_BODY
end

Private Class Methods

each_response_header(sock) { |key, value| ... } click to toggle source
# File rubygems/net-http/lib/net/http/response.rb, line 170
def each_response_header(sock)
  key = value = nil
  while true
    line = sock.readuntil("\n", true).sub(/\s+\z/, '')
    break if line.empty?
    if line[0] == ?\s or line[0] == ?\t and value
      value << ' ' unless value.empty?
      value << line.strip
    else
      yield key, value if key
      key, value = line.strip.split(/\s*:\s*/, 2)
      raise Gem::Net::HTTPBadResponse, 'wrong header line format' if value.nil?
    end
  end
  yield key, value if key
end
read_status_line(sock) click to toggle source
# File rubygems/net-http/lib/net/http/response.rb, line 157
def read_status_line(sock)
  str = sock.readline
  m = /\AHTTP(?:\/(\d+\.\d+))?\s+(\d\d\d)(?:\s+(.*))?\z/in.match(str) or
    raise Gem::Net::HTTPBadResponse, "wrong status line: #{str.dump}"
  m.captures
end
response_class(code) click to toggle source
# File rubygems/net-http/lib/net/http/response.rb, line 164
def response_class(code)
  CODE_TO_OBJ[code] or
  CODE_CLASS_TO_OBJ[code[0,1]] or
  Gem::Net::HTTPUnknownResponse
end

Public Instance Methods

body() click to toggle source

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
# File rubygems/net-http/lib/net/http/response.rb, line 400
def body
  read_body()
end
Also aliased as: entity
body=(value) click to toggle source

Sets the body of the response to the given value.

# File rubygems/net-http/lib/net/http/response.rb, line 405
def body=(value)
  @body = value
end
body_encoding=(value) click to toggle source

Sets the encoding that should be used when reading the body:

  • If the given value is an Encoding object, that encoding will be used.

  • Otherwise if the value is a string, the value of Encoding#find(value) will be used.

  • Otherwise an encoding will be deduced from the body itself.

Examples:

http = Gem::Net::HTTP.new(hostname)
req = Gem::Net::HTTP::Get.new('/')

http.request(req) do |res|
  p res.body.encoding # => #<Encoding:ASCII-8BIT>
end

http.request(req) do |res|
  res.body_encoding = "UTF-8"
  p res.body.encoding # => #<Encoding:UTF-8>
end
# File rubygems/net-http/lib/net/http/response.rb, line 253
def body_encoding=(value)
  value = Encoding.find(value) if value.is_a?(String)
  @body_encoding = value
end
entity()
Alias for: body
inspect() click to toggle source
# File rubygems/net-http/lib/net/http/response.rb, line 262
def inspect
  "#<#{self.class} #{@code} #{@message} readbody=#{@read}>"
end
read_body(dest = nil, &block) click to toggle source

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
}
# File rubygems/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
value() click to toggle source

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

# File rubygems/net-http/lib/net/http/response.rb, line 285
def value
  error! unless self.kind_of?(Gem::Net::HTTPSuccess)
end