Helpers to ease handling of headers

[lfcipriani]

Users must have a easy way to use the raw or converted to ruby objects values of the request or response headers specified in the RFC [1, 2].

• The user could access the header via a Hash object for raw values, the keys of this Hash should be compliant with HTTP RFC (capitalize first letter, splitting with hyphen, etc). Ex.: headers["Accept-Encoding"]
• The user could also access via a helper method (lowercase and subst hyphen by underline pattern) the ruby object for special values, such as date, cache-control, etc. Ex.: headers.accept_encoding
• The user could check for header existence with headers.accept_encoding?
• The user could also retrieve the raw values with headers.accept_encoding!

Only RFC specified headers are accessed by these helpers, extensions should be available only by the Hash.

For complex values, the implementation should do a lazy instantiation of the objects involved.

For value types, check [3, 4]. The lists below shows what value a header will get after converting from raw value. Some of the headers will be improved on later milestones (check "improve later" headers, below):

General Headers Types

general-header = Cache-Control            ;  check [5, 6]
                  | Connection               ;  token (1*<any CHAR except CTLs or separators>) > string
                  | Date                     ; HTTP-date [7]
                  | Pragma                   ; token > string
                  | Trailer                  ; #field-name > string
                  | Transfer-Encoding        ; #transfer-coding > string (improve later)
                  | Upgrade                  ; token > string
                  | Via                      ;  1#( received-protocol received-by [ comment ] ) > string (improve later)
                  | Warning                  ; 1#warning-value > Object with code, agent, text, [date]

Entity Headers Types

entity-header  = Allow                    ; #Method > string (normalization to all caps)
                  | Content-Encoding         ; 1#content-coding > string (improve later)
                  | Content-Language         ;  1#language-tag > array of langs
                  | Content-Length           ;  Integer
                  | Content-Location         ;  ( absoluteURI | relativeURI ) > Object uri
                  | Content-MD5              ;  <base64 of 128 bit MD5 digest as per RFC 1864> > string (maybe provide helper for that)
                  | Content-Range            ;  content-range-spec (see Range, below) > string (improve later)
                  | Content-Type             ;  media-type [9] > Object mediatype, charset
                  | Expires                  ;  HTTP-date [7]
                  | Last-Modified            ;  HTTP-date [7]

Request Headers Types

request-header = Accept                   ; #( media-range [ accept-params ] ) > Object
                  | Accept-Charset           ; 1#( ( charset | "*" )[ ";" "q" "=" qvalue ] ) > Object
                  | Accept-Encoding          ;  1#( codings [ ";" "q" "=" qvalue ] ) > Object
                  | Accept-Language          ; 1#( language-range [ ";" "q" "=" qvalue ] ) > Object
                  | Authorization            ; Object? Gem? Middleware? (improve later) [8]
                  | Expect                   ; 1#expectation > string (improve later)
                  | From                     ; mailbox > string (maybe improve later)
                  | Host                     ;  HTTP URL (sect 3.2.2) > Object uri
                  | If-Match                 ; entity-tag (sect 3.11) > quoted string (maybe object)
                  | If-Modified-Since        ;  HTTP-date [7]
                  | If-None-Match            ; entity-tag (sect 3.11) > quoted string (maybe object)
                  | If-Range                 ;  HTTP-date [7] | entity-tag
                  | If-Unmodified-Since      ;  HTTP-date [7]
                  | Max-Forwards             ; Integer
                  | Proxy-Authorization      ;  Object? Gem? Middleware? (improve later) [8]
                  | Range                    ; byte-ranges-specifier | ranges-specifier > string (improve later)
                  | Referer                  ;  absoluteURI | relativeURI > Object URI
                  | TE                       ;  #( t-codings ) > string (improve later)
                  | User-Agent               ;  1*( product | comment ) > string (improve later [wurfl?])

Response Types

response-header = Accept-Ranges           ; 1#range-unit | "none" > string (maybe improve later)
                   | Age                     ; Integer
                   | ETag                    ; entity-tag (sect 3.11) > quoted string (maybe object)
                   | Location                ; absoluteURI > object uri
                   | Proxy-Authenticate      ; 1#challenge > string (improve later)
                   | Retry-After             ; HTTP-date | delta-seconds (Integer)
                   | Server                  ;  1*( product | comment ) > string (improve later)
                   | Vary                    ;   "*" | 1#field-name > string (maybe improve later)
                   | WWW-Authenticate        ; 1#challenge > string (improve later)

[1] http://www.w3.org/Protocols/rfc2616/rfc2616.html
[2] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14
[3] http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2
[4] http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3
[5] https://github.com/abril/cachebag/blob/master/lib/cachebag/cache_control.rb
[6] https://github.com/abril/cachebag/blob/master/test/cachebag/cache_control_test.rb
[7] http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1
[8] http://www.ietf.org/rfc/rfc2617.txt
[9] http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7

[rogerleite]

Response headers OK.
Request headers is pending.