Class: FTW::HTTP::Headers

Inherits:
Object
  • Object
show all
Includes:
Enumerable, CRLF
Defined in:
lib/ftw/http/headers.rb

Overview

HTTP Headers

See RFC2616 section 4.2: <tools.ietf.org/html/rfc2616#section-4.2>

Section 14.44 says Field Names in the header are case-insensitive, so this library always forces field names to be lowercase. This includes get() calls.

headers.set("HELLO", "world")
headers.get("hello")   # ===> "world"

Constant Summary

Constants included from CRLF

CRLF::CRLF

Instance Method Summary collapse

Instance Method Details

#add(field, value) ⇒ Object

Add a header field with a value.

If this field already exists, another value is added. If this field does not already exist, it is set.



50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/ftw/http/headers.rb', line 50

def add(field, value)
  field = field.downcase
  if @headers.include?(field)
    if @headers[field].is_a?(Array)
      @headers[field] << value
    else
      @headers[field] = [@headers[field], value]
    end
  else
    set(field, value)
  end
end

#each(&block) ⇒ Object

Iterate over headers. Given to the block are two arguments, the field name and the field value. For fields with multiple values, you will receive that same field name multiple times, like:

yield "Host", "www.example.com"
yield "X-Forwarded-For", "1.2.3.4"
yield "X-Forwarded-For", "1.2.3.5"



117
118
119
120
121
122
123
124
125
 
# File 'lib/ftw/http/headers.rb', line 117

def each(&block)
  @headers.each do |field_name, field_value|
    if field_value.is_a?(Array)
      field_value.map { |value| yield field_name, value }
    else
      yield field_name, field_value
    end
  end
end

#get(field) ⇒ String, ... Also known as: []

Get a field value.

Returns:

  • (String) —

    if there is only one value for this field

  • (Array) —

    if there are multiple values for this field

  • (nil) —

    if there are no values for this field



104
105
106
107
 
# File 'lib/ftw/http/headers.rb', line 104

def get(field)
  field = field.downcase
  return @headers[field]
end

#include?(field) ⇒ true, false

Does this header include this field name?

Returns:

  • (true, false) 


42
43
44
 
# File 'lib/ftw/http/headers.rb', line 42

def include?(field)
  @headers.include?(field.downcase)
end

#inspect ⇒ Object

Inspect this object



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

def inspect
  return "#{self.class.name} <#{to_hash.inspect}>"
end

#remove(field, value = nil) ⇒ Object

Removes a header entry. If the header has multiple values (like X-Forwarded-For can), you can delete a specific entry by passing the value of the header field to remove.

# Remove all X-Forwarded-For entries
headers.remove("X-Forwarded-For") 
# Remove a specific X-Forwarded-For entry
headers.remove("X-Forwarded-For", "1.2.3.4")

  • If you remove a field that doesn’t exist, no error will occur.

  • If you remove a field value that doesn’t exist, no error will occur.

  • If you remove a field value that is the only value, it is the same as removing that field by name.



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/ftw/http/headers.rb', line 76

def remove(field, value=nil)
  field = field.downcase
  if value.nil?
    # no value, given, remove the entire field.
    @headers.delete(field)
  else
    field_value = @headers[field]
    if field_value.is_a?(Array)
      # remove a specific value
      field_value.delete(value)
      # Down to a String again if there's only one value.
      if field_value.size == 1
        set(field, field_value.first)
      end
    else
      # Remove this field if the value matches
      if field_value == value
        remove(field)
      end
    end
  end
end

#set(field, value) ⇒ Object Also known as: []=

Set a header field to a specific value. Any existing value(s) for this field are destroyed.

Parameters:

  • the (String) —

    name of the field to set

  • the (String or Array) —

    value of the field to set



34
35
36
 
# File 'lib/ftw/http/headers.rb', line 34

def set(field, value)
  @headers[field.downcase] = value
end

#to_hash ⇒ Hash

Returns String keys and values of String (field value) or Array (of String field values).

Returns:

  • (Hash) —

    String keys and values of String (field value) or Array (of String field values)



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

def to_hash
  return @headers
end

#to_s ⇒ Object

Serialize this object to a string in HTTP format described by RFC2616

Example:

headers = FTW::HTTP::Headers.new
headers.add("Host", "example.com")
headers.add("X-Forwarded-For", "1.2.3.4")
headers.add("X-Forwarded-For", "192.168.0.1")
puts headers.to_s

# Result
Host: example.com
X-Forwarded-For: 1.2.3.4
X-Forwarded-For: 192.168.0.1



146
147
148
 
# File 'lib/ftw/http/headers.rb', line 146

def to_s
  return @headers.collect { |name, value| "#{name}: #{value}" }.join(CRLF) + CRLF
end