class HTTP::Message

Represents a HTTP message. A message is for a request or a response.

Request message is generated from given parameters internally so users don’t need to care about it. Response message is the instance that methods of HTTPClient returns so users need to know how to extract HTTP response data from Message.

Some attributes are only for a request or a response, not both.

How to use HTTP response message

  1. Gets response message body.

    res = clnt.get(url)
    p res.content #=> String
    
  2. Gets response status code.

    res = clnt.get(url)
    p res.status #=> 200, 501, etc. (Integer)
    
  3. Gets response header.

    res = clnt.get(url)
    res.header['set-cookie'].each do |value|
      p value
    end
    assert_equal(1, res.header['last-modified'].size)
    p res.header['last-modified'].first
    

Constants

CRLF
VERSION_WARNING

Attributes

header[RW]
HTTP::Message::Headers

message header.

http_body[R]
HTTP::Message::Body

message body.

http_header[RW]
HTTP::Message::Headers

message header.

oauth_params[RW]
peer_cert[RW]
OpenSSL::X509::Certificate

response only. server certificate which is used for retrieving the response.

previous[RW]

The other Message object when this Message is generated instead of the Message because of redirection, negotiation, or format conversion.

Public Class Methods

file?(obj) click to toggle source

Returns true if the given object is a File. In HTTPClient, a file is;

  • must respond to :read for retrieving String chunks.

  • must respond to :pos and :pos= to rewind for reading. Rewinding is only needed for following HTTP redirect. Some IO impl defines :pos= but raises an Exception for pos= such as StringIO but there’s no problem as far as using it for non-following methods (get/post/etc.)

# File lib/httpclient/http.rb, line 846
def file?(obj)
  obj.respond_to?(:read) and obj.respond_to?(:pos) and
    obj.respond_to?(:pos=)
end
get_mime_type_func()
Alias for: mime_type_handler
internal_mime_type(path) click to toggle source

Default MIME type handler. See mime_type_handler=.

# File lib/httpclient/http.rb, line 807
def internal_mime_type(path)
  case path
  when /\.txt$/i
    'text/plain'
  when /\.xml$/i
    'text/xml'
  when /\.(htm|html)$/i
    'text/html'
  when /\.doc$/i
    'application/msword'
  when /\.png$/i
    'image/png'
  when /\.gif$/i
    'image/gif'
  when /\.(jpg|jpeg)$/i
    'image/jpeg'
  else
    'application/octet-stream'
  end
end
keep_alive_enabled?(version) click to toggle source

Returns true if the given HTTP version allows keep alive connection.

version

String

# File lib/httpclient/http.rb, line 830
def keep_alive_enabled?(version)
  version >= '1.1'
end
mime_type_handler() click to toggle source

Returns MIME type handler.

# File lib/httpclient/http.rb, line 784
def mime_type_handler
  @@mime_type_handler
end
Also aliased as: get_mime_type_func
mime_type_handler=(handler) click to toggle source

Sets MIME type handler.

handler must respond to :call with a single argument :path and returns a MIME type String e.g. ‘text/html’. When the handler returns nil or an empty String, ‘application/octet-stream’ is used.

When you set nil to the handler, internal_mime_type is used instead. The handler is nil by default.

# File lib/httpclient/http.rb, line 779
def mime_type_handler=(handler)
  @@mime_type_handler = handler
end
Also aliased as: set_mime_type_func
multiparam_query?(query) click to toggle source

Returns true if the given query (or body) has a multiple parameter.

# File lib/httpclient/http.rb, line 835
def multiparam_query?(query)
  query.is_a?(Array) or query.is_a?(Hash)
end
new_connect_request(uri) click to toggle source

Creates a Message instance of ‘CONNECT’ request. ‘CONNECT’ request does not have Body.

uri

an URI that need to connect. Only uri.host and uri.port are used.

# File lib/httpclient/http.rb, line 723
def new_connect_request(uri)
  m = new
  m.http_header.init_connect_request(uri)
  m.http_header.body_size = nil
  m
end
new_request(method, uri, query = nil, body = nil, boundary = nil) click to toggle source

Creates a Message instance of general request.

method

HTTP method String.

uri

an URI object which represents an URL of web resource.

query

a Hash or an Array of query part of URL. e.g. { “a” => “b” } => ‘host/part?a=b’ Give an array to pass multiple value like

[“a”, “b”], [“a”, “c”]

> ‘host/part?a=b&a=c

body

a Hash or an Array of body part. e.g. { “a” => “b” } => ‘a=b’. Give an array to pass multiple value like

[“a”, “b”], [“a”, “c”]

> ‘a=b&a=c’.

boundary

When the boundary given, it is sent as a multipart/form-data using this boundary String.

# File lib/httpclient/http.rb, line 743
def new_request(method, uri, query = nil, body = nil, boundary = nil)
  m = new
  m.http_header.init_request(method, uri, query)
  m.http_body = Body.new
  m.http_body.init_request(body || '', boundary)
  if body
    m.http_header.body_size = m.http_body.size
    m.http_header.chunked = true if m.http_body.size.nil?
  else
    m.http_header.body_size = nil
  end
  m
end
new_response(body, req = nil) click to toggle source

Creates a Message instance of response.

body

a String or an IO of response message body.

# File lib/httpclient/http.rb, line 759
def new_response(body, req = nil)
  m = new
  m.http_header.init_response(Status::OK, req)
  m.http_body = Body.new
  m.http_body.init_response(body)
  m.http_header.body_size = m.http_body.size || 0
  m
end
parse(query) click to toggle source

from CGI.parse

# File lib/httpclient/http.rb, line 909
def parse(query)
  params = Hash.new([].freeze)
  query.split(/[&;]/n).each do |pairs|
    key, value = pairs.split('=',2).collect{|v| unescape(v) }
    if params.has_key?(key)
      params[key].push(value)
    else
      params[key] = [value]
    end
  end
  params
end
set_mime_type_func(handler)

For backward compatibility.

Alias for: mime_type_handler=
unescape(string) click to toggle source

from CGI.unescape

# File lib/httpclient/http.rb, line 923
def unescape(string)
  string.tr('+', ' ').gsub(/((?:%[0-9a-fA-F]{2})+)/n) do
    [$1.delete('%')].pack('H*')
  end
end

Public Instance Methods

body()
Alias for: content
body=(body)
Alias for: http_body=
body_encoding() click to toggle source

Returns content encoding

# File lib/httpclient/http.rb, line 1033
def body_encoding
  @http_header.body_encoding
end
code()
Alias for: status
content() click to toggle source

Returns a content of message body. A String or an IO.

# File lib/httpclient/http.rb, line 1038
def content
  @http_body.content
end
Also aliased as: body
content_type() click to toggle source

Returns ‘Content-Type’ header value.

# File lib/httpclient/http.rb, line 1021
def content_type
  @http_header.content_type
end
Also aliased as: contenttype
content_type=(content_type) click to toggle source

Sets ‘Content-Type’ header value. Overrides if already exists.

# File lib/httpclient/http.rb, line 1026
def content_type=(content_type)
  @http_header.content_type = content_type
end
Also aliased as: contenttype=
contenttype()
Alias for: content_type
contenttype=(content_type)
Alias for: content_type=
cookies() click to toggle source

Extracts cookies from ‘Set-Cookie’ header. Supports ‘Set-Cookie’ in response header only. Do we need ‘Cookie’ support in request header?

# File lib/httpclient/http.rb, line 1056
def cookies
  set_cookies = http_header['set-cookie']
  unless set_cookies.empty?
    uri = http_header.request_uri
    set_cookies.map { |str|
      WebAgent::Cookie.parse(str, uri)
    }.flatten
  end
end
dump(dev = '') click to toggle source

Dumps message (header and body) to given dev. dev needs to respond to <<.

# File lib/httpclient/http.rb, line 956
def dump(dev = '')
  str = @http_header.dump + CRLF
  if @http_header.chunked
    dev = @http_body.dump_chunked(str, dev)
  elsif @http_body
    dev = @http_body.dump(str, dev)
  else
    dev << str
  end
  dev
end
headers() click to toggle source

Returns Hash of header. key and value are both String. Each key has a single value so you can’t extract exact value when a message has multiple headers like ‘Set-Cookie’. Use header for that purpose. (It returns an Array always)

# File lib/httpclient/http.rb, line 1049
def headers
  Hash[*http_header.all.flatten]
end
http_body=(body) click to toggle source

Sets a new body. header.body_size is updated with new body.size.

# File lib/httpclient/http.rb, line 969
def http_body=(body)
  @http_body = body
  @http_header.body_size = @http_body.size if @http_header
end
Also aliased as: body=
http_version() click to toggle source

Returns HTTP version in a HTTP header. String.

# File lib/httpclient/http.rb, line 976
def http_version
  @http_header.http_version
end
http_version=(http_version) click to toggle source

Sets HTTP version in a HTTP header. String.

# File lib/httpclient/http.rb, line 981
def http_version=(http_version)
  @http_header.http_version = http_version
end
ok?() click to toggle source

Convenience method to return boolean of whether we had a successful request

# File lib/httpclient/http.rb, line 1067
def ok?
  HTTP::Status.successful?(status)
end
reason() click to toggle source

Returns HTTP status reason phrase in response. String.

# File lib/httpclient/http.rb, line 1011
def reason
  @http_header.reason_phrase
end
reason=(reason) click to toggle source

Sets HTTP status reason phrase of response. String.

# File lib/httpclient/http.rb, line 1016
def reason=(reason)
  @http_header.reason_phrase = reason
end
redirect?() click to toggle source
# File lib/httpclient/http.rb, line 1071
def redirect?
  HTTP::Status.redirect?(status)
end
see_other?() click to toggle source

SEE_OTHER is a redirect, but it should sent as GET

# File lib/httpclient/http.rb, line 1076
def see_other?
  status == HTTP::Status::SEE_OTHER
end
status() click to toggle source

Returns HTTP status code in response. Integer.

# File lib/httpclient/http.rb, line 997
def status
  @http_header.status_code
end
Also aliased as: code, status_code
status=(status) click to toggle source

Sets HTTP status code of response. Integer. Reason phrase is updated, too.

# File lib/httpclient/http.rb, line 1006
def status=(status)
  @http_header.status_code = status
end
status_code()
Alias for: status
version() click to toggle source
# File lib/httpclient/http.rb, line 986
def version
  warning(VERSION_WARNING)
  @http_header.http_version.to_f
end
version=(version) click to toggle source
# File lib/httpclient/http.rb, line 991
def version=(version)
  warning(VERSION_WARNING)
  @http_header.http_version = version
end