Net::HTTPHeader

Module

The HTTPHeader module provides access to HTTP headers.

The module is included in:

The headers are a hash-like collection of key/value pairs called fields.

Request and Response Fields

Headers may be included in:

  • A Net::HTTPRequest object: the object’s headers will be sent with the request. Any fields may be defined in the request; see Setters.

  • A Net::HTTPResponse object: the objects headers are usually those returned from the host. Fields may be retrieved from the object; see Getters and Iterators.

Exactly which fields should be sent or expected depends on the host; see:

About the Examples

Fields

A header field is a key/value pair.

Field Keys

A field key may be:

  • A string: Key 'Accept' is treated as if it were 'Accept'.downcase; i.e., 'accept'.

  • A symbol: Key :Accept is treated as if it were :Accept.to_s.downcase; i.e., 'accept'.

Examples:

req = Net::HTTP::Get.new(uri)
req[:accept]  # => "*/*"
req['Accept'] # => "*/*"
req['ACCEPT'] # => "*/*"

req['accept'] = 'text/html'
req[:accept] = 'text/html'
req['ACCEPT'] = 'text/html'

Field Values

A field value may be returned as an array of strings or as a string:

  • These methods return field values as arrays:

    • get_fields: Returns the array value for the given key, or nil if it does not exist.

    • to_hash: Returns a hash of all header fields: each key is a field name; its value is the array value for the field.

  • These methods return field values as string; the string value for a field is equivalent to self[key.downcase.to_s].join(', ')):

    • []: Returns the string value for the given key, or nil if it does not exist.

    • fetch: Like [], but accepts a default value to be returned if the key does not exist.

The field value may be set:

  • []=: Sets the value for the given key; the given value may be a string, a symbol, an array, or a hash.

  • add_field: Adds a given value to a value for the given key (not overwriting the existing value).

  • delete: Deletes the field for the given key.

Example field values:

  • String:

    req['Accept'] = 'text/html' # => "text/html"
req['Accept']               # => "text/html"
req.get_fields('Accept')    # => ["text/html"]

  • Symbol:

    req['Accept'] = :text    # => :text
req['Accept']            # => "text"
req.get_fields('Accept') # => ["text"]

  • Simple array:

    req[:foo] = %w[bar baz bat]
req[:foo]            # => "bar, baz, bat"
req.get_fields(:foo) # => ["bar", "baz", "bat"]

  • Simple hash:

    req[:foo] = {bar: 0, baz: 1, bat: 2}
req[:foo]            # => "bar, 0, baz, 1, bat, 2"
req.get_fields(:foo) # => ["bar", "0", "baz", "1", "bat", "2"]

  • Nested:

    req[:foo] = [%w[bar baz], {bat: 0, bam: 1}]
req[:foo]            # => "bar, baz, bat, 0, bam, 1"
req.get_fields(:foo) # => ["bar", "baz", "bat", "0", "bam", "1"]

req[:foo] = {bar: %w[baz bat], bam: {bah: 0, bad: 1}}
req[:foo]            # => "bar, baz, bat, bam, bah, 0, bad, 1"
req.get_fields(:foo) # => ["bar", "baz", "bat", "bam", "bah", "0", "bad", "1"]

Convenience Methods

Various convenience methods retrieve values, set values, query values, set form values, or iterate over fields.

Setters

Method []= can set any field, but does little to validate the new value; some of the other setter methods provide some validation:

  • []=: Sets the string or array value for the given key.

  • add_field: Creates or adds to the array value for the given key.

  • basic_auth: Sets the string authorization header for 'Authorization'.

  • content_length=: Sets the integer length for field 'Content-Length.

  • content_type=: Sets the string value for field 'Content-Type'.

  • proxy_basic_auth: Sets the string authorization header for 'Proxy-Authorization'.

  • set_range: Sets the value for field 'Range'.

Form Setters

  • set_form: Sets an HTML form data set.

  • set_form_data: Sets header fields and a body from HTML form data.

Getters

Method [] can retrieve the value of any field that exists, but always as a string; some of the other getter methods return something different from the simple string value:

  • []: Returns the string field value for the given key.

  • content_length: Returns the integer value of field 'Content-Length'.

  • content_range: Returns the Range value of field 'Content-Range'.

  • content_type: Returns the string value of field 'Content-Type'.

  • fetch: Returns the string field value for the given key.

  • get_fields: Returns the array field value for the given key.

  • main_type: Returns first part of the string value of field 'Content-Type'.

  • sub_type: Returns second part of the string value of field 'Content-Type'.

  • range: Returns an array of Range objects of field 'Range', or nil.

  • range_length: Returns the integer length of the range given in field 'Content-Range'.

  • type_params: Returns the string parameters for 'Content-Type'.

Queries

  • chunked?: Returns whether field 'Transfer-Encoding' is set to 'chunked'.

  • connection_close?: Returns whether field 'Connection' is set to 'close'.

  • connection_keep_alive?: Returns whether field 'Connection' is set to 'keep-alive'.

  • key?: Returns whether a given key exists.

Iterators

Instance Methods

[](key)
#

Returns the string field value for the case-insensitive field key, or nil if there is no such key; see Fields:

res = Net::HTTP.get_response(hostname, '/todos/1')
res['Connection'] # => "keep-alive"
res['Nosuch']     # => nil

Note that some field values may be retrieved via convenience methods; see Getters.

[]=(key, val)
#

Sets the value for the case-insensitive key to val, overwriting the previous value if the field exists; see Fields:

req = Net::HTTP::Get.new(uri)
req['Accept'] # => "*/*"
req['Accept'] = 'text/html'
req['Accept'] # => "text/html"

Note that some field values may be set via convenience methods; see Setters.

add_field(key, val)
#

Adds value val to the value array for field key if the field exists; creates the field with the given key and val if it does not exist. see Fields:

req = Net::HTTP::Get.new(uri)
req.add_field('Foo', 'bar')
req['Foo']            # => "bar"
req.add_field('Foo', 'baz')
req['Foo']            # => "bar, baz"
req.add_field('Foo', %w[baz bam])
req['Foo']            # => "bar, baz, baz, bam"
req.get_fields('Foo') # => ["bar", "baz", "baz", "bam"]

append_field_value(ary, val)
#
No documentation available

basic_auth(account, password)
#

Set the Authorization: header for “Basic” authorization.

basic_encode(account, password)
#
No documentation available

canonical_each
#
An alias for each_capitalized

capitalize(name)
#
No documentation available

chunked?
#

Returns true if field 'Transfer-Encoding' exists and has value 'chunked', false otherwise; see Transfer-Encoding response header:

res = Net::HTTP.get_response(hostname, '/todos/1')
res['Transfer-Encoding'] # => "chunked"
res.chunked?             # => true

connection_close?
#
No documentation available

connection_keep_alive?
#
No documentation available

content_length
#

Returns the value of field 'Content-Length' as an integer, or nil if there is no such field; see Content-Length request header:

res = Net::HTTP.get_response(hostname, '/nosuch/1')
res.content_length # => 2
res = Net::HTTP.get_response(hostname, '/todos/1')
res.content_length # => nil

content_length=(len)
#

Sets the value of field 'Content-Length' to the given numeric; see Content-Length response header:

_uri = uri.dup
hostname = _uri.hostname           # => "jsonplaceholder.typicode.com"
_uri.path = '/posts'               # => "/posts"
req = Net::HTTP::Post.new(_uri)    # => #<Net::HTTP::Post POST>
req.body = '{"title": "foo","body": "bar","userId": 1}'
req.content_length = req.body.size # => 42
req.content_type = 'application/json'
res = Net::HTTP.start(hostname) do |http|
  http.request(req)
end # => #<Net::HTTPCreated 201 Created readbody=true>

content_range
#

Returns a Range object representing the value of field 'Content-Range', or nil if no such field exists; see Content-Range response header:

res = Net::HTTP.get_response(hostname, '/todos/1')
res['Content-Range'] # => nil
res['Content-Range'] = 'bytes 0-499/1000'
res['Content-Range'] # => "bytes 0-499/1000"
res.content_range    # => 0..499

content_type
#

Returns the media type from the value of field 'Content-Type', or nil if no such field exists; see Content-Type response header:

res = Net::HTTP.get_response(hostname, '/todos/1')
res['content-type'] # => "application/json; charset=utf-8"
res.content_type    # => "application/json"

content_type=(type, params = {})
#
An alias for set_content_type

delete(key)
#

Removes the header for the given case-insensitive key (see Fields); returns the deleted value, or nil if no such field exists:

req = Net::HTTP::Get.new(uri)
req.delete('Accept') # => ["*/*"]
req.delete('Nosuch') # => nil

each
#
An alias for each_header

each_capitalized() { |capitalize(k), join(', ')| ... }
#

Like each_header, but the keys are returned in capitalized form.

Net::HTTPHeader#canonical_each is an alias for Net::HTTPHeader#each_capitalized.

each_capitalized_name() { |key| ... }
#

Calls the block with each capitalized field name:

res = Net::HTTP.get_response(hostname, '/todos/1')
res.each_capitalized_name do |key|
  p key if key.start_with?('C')
end

Output:

"Content-Type"
"Connection"
"Cache-Control"
"Cf-Cache-Status"
"Cf-Ray"

The capitalization is system-dependent; see Case Mapping.

Returns an enumerator if no block is given.

each_header() { |key| ... }
#

Calls the block with each key/value pair:

res = Net::HTTP.get_response(hostname, '/todos/1')
res.each_header do |key, value|
  p [key, value] if key.start_with?('c')
end

Output:

["content-type", "application/json; charset=utf-8"]
["connection", "keep-alive"]
["cache-control", "max-age=43200"]
["cf-cache-status", "HIT"]
["cf-ray", "771d17e9bc542cf5-ORD"]

Returns an enumerator if no block is given.

Net::HTTPHeader#each is an alias for Net::HTTPHeader#each_header.

each_key
#
An alias for each_name

each_name() { |key| ... }
#

Calls the block with each field key:

res = Net::HTTP.get_response(hostname, '/todos/1')
res.each_key do |key|
  p key if key.start_with?('c')
end

Output:

"content-type"
"connection"
"cache-control"
"cf-cache-status"
"cf-ray"

Returns an enumerator if no block is given.

Net::HTTPHeader#each_name is an alias for Net::HTTPHeader#each_key.

each_value() { |value| ... }
#

Calls the block with each string field value:

res = Net::HTTP.get_response(hostname, '/todos/1')
res.each_value do |value|
  p value if value.start_with?('c')
end

Output:

"chunked"
"cf-q-config;dur=6.0000002122251e-06"
"cloudflare"

Returns an enumerator if no block is given.

fetch(key, default_val = nil) {|key| ... } → object

fetch(key, default_val = nil) → value or default_val
#

With a block, returns the string value for key if it exists; otherwise returns the value of the block; ignores the default_val; see Fields:

res = Net::HTTP.get_response(hostname, '/todos/1')

# Field exists; block not called.
res.fetch('Connection') do |value|
  fail 'Cannot happen'
end # => "keep-alive"

# Field does not exist; block called.
res.fetch('Nosuch') do |value|
  value.downcase
end # => "nosuch"

With no block, returns the string value for key if it exists; otherwise, returns default_val if it was given; otherwise raises an exception:

res.fetch('Connection', 'Foo') # => "keep-alive"
res.fetch('Nosuch', 'Foo')     # => "Foo"
res.fetch('Nosuch')            # Raises KeyError.

form_data=(params, sep = '&')
#
An alias for set_form_data

get_fields(key)
#

Returns the array field value for the given key, or nil if there is no such field; see Fields:

res = Net::HTTP.get_response(hostname, '/todos/1')
res.get_fields('Connection') # => ["keep-alive"]
res.get_fields('Nosuch')     # => nil

key?(key)
#

Returns true if the field for the case-insensitive key exists, false otherwise:

req = Net::HTTP::Get.new(uri)
req.key?('Accept') # => true
req.key?('Nosuch') # => false

main_type
#

Returns the leading (‘type’) part of the media type from the value of field 'Content-Type', or nil if no such field exists; see Content-Type response header:

res = Net::HTTP.get_response(hostname, '/todos/1')
res['content-type'] # => "application/json; charset=utf-8"
res.main_type       # => "application"

proxy_basic_auth(account, password)
#

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

range
#

Returns an array of Range objects that represent the value of field 'Range', or nil if there is no such field; see Range request header:

req = Net::HTTP::Get.new(uri)
req['Range'] = 'bytes=0-99,200-299,400-499'
req.range # => [0..99, 200..299, 400..499]
req.delete('Range')
req.range # # => nil

range=(r, e = nil)
#
An alias for set_range

range_length
#

Returns the integer representing length of the value of field 'Content-Range', or nil if no such field exists; see Content-Range response header:

res = Net::HTTP.get_response(hostname, '/todos/1')
res['Content-Range'] # => nil
res['Content-Range'] = 'bytes 0-499/1000'
res.range_length     # => 500

set_content_type(type, params = {})
#

Sets the value of field 'Content-Type'; returns the new value; see Content-Type request header:

req = Net::HTTP::Get.new(uri)
req.set_content_type('application/json') # => ["application/json"]

Net::HTTPHeader#content_type= is an alias for Net::HTTPHeader#set_content_type.

set_field(key, val)
#
No documentation available

set_form(params, enctype='application/x-www-form-urlencoded', formopt={})
#

Set an HTML form data set.

params

The form data to set, which should be an enumerable. See below for more details.

enctype

The content type to use to encode the form submission, which should be application/x-www-form-urlencoded or multipart/form-data.

formopt

An options hash, supporting the following options:

:boundary

The boundary of the multipart message. If not given, a random boundary will be used.

:charset

The charset of the form submission. All field names and values of non-file fields should be encoded with this charset.

Each item of params should respond to each and yield 2-3 arguments, or an array of 2-3 elements. The arguments yielded should be:

  • The name of the field.

  • The value of the field, it should be a String or a File or IO-like.

  • An options hash, supporting the following options (used only for file uploads); entries:

    • :filename: The name of the file to use.

    • :content_type: The content type of the uploaded file.

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

If Transfer-Encoding is set as chunked, this sends the request using chunked encoding. Because chunked encoding is HTTP/1.1 feature, you should confirm that the server supports HTTP/1.1 before using chunked encoding.

Example:

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

req.set_form({"f"=>File.open('/path/to/filename')},
             "multipart/form-data",
             charset: "UTF-8",
)

req.set_form([["f",
               File.open('/path/to/filename.bar'),
               {filename: "other-filename.foo"}
             ]],
             "multipart/form-data",
)

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

set_form_data(params, sep = '&')
#

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"}, ';')

Net::HTTPHeader#form_data= is an alias for Net::HTTPHeader#set_form_data.

set_range(length) → length

set_range(offset, length) → range

set_range(begin..length) → range
#

Sets the value for field 'Range'; see Range request header:

With argument length:

req = Net::HTTP::Get.new(uri)
req.set_range(100)      # => 100
req['Range']            # => "bytes=0-99"

With arguments offset and length:

req.set_range(100, 100) # => 100...200
req['Range']            # => "bytes=100-199"

With argument range:

req.set_range(100..199) # => 100..199
req['Range']            # => "bytes=100-199"

Net::HTTPHeader#range= is an alias for Net::HTTPHeader#set_range.

sub_type
#

Returns the trailing (‘subtype’) part of the media type from the value of field 'Content-Type', or nil if no such field exists; see Content-Type response header:

res = Net::HTTP.get_response(hostname, '/todos/1')
res['content-type'] # => "application/json; charset=utf-8"
res.sub_type        # => "json"

to_hash
#

Returns a hash of the key/value pairs:

req = Net::HTTP::Get.new(uri)
req.to_hash
# =>
{"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"],
 "accept"=>["*/*"],
 "user-agent"=>["Ruby"],
 "host"=>["jsonplaceholder.typicode.com"]}

type_params
#

Returns the trailing (‘parameters’) part of the value of field 'Content-Type', or nil if no such field exists; see Content-Type response header:

res = Net::HTTP.get_response(hostname, '/todos/1')
res['content-type'] # => "application/json; charset=utf-8"
res.type_params     # => {"charset"=>"utf-8"}