Warning: This is the manual of the legacy Guile 2.2 series. You may want to read the manual of the current stable series instead.
Next: Transfer Codings, Previous: HTTP, Up: Web [Contents][Index]
In addition to defining the infrastructure to parse headers, the
(web http) module defines specific parsers and unparsers for all
headers defined in the HTTP/1.1 standard.
For example, if you receive a header named ‘Accept-Language’ with a value ‘en, es;q=0.8’, Guile parses it as a quality list (defined below):
(parse-header 'accept-language "en, es;q=0.8") ⇒ ((1000 . "en") (800 . "es"))
The format of the value for ‘Accept-Language’ headers is defined below, along with all other headers defined in the HTTP standard. (If the header were unknown, the value would have been returned as a string.)
For brevity, the header definitions below are given in the form,
Type name, indicating that values for the header
name will be of the given Type. Since Guile
internally treats header names in lower case, in this document we give
types title-cased names. A short description of the each header’s
purpose and an example follow.
For full details on the meanings of all of these headers, see the HTTP 1.1 standard, RFC 2616.
Here we define the types that are used below, when defining headers.
A SRFI-19 date.
A list whose elements are keys or key-value pairs. Keys are parsed to symbols. Values are strings by default. Non-string values are the exception, and are mentioned explicitly below, as appropriate.
A list of strings.
An exact integer between 0 and 1000. Qualities are used to express preference, given multiple options. An option with a quality of 870, for example, is preferred over an option with quality 500.
(Qualities are written out over the wire as numbers between 0.0 and 1.0, but since the standard only allows three digits after the decimal, it’s equivalent to integers between 0 and 1000, so that’s what Guile uses.)
A quality list: a list of pairs, the car of which is a quality, and the cdr a string. Used to express a list of options, along with their qualities.
An entity tag, represented as a pair. The car of the pair is an opaque
string, and the cdr is #t if the entity tag is a “strong” entity
tag, and #f otherwise.
General HTTP headers may be present in any HTTP message.
A key-value list of cache-control directives. See RFC 2616, for more details.
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, as symbols.
(parse-header 'cache-control "no-cache,no-store" ⇒ (no-cache no-store) (parse-header 'cache-control "no-cache=\"Authorization,Date\",no-store" ⇒ ((no-cache . (authorization date)) no-store) (parse-header 'cache-control "no-cache=\"Authorization,Date\",max-age=10" ⇒ ((no-cache . (authorization date)) (max-age . 10))
A list of header names that apply only to this HTTP connection, as symbols. Additionally, the symbol ‘close’ may be present, to indicate that the server should close the connection after responding to the request.
(parse-header 'connection "close") ⇒ (close)
The date that a given HTTP message was originated.
(parse-header 'date "Tue, 15 Nov 1994 08:12:31 GMT") ⇒ #<date ...>
A key-value list of implementation-specific directives.
(parse-header 'pragma "no-cache, broccoli=tasty") ⇒ (no-cache (broccoli . "tasty"))
A list of header names which will appear after the message body, instead of with the message headers.
(parse-header 'trailer "ETag") ⇒ (etag)
A list of transfer codings, expressed as key-value lists. The only
transfer coding defined by the specification is chunked.
(parse-header 'transfer-encoding "chunked") ⇒ ((chunked))
A list of strings, indicating additional protocols that a server could use in response to a request.
(parse-header 'upgrade "WebSocket")
⇒ ("WebSocket")
FIXME: parse out more fully?
A list of strings, indicating the protocol versions and hosts of
intermediate servers and proxies. There may be multiple via
headers in one message.
(parse-header 'via "1.0 venus, 1.1 mars")
⇒ ("1.0 venus" "1.1 mars")
A list of warnings given by a server or intermediate proxy. 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.
(parse-header 'warning "123 foo \"core breach imminent\"") ⇒ ((123 "foo" "core-breach imminent" #f))
Entity headers may be present in any HTTP message, and refer to the resource referenced in the HTTP request or response.
A list of allowed methods on a given resource, as symbols.
(parse-header 'allow "GET, HEAD") ⇒ (GET HEAD)
A list of content codings, as symbols.
(parse-header 'content-encoding "gzip") ⇒ (gzip)
The languages that a resource is in, as strings.
(parse-header 'content-language "en")
⇒ ("en")
The number of bytes in a resource, as an exact, non-negative integer.
(parse-header 'content-length "300") ⇒ 300
The canonical URI for a resource, in the case that it is also accessible from a different URI.
(parse-header 'content-location "http://example.com/foo") ⇒ #<<uri> ...>
The MD5 digest of a resource.
(parse-header 'content-md5 "ffaea1a79810785575e29e2bd45e2fa5") ⇒ "ffaea1a79810785575e29e2bd45e2fa5"
A range specification, as 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. Used to indicate that a response only includes part of
a resource.
(parse-header 'content-range "bytes 10-20/*") ⇒ (bytes (10 . 20) *)
The MIME type of a resource, as a symbol, along with any parameters.
(parse-header 'content-type "text/plain") ⇒ (text/plain) (parse-header 'content-type "text/plain;charset=utf-8") ⇒ (text/plain (charset . "utf-8"))
Note that the charset parameter is something of a misnomer, and
the HTTP specification admits this. It specifies the encoding of
the characters, not the character set.
The date/time after which the resource given in a response is considered stale.
(parse-header 'expires "Tue, 15 Nov 1994 08:12:31 GMT") ⇒ #<date ...>
The date/time on which the resource given in a response was last modified.
(parse-header 'expires "Tue, 15 Nov 1994 08:12:31 GMT") ⇒ #<date ...>
Request headers may only appear in an HTTP request, not in a response.
A list of preferred media types for a response. Each element of the
list is itself a list, in the same format as content-type.
(parse-header 'accept "text/html,text/plain;charset=utf-8") ⇒ ((text/html) (text/plain (charset . "utf-8")))
Preference is expressed with quality values:
(parse-header 'accept "text/html;q=0.8,text/plain;q=0.6") ⇒ ((text/html (q . 800)) (text/plain (q . 600)))
A quality list of acceptable charsets. Note again that what HTTP calls a “charset” is what Guile calls a “character encoding”.
(parse-header 'accept-charset "iso-8859-5, unicode-1-1;q=0.8") ⇒ ((1000 . "iso-8859-5") (800 . "unicode-1-1"))
A quality list of acceptable content codings.
(parse-header 'accept-encoding "gzip,identity=0.8") ⇒ ((1000 . "gzip") (800 . "identity"))
A quality list of acceptable languages.
(parse-header 'accept-language "cn,en=0.75") ⇒ ((1000 . "cn") (750 . "en"))
Authorization credentials. The car of the pair indicates the
authentication scheme, like basic. For basic authentication, the
cdr of the pair will be the base64-encoded ‘user:pass’
string. For other authentication schemes, like digest, the cdr
will be a key-value list of credentials.
(parse-header 'authorization "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" ⇒ (basic . "QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
A list of expectations that a client has of a server. The expectations are key-value lists.
(parse-header 'expect "100-continue") ⇒ ((100-continue))
The email address of a user making an HTTP request.
(parse-header 'from "bob@example.com") ⇒ "bob@example.com"
The host for the resource being requested, as a hostname-port pair. If
no port is given, the port is #f.
(parse-header 'host "gnu.org:80")
⇒ ("gnu.org" . 80)
(parse-header 'host "gnu.org")
⇒ ("gnu.org" . #f)
A set of etags, indicating that the request should proceed if and only
if the etag of the resource is in that set. Either the symbol *,
indicating any etag, or a list of entity tags.
(parse-header 'if-match "*")
⇒ *
(parse-header 'if-match "asdfadf")
⇒ (("asdfadf" . #t))
(parse-header 'if-match W/"asdfadf")
⇒ (("asdfadf" . #f))
Indicates that a response should proceed if and only if the resource has been modified since the given date.
(parse-header 'if-modified-since "Tue, 15 Nov 1994 08:12:31 GMT") ⇒ #<date ...>
A set of etags, indicating that the request should proceed if and only
if the etag of the resource is not in the set. Either the symbol
*, indicating any etag, or a list of entity tags.
(parse-header 'if-none-match "*") ⇒ *
Indicates that the range request should proceed if and only if the resource matches a modification date or an etag. Either an entity tag, or a SRFI-19 date.
(parse-header 'if-range "\"original-etag\"")
⇒ ("original-etag" . #t)
Indicates that a response should proceed if and only if the resource has not been modified since the given date.
(parse-header 'if-not-modified-since "Tue, 15 Nov 1994 08:12:31 GMT") ⇒ #<date ...>
The maximum number of proxy or gateway hops that a request should be subject to.
(parse-header 'max-forwards "10") ⇒ 10
Authorization credentials for a proxy connection. See the documentation
for authorization above for more information on the format.
(parse-header 'proxy-authorization "Digest foo=bar,baz=qux" ⇒ (digest (foo . "bar") (baz . "qux"))
A range request, indicating that the client wants only part of a
resource. The car of the pair is the symbol bytes, and the 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.
(parse-header 'range "bytes=10-30,50-") ⇒ (bytes (10 . 30) (50 . #f))
The URI of the resource that referred the user to this resource. The name of the header is a misspelling, but we are stuck with it.
(parse-header 'referer "http://www.gnu.org/") ⇒ #<uri ...>
A list of transfer codings, expressed as key-value lists. A common
transfer coding is trailers.
(parse-header 'te "trailers") ⇒ ((trailers))
A string indicating the user agent making the request. The specification defines a structured format for this header, but it is widely disregarded, so Guile does not attempt to parse strictly.
(parse-header 'user-agent "Mozilla/5.0") ⇒ "Mozilla/5.0"
A list of range units that the server supports, as symbols.
(parse-header 'accept-ranges "bytes") ⇒ (bytes)
The age of a cached response, in seconds.
(parse-header 'age "3600") ⇒ 3600
The entity-tag of the resource.
(parse-header 'etag "\"foo\"")
⇒ ("foo" . #t)
A URI reference on which a request may be completed. Used in combination with a redirecting status code to perform client-side redirection.
(parse-header 'location "http://example.com/other") ⇒ #<uri ...>
A list of challenges to a proxy, indicating the need for authentication.
(parse-header 'proxy-authenticate "Basic realm=\"foo\"") ⇒ ((basic (realm . "foo")))
Used in combination with a server-busy status code, like 503, to indicate that a client should retry later. Either a number of seconds, or a date.
(parse-header 'retry-after "60") ⇒ 60
A string identifying the server.
(parse-header 'server "My first web server") ⇒ "My first web server"
A set of request headers that were used in computing this response.
Used to indicate that server-side content negotiation was performed, for
example in response to the accept-language header. Can also be
the symbol *, indicating that all headers were considered.
(parse-header 'vary "Accept-Language, Accept") ⇒ (accept-language accept)
A list of challenges to a user, indicating the need for authentication.
(parse-header 'www-authenticate "Basic realm=\"foo\"") ⇒ ((basic (realm . "foo")))
Next: Transfer Codings, Previous: HTTP, Up: Web [Contents][Index]