Class: HTTP::Headers

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable
Defined in:
lib/http/headers.rb,
lib/http/headers/known.rb,
lib/http/headers/mixin.rb

Overview

HTTP Headers container.

Defined Under Namespace

Modules: Mixin

Constant Summary collapse

CANONICAL_NAME_RE =

Matches HTTP header names when in "Canonical-Http-Format"

/^[A-Z][a-z]*(?:-[A-Z][a-z]*)*$/
COMPLIANT_NAME_RE =

Matches valid header field name according to RFC.

See Also:

/^[A-Za-z0-9!#\$%&'*+\-.^_`|~]+$/
ACCEPT =

Content-Types that are acceptable for the response.

"Accept".freeze
AGE =

The age the object has been in a proxy cache in seconds.

"Age".freeze
AUTHORIZATION =

Authentication credentials for HTTP authentication.

"Authorization".freeze
CACHE_CONTROL =

Used to specify directives that must be obeyed by all caching mechanisms along the request-response chain.

"Cache-Control".freeze

"Cookie".freeze
CONNECTION =

Control options for the current connection and list of hop-by-hop request fields.

"Connection".freeze
CONTENT_LENGTH =

The length of the request body in octets (8-bit bytes).

"Content-Length".freeze
CONTENT_TYPE =

The MIME type of the body of the request (used with POST and PUT requests).

"Content-Type".freeze
DATE =

The date and time that the message was sent (in "HTTP-date" format as defined by RFC 7231 Date/Time Formats).

"Date".freeze
ETAG =

An identifier for a specific version of a resource, often a message digest.

"ETag".freeze
EXPIRES =

Gives the date/time after which the response is considered stale (in "HTTP-date" format as defined by RFC 7231).

"Expires".freeze
HOST =

The domain name of the server (for virtual hosting), and the TCP port number on which the server is listening. The port number may be omitted if the port is the standard port for the service requested.

"Host".freeze
IF_MODIFIED_SINCE =

Allows a 304 Not Modified to be returned if content is unchanged.

"If-Modified-Since".freeze
IF_NONE_MATCH =

Allows a 304 Not Modified to be returned if content is unchanged.

"If-None-Match".freeze
LAST_MODIFIED =

The last modified date for the requested object (in "HTTP-date" format as defined by RFC 7231).

"Last-Modified".freeze
LOCATION =

Used in redirection, or when a new resource has been created.

"Location".freeze
PROXY_AUTHORIZATION =

Authorization credentials for connecting to a proxy.

"Proxy-Authorization".freeze

"Set-Cookie".freeze
TRANSFER_ENCODING =

The form of encoding used to safely transfer the entity to the user. Currently defined methods are: chunked, compress, deflate, gzip, identity.

"Transfer-Encoding".freeze
USER_AGENT =

The user agent string of the user agent.

"User-Agent".freeze
VARY =

Tells downstream proxies how to match future request headers to decide whether the cached response can be used rather than requesting a fresh one from the origin server.

"Vary".freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Headers

Class constructor.



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

def initialize
  @pile = []
end

Class Method Details

.coerce(object) ⇒ Headers Also known as: []

Coerces given object into Headers.

Parameters:

Returns:

Raises:

  • (Error) —

    if object can't be coerced



169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/http/headers.rb', line 169

def coerce(object)
  unless object.is_a? self
    object = case
             when object.respond_to?(:to_hash) then object.to_hash
             when object.respond_to?(:to_h)    then object.to_h
             when object.respond_to?(:to_a)    then object.to_a
             else raise Error, "Can't coerce #{object.inspect} to Headers"
             end
  end

  headers = new
  object.each { |k, v| headers.add k, v }
  headers
end

Instance Method Details

#==(other) ⇒ Boolean

Compares headers to another Headers or Array of key/value pairs

Returns:

  • (Boolean) 


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

def ==(other)
  return false unless other.respond_to? :to_a
  @pile == other.to_a
end

#[](name) ⇒ nil, ...

Smart version of #get.

Returns:

  • (nil) —

    if header was not set

  • (String) —

    if header has exactly one value

  • (Array<String>) —

    if header has more than one value



68
69
70
71
72
73
74
75
76
 
# File 'lib/http/headers.rb', line 68

def [](name)
  values = get(name)

  case values.count
  when 0 then nil
  when 1 then values.first
  else        values
  end
end

#add(name, value) ⇒ void

This method returns an undefined value.

Appends header.

Parameters:

  • name (#to_s) —

    header name

  • value (Array<#to_s>, #to_s) —

    header value(s) to be appended



50
51
52
53
 
# File 'lib/http/headers.rb', line 50

def add(name, value)
  name = normalize_header name.to_s
  Array(value).each { |v| @pile << [name, v.to_s] }
end

#delete(name) ⇒ void

This method returns an undefined value.

Removes header.

Parameters:

  • name (#to_s) —

    header name



40
41
42
43
 
# File 'lib/http/headers.rb', line 40

def delete(name)
  name = normalize_header name.to_s
  @pile.delete_if { |k, _| k == name }
end

#each ⇒ Enumerator, Headers

Calls the given block once for each key/value pair in headers container.

Returns:

  • (Enumerator) —

    if no block given

  • (Headers) —

    self-reference



119
120
121
122
123
 
# File 'lib/http/headers.rb', line 119

def each
  return to_enum(__method__) unless block_given?
  @pile.each { |arr| yield(arr) }
  self
end

#empty? ⇒ Boolean

Returns true if self has no key/value pairs

Returns:

  • (Boolean) 


129
 
# File 'lib/http/headers.rb', line 129

def_delegator :@pile, :empty?

#get(name) ⇒ Array<String>

Returns list of header values if any.

Returns:

  • (Array<String>) 


58
59
60
61
 
# File 'lib/http/headers.rb', line 58

def get(name)
  name = normalize_header name.to_s
  @pile.select { |k, _| k == name }.map { |_, v| v }
end

#hash ⇒ Fixnum

Compute a hash-code for this headers container. Two conatiners with the same content will have the same hash code.

Returns:

  • (Fixnum)

See Also:



137
 
# File 'lib/http/headers.rb', line 137

def_delegator :@pile, :hash

#initialize_copy(orig) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Properly clones internal key/value storage.



142
143
144
145
 
# File 'lib/http/headers.rb', line 142

def initialize_copy(orig)
  super
  @pile = to_a
end

#inspect ⇒ String

Returns human-readable representation of self instance.

Returns:

  • (String) 


96
97
98
 
# File 'lib/http/headers.rb', line 96

def inspect
  "#<#{self.class} #{to_h.inspect}>"
end

#keys ⇒ Array<String>

Returns list of header names.

Returns:

  • (Array<String>) 


103
104
105
 
# File 'lib/http/headers.rb', line 103

def keys
  @pile.map { |k, _| k }.uniq
end

#merge(other) ⇒ Headers

Returns new instance with other headers merged in.

Returns:

See Also:



159
160
161
 
# File 'lib/http/headers.rb', line 159

def merge(other)
  dup.tap { |dupped| dupped.merge! other }
end

#merge!(other) ⇒ void

This method returns an undefined value.

Merges other headers into self.

See Also:



151
152
153
 
# File 'lib/http/headers.rb', line 151

def merge!(other)
  self.class.coerce(other).to_h.each { |name, values| set name, values }
end

#set(name, value) ⇒ void Also known as: []=

This method returns an undefined value.

Sets header.

Parameters:

  • name (#to_s) —

    header name

  • value (Array<#to_s>, #to_s) —

    header value(s) to be appended



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

def set(name, value)
  delete(name)
  add(name, value)
end

#to_a ⇒ Array<[String, String]>

Returns headers key/value pairs.

Returns:

  • (Array<[String, String]>) 


89
90
91
 
# File 'lib/http/headers.rb', line 89

def to_a
  @pile.map { |pair| pair.map(&:dup) }
end

#to_h ⇒ Hash Also known as: to_hash

Returns Rack-compatible headers Hash

Returns:

  • (Hash) 


81
82
83
 
# File 'lib/http/headers.rb', line 81

def to_h
  Hash[keys.map { |k| [k, self[k]] }]
end