Next: , Previous: HTTP, Up: Web

7.3.3 HTTP Headers

The (web http) module defines parsers and unparsers for all headers defined in the HTTP/1.1 standard. This section describes the parsed format of the various headers.

We cannot describe the function of all of these headers, however, in sufficient detail. The interested reader would do well to download a copy of RFC 2616 and have it on hand.

To begin with, we should make a few definitions:

key-value list
A key-value list is a list of values. Each value may be a string, a symbol, or a pair. Known keys are parsed to symbols; otherwise keys are left as strings. Keys with values are parsed to pairs, the car of which is the symbol or string key, and the cdr is the parsed value. Parsed values for known keys have key-dependent formats. Parsed values for unknown keys are strings.
param list
A param list is a list of key-value lists. When serialized to a string, items in the inner lists are separated by semicolons. Again, known keys are parsed to symbols.
quality
A number of headers have quality values in them, which are decimal fractions between zero and one indicating a preference for various kinds of responses, which the server may choose to heed. Given that only three digits are allowed in the fractional part, Guile parses quality values to integers between 0 and 1000 instead of inexact numbers between 0.0 and 1.0.
quality list
A list of pairs, the car of which is a quality value.
entity tag
A pair, the car of which is an opaque string, and the cdr of which is true iff the entity tag is a “strong” entity tag.
7.3.3.1 General Headers
cache-control
A key-value list of cache-control directives. Known keys are max-age, max-stale, min-fresh, must-revalidate, no-cache, no-store, no-transform, only-if-cached, private, proxy-revalidate, public, and s-maxage.

If present, parameters to max-age, max-stale, min-fresh, and s-maxage are all parsed as non-negative integers.

If present, parameters to private and no-cache are parsed as lists of header names, represented as symbols if they are known headers or strings otherwise.

connection
A list of connection tokens. A connection token is a string.
date
A SRFI-19 date record.
pragma
A key-value list of pragma directives. no-cache is the only known key.
trailer
A list of header names. Known header names are parsed to symbols, otherwise they are left as strings.
transfer-encoding
A param list of transfer codings. chunked is the only known key.
upgrade
A list of strings.
via
A list of strings. There may be multiple via headers in ne message.
warning
A list of warnings. Each warning is a itself a list of four elements: a code, as an exact integer between 0 and 1000, a host as a string, the warning text as a string, and either #f or a SRFI-19 date.

There may be multiple warning headers in one message.

7.3.3.2 Entity Headers
allow
A list of methods, as strings. Methods are parsed as strings instead of parse-http-method so as to allow for new methods.
content-encoding
A list of content codings, as strings.
content-language
A list of language tags, as strings.
content-length
An exact, non-negative integer.
content-location
A URI record.
content-md5
A string.
content-range
A list of three elements: the symbol bytes, either the symbol * or a pair of integers, indicating the byte rage, and either * or an integer, for the instance length.
content-type
A pair, the car of which is the media type as a string, and the cdr is an alist of parameters, with strings as keys and values.

For example, "text/plain" parses as ("text/plain"), and "text/plain;charset=utf-8" parses as ("text/plain" ("charset" . "utf-8")).

expires
A SRFI-19 date.
last-modified
A SRFI-19 date.
7.3.3.3 Request Headers
accept
A param list. Each element in the list indicates one media-range with accept-params. They only known key is q, whose value is parsed as a quality value.
accept-charset
A quality-list of charsets, as strings.
accept-encoding
A quality-list of content codings, as strings.
accept-language
A quality-list of languages, as strings.
authorization
A string.
expect
A param list of expectations. The only known key is 100-continue.
from
A string.
host
A pair of the host, as a string, and the port, as an integer. If no port is given, port is #f.
if-match
Either the symbol *, or a list of entity tags (see above).
if-modified-since
A SRFI-19 date.
if-none-match
Either the symbol *, or a list of entity tags (see above).
if-range
Either an entity tag, or a SRFI-19 date.
if-unmodified-since
A SRFI-19 date.
max-forwards
An exact non-negative integer.
proxy-authorization
A string.
range
A pair whose car is the symbol bytes, and whose cdr is a list of pairs. Each element of the cdr indicates a range; the car is the first byte position and the cdr is the last byte position, as integers, or #f if not given.
referer
A URI.
te
A param list of transfer-codings. The only known key is trailers.
user-agent
A string.
7.3.3.4 Response Headers
accept-ranges
A list of strings.
age
An exact, non-negative integer.
etag
An entity tag.
location
A URI.
proxy-authenticate
A string.
retry-after
Either an exact, non-negative integer, or a SRFI-19 date.
server
A string.
vary
Either the symbol *, or a list of headers, with known headers parsed to symbols.
www-authenticate
A string.