The initial motivation for including web functionality in Guile, rather than rely on an external package, was to establish a standard base on which people can share code. To that end, we continue the focus on data types by providing a number of low-level parsers and unparsers for elements of the HTTP protocol.
If you are want to skip the low-level details for now and move on to web pages, see Web Client, and see Web Server. Otherwise, load the HTTP module, and read on.
(use-modules (web http))
The focus of the (web http)
module is to parse and unparse
standard HTTP headers, representing them to Guile as native data
structures. For example, a Date:
header will be represented as a
SRFI-19 date record (see SRFI-19 - Time/Date Library), rather than as a string.
Guile tries to follow RFCs fairly strictly—the road to perdition being paved with compatibility hacks—though some allowances are made for not-too-divergent texts.
Header names are represented as lower-case symbols.
Parse name to a symbolic header name.
Return the string form for the header named sym.
For example:
(string->header "Content-Length") ⇒ content-length (header->string 'content-length) ⇒ "Content-Length" (string->header "FOO") ⇒ foo (header->string 'foo) ⇒ "Foo"
Guile keeps a registry of known headers, their string names, and some parsing and serialization procedures. If a header is unknown, its string name is simply its symbol name in title-case.
Return #t
if sym is a known header, with associated
parsers and serialization procedures, or #f
otherwise.
Return the value parser for headers named sym. The result is a procedure that takes one argument, a string, and returns the parsed value. If the header isn’t known to Guile, a default parser is returned that passes through the string unchanged.
Return a predicate which returns #t
if the given value is valid
for headers named sym. The default validator for unknown headers
is string?
.
Return a procedure that writes values for headers named sym to a
port. The resulting procedure takes two arguments: a value and a port.
The default writer is display
.
For more on the set of headers that Guile knows about out of the box,
see HTTP Headers. To add your own, use the declare-header!
procedure:
#f
] ¶Declare a parser, validator, and writer for a given header.
For example, let’s say you are running a web server behind some sort of
proxy, and your proxy adds an X-Client-Address
header, indicating
the IPv4 address of the original client. You would like for the HTTP
request record to parse out this header to a Scheme value, instead of
leaving it as a string. You could register this header with Guile’s
HTTP stack like this:
(declare-header! "X-Client-Address" (lambda (str) (inet-pton AF_INET str)) (lambda (ip) (and (integer? ip) (exact? ip) (<= 0 ip #xffffffff))) (lambda (ip port) (display (inet-ntop AF_INET ip) port)))
A specialised version of declare-header!
for the case in which
you want a header’s value to be returned/written “as-is”.
Return a true value if val is a valid Scheme value for the header
with name sym, or #f
otherwise.
Now that we have a generic interface for reading and writing headers, we do just that.
Read one HTTP header from port. Return two values: the header name and the parsed Scheme value. May raise an exception if the header was known but the value was invalid.
Returns the end-of-file object for both values if the end of the message body was reached (i.e., a blank line).
Parse val, a string, with the parser for the header named name. Returns the parsed value.
Write the given header name and value to port, using the writer
from header-writer
.
Read the headers of an HTTP message from port, returning them as an ordered alist.
Write the given header alist to port. Doesn’t write the final ‘\r\n’, as the user might want to add another header.
The (web http)
module also has some utility procedures to read
and write request and response lines.
Parse an HTTP method from str. The result is an upper-case symbol,
like GET
.
Parse an HTTP version from str, returning it as a major–minor
pair. For example, HTTP/1.1
parses as the pair of integers,
(1 . 1)
.
Parse a URI from an HTTP request line. Note that URIs in requests do not have to have a scheme or host name. The result is a URI object.
Read the first line of an HTTP request from port, returning three values: the method, the URI, and the version.
Write the first line of an HTTP request to port.
Read the first line of an HTTP response from port, returning three values: the HTTP version, the response code, and the “reason phrase”.
Write the first line of an HTTP response to port.