module Net::HTTPHeader

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.

# File net/http/header.rb, line 216
def [](key)
  a = @header[key.downcase.to_s] or return nil
  a.join(', ')
end

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.

# File net/http/header.rb, line 232
def []=(key, val)
  unless val
    @header.delete key.downcase.to_s
    return val
  end
  set_field(key, val)
end

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"]

# File net/http/header.rb, line 253
def add_field(key, val)
  stringified_downcased_key = key.downcase.to_s
  if @header.key?(stringified_downcased_key)
    append_field_value(@header[stringified_downcased_key], val)
  else
    set_field(key, val)
  end
end

Set the Authorization: header for “Basic” authorization.

# File net/http/header.rb, line 856
def basic_auth(account, password)
  @header['authorization'] = [basic_encode(account, password)]
end

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

# File net/http/header.rb, line 646
def chunked?
  return false unless @header['transfer-encoding']
  field = self['Transfer-Encoding']
  (/(?:\A|[^\-\w])chunked(?![\-\w])/i =~ field) ? true : false
end

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

# File net/http/header.rb, line 608
def content_length
  return nil unless key?('Content-Length')
  len = self['Content-Length'].slice(/\d+/) or
      raise Net::HTTPHeaderSyntaxError, 'wrong Content-Length format'
  len.to_i
end

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>

# File net/http/header.rb, line 629
def content_length=(len)
  unless len
    @header.delete 'content-length'
    return nil
  end
  @header['content-length'] = [len.to_i.to_s]
end

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

# File net/http/header.rb, line 662
def content_range
  return nil unless @header['content-range']
  m = %r<\A\s*(\w+)\s+(\d+)-(\d+)/(\d+|\*)>.match(self['Content-Range']) or
      raise Net::HTTPHeaderSyntaxError, 'wrong Content-Range format'
  return unless m[1] == 'bytes'
  m[2].to_i .. m[3].to_i
end

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"

# File net/http/header.rb, line 693
def content_type
  return nil unless main_type()
  if sub_type()
  then "#{main_type()}/#{sub_type()}"
  else main_type()
  end
end

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

# File net/http/header.rb, line 445
def delete(key)
  @header.delete(key.downcase.to_s)
end

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

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

# File net/http/header.rb, line 476
def each_capitalized
  block_given? or return enum_for(__method__) { @header.size }
  @header.each do |k,v|
    yield capitalize(k), v.join(', ')
  end
end

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.

# File net/http/header.rb, line 409
def each_capitalized_name  #:yield: +key+
  block_given? or return enum_for(__method__) { @header.size }
  @header.each_key do |k|
    yield capitalize(k)
  end
end

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.

# File net/http/header.rb, line 356
def each_header   #:yield: +key+, +value+
  block_given? or return enum_for(__method__) { @header.size }
  @header.each do |k,va|
    yield k, va.join(', ')
  end
end

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.

# File net/http/header.rb, line 383
def each_name(&block)   #:yield: +key+
  block_given? or return enum_for(__method__) { @header.size }
  @header.each_key(&block)
end

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.

# File net/http/header.rb, line 430
def each_value   #:yield: +value+
  block_given? or return enum_for(__method__) { @header.size }
  @header.each_value do |va|
    yield va.join(', ')
  end
end

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.

# File net/http/header.rb, line 333
def fetch(key, *args, &block)   #:yield: +key+
  a = @header.fetch(key.downcase.to_s, *args, &block)
  a.kind_of?(Array) ? a.join(', ') : a
end

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

# File net/http/header.rb, line 298
def get_fields(key)
  stringified_downcased_key = key.downcase.to_s
  return nil unless @header[stringified_downcased_key]
  @header[stringified_downcased_key].dup
end

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

# File net/http/header.rb, line 455
def key?(key)
  @header.key?(key.downcase.to_s)
end

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"

# File net/http/header.rb, line 711
def main_type
  return nil unless @header['content-type']
  self['Content-Type'].split(';').first.to_s.split('/')[0].to_s.strip
end

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

# File net/http/header.rb, line 861
def proxy_basic_auth(account, password)
  @header['proxy-authorization'] = [basic_encode(account, password)]
end

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

# File net/http/header.rb, line 501
def range
  return nil unless @header['range']

  value = self['Range']
  # byte-range-set = *( "," OWS ) ( byte-range-spec / suffix-byte-range-spec )
  #   *( OWS "," [ OWS ( byte-range-spec / suffix-byte-range-spec ) ] )
  # corrected collected ABNF
  # http://tools.ietf.org/html/draft-ietf-httpbis-p5-range-19#section-5.4.1
  # http://tools.ietf.org/html/draft-ietf-httpbis-p5-range-19#appendix-C
  # http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-19#section-3.2.5
  unless /\Abytes=((?:,[ \t]*)*(?:\d+-\d*|-\d+)(?:[ \t]*,(?:[ \t]*\d+-\d*|-\d+)?)*)\z/ =~ value
    raise Net::HTTPHeaderSyntaxError, "invalid syntax for byte-ranges-specifier: '#{value}'"
  end

  byte_range_set = $1
  result = byte_range_set.split(/,/).map {|spec|
    m = /(\d+)?\s*-\s*(\d+)?/i.match(spec) or
            raise Net::HTTPHeaderSyntaxError, "invalid byte-range-spec: '#{spec}'"
    d1 = m[1].to_i
    d2 = m[2].to_i
    if m[1] and m[2]
      if d1 > d2
        raise Net::HTTPHeaderSyntaxError, "last-byte-pos MUST greater than or equal to first-byte-pos but '#{spec}'"
      end
      d1..d2
    elsif m[1]
      d1..-1
    elsif m[2]
      -d2..-1
    else
      raise Net::HTTPHeaderSyntaxError, 'range is not specified'
    end
  }
  # if result.empty?
  # byte-range-set must include at least one byte-range-spec or suffix-byte-range-spec
  # but above regexp already denies it.
  if result.size == 1 && result[0].begin == 0 && result[0].end == -1
    raise Net::HTTPHeaderSyntaxError, 'only one suffix-byte-range-spec with zero suffix-length'
  end
  result
end

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

# File net/http/header.rb, line 679
def range_length
  r = content_range() or return nil
  r.end - r.begin + 1
end

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.

# File net/http/header.rb, line 760
def set_content_type(type, params = {})
  @header['content-type'] = [type + params.map{|k,v|"; #{k}=#{v}"}.join('')]
end

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

# File net/http/header.rb, line 841
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 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.

# File net/http/header.rb, line 781
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

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.

# File net/http/header.rb, line 568
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.end
    last -= 1 if r.exclude_end?
    if last == -1
      rangestr = (first > 0 ? "#{first}-" : "-#{-first}")
    else
      raise Net::HTTPHeaderSyntaxError, 'range.first is negative' if first < 0
      raise Net::HTTPHeaderSyntaxError, 'range.last is negative' if last < 0
      raise Net::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

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"

# File net/http/header.rb, line 726
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

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"]}

# File net/http/header.rb, line 469
def to_hash
  @header.dup
end

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"}

# File net/http/header.rb, line 741
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