Extended maintenance of Ruby 1.9.3 ended on February 23, 2015. Read more

In Files

  • net/http.rb

Net::HTTPHeader

The HTTPHeader module defines methods for reading and writing HTTP headers.

It is used as a mixin by other classes, to provide hash-like access to HTTP header values. Unlike raw hash access, HTTPHeader provides access via case-insensitive keys. It also provides methods for accessing commonly-used HTTP header values in more convenient formats.

Public Instance Methods

[](key) click to toggle source

Returns the header field corresponding to the case-insensitive key. For example, a key of “Content-Type” might return “text/html”

 
               # File net/http.rb, line 1448
def [](key)
  a = @header[key.downcase] or return nil
  a.join(', ')
end
            
[]=(key, val) click to toggle source

Sets the header field corresponding to the case-insensitive key.

 
               # File net/http.rb, line 1454
def []=(key, val)
  unless val
    @header.delete key.downcase
    return val
  end
  @header[key.downcase] = [val]
end
            
add_field(key, val) click to toggle source
Ruby 1.8.3

Adds a value to a named header field, instead of replacing its value. Second argument val must be a String. See also []=, [] and get_fields.

request.add_field 'X-My-Header', 'a'
p request['X-My-Header']              #=> "a"
p request.get_fields('X-My-Header')   #=> ["a"]
request.add_field 'X-My-Header', 'b'
p request['X-My-Header']              #=> "a, b"
p request.get_fields('X-My-Header')   #=> ["a", "b"]
request.add_field 'X-My-Header', 'c'
p request['X-My-Header']              #=> "a, b, c"
p request.get_fields('X-My-Header')   #=> ["a", "b", "c"]
 
               # File net/http.rb, line 1477
def add_field(key, val)
  if @header.key?(key.downcase)
    @header[key.downcase].push val
  else
    @header[key.downcase] = [val]
  end
end
            
basic_auth(account, password) click to toggle source

Set the Authorization: header for “Basic” authorization.

 
               # File net/http.rb, line 1812
def basic_auth(account, password)
  @header['authorization'] = [basic_encode(account, password)]
end
            
canonical_each() click to toggle source
Alias for: each_capitalized
chunked?() click to toggle source

Returns “true” if the “transfer-encoding” header is present and set to “chunked”. This is an HTTP/1.1 feature, allowing the the content to be sent in “chunks” without at the outset stating the entire content length.

 
               # File net/http.rb, line 1673
def chunked?
  return false unless @header['transfer-encoding']
  field = self['Transfer-Encoding']
  (/(?:\A|[^\-\w])chunked(?![\-\w])/i =~ field) ? true : false
end
            
connection_close?() click to toggle source
 
               # File net/http.rb, line 1826
def connection_close?
  tokens(@header['connection']).include?('close') or
  tokens(@header['proxy-connection']).include?('close')
end
            
connection_keep_alive?() click to toggle source
 
               # File net/http.rb, line 1831
def connection_keep_alive?
  tokens(@header['connection']).include?('keep-alive') or
  tokens(@header['proxy-connection']).include?('keep-alive')
end
            
content_length() click to toggle source

Returns an Integer object which represents the HTTP Content-Length: header field, or nil if that field was not provided.

 
               # File net/http.rb, line 1654
def content_length
  return nil unless key?('Content-Length')
  len = self['Content-Length'].slice(/\d+/) or
      raise HTTPHeaderSyntaxError, 'wrong Content-Length format'
  len.to_i
end
            
content_length=(len) click to toggle source
 
               # File net/http.rb, line 1661
def content_length=(len)
  unless len
    @header.delete 'content-length'
    return nil
  end
  @header['content-length'] = [len.to_i.to_s]
end
            
content_range() click to toggle source

Returns a Range object which represents the value of the Content-Range: header field. For a partial entity body, this indicates where this fragment fits inside the full entity body, as range of byte offsets.

 
               # File net/http.rb, line 1683
def content_range
  return nil unless @header['content-range']
  m = %r<bytes\s+(\d+)-(\d+)/(\d+|\*)>i.match(self['Content-Range']) or
      raise HTTPHeaderSyntaxError, 'wrong Content-Range format'
  m[1].to_i .. m[2].to_i
end
            
content_type() click to toggle source

Returns a content type string such as “text/html”. This method returns nil if Content-Type: header field does not exist.

 
               # File net/http.rb, line 1698
def content_type
  return nil unless main_type()
  if sub_type()
  then "#{main_type()}/#{sub_type()}"
  else main_type()
  end
end
            
content_type=(type, params = {}) click to toggle source
Alias for: set_content_type
delete(key) click to toggle source

Removes a header field, specified by case-insensitive key.

 
               # File net/http.rb, line 1558
def delete(key)
  @header.delete(key.downcase)
end
            
each() click to toggle source
Alias for: each_header
each_capitalized() click to toggle source

As for each_header, except the keys are provided in capitalized form.

Note that header names are capitalized systematically; capitalization may not match that used by the remote HTTP server in its response.

 
               # File net/http.rb, line 1581
def each_capitalized
  block_given? or return enum_for(__method__)
  @header.each do |k,v|
    yield capitalize(k), v.join(', ')
  end
end
            
Also aliased as: canonical_each
each_capitalized_name() click to toggle source

Iterates through the header names in the header, passing capitalized header names to the code block.

Note that header names are capitalized systematically; capitalization may not match that used by the remote HTTP server in its response.

 
               # File net/http.rb, line 1541
def each_capitalized_name  #:yield: +key+
  block_given? or return enum_for(__method__)
  @header.each_key do |k|
    yield capitalize(k)
  end
end
            
each_header() click to toggle source

Iterates through the header names and values, passing in the name and value to the code block supplied.

Example:

response.header.each_header {|key,value| puts "#{key} = #{value}" }
 
               # File net/http.rb, line 1517
def each_header   #:yield: +key+, +value+
  block_given? or return enum_for(__method__)
  @header.each do |k,va|
    yield k, va.join(', ')
  end
end
            
Also aliased as: each
each_key() click to toggle source
Alias for: each_name
each_name() click to toggle source

Iterates through the header names in the header, passing each header name to the code block.

 
               # File net/http.rb, line 1528
def each_name(&block)   #:yield: +key+
  block_given? or return enum_for(__method__)
  @header.each_key(&block)
end
            
Also aliased as: each_key
each_value() click to toggle source

Iterates through header values, passing each value to the code block.

 
               # File net/http.rb, line 1550
def each_value   #:yield: +value+
  block_given? or return enum_for(__method__)
  @header.each_value do |va|
    yield va.join(', ')
  end
end
            
fetch(key, *args) click to toggle source

Returns the header field corresponding to the case-insensitive key. Returns the default value args, or the result of the block, or raises an IndexError if there’s no header field named key See Hash#fetch

 
               # File net/http.rb, line 1505
def fetch(key, *args, &block)   #:yield: +key+
  a = @header.fetch(key.downcase, *args, &block)
  a.kind_of?(Array) ? a.join(', ') : a
end
            
form_data=(params, sep = '&') click to toggle source
Alias for: set_form_data
get_fields(key) click to toggle source
Ruby 1.8.3

Returns an array of header field strings corresponding to the case-insensitive key. This method allows you to get duplicated header fields without any processing. See also [].

p response.get_fields('Set-Cookie')
  #=> ["session=al98axx; expires=Fri, 31-Dec-1999 23:58:23",
       "query=rubyscript; expires=Fri, 31-Dec-1999 23:58:23"]
p response['Set-Cookie']
  #=> "session=al98axx; expires=Fri, 31-Dec-1999 23:58:23, query=rubyscript; expires=Fri, 31-Dec-1999 23:58:23"
 
               # File net/http.rb, line 1496
def get_fields(key)
  return nil unless @header[key.downcase]
  @header[key.downcase].dup
end
            
initialize_http_header(initheader) click to toggle source
 
               # File net/http.rb, line 1431
def initialize_http_header(initheader)
  @header = {}
  return unless initheader
  initheader.each do |key, value|
    warn "net/http: warning: duplicated HTTP header: #{key}" if key?(key) and $VERBOSE
    @header[key.downcase] = [value.strip]
  end
end
            
key?(key) click to toggle source

true if key header exists.

 
               # File net/http.rb, line 1563
def key?(key)
  @header.key?(key.downcase)
end
            
main_type() click to toggle source

Returns a content type string such as “text”. This method returns nil if Content-Type: header field does not exist.

 
               # File net/http.rb, line 1708
def main_type
  return nil unless @header['content-type']
  self['Content-Type'].split(';').first.to_s.split('/')[0].to_s.strip
end
            
proxy_basic_auth(account, password) click to toggle source

Set Proxy-Authorization: header for “Basic” authorization.

 
               # File net/http.rb, line 1817
def proxy_basic_auth(account, password)
  @header['proxy-authorization'] = [basic_encode(account, password)]
end
            
range() click to toggle source

Returns an Array of Range objects which represent the Range: HTTP header field, or nil if there is no such header.

 
               # File net/http.rb, line 1597
def range
  return nil unless @header['range']
  self['Range'].split(/,/).map {|spec|
    m = /bytes\s*=\s*(\d+)?\s*-\s*(\d+)?/i.match(spec) or
            raise HTTPHeaderSyntaxError, "wrong Range: #{spec}"
    d1 = m[1].to_i
    d2 = m[2].to_i
    if    m[1] and m[2] then  d1..d2
    elsif m[1]          then  d1..-1
    elsif          m[2] then -d2..-1
    else
      raise HTTPHeaderSyntaxError, 'range is not specified'
    end
  }
end
            
range=(r, e = nil) click to toggle source
Alias for: set_range
range_length() click to toggle source

The length of the range represented in Content-Range: header.

 
               # File net/http.rb, line 1691
def range_length
  r = content_range() or return nil
  r.end - r.begin + 1
end
            
set_content_type(type, params = {}) click to toggle source

Sets the content type in an HTTP header. The type should be a full HTTP content type, e.g. “text/html”. The params are an optional Hash of parameters to add after the content type, e.g. {‘charset’ => ‘iso-8859-1’}

 
               # File net/http.rb, line 1741
def set_content_type(type, params = {})
  @header['content-type'] = [type + params.map{|k,v|"; #{k}=#{v}"}.join('')]
end
            
Also aliased as: content_type=
set_form(params, enctype='application/x-www-form-urlencoded', formopt={}) click to toggle source

Set a HTML form data set. params is the form data set; it is an Array of Arrays or a Hash +enctype is the type to encode the form data set. It is application/x-www-form-urlencoded or multipart/form-data. formpot is an optional hash to specify the detail.

boundary

the boundary of the multipart message

charset

the charset of the message. All names and the values of non-file fields are encoded as the charset.

Each item of params is an array and contains following items:

name

the name of the field

value

the value of the field, it should be a String or a File

opt

an optional hash to specify additional information

Each item is a file field or a normal field. If value is a File object or the opt have a filename key, the item is treated as a file field.

If Transfer-Encoding is set as chunked, this send the request in chunked encoding. Because chunked encoding is HTTP/1.1 feature, you must confirm the server to support HTTP/1.1 before sending it.

Example:

http.set_form([["q", "ruby"], ["lang", "en"]])

See also RFC 2388, RFC 2616, HTML 4.01, and HTML5

 
               # File net/http.rb, line 1797
def set_form(params, enctype='application/x-www-form-urlencoded', formopt={})
  @body_data = params
  @body = nil
  @body_stream = nil
  @form_option = formopt
  case enctype
  when /\Aapplication\/x-www-form-urlencoded\z/i,
    /\Amultipart\/form-data\z/i
    self.content_type = enctype
  else
    raise ArgumentError, "invalid enctype: #{enctype}"
  end
end
            
set_form_data(params, sep = '&') click to toggle source

Set header fields and a body from HTML form data. params should be an Array of Arrays or a Hash containing HTML form data. Optional argument sep means data record separator.

Values are URL encoded as necessary and the content-type is set to application/x-www-form-urlencoded

Example:

http.form_data = {"q" => "ruby", "lang" => "en"}
http.form_data = {"q" => ["ruby", "perl"], "lang" => "en"}
http.set_form_data({"q" => "ruby", "lang" => "en"}, ';')
 
               # File net/http.rb, line 1760
def set_form_data(params, sep = '&')
  query = URI.encode_www_form(params)
  query.gsub!(/&/, sep) if sep != '&'
  self.body = query
  self.content_type = 'application/x-www-form-urlencoded'
end
            
Also aliased as: form_data=
set_range(r, e = nil) click to toggle source

Sets the HTTP Range: header. Accepts either a Range object as a single argument, or a beginning index and a length from that index. Example:

req.range = (0..1023)
req.set_range 0, 1023
 
               # File net/http.rb, line 1621
def set_range(r, e = nil)
  unless r
    @header.delete 'range'
    return r
  end
  r = (r...r+e) if e
  case r
  when Numeric
    n = r.to_i
    rangestr = (n > 0 ? "0-#{n-1}" : "-#{-n}")
  when Range
    first = r.first
    last = r.last
    last -= 1 if r.exclude_end?
    if last == -1
      rangestr = (first > 0 ? "#{first}-" : "-#{-first}")
    else
      raise HTTPHeaderSyntaxError, 'range.first is negative' if first < 0
      raise HTTPHeaderSyntaxError, 'range.last is negative' if last < 0
      raise HTTPHeaderSyntaxError, 'must be .first < .last' if first > last
      rangestr = "#{first}-#{last}"
    end
  else
    raise TypeError, 'Range/Integer is required'
  end
  @header['range'] = ["bytes=#{rangestr}"]
  r
end
            
Also aliased as: range=
sub_type() click to toggle source

Returns a content type string such as “html”. This method returns nil if Content-Type: header field does not exist or sub-type is not given (e.g. “Content-Type: text”).

 
               # File net/http.rb, line 1716
def sub_type
  return nil unless @header['content-type']
  _, sub = *self['Content-Type'].split(';').first.to_s.split('/')
  return nil unless sub
  sub.strip
end
            
to_hash() click to toggle source

Returns a Hash consisting of header names and values. e.g. {“cache-control” => “private”,

"content-type" => "text/html",
"date" => "Wed, 22 Jun 2005 22:11:50 GMT"}
 
               # File net/http.rb, line 1572
def to_hash
  @header.dup
end
            
type_params() click to toggle source

Any parameters specified for the content type, returned as a Hash. For example, a header of Content-Type: text/html; charset=EUC-JP would result in #type_params returning {‘charset’ => ‘EUC-JP’}

 
               # File net/http.rb, line 1726
def type_params
  result = {}
  list = self['Content-Type'].to_s.split(';')
  list.shift
  list.each do |param|
    k, v = *param.split('=', 2)
    result[k.strip] = v.strip
  end
  result
end
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.