2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 2010 Free Software Foundation, Inc.
4 @c See the file guile.texi for copying conditions.
7 @section @acronym{HTTP}, the Web, and All That
12 When Guile started back in the mid-nineties, the GNU system was still
13 focused on producing a good POSIX implementation. This is why Guile's
14 POSIX support is good, and has been so for a while.
16 But times change, and in a way these days the web is the new POSIX: a
17 standard and a motley set of implementations on which much computing is
18 done. So today's Guile also supports the web at the programming
19 language level, by defining common data types and operations for the
20 technologies underpinning the web: URIs, HTTP, and XML.
22 It is particularly important to define native web data types. Though
23 the web is text in motion, programming the web in text is like
24 programming with @code{goto}: muddy, and error-prone. Most current
25 security problems on the web are due to treating the web as text instead
26 of as instances of the proper data types.
28 In addition, common web data types help programmers to share code.
30 Well. That's all very nice and opinionated and such, but how do I use
34 * URIs:: Universal Resource Identifiers.
35 * HTTP:: The Hyper-Text Transfer Protocol.
36 * HTTP Headers:: How Guile represents specific header values.
37 * Requests:: HTTP requests.
38 * Responses:: HTTP responses.
39 * Web Handlers:: A simple web application interface.
40 * Web Server:: Serving HTTP to the internet.
44 @subsection Universal Resource Identifiers
46 Guile provides a standard data type for Universal Resource Identifiers
47 (URIs), as defined in RFC 3986.
49 The generic URI syntax is as follows:
52 URI := scheme ":" ["//" [userinfo "@@"] host [":" port]] path \
53 [ "?" query ] [ "#" fragment ]
56 So, all URIs have a scheme and a path. Some URIs have a host, and some
57 of those have ports and userinfo. Any URI might have a query part or a
60 Userinfo is something of an abstraction, as some legacy URI schemes
61 allowed userinfo of the form @code{@var{username}:@var{passwd}}.
62 Passwords don't belong in URIs, so the RFC does not want to condone
63 this, but neither can it say that what is before the @code{@@} sign is
64 just a username, so the RFC punts on the issue and calls it
67 Also, strictly speaking, a URI with a fragment is a @dfn{URI
68 reference}. A fragment is typically not serialized when sending a URI
69 over the wire; that is, it is not part of the identifier of a resource.
70 It only identifies a part of a given resource. But it's useful to have
71 a field for it in the URI record itself, so we hope you will forgive the
75 (use-modules (web uri))
78 The following procedures can be found in the @code{(web uri)}
79 module. Load it into your Guile, using a form like the above, to have
82 @defun build-uri scheme [#:userinfo] [#:host] [#:port] [#:path] [#:query] [#:fragment] [#:validate?]
83 Construct a URI object. If @var{validate?} is true, also run some
84 consistency checks to make sure that the constructed URI is valid.
88 @defunx uri-scheme uri
89 @defunx uri-userinfo uri
94 @defunx uri-fragment uri
95 A predicate and field accessors for the URI record type.
98 @defun declare-default-port! scheme port
99 Declare a default port for the given URI scheme.
101 Default ports are for printing URI objects: a default port is not
105 @defun parse-uri string
106 Parse @var{string} into a URI object. Returns @code{#f} if the string
110 @defun unparse-uri uri
111 Serialize @var{uri} to a string.
114 @defun uri-decode str [#:charset]
115 Percent-decode the given @var{str}, according to @var{charset}.
117 Note that this function should not generally be applied to a full URI
118 string. For paths, use split-and-decode-uri-path instead. For query
119 strings, split the query on @code{&} and @code{=} boundaries, and decode
120 the components separately.
122 Note that percent-encoded strings encode @emph{bytes}, not characters.
123 There is no guarantee that a given byte sequence is a valid string
124 encoding. Therefore this routine may signal an error if the decoded
125 bytes are not valid for the given encoding. Pass @code{#f} for
126 @var{charset} if you want decoded bytes as a bytevector directly.
129 @defun uri-encode str [#:charset] [#:unescaped-chars]
130 Percent-encode any character not in @var{unescaped-chars}.
132 Percent-encoding first writes out the given character to a bytevector
133 within the given @var{charset}, then encodes each byte as
134 @code{%@var{HH}}, where @var{HH} is the hexadecimal representation of
138 @defun split-and-decode-uri-path path
139 Split @var{path} into its components, and decode each component,
140 removing empty components.
142 For example, @code{"/foo/bar/"} decodes to the two-element list,
143 @code{("foo" "bar")}.
146 @defun encode-and-join-uri-path parts
147 URI-encode each element of @var{parts}, which should be a list of
148 strings, and join the parts together with @code{/} as a delimiter.
152 @subsection The Hyper-Text Transfer Protocol
154 The initial motivation for including web functionality in Guile, rather
155 than rely on an external package, was to establish a standard base on
156 which people can share code. To that end, we continue the focus on data
157 types by providing a number of low-level parsers and unparsers for
158 elements of the HTTP protocol.
160 If you are want to skip the low-level details for now and move on to web
161 pages, @pxref{Web Server}. Otherwise, load the HTTP module, and read
165 (use-modules (web http))
168 The focus of the @code{(web http)} module is to parse and unparse
169 standard HTTP headers, representing them to Guile as native data
170 structures. For example, a @code{Date:} header will be represented as a
171 SRFI-19 date record (@pxref{SRFI-19}), rather than as a string.
173 Guile tries to follow RFCs fairly strictly---the road to perdition being
174 paved with compatibility hacks---though some allowances are made for
175 not-too-divergent texts.
177 The first bit is to define a registry of parsers, validators, and
178 unparsers, keyed by header name. That is the function of the
179 @code{<header-decl>} object.
181 @defun make-header-decl sym name multiple? parser validator writer
182 @defunx header-decl? x
183 @defunx header-decl-sym decl
184 @defunx header-decl-name decl
185 @defunx header-decl-multiple? decl
186 @defunx header-decl-parser decl
187 @defunx header-decl-validator decl
188 @defunx header-decl-writer decl.
189 A constructor, predicate, and field accessors for the
190 @code{<header-decl>} type. The fields are as follows:
194 The symbol name for this header field, always in lower-case. For
195 example, @code{"Content-Length"} has a symbolic name of
196 @code{content-length}.
198 The string name of the header, in its preferred capitalization.
200 @code{#t} iff this header may appear multiple times in a message.
202 A procedure which takes a string and returns a parsed value.
204 A predicate, returning @code{#t} iff the value is valid for this header.
206 A writer, which writes a value to the port given in the second argument.
210 @defun declare-header! sym name [#:multiple?] [#:parser] [#:validator] [#:writer]
211 Make a header declaration, as above, and register it by symbol and by
215 @defun lookup-header-decl name
216 Return the @var{header-decl} object registered for the given @var{name}.
218 @var{name} may be a symbol or a string. Strings are mapped to headers in
219 a case-insensitive fashion.
222 @defun valid-header? sym val
223 Returns a true value iff @var{val} is a valid Scheme value for the
224 header with name @var{sym}.
227 Now that we have a generic interface for reading and writing headers, we
230 @defun read-header port
231 Reads one HTTP header from @var{port}. Returns two values: the header
232 name and the parsed Scheme value. May raise an exception if the header
233 was known but the value was invalid.
235 Returns @var{#f} for both values if the end of the message body was
236 reached (i.e., a blank line).
239 @defun parse-header name val
240 Parse @var{val}, a string, with the parser for the header named
243 Returns two values, the header name and parsed value. If a parser was
244 found, the header name will be returned as a symbol. If a parser was not
245 found, both the header name and the value are returned as strings.
248 @defun write-header name val port
249 Writes the given header name and value to @var{port}. If @var{name} is a
250 symbol, looks up a declared header and uses that writer. Otherwise the
251 value is written using @var{display}.
254 @defun read-headers port
255 Read an HTTP message from @var{port}, returning the headers as an
259 @defun write-headers headers port
260 Write the given header alist to @var{port}. Doesn't write the final
261 \r\n, as the user might want to add another header.
264 The @code{(web http)} module also has some utility procedures to read
265 and write request and response lines.
267 @defun parse-http-method str [start] [end]
268 Parse an HTTP method from @var{str}. The result is an upper-case symbol,
272 @defun parse-http-version str [start] [end]
273 Parse an HTTP version from @var{str}, returning it as a major-minor
274 pair. For example, @code{HTTP/1.1} parses as the pair of integers,
278 @defun parse-request-uri str [start] [end]
279 Parse a URI from an HTTP request line. Note that URIs in requests do not
280 have to have a scheme or host name. The result is a URI object.
283 @defun read-request-line port
284 Read the first line of an HTTP request from @var{port}, returning three
285 values: the method, the URI, and the version.
288 @defun write-request-line method uri version port
289 Write the first line of an HTTP request to @var{port}.
292 @defun read-response-line port
293 Read the first line of an HTTP response from @var{port}, returning three
294 values: the HTTP version, the response code, and the "reason phrase".
297 @defun write-response-line version code reason-phrase port
298 Write the first line of an HTTP response to @var{port}.
303 @subsection HTTP Headers
305 The @code{(web http)} module defines parsers and unparsers for all
306 headers defined in the HTTP/1.1 standard. This section describes the
307 parsed format of the various headers.
309 We cannot describe the function of all of these headers, however, in
310 sufficient detail. The interested reader would do well to download a
311 copy of RFC 2616 and have it on hand.
313 To begin with, we should make a few definitions:
317 A key-value list is a list of values. Each value may be a string,
318 a symbol, or a pair. Known keys are parsed to symbols; otherwise keys
319 are left as strings. Keys with values are parsed to pairs, the car of
320 which is the symbol or string key, and the cdr is the parsed value.
321 Parsed values for known keys have key-dependent formats. Parsed values
322 for unknown keys are strings.
325 A param list is a list of key-value lists. When serialized to a string,
326 items in the inner lists are separated by semicolons. Again, known keys
327 are parsed to symbols.
330 A number of headers have quality values in them, which are decimal
331 fractions between zero and one indicating a preference for various kinds
332 of responses, which the server may choose to heed. Given that only
333 three digits are allowed in the fractional part, Guile parses quality
334 values to integers between 0 and 1000 instead of inexact numbers between
338 A list of pairs, the car of which is a quality value.
341 A pair, the car of which is an opaque string, and the cdr of which is
342 true iff the entity tag is a ``strong'' entity tag.
346 @subsubsection General Headers
350 A key-value list of cache-control directives. Known keys are
351 @code{max-age}, @code{max-stale}, @code{min-fresh},
352 @code{must-revalidate}, @code{no-cache}, @code{no-store},
353 @code{no-transform}, @code{only-if-cached}, @code{private},
354 @code{proxy-revalidate}, @code{public}, and @code{s-maxage}.
356 If present, parameters to @code{max-age}, @code{max-stale},
357 @code{min-fresh}, and @code{s-maxage} are all parsed as non-negative
360 If present, parameters to @code{private} and @code{no-cache} are parsed
361 as lists of header names, represented as symbols if they are known
362 headers or strings otherwise.
365 A list of connection tokens. A connection token is a string.
368 A SRFI-19 date record.
371 A key-value list of pragma directives. @code{no-cache} is the only
375 A list of header names. Known header names are parsed to symbols,
376 otherwise they are left as strings.
378 @item transfer-encoding
379 A param list of transfer codings. @code{chunked} is the only known key.
385 A list of strings. There may be multiple @code{via} headers in ne
389 A list of warnings. Each warning is a itself a list of four elements: a
390 code, as an exact integer between 0 and 1000, a host as a string, the
391 warning text as a string, and either @code{#f} or a SRFI-19 date.
393 There may be multiple @code{warning} headers in one message.
397 @subsubsection Entity Headers
401 A list of methods, as strings. Methods are parsed as strings instead of
402 @code{parse-http-method} so as to allow for new methods.
404 @item content-encoding
405 A list of content codings, as strings.
407 @item content-language
408 A list of language tags, as strings.
411 An exact, non-negative integer.
413 @item content-location
420 A list of three elements: the symbol @code{bytes}, either the symbol
421 @code{*} or a pair of integers, indicating the byte rage, and either
422 @code{*} or an integer, for the instance length.
425 A pair, the car of which is the media type as a string, and the cdr is
426 an alist of parameters, with strings as keys and values.
428 For example, @code{"text/plain"} parses as @code{("text/plain")}, and
429 @code{"text/plain;charset=utf-8"} parses as @code{("text/plain"
430 ("charset" . "utf-8"))}.
441 @subsubsection Request Headers
445 A param list. Each element in the list indicates one media-range
446 with accept-params. They only known key is @code{q}, whose value is
447 parsed as a quality value.
450 A quality-list of charsets, as strings.
452 @item accept-encoding
453 A quality-list of content codings, as strings.
455 @item accept-language
456 A quality-list of languages, as strings.
462 A param list of expectations. The only known key is
469 A pair of the host, as a string, and the port, as an integer. If no port
470 is given, port is @code{#f}.
473 Either the symbol @code{*}, or a list of entity tags (see above).
475 @item if-modified-since
479 Either the symbol @code{*}, or a list of entity tags (see above).
482 Either an entity tag, or a SRFI-19 date.
484 @item if-unmodified-since
488 An exact non-negative integer.
490 @item proxy-authorization
494 A pair whose car is the symbol @code{bytes}, and whose cdr is a list of
495 pairs. Each element of the cdr indicates a range; the car is the first
496 byte position and the cdr is the last byte position, as integers, or
497 @code{#f} if not given.
503 A param list of transfer-codings. The only known key is
511 @subsubsection Response Headers
518 An exact, non-negative integer.
526 @item proxy-authenticate
530 Either an exact, non-negative integer, or a SRFI-19 date.
536 Either the symbol @code{*}, or a list of headers, with known headers
539 @item www-authenticate
545 @subsection HTTP Requests
548 (use-modules (web request))
554 @defun request-method
560 @defun request-version
563 @defun request-headers
572 @defun read-request port [meta]
573 Read an HTTP request from @var{port}, optionally attaching the given
574 metadata, @var{meta}.
576 As a side effect, sets the encoding on @var{port} to ISO-8859-1
577 (latin-1), so that reading one character reads one byte. See the
578 discussion of character sets in "HTTP Requests" in the manual, for more
582 @defun build-request [#:method] [#:uri] [#:version] [#:headers] [#:port] [#:meta] [#:validate-headers?]
583 Construct an HTTP request object. If @var{validate-headers?} is true,
584 the headers are each run through their respective validators.
587 @defun write-request r port
588 Write the given HTTP request to @var{port}.
590 Returns a new request, whose @code{request-port} will continue writing
591 on @var{port}, perhaps using some transfer encoding.
594 @defun read-request-body/latin-1 r
595 Reads the request body from @var{r}, as a string.
597 Assumes that the request port has ISO-8859-1 encoding, so that the
598 number of characters to read is the same as the
599 @code{request-content-length}. Returns @code{#f} if there was no request
603 @defun write-request-body/latin-1 r body
604 Write @var{body}, a string encodable in ISO-8859-1, to the port
605 corresponding to the HTTP request @var{r}.
608 @defun read-request-body/bytevector r
609 Reads the request body from @var{r}, as a bytevector. Returns @code{#f}
610 if there was no request body.
613 @defun write-request-body/bytevector r bv
614 Write @var{body}, a bytevector, to the port corresponding to the HTTP
618 @defun request-accept request [default='()]
619 @defunx request-accept-charset request [default='()]
620 @defunx request-accept-encoding request [default='()]
621 @defunx request-accept-language request [default='()]
622 @defunx request-allow request [default='()]
623 @defunx request-authorization request [default=#f]
624 @defunx request-cache-control request [default='()]
625 @defunx request-connection request [default='()]
626 @defunx request-content-encoding request [default='()]
627 @defunx request-content-language request [default='()]
628 @defunx request-content-length request [default=#f]
629 @defunx request-content-location request [default=#f]
630 @defunx request-content-md5 request [default=#f]
631 @defunx request-content-range request [default=#f]
632 @defunx request-content-type request [default=#f]
633 @defunx request-date request [default=#f]
634 @defunx request-expect request [default='()]
635 @defunx request-expires request [default=#f]
636 @defunx request-from request [default=#f]
637 @defunx request-host request [default=#f]
638 @defunx request-if-match request [default=#f]
639 @defunx request-if-modified-since request [default=#f]
640 @defunx request-if-none-match request [default=#f]
641 @defunx request-if-range request [default=#f]
642 @defunx request-if-unmodified-since request [default=#f]
643 @defunx request-last-modified request [default=#f]
644 @defunx request-max-forwards request [default=#f]
645 @defunx request-pragma request [default='()]
646 @defunx request-proxy-authorization request [default=#f]
647 @defunx request-range request [default=#f]
648 @defunx request-referer request [default=#f]
649 @defunx request-te request [default=#f]
650 @defunx request-trailer request [default='()]
651 @defunx request-transfer-encoding request [default='()]
652 @defunx request-upgrade request [default='()]
653 @defunx request-user-agent request [default=#f]
654 @defunx request-via request [default='()]
655 @defunx request-warning request [default='()]
658 @defun request-absolute-uri r [default-host] [default-port]
664 @subsection HTTP Responses
667 (use-modules (web response))
674 @defun response-version
680 @defun response-reason-phrase response
681 Return the reason phrase given in @var{response}, or the standard reason
682 phrase for the response's code.
685 @defun response-headers
691 @defun read-response port
692 Read an HTTP response from @var{port}, optionally attaching the given
693 metadata, @var{meta}.
695 As a side effect, sets the encoding on @var{port} to ISO-8859-1
696 (latin-1), so that reading one character reads one byte. See the
697 discussion of character sets in "HTTP Responses" in the manual, for more
701 @defun build-response [#:version] [#:code] [#:reason-phrase] [#:headers] [#:port]
702 Construct an HTTP response object. If @var{validate-headers?} is true,
703 the headers are each run through their respective validators.
706 @defun extend-response r k v . additional
707 Extend an HTTP response by setting additional HTTP headers @var{k},
708 @var{v}. Returns a new HTTP response.
711 @defun adapt-response-version response version
712 Adapt the given response to a different HTTP version. Returns a new HTTP
715 The idea is that many applications might just build a response for the
716 default HTTP version, and this method could handle a number of
717 programmatic transformations to respond to older HTTP versions (0.9 and
718 1.0). But currently this function is a bit heavy-handed, just updating
722 @defun write-response r port
723 Write the given HTTP response to @var{port}.
725 Returns a new response, whose @code{response-port} will continue writing
726 on @var{port}, perhaps using some transfer encoding.
729 @defun read-response-body/latin-1 r
730 Reads the response body from @var{r}, as a string.
732 Assumes that the response port has ISO-8859-1 encoding, so that the
733 number of characters to read is the same as the
734 @code{response-content-length}. Returns @code{#f} if there was no
738 @defun write-response-body/latin-1 r body
739 Write @var{body}, a string encodable in ISO-8859-1, to the port
740 corresponding to the HTTP response @var{r}.
743 @defun read-response-body/bytevector r
744 Reads the response body from @var{r}, as a bytevector. Returns @code{#f}
745 if there was no response body.
748 @defun write-response-body/bytevector r bv
749 Write @var{body}, a bytevector, to the port corresponding to the HTTP
753 @defun response-accept-ranges response [default=#f]
754 @defunx response-age response [default='()]
755 @defunx response-allow response [default='()]
756 @defunx response-cache-control response [default='()]
757 @defunx response-connection response [default='()]
758 @defunx response-content-encoding response [default='()]
759 @defunx response-content-language response [default='()]
760 @defunx response-content-length response [default=#f]
761 @defunx response-content-location response [default=#f]
762 @defunx response-content-md5 response [default=#f]
763 @defunx response-content-range response [default=#f]
764 @defunx response-content-type response [default=#f]
765 @defunx response-date response [default=#f]
766 @defunx response-etag response [default=#f]
767 @defunx response-expires response [default=#f]
768 @defunx response-last-modified response [default=#f]
769 @defunx response-location response [default=#f]
770 @defunx response-pragma response [default='()]
771 @defunx response-proxy-authenticate response [default=#f]
772 @defunx response-retry-after response [default=#f]
773 @defunx response-server response [default=#f]
774 @defunx response-trailer response [default='()]
775 @defunx response-transfer-encoding response [default='()]
776 @defunx response-upgrade response [default='()]
777 @defunx response-vary response [default='()]
778 @defunx response-via response [default='()]
779 @defunx response-warning response [default='()]
780 @defunx response-www-authenticate response [default=#f]
785 @subsection Web Handlers
787 from request to response
790 @subsection Web Server
792 @code{(web server)} is a generic web server interface, along with a main
793 loop implementation for web servers controlled by Guile.
795 The lowest layer is the <server-impl> object, which defines a set of
796 hooks to open a server, read a request from a client, write a
797 response to a client, and close a server. These hooks -- open,
798 read, write, and close, respectively -- are bound together in a
799 <server-impl> object. Procedures in this module take a
800 <server-impl> object, if needed.
802 A <server-impl> may also be looked up by name. If you pass the
803 @code{http} symbol to @code{run-server}, Guile looks for a variable named
804 @code{http} in the @code{(web server http)} module, which should be bound to a
805 <server-impl> object. Such a binding is made by instantiation of
806 the @code{define-server-impl} syntax. In this way the run-server loop can
807 automatically load other backends if available.
809 The life cycle of a server goes as follows:
813 The @code{open} hook is called, to open the server. @code{open} takes 0 or
814 more arguments, depending on the backend, and returns an opaque
815 server socket object, or signals an error.
818 The @code{read} hook is called, to read a request from a new client.
819 The @code{read} hook takes one arguments, the server socket. It
820 should return three values: an opaque client socket, the
821 request, and the request body. The request should be a
822 @code{<request>} object, from @code{(web request)}. The body should be a
823 string or a bytevector, or @code{#f} if there is no body.
825 If the read failed, the @code{read} hook may return #f for the client
826 socket, request, and body.
829 A user-provided handler procedure is called, with the request
830 and body as its arguments. The handler should return two
831 values: the response, as a @code{<response>} record from @code{(web
832 response)}, and the response body as a string, bytevector, or
833 @code{#f} if not present. We also allow the reponse to be simply an
834 alist of headers, in which case a default response object is
835 constructed with those headers.
838 The @code{write} hook is called with three arguments: the client
839 socket, the response, and the body. The @code{write} hook returns no
843 At this point the request handling is complete. For a loop, we
844 loop back and try to read a new request.
847 If the user interrupts the loop, the @code{close} hook is called on
851 @defun define-server-impl name open read write close
854 @defun lookup-server-impl impl
855 Look up a server implementation. If @var{impl} is a server
856 implementation already, it is returned directly. If it is a symbol, the
857 binding named @var{impl} in the @code{(web server @var{impl})} module is
858 looked up. Otherwise an error is signaled.
860 Currently a server implementation is a somewhat opaque type, useful only
861 for passing to other procedures in this module, like @code{read-client}.
864 @defun open-server impl open-params
865 Open a server for the given implementation. Returns one value, the new
866 server object. The implementation's @code{open} procedure is applied to
867 @var{open-params}, which should be a list.
870 @defun read-client impl server
871 Read a new client from @var{server}, by applying the implementation's
872 @code{read} procedure to the server. If successful, returns three
873 values: an object corresponding to the client, a request object, and the
874 request body. If any exception occurs, returns @code{#f} for all three
878 @defun handle-request handler request body state
879 Handle a given request, returning the response and body.
881 The response and response body are produced by calling the given
882 @var{handler} with @var{request} and @var{body} as arguments.
884 The elements of @var{state} are also passed to @var{handler} as
885 arguments, and may be returned as additional values. The new
886 @var{state}, collected from the @var{handler}'s return values, is then
887 returned as a list. The idea is that a server loop receives a handler
888 from the user, along with whatever state values the user is interested
889 in, allowing the user's handler to explicitly manage its state.
892 @defun sanitize-response request response body
893 "Sanitize" the given response and body, making them appropriate for the
896 As a convenience to web handler authors, @var{response} may be given as
897 an alist of headers, in which case it is used to construct a default
898 response. Ensures that the response version corresponds to the request
899 version. If @var{body} is a string, encodes the string to a bytevector,
900 in an encoding appropriate for @var{response}. Adds a
901 @code{content-length} and @code{content-type} header, as necessary.
903 If @var{body} is a procedure, it is called with a port as an argument,
904 and the output collected as a bytevector. In the future we might try to
905 instead use a compressing, chunk-encoded port, and call this procedure
906 later, in the write-client procedure. Authors are advised not to rely on
907 the procedure being called at any particular time.
910 @defun write-client impl server client response body
911 Write an HTTP response and body to @var{client}. If the server and
912 client support persistent connections, it is the implementation's
913 responsibility to keep track of the client thereafter, presumably by
914 attaching it to the @var{server} argument somehow.
917 @defun close-server impl server
918 Release resources allocated by a previous invocation of
922 @defun serve-one-client handler impl server state
923 Read one request from @var{server}, call @var{handler} on the request
924 and body, and write the response to the client. Returns the new state
925 produced by the handler procedure.
928 @defun run-server handler [impl] [open-params] . state
929 Run Guile's built-in web server.
931 @var{handler} should be a procedure that takes two or more arguments,
932 the HTTP request and request body, and returns two or more values, the
933 response and response body.
935 For example, here is a simple "Hello, World!" server:
938 (define (handler request body)
939 (values '((content-type . ("text/plain")))
944 The response and body will be run through @code{sanitize-response}
945 before sending back to the client.
947 Additional arguments to @var{handler} are taken from @var{state}.
948 Additional return values are accumulated into a new @var{state}, which
949 will be used for subsequent requests. In this way a handler can
950 explicitly manage its state.
952 The default server implementation is @code{http}, which accepts
953 @var{open-params} like @code{(#:port 8081)}, among others. See "Web
954 Server" in the manual, for more information.
958 (use-modules (web server))
963 @c TeX-master: "guile.texi"