Module: Net::HTTPHeader

Included in:
HTTPGenericRequest, HTTPResponse
Defined in:
lib/net/http/header.rb

Overview

The HTTPHeader module provides access to HTTP headers.

The module is included in:

  • Net::HTTPGenericRequest (and therefore Net::HTTPRequest).

  • Net::HTTPResponse.

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

:include: doc/net-http/examples.rdoc

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

  • #each_capitalized: Passes each field capitalized-name/value pair to the block.

  • #each_capitalized_name: Passes each capitalized field name to the block.

  • #each_header: Passes each field name/value pair to the block.

  • #each_name: Passes each field name to the block.

  • #each_value: Passes each string field value to the block.

Constant Summary collapse

MAX_KEY_LENGTH =

The maximum length of HTTP header keys.

1024
MAX_FIELD_LENGTH =

The maximum length of HTTP header values.

65536

Instance Method Summary collapse

Instance Method Details

#[](key) ⇒ Object

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.



226
227
228
229
 
# File 'lib/net/http/header.rb', line 226

def [](key)
  a = @header[key.downcase.to_s] or return nil
  a.join(', ')
end

#[]=(key, val) ⇒ Object

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.



242
243
244
245
246
247
248
 
# File 'lib/net/http/header.rb', line 242

def []=(key, val)
  unless val
    @header.delete key.downcase.to_s
    return val
  end
  set_field(key, val)
end

#add_field(key, val) ⇒ Object

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



263
264
265
266
267
268
269
270
 
# File 'lib/net/http/header.rb', line 263

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

#basic_auth(account, password) ⇒ Object

Sets header 'Authorization' using the given account and password strings:

req.basic_auth('my_account', 'my_password')
req['Authorization']
# => "Basic bXlfYWNjb3VudDpteV9wYXNzd29yZA=="



949
950
951
 
# File 'lib/net/http/header.rb', line 949

def basic_auth(, password)
  @header['authorization'] = [basic_encode(, password)]
end

#chunked? ⇒ Boolean

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

Returns:

  • (Boolean) 


658
659
660
661
662
 
# File 'lib/net/http/header.rb', line 658

def chunked?
  return false unless @header['transfer-encoding']
  field = self['Transfer-Encoding']
  (/(?:\A|[^\-\w])chunked(?![\-\w])/i =~ field) ? true : false
end

#connection_close? ⇒ Boolean

Returns whether the HTTP session is to be closed.

Returns:

  • (Boolean) 


970
971
972
973
974
975
 
# File 'lib/net/http/header.rb', line 970

def connection_close?
  token = /(?:\A|,)\s*close\s*(?:\z|,)/i
  @header['connection']&.grep(token) {return true}
  @header['proxy-connection']&.grep(token) {return true}
  false
end

#connection_keep_alive? ⇒ Boolean

Returns whether the HTTP session is to be kept alive.

Returns:

  • (Boolean) 


978
979
980
981
982
983
 
# File 'lib/net/http/header.rb', line 978

def connection_keep_alive?
  token = /(?:\A|,)\s*keep-alive\s*(?:\z|,)/i
  @header['connection']&.grep(token) {return true}
  @header['proxy-connection']&.grep(token) {return true}
  false
end

#content_length ⇒ Object

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



620
621
622
623
624
625
 
# File 'lib/net/http/header.rb', line 620

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

#content_length=(len) ⇒ Object

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>



641
642
643
644
645
646
647
 
# File 'lib/net/http/header.rb', line 641

def content_length=(len)
  unless len
    @header.delete 'content-length'
    return nil
  end
  @header['content-length'] = [len.to_i.to_s]
end

#content_range ⇒ Object

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



674
675
676
677
678
679
680
 
# File 'lib/net/http/header.rb', line 674

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

#content_type ⇒ Object

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"



705
706
707
708
709
710
711
712
713
714
715
 
# File 'lib/net/http/header.rb', line 705

def content_type
  main = main_type()
  return nil unless main

  sub = sub_type()
  if sub
    "#{main}/#{sub}"
  else
    main
  end
end

#delete(key) ⇒ Object

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



457
458
459
 
# File 'lib/net/http/header.rb', line 457

def delete(key)
  @header.delete(key.downcase.to_s)
end

#each_capitalized ⇒ Object Also known as: canonical_each

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

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



488
489
490
491
492
493
 
# File 'lib/net/http/header.rb', line 488

def each_capitalized
  block_given? or return enum_for(__method__) { @header.size }
  @header.each do |k,v|
    yield capitalize(k), v.join(', ')
  end
end

#each_capitalized_name ⇒ Object

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.



421
422
423
424
425
426
 
# File 'lib/net/http/header.rb', line 421

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

#each_header ⇒ Object Also known as: each

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.



368
369
370
371
372
373
 
# File 'lib/net/http/header.rb', line 368

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

#each_name(&block) ⇒ Object Also known as: each_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.



395
396
397
398
 
# File 'lib/net/http/header.rb', line 395

def each_name(&block)   #:yield: +key+
  block_given? or return enum_for(__method__) { @header.size }
  @header.each_key(&block)
end

#each_value ⇒ Object

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.



442
443
444
445
446
447
 
# File 'lib/net/http/header.rb', line 442

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

#fetch(key, *args, &block) ⇒ Object

call-seq:

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.



345
346
347
348
 
# File 'lib/net/http/header.rb', line 345

def fetch(key, *args, &block)   #:yield: +key+
  a = @header.fetch(key.downcase.to_s, *args, &block)
  a.kind_of?(Array) ? a.join(', ') : a
end

#get_fields(key) ⇒ Object

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



310
311
312
313
314
 
# File 'lib/net/http/header.rb', line 310

def get_fields(key)
  stringified_downcased_key = key.downcase.to_s
  return nil unless @header[stringified_downcased_key]
  @header[stringified_downcased_key].dup
end

#initialize_http_header(initheader) ⇒ Object

:nodoc:



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/net/http/header.rb', line 187

def initialize_http_header(initheader) #:nodoc:
  @header = {}
  return unless initheader
  initheader.each do |key, value|
    warn "net/http: duplicated HTTP header: #{key}", uplevel: 3 if key?(key) and $VERBOSE
    if value.nil?
      warn "net/http: nil HTTP header: #{key}", uplevel: 3 if $VERBOSE
    else
      value = value.strip # raise error for invalid byte sequences
      if key.to_s.bytesize > MAX_KEY_LENGTH
        raise ArgumentError, "too long (#{key.bytesize} bytes) header: #{key[0, 30].inspect}..."
      end
      if value.to_s.bytesize > MAX_FIELD_LENGTH
        raise ArgumentError, "header #{key} has too long field value: #{value.bytesize}"
      end
      if value.count("\r\n") > 0
        raise ArgumentError, "header #{key} has field value #{value.inspect}, this cannot include CR/LF"
      end
      @header[key.downcase.to_s] = [value]
    end
  end
end

#key?(key) ⇒ Boolean

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

Returns:

  • (Boolean) 


467
468
469
 
# File 'lib/net/http/header.rb', line 467

def key?(key)
  @header.key?(key.downcase.to_s)
end

#main_type ⇒ Object

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"



727
728
729
730
 
# File 'lib/net/http/header.rb', line 727

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) ⇒ Object

Sets header 'Proxy-Authorization' using the given account and password strings:

req.proxy_basic_auth('my_account', 'my_password')
req['Proxy-Authorization']
# => "Basic bXlfYWNjb3VudDpteV9wYXNzd29yZA=="



960
961
962
 
# File 'lib/net/http/header.rb', line 960

def proxy_basic_auth(, password)
  @header['proxy-authorization'] = [basic_encode(, password)]
end

#range ⇒ Object

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



513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
 
# File 'lib/net/http/header.rb', line 513

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

#range_length ⇒ Object

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



691
692
693
694
 
# File 'lib/net/http/header.rb', line 691

def range_length
  r = content_range() or return nil
  r.end - r.begin + 1
end

#set_content_type(type, params = {}) ⇒ Object Also known as: content_type=

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.



776
777
778
 
# File 'lib/net/http/header.rb', line 776

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

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

Stores form data to be used in a POST or PUT request.

The form data given in params consists of zero or more fields; each field is:

  • A scalar value.

  • A name/value pair.

  • An IO stream opened for reading.

Argument params should be an Enumerable (method params.map will be called), and is often an array or hash.

First, we set up a request:

_uri = uri.dup
_uri.path ='/posts'
req = Net::HTTP::Post.new(_uri)

Argument params As an Array

When params is an array, each of its elements is a subarray that defines a field; the subarray may contain:

  • One string:

    req.set_form([['foo'], ['bar'], ['baz']])

  • Two strings:

    req.set_form([%w[foo 0], %w[bar 1], %w[baz 2]])

  • When argument enctype (see below) is given as 'multipart/form-data':

    • A string name and an IO stream opened for reading:

      require 'stringio'
req.set_form([['file', StringIO.new('Ruby is cool.')]])

    • A string name, an IO stream opened for reading, and an options hash, which may contain these entries:

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

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

      Example:

      req.set_form([['file', file, {filename: "other-filename.foo"}]]

The various forms may be mixed:

req.set_form(['foo', %w[bar 1], ['file', file]])

Argument params As a Hash

When params is a hash, each of its entries is a name/value pair that defines a field:

  • The name is a string.

  • The value may be:

    • nil.

    • Another string.

    • An IO stream opened for reading (only when argument enctype – see below – is given as 'multipart/form-data').

Examples:

# Nil-valued fields.
req.set_form({'foo' => nil, 'bar' => nil, 'baz' => nil})

# String-valued fields.
req.set_form({'foo' => 0, 'bar' => 1, 'baz' => 2})

# IO-valued field.
require 'stringio'
req.set_form({'file' => StringIO.new('Ruby is cool.')})

# Mixture of fields.
req.set_form({'foo' => nil, 'bar' => 1, 'file' => file})

Optional argument enctype specifies the value to be given to field 'Content-Type', and must be one of:

  • 'application/x-www-form-urlencoded' (the default).

  • 'multipart/form-data'; see RFC 7578.

Optional argument formopt is a hash of options (applicable only when argument enctype is 'multipart/form-data') that may include the following entries:

  • :boundary: The value is the boundary string for the multipart message. If not given, the boundary is a random string. See Boundary.

  • :charset: Value is the character set for the form submission. Field names and values of non-file fields should be encoded with this charset.



928
929
930
931
932
933
934
935
936
937
938
939
940
 
# File 'lib/net/http/header.rb', line 928

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 = '&') ⇒ Object Also known as: form_data=

Sets the request body to a URL-encoded string derived from argument params, and sets request header field 'Content-Type' to 'application/x-www-form-urlencoded'.

The resulting request is suitable for HTTP request POST or PUT.

Argument params must be suitable for use as argument enum to URI.encode_www_form.

With only argument params given, sets the body to a URL-encoded string with the default separator '&':

req = Net::HTTP::Post.new('example.com')

req.set_form_data(q: 'ruby', lang: 'en')
req.body            # => "q=ruby&lang=en"
req['Content-Type'] # => "application/x-www-form-urlencoded"

req.set_form_data([['q', 'ruby'], ['lang', 'en']])
req.body            # => "q=ruby&lang=en"

req.set_form_data(q: ['ruby', 'perl'], lang: 'en')
req.body            # => "q=ruby&q=perl&lang=en"

req.set_form_data([['q', 'ruby'], ['q', 'perl'], ['lang', 'en']])
req.body            # => "q=ruby&q=perl&lang=en"

With string argument sep also given, uses that string as the separator:

req.set_form_data({q: 'ruby', lang: 'en'}, '|')
req.body # => "q=ruby|lang=en"

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



816
817
818
819
820
821
 
# File 'lib/net/http/header.rb', line 816

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

#set_range(r, e = nil) ⇒ Object Also known as: range=

call-seq:

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.



580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
 
# File 'lib/net/http/header.rb', line 580

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

#size ⇒ Object Also known as: length

:nodoc: obsolete



210
211
212
 
# File 'lib/net/http/header.rb', line 210

def size   #:nodoc: obsolete
  @header.size
end

#sub_type ⇒ Object

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"



742
743
744
745
746
747
 
# File 'lib/net/http/header.rb', line 742

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 ⇒ Object

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



481
482
483
 
# File 'lib/net/http/header.rb', line 481

def to_hash
  @header.dup
end

#type_params ⇒ Object

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



757
758
759
760
761
762
763
764
765
766
 
# File 'lib/net/http/header.rb', line 757

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