Module: Net::HTTPHeader

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

Overview

frozen_string_literal: false 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.

Instance Method Summary collapse

Instance Method Details

#[](key) ⇒ Object

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



30
31
32
33
 
# File 'lib/net/http/header.rb', line 30

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

#[]=(key, val) ⇒ Object

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



36
37
38
39
40
41
42
 
# File 'lib/net/http/header.rb', line 36

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

#add_field(key, val) ⇒ Object

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



59
60
61
62
63
64
65
 
# File 'lib/net/http/header.rb', line 59

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

Set the Authorization: header for “Basic” authorization.



420
421
422
 
# File 'lib/net/http/header.rb', line 420

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

#chunked? ⇒ Boolean

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.

Returns:

  • (Boolean) 


281
282
283
284
285
 
# File 'lib/net/http/header.rb', line 281

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:

  • (Boolean) 


434
435
436
437
 
# File 'lib/net/http/header.rb', line 434

def connection_close?
  tokens(@header['connection']).include?('close') or
  tokens(@header['proxy-connection']).include?('close')
end

#connection_keep_alive? ⇒ Boolean

Returns:

  • (Boolean) 


439
440
441
442
 
# File 'lib/net/http/header.rb', line 439

def connection_keep_alive?
  tokens(@header['connection']).include?('keep-alive') or
  tokens(@header['proxy-connection']).include?('keep-alive')
end

#content_length ⇒ Object

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



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

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 



269
270
271
272
273
274
275
 
# File 'lib/net/http/header.rb', line 269

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 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.



291
292
293
294
295
296
 
# File 'lib/net/http/header.rb', line 291

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

#content_type ⇒ Object

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



306
307
308
309
310
311
312
 
# File 'lib/net/http/header.rb', line 306

def content_type
  return nil unless main_type()
  if sub_type()
  then "#{main_type()}/#{sub_type()}"
  else main_type()
  end
end

#delete(key) ⇒ Object

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



140
141
142
 
# File 'lib/net/http/header.rb', line 140

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

#each_capitalized ⇒ Object Also known as: canonical_each

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.



163
164
165
166
167
168
 
# File 'lib/net/http/header.rb', line 163

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

#each_capitalized_name ⇒ Object

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.



123
124
125
126
127
128
 
# File 'lib/net/http/header.rb', line 123

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 ⇒ Object Also known as: each

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



99
100
101
102
103
104
 
# File 'lib/net/http/header.rb', line 99

def each_header   #:yield: +key+, +value+
  block_given? or return enum_for(__method__)
  @header.each do |k,va|
    yield k, va.join(', ')
  end
end

#each_name(&block) ⇒ Object Also known as: each_key

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



110
111
112
113
 
# File 'lib/net/http/header.rb', line 110

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

#each_value ⇒ Object

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



132
133
134
135
136
137
 
# File 'lib/net/http/header.rb', line 132

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, &block) ⇒ Object

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



87
88
89
90
 
# File 'lib/net/http/header.rb', line 87

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

#get_fields(key) ⇒ Object

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"



78
79
80
81
 
# File 'lib/net/http/header.rb', line 78

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

#initialize_http_header(initheader) ⇒ Object 



13
14
15
16
17
18
19
20
 
# File 'lib/net/http/header.rb', line 13

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

true if key header exists.

Returns:

  • (Boolean) 


145
146
147
 
# File 'lib/net/http/header.rb', line 145

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

#main_type ⇒ Object

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



316
317
318
319
 
# File 'lib/net/http/header.rb', line 316

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

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



425
426
427
 
# File 'lib/net/http/header.rb', line 425

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

#range ⇒ Object

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



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/net/http/header.rb', line 179

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

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



299
300
301
302
 
# File 'lib/net/http/header.rb', line 299

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 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. => ‘iso-8859-1’



349
350
351
 
# File 'lib/net/http/header.rb', line 349

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

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. formopt 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



405
406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/net/http/header.rb', line 405

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=

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



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

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=

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



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/net/http/header.rb', line 229

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



22
23
24
 
# File 'lib/net/http/header.rb', line 22

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

#sub_type ⇒ Object

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”).



324
325
326
327
328
329
 
# File 'lib/net/http/header.rb', line 324

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 consisting of header names and array of values. e.g. => [“private”],

"content-type" => ["text/html"],
"date" => ["Wed, 22 Jun 2005 22:11:50 GMT"]



154
155
156
 
# File 'lib/net/http/header.rb', line 154

def to_hash
  @header.dup
end

#type_params ⇒ Object

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 => ‘EUC-JP’



334
335
336
337
338
339
340
341
342
343
 
# File 'lib/net/http/header.rb', line 334

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