@node HTTP Headers
@subsection HTTP Headers
-In addition to defining the infrastructure to parse headers, the
-@code{(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 @samp{Accept-Language} with a
-value @samp{en, es;q=0.8}, Guile parses it as follows:
-
-@example
-(parse-header "Accept-Language" "en, es;q=0.8")
-@result{} accept-language
-@result{} ((1000 . "en") (800 . "es"))
-@end example
-
-There are two results, because @code{parse-header} returns two
-values. The first value is a symbol, because the @code{accept-language}
-header is known to Guile and has a parser registered. The format of the
-value for @code{accept-language} headers is defined below, along with
-all other headers defined in the HTTP standard. (If the header were not
-recognized, it and the value would be returned as strings.)
-
-For brevity, the header definitions below are given in the form,
-@var{type} @code{@var{name}}, indicating that values for the header
-@code{@var{name}} will be of the given @var{type}. 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.
-
-@subsubsection HTTP Header Types
-@deftp {HTTP Header Type} Date
-foo
-@end deftp
-
-So for example if you are implementing a
-
-This section describes the
+The @code{(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.
-example? and examples in each, and brief meaning description.
-
To begin with, we should make a few definitions:
@table @dfn
Parsed values for known keys have key-dependent formats. Parsed values
for unknown keys are strings.
+@item 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.
+
@item quality
A number of headers have quality values in them, which are decimal
fractions between zero and one indicating a preference for various kinds
@subsubsection General Headers
-@deftypevr {HTTP Header} KVList cache-control
+@table @code
+@item cache-control
A key-value list of cache-control directives. Known keys are
@code{max-age}, @code{max-stale}, @code{min-fresh},
@code{must-revalidate}, @code{no-cache}, @code{no-store},
If present, parameters to @code{private} and @code{no-cache} are parsed
as lists of header names, represented as symbols if they are known
headers or strings otherwise.
-@end deftypevr
-@deftypevr {HTTP Header} @i{List of Strings} connection
+@item connection
A list of connection tokens. A connection token is a string.
-@end deftypevr
-@deftypevr {HTTP Header} {date} date
+@item date
A SRFI-19 date record.
-@end deftypevr
-@deftypevr {HTTP Header} {Key-Value List} pragma
+@item pragma
A key-value list of pragma directives. @code{no-cache} is the only
known key.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} trailer
+@item trailer
A list of header names. Known header names are parsed to symbols,
otherwise they are left as strings.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} transfer-encoding
+@item transfer-encoding
A param list of transfer codings. @code{chunked} is the only known key.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} upgrade
+@item upgrade
A list of strings.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} via
+@item via
A list of strings. There may be multiple @code{via} headers in ne
message.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} warning
+@item 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 @code{#f} or a SRFI-19 date.
There may be multiple @code{warning} headers in one message.
-@end deftypevr
+@end table
@subsubsection Entity Headers
-@deftypevr {HTTP Header} {tp} allow
+@table @code
+@item allow
A list of methods, as strings. Methods are parsed as strings instead of
@code{parse-http-method} so as to allow for new methods.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} content-encoding
+@item content-encoding
A list of content codings, as strings.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} content-language
+@item content-language
A list of language tags, as strings.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} content-length
+@item content-length
An exact, non-negative integer.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} content-location
+@item content-location
A URI record.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} content-md5
+@item content-md5
A string.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} content-range
+@item content-range
A list of three elements: the symbol @code{bytes}, either the symbol
@code{*} or a pair of integers, indicating the byte rage, and either
@code{*} or an integer, for the instance length.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} content-type
+@item 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.
@code{"text/plain;charset=utf-8"} parses as @code{("text/plain"
("charset" . "utf-8"))}.
-note charset and encoding
-@end deftypevr
-
-@deftypevr {HTTP Header} {tp} expires
+@item expires
A SRFI-19 date.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} last-modified
+@item last-modified
A SRFI-19 date.
-@end deftypevr
+
+@end table
@subsubsection Request Headers
-@deftypevr {HTTP Header} {tp} accept
+@table @code
+@item accept
A param list. Each element in the list indicates one media-range
with accept-params. They only known key is @code{q}, whose value is
parsed as a quality value.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} accept-charset
+@item accept-charset
A quality-list of charsets, as strings.
-charset and encoding
-@end deftypevr
-@deftypevr {HTTP Header} {tp} accept-encoding
+@item accept-encoding
A quality-list of content codings, as strings.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} accept-language
+@item accept-language
A quality-list of languages, as strings.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} authorization
+@item authorization
A string.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} expect
+@item expect
A param list of expectations. The only known key is
@code{100-continue}.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} from
+@item from
A string.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} host
+@item host
A pair of the host, as a string, and the port, as an integer. If no port
is given, port is @code{#f}.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} if-match
+@item if-match
Either the symbol @code{*}, or a list of entity tags (see above).
-@end deftypevr
-@deftypevr {HTTP Header} {tp} if-modified-since
+@item if-modified-since
A SRFI-19 date.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} if-none-match
+@item if-none-match
Either the symbol @code{*}, or a list of entity tags (see above).
-@end deftypevr
-@deftypevr {HTTP Header} {tp} if-range
+@item if-range
Either an entity tag, or a SRFI-19 date.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} if-unmodified-since
+@item if-unmodified-since
A SRFI-19 date.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} max-forwards
+@item max-forwards
An exact non-negative integer.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} proxy-authorization
+@item proxy-authorization
A string.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} range
+@item range
A pair whose car is the symbol @code{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
@code{#f} if not given.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} referer
+@item referer
A URI.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} te
+@item te
A param list of transfer-codings. The only known key is
@code{trailers}.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} user-agent
+@item user-agent
A string.
-@end deftypevr
+@end table
@subsubsection Response Headers
-@deftypevr {HTTP Header} {tp} accept-ranges
+@table @code
+@item accept-ranges
A list of strings.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} age
+@item age
An exact, non-negative integer.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} etag
+@item etag
An entity tag.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} location
+@item location
A URI.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} proxy-authenticate
+@item proxy-authenticate
A string.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} retry-after
+@item retry-after
Either an exact, non-negative integer, or a SRFI-19 date.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} server
+@item server
A string.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} vary
+@item vary
Either the symbol @code{*}, or a list of headers, with known headers
parsed to symbols.
-@end deftypevr
-@deftypevr {HTTP Header} {tp} www-authenticate
-A string. (FIXME)
-@end deftypevr
+@item www-authenticate
+A string.
+@end table
@node Requests
read a request, you may read the body separately, and likewise for
writing requests.
-discussion of charsets and bytes and stuff.
-
@defun build-request [#:method] [#:uri] [#:version] [#:headers] [#:port] [#:meta] [#:validate-headers?]
Construct an HTTP request object. If @var{validate-headers?} is true,
the headers are each run through their respective validators.
information.
@end defun
-Fixme^
-
@defun write-request r port
Write the given HTTP request to @var{port}.
-Return a new request, whose @code{request-port} will continue writing
+Returns a new request, whose @code{request-port} will continue writing
on @var{port}, perhaps using some transfer encoding.
@end defun
Assumes that the request port has ISO-8859-1 encoding, so that the
number of characters to read is the same as the
-@code{request-content-length}. Return @code{#f} if there was no request
+@code{request-content-length}. Returns @code{#f} if there was no request
body.
@end defun
@end defun
@defun read-request-body/bytevector r
-Reads the request body from @var{r}, as a bytevector. Return @code{#f}
+Reads the request body from @var{r}, as a bytevector. Returns @code{#f}
if there was no request body.
@end defun
the headers are each run through their respective validators.
@end defun
-FIXME
@defun extend-response r k v . additional
Extend an HTTP response by setting additional HTTP headers @var{k},
-@var{v}. Return a new HTTP response.
+@var{v}. Returns a new HTTP response.
@end defun
@defun adapt-response-version response version
-Adapt the given response to a different HTTP version. Return a new HTTP
+Adapt the given response to a different HTTP version. Returns a new HTTP
response.
The idea is that many applications might just build a response for the
@defun write-response r port
Write the given HTTP response to @var{port}.
-Return a new response, whose @code{response-port} will continue writing
+Returns a new response, whose @code{response-port} will continue writing
on @var{port}, perhaps using some transfer encoding.
@end defun
Assumes that the response port has ISO-8859-1 encoding, so that the
number of characters to read is the same as the
-@code{response-content-length}. Return @code{#f} if there was no
+@code{response-content-length}. Returns @code{#f} if there was no
response body.
@end defun
@end defun
@defun read-response-body/bytevector r
-Read the response body from @var{r}, as a bytevector. Return @code{#f}
+Reads the response body from @var{r}, as a bytevector. Returns @code{#f}
if there was no response body.
@end defun
and body as its arguments. The handler should return two
values: the response, as a @code{<response>} record from @code{(web
response)}, and the response body as a string, bytevector, or
-@code{#f} if not present. We also allow the response to be simply an
+@code{#f} if not present. We also allow the reponse to be simply an
alist of headers, in which case a default response object is
constructed with those headers.
any access to the impl objects.
@defun open-server impl open-params
-Open a server for the given implementation. Return one value, the new
+Open a server for the given implementation. Returns one value, the new
server object. The implementation's @code{open} procedure is applied to
@var{open-params}, which should be a list.
@end defun
@defun read-client impl server
Read a new client from @var{server}, by applying the implementation's
-@code{read} procedure to the server. If successful, return three
+@code{read} procedure to the server. If successful, returns three
values: an object corresponding to the client, a request object, and the
-request body. If any exception occurs, return @code{#f} for all three
+request body. If any exception occurs, returns @code{#f} for all three
values.
@end defun
@defun serve-one-client handler impl server state
Read one request from @var{server}, call @var{handler} on the request
-and body, and write the response to the client. Return the new state
+and body, and write the response to the client. Returns the new state
produced by the handler procedure.
@end defun
will be used for subsequent requests. In this way a handler can
explicitly manage its state.
-FIXME: elide?
-
The default server implementation is @code{http}, which accepts
@var{open-params} like @code{(#:port 8081)}, among others. See "Web
Server" in the manual, for more information.
the time the arguments are fully parsed, the @code{sxml} local variable
will hold the templated SXML, ready for sending out to the client.
-Also, instead of returning the body as a string, @code{respond} gives a
-procedure, which will be called by the web server to write out the
-response to the client.
+Instead of returning the body as a string, here we give a procedure,
+which will be called by the web server to write out the response to the
+client.
Now, a simple example using this responder, which lays out the incoming
headers in an HTML table.
HCoop / bpt / guile.git / commitdiff