Commit | Line | Data |
---|---|---|
8db7e094 AW |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
d64146f2 | 3 | @c Copyright (C) 2010, 2011, 2012, 2013, 2015 Free Software Foundation, Inc. |
8db7e094 AW |
4 | @c See the file guile.texi for copying conditions. |
5 | ||
6 | @node Web | |
7 | @section @acronym{HTTP}, the Web, and All That | |
8 | @cindex Web | |
9 | @cindex WWW | |
10 | @cindex HTTP | |
11 | ||
d75a81b1 | 12 | It has always been possible to connect computers together and share |
dc871261 | 13 | information between them, but the rise of the World Wide Web over the |
d75a81b1 AW |
14 | last couple of decades has made it much easier to do so. The result is |
15 | a richly connected network of computation, in which Guile forms a part. | |
8db7e094 | 16 | |
d75a81b1 AW |
17 | By ``the web'', we mean the HTTP protocol@footnote{Yes, the P is for |
18 | protocol, but this phrase appears repeatedly in RFC 2616.} as handled by | |
19 | servers, clients, proxies, caches, and the various kinds of messages and | |
20 | message components that can be sent and received by that protocol, | |
21 | notably HTML. | |
8db7e094 | 22 | |
d75a81b1 AW |
23 | On one level, the web is text in motion: the protocols themselves are |
24 | textual (though the payload may be binary), and it's possible to create | |
25 | a socket and speak text to the web. But such an approach is obviously | |
26 | primitive. This section details the higher-level data types and | |
27 | operations provided by Guile: URIs, HTTP request and response records, | |
28 | and a conventional web server implementation. | |
8db7e094 | 29 | |
d75a81b1 AW |
30 | The material in this section is arranged in ascending order, in which |
31 | later concepts build on previous ones. If you prefer to start with the | |
32 | highest-level perspective, @pxref{Web Examples}, and work your way | |
33 | back. | |
8db7e094 AW |
34 | |
35 | @menu | |
d75a81b1 | 36 | * Types and the Web:: Types prevent bugs and security problems. |
8db7e094 AW |
37 | * URIs:: Universal Resource Identifiers. |
38 | * HTTP:: The Hyper-Text Transfer Protocol. | |
1148d029 | 39 | * HTTP Headers:: How Guile represents specific header values. |
312e79f8 | 40 | * Transfer Codings:: HTTP Transfer Codings. |
8db7e094 AW |
41 | * Requests:: HTTP requests. |
42 | * Responses:: HTTP responses. | |
ec811439 | 43 | * Web Client:: Accessing web resources over HTTP. |
8db7e094 | 44 | * Web Server:: Serving HTTP to the internet. |
e471a3ee | 45 | * Web Examples:: How to use this thing. |
8db7e094 AW |
46 | @end menu |
47 | ||
d75a81b1 AW |
48 | @node Types and the Web |
49 | @subsection Types and the Web | |
50 | ||
51 | It is a truth universally acknowledged, that a program with good use of | |
52 | data types, will be free from many common bugs. Unfortunately, the | |
53 | common practice in web programming seems to ignore this maxim. This | |
54 | subsection makes the case for expressive data types in web programming. | |
55 | ||
56 | By ``expressive data types'', we mean that the data types @emph{say} | |
57 | something about how a program solves a problem. For example, if we | |
58 | choose to represent dates using SRFI 19 date records (@pxref{SRFI-19}), | |
59 | this indicates that there is a part of the program that will always have | |
60 | valid dates. Error handling for a number of basic cases, like invalid | |
61 | dates, occurs on the boundary in which we produce a SRFI 19 date record | |
62 | from other types, like strings. | |
63 | ||
5ec48b70 NJ |
64 | With regards to the web, data types are helpful in the two broad phases |
65 | of HTTP messages: parsing and generation. | |
d75a81b1 AW |
66 | |
67 | Consider a server, which has to parse a request, and produce a response. | |
68 | Guile will parse the request into an HTTP request object | |
69 | (@pxref{Requests}), with each header parsed into an appropriate Scheme | |
70 | data type. This transition from an incoming stream of characters to | |
71 | typed data is a state change in a program---the strings might parse, or | |
72 | they might not, and something has to happen if they do not. (Guile | |
73 | throws an error in this case.) But after you have the parsed request, | |
74 | ``client'' code (code built on top of the Guile web framework) will not | |
75 | have to check for syntactic validity. The types already make this | |
76 | information manifest. | |
77 | ||
78 | This state change on the parsing boundary makes programs more robust, | |
79 | as they themselves are freed from the need to do a number of common | |
80 | error checks, and they can use normal Scheme procedures to handle a | |
81 | request instead of ad-hoc string parsers. | |
82 | ||
83 | The need for types on the response generation side (in a server) is more | |
84 | subtle, though not less important. Consider the example of a POST | |
85 | handler, which prints out the text that a user submits from a form. | |
86 | Such a handler might include a procedure like this: | |
87 | ||
88 | @example | |
89 | ;; First, a helper procedure | |
90 | (define (para . contents) | |
91 | (string-append "<p>" (string-concatenate contents) "</p>")) | |
92 | ||
93 | ;; Now the meat of our simple web application | |
94 | (define (you-said text) | |
95 | (para "You said: " text)) | |
96 | ||
97 | (display (you-said "Hi!")) | |
98 | @print{} <p>You said: Hi!</p> | |
99 | @end example | |
100 | ||
101 | This is a perfectly valid implementation, provided that the incoming | |
102 | text does not contain the special HTML characters @samp{<}, @samp{>}, or | |
103 | @samp{&}. But this provision of a restricted character set is not | |
104 | reflected anywhere in the program itself: we must @emph{assume} that the | |
105 | programmer understands this, and performs the check elsewhere. | |
106 | ||
107 | Unfortunately, the short history of the practice of programming does not | |
108 | bear out this assumption. A @dfn{cross-site scripting} (@acronym{XSS}) | |
109 | vulnerability is just such a common error in which unfiltered user input | |
110 | is allowed into the output. A user could submit a crafted comment to | |
111 | your web site which results in visitors running malicious Javascript, | |
112 | within the security context of your domain: | |
113 | ||
114 | @example | |
115 | (display (you-said "<script src=\"http://bad.com/nasty.js\" />")) | |
116 | @print{} <p>You said: <script src="http://bad.com/nasty.js" /></p> | |
117 | @end example | |
118 | ||
119 | The fundamental problem here is that both user data and the program | |
120 | template are represented using strings. This identity means that types | |
121 | can't help the programmer to make a distinction between these two, so | |
122 | they get confused. | |
123 | ||
124 | There are a number of possible solutions, but perhaps the best is to | |
125 | treat HTML not as strings, but as native s-expressions: as SXML. The | |
126 | basic idea is that HTML is either text, represented by a string, or an | |
127 | element, represented as a tagged list. So @samp{foo} becomes | |
128 | @samp{"foo"}, and @samp{<b>foo</b>} becomes @samp{(b "foo")}. | |
129 | Attributes, if present, go in a tagged list headed by @samp{@@}, like | |
3e31e75a AW |
130 | @samp{(img (@@ (src "http://example.com/foo.png")))}. @xref{SXML}, for |
131 | more information. | |
d75a81b1 AW |
132 | |
133 | The good thing about SXML is that HTML elements cannot be confused with | |
134 | text. Let's make a new definition of @code{para}: | |
135 | ||
136 | @example | |
137 | (define (para . contents) | |
138 | `(p ,@@contents)) | |
139 | ||
140 | (use-modules (sxml simple)) | |
141 | (sxml->xml (you-said "Hi!")) | |
142 | @print{} <p>You said: Hi!</p> | |
143 | ||
144 | (sxml->xml (you-said "<i>Rats, foiled again!</i>")) | |
145 | @print{} <p>You said: <i>Rats, foiled again!</i></p> | |
146 | @end example | |
147 | ||
148 | So we see in the second example that HTML elements cannot be unwittingly | |
569269b4 AW |
149 | introduced into the output. However it is now perfectly acceptable to |
150 | pass SXML to @code{you-said}; in fact, that is the big advantage of SXML | |
151 | over everything-as-a-string. | |
d75a81b1 AW |
152 | |
153 | @example | |
154 | (sxml->xml (you-said (you-said "<Hi!>"))) | |
155 | @print{} <p>You said: <p>You said: <Hi!></p></p> | |
156 | @end example | |
157 | ||
158 | The SXML types allow procedures to @emph{compose}. The types make | |
159 | manifest which parts are HTML elements, and which are text. So you | |
160 | needn't worry about escaping user input; the type transition back to a | |
161 | string handles that for you. @acronym{XSS} vulnerabilities are a thing | |
162 | of the past. | |
163 | ||
164 | Well. That's all very nice and opinionated and such, but how do I use | |
165 | the thing? Read on! | |
166 | ||
8db7e094 AW |
167 | @node URIs |
168 | @subsection Universal Resource Identifiers | |
169 | ||
299cd1a2 AW |
170 | Guile provides a standard data type for Universal Resource Identifiers |
171 | (URIs), as defined in RFC 3986. | |
8db7e094 | 172 | |
299cd1a2 | 173 | The generic URI syntax is as follows: |
8db7e094 | 174 | |
299cd1a2 | 175 | @example |
ac7f17e3 | 176 | URI := scheme ":" ["//" [userinfo "@@"] host [":" port]] path \ |
299cd1a2 AW |
177 | [ "?" query ] [ "#" fragment ] |
178 | @end example | |
8db7e094 | 179 | |
b3f94448 AW |
180 | For example, in the URI, @indicateurl{http://www.gnu.org/help/}, the |
181 | scheme is @code{http}, the host is @code{www.gnu.org}, the path is | |
98aa6f5b AW |
182 | @code{/help/}, and there is no userinfo, port, query, or fragment. All |
183 | URIs have a scheme and a path (though the path might be empty). Some | |
184 | URIs have a host, and some of those have ports and userinfo. Any URI | |
185 | might have a query part or a fragment. | |
8db7e094 | 186 | |
d64146f2 AW |
187 | There is also a ``URI-reference'' data type, which is the same as a URI |
188 | but where the scheme is optional. In this case, the scheme is taken to | |
189 | be relative to some other related URI. A common use of URI references | |
190 | is when you want to be vague regarding the choice of HTTP or HTTPS -- | |
191 | serving a web page referring to @code{/foo.css} will use HTTPS if loaded | |
192 | over HTTPS, or HTTP otherwise. | |
193 | ||
299cd1a2 | 194 | Userinfo is something of an abstraction, as some legacy URI schemes |
b3f94448 AW |
195 | allowed userinfo of the form @code{@var{username}:@var{passwd}}. But |
196 | since passwords do not belong in URIs, the RFC does not want to condone | |
197 | this practice, so it calls anything before the @code{@@} sign | |
299cd1a2 | 198 | @dfn{userinfo}. |
8db7e094 | 199 | |
b3f94448 AW |
200 | Properly speaking, a fragment is not part of a URI. For example, when a |
201 | web browser follows a link to @indicateurl{http://example.com/#foo}, it | |
202 | sends a request for @indicateurl{http://example.com/}, then looks in the | |
203 | resulting page for the fragment identified @code{foo} reference. A | |
204 | fragment identifies a part of a resource, not the resource itself. But | |
205 | it is useful to have a fragment field in the URI record itself, so we | |
206 | hope you will forgive the inconsistency. | |
8db7e094 | 207 | |
299cd1a2 AW |
208 | @example |
209 | (use-modules (web uri)) | |
210 | @end example | |
8db7e094 | 211 | |
299cd1a2 AW |
212 | The following procedures can be found in the @code{(web uri)} |
213 | module. Load it into your Guile, using a form like the above, to have | |
214 | access to them. | |
8db7e094 | 215 | |
dc871261 DH |
216 | @deffn {Scheme Procedure} build-uri scheme @ |
217 | [#:userinfo=@code{#f}] [#:host=@code{#f}] [#:port=@code{#f}] @ | |
218 | [#:path=@code{""}] [#:query=@code{#f}] [#:fragment=@code{#f}] @ | |
219 | [#:validate?=@code{#t}] | |
89064755 DH |
220 | Construct a URI object. @var{scheme} should be a symbol, @var{port} |
221 | either a positive, exact integer or @code{#f}, and the rest of the | |
222 | fields are either strings or @code{#f}. If @var{validate?} is true, | |
223 | also run some consistency checks to make sure that the constructed URI | |
224 | is valid. | |
2e6f5ea4 AW |
225 | @end deffn |
226 | ||
d64146f2 AW |
227 | @deffn {Scheme Procedure} build-uri-reference [#:scheme=@code{#f}]@ |
228 | [#:userinfo=@code{#f}] [#:host=@code{#f}] [#:port=@code{#f}] @ | |
229 | [#:path=@code{""}] [#:query=@code{#f}] [#:fragment=@code{#f}] @ | |
230 | [#:validate?=@code{#t}] | |
231 | Like @code{build-uri}, but with an optional scheme. | |
232 | @end deffn | |
233 | ||
234 | In Guile, both URI and URI reference data types are represented in the | |
235 | same way, as URI objects. | |
236 | ||
dc871261 | 237 | @deffn {Scheme Procedure} uri? obj |
2e6f5ea4 AW |
238 | @deffnx {Scheme Procedure} uri-scheme uri |
239 | @deffnx {Scheme Procedure} uri-userinfo uri | |
240 | @deffnx {Scheme Procedure} uri-host uri | |
241 | @deffnx {Scheme Procedure} uri-port uri | |
242 | @deffnx {Scheme Procedure} uri-path uri | |
243 | @deffnx {Scheme Procedure} uri-query uri | |
244 | @deffnx {Scheme Procedure} uri-fragment uri | |
569269b4 | 245 | A predicate and field accessors for the URI record type. The URI scheme |
d64146f2 AW |
246 | will be a symbol, or @code{#f} if the object is a URI reference but not |
247 | a URI. The port will be either a positive, exact integer or @code{#f}, | |
248 | and the rest of the fields will be either strings or @code{#f} if not | |
249 | present. | |
2e6f5ea4 | 250 | @end deffn |
299cd1a2 | 251 | |
2e6f5ea4 | 252 | @deffn {Scheme Procedure} string->uri string |
569269b4 AW |
253 | Parse @var{string} into a URI object. Return @code{#f} if the string |
254 | could not be parsed. | |
2e6f5ea4 | 255 | @end deffn |
8db7e094 | 256 | |
d64146f2 AW |
257 | @deffn {Scheme Procedure} string->uri-reference string |
258 | Parse @var{string} into a URI object, while not requiring a scheme. | |
259 | Return @code{#f} if the string could not be parsed. | |
260 | @end deffn | |
261 | ||
2e6f5ea4 | 262 | @deffn {Scheme Procedure} uri->string uri |
569269b4 AW |
263 | Serialize @var{uri} to a string. If the URI has a port that is the |
264 | default port for its scheme, the port is not included in the | |
265 | serialization. | |
2e6f5ea4 | 266 | @end deffn |
8db7e094 | 267 | |
2e6f5ea4 | 268 | @deffn {Scheme Procedure} declare-default-port! scheme port |
569269b4 | 269 | Declare a default port for the given URI scheme. |
2e6f5ea4 | 270 | @end deffn |
8db7e094 | 271 | |
2e6f5ea4 | 272 | @deffn {Scheme Procedure} uri-decode str [#:encoding=@code{"utf-8"}] |
569269b4 AW |
273 | Percent-decode the given @var{str}, according to @var{encoding}, which |
274 | should be the name of a character encoding. | |
8db7e094 AW |
275 | |
276 | Note that this function should not generally be applied to a full URI | |
dc871261 DH |
277 | string. For paths, use @code{split-and-decode-uri-path} instead. For |
278 | query strings, split the query on @code{&} and @code{=} boundaries, and | |
279 | decode the components separately. | |
8db7e094 | 280 | |
569269b4 AW |
281 | Note also that percent-encoded strings encode @emph{bytes}, not |
282 | characters. There is no guarantee that a given byte sequence is a valid | |
283 | string encoding. Therefore this routine may signal an error if the | |
284 | decoded bytes are not valid for the given encoding. Pass @code{#f} for | |
285 | @var{encoding} if you want decoded bytes as a bytevector directly. | |
286 | @xref{Ports, @code{set-port-encoding!}}, for more information on | |
287 | character encodings. | |
288 | ||
289 | Returns a string of the decoded characters, or a bytevector if | |
290 | @var{encoding} was @code{#f}. | |
2e6f5ea4 | 291 | @end deffn |
8db7e094 | 292 | |
2e6f5ea4 | 293 | @deffn {Scheme Procedure} uri-encode str [#:encoding=@code{"utf-8"}] [#:unescaped-chars] |
569269b4 AW |
294 | Percent-encode any character not in the character set, |
295 | @var{unescaped-chars}. | |
296 | ||
297 | The default character set includes alphanumerics from ASCII, as well as | |
298 | the special characters @samp{-}, @samp{.}, @samp{_}, and @samp{~}. Any | |
299 | other character will be percent-encoded, by writing out the character to | |
300 | a bytevector within the given @var{encoding}, then encoding each byte as | |
8db7e094 AW |
301 | @code{%@var{HH}}, where @var{HH} is the hexadecimal representation of |
302 | the byte. | |
2e6f5ea4 | 303 | @end deffn |
8db7e094 | 304 | |
2e6f5ea4 | 305 | @deffn {Scheme Procedure} split-and-decode-uri-path path |
8db7e094 AW |
306 | Split @var{path} into its components, and decode each component, |
307 | removing empty components. | |
308 | ||
569269b4 AW |
309 | For example, @code{"/foo/bar%20baz/"} decodes to the two-element list, |
310 | @code{("foo" "bar baz")}. | |
2e6f5ea4 | 311 | @end deffn |
8db7e094 | 312 | |
2e6f5ea4 | 313 | @deffn {Scheme Procedure} encode-and-join-uri-path parts |
8db7e094 AW |
314 | URI-encode each element of @var{parts}, which should be a list of |
315 | strings, and join the parts together with @code{/} as a delimiter. | |
569269b4 AW |
316 | |
317 | For example, the list @code{("scrambled eggs" "biscuits&gravy")} encodes | |
318 | as @code{"scrambled%20eggs/biscuits%26gravy"}. | |
2e6f5ea4 | 319 | @end deffn |
8db7e094 AW |
320 | |
321 | @node HTTP | |
322 | @subsection The Hyper-Text Transfer Protocol | |
323 | ||
299cd1a2 AW |
324 | The initial motivation for including web functionality in Guile, rather |
325 | than rely on an external package, was to establish a standard base on | |
326 | which people can share code. To that end, we continue the focus on data | |
327 | types by providing a number of low-level parsers and unparsers for | |
328 | elements of the HTTP protocol. | |
329 | ||
330 | If you are want to skip the low-level details for now and move on to web | |
ec811439 AW |
331 | pages, @pxref{Web Client}, and @pxref{Web Server}. Otherwise, load the |
332 | HTTP module, and read on. | |
299cd1a2 | 333 | |
8db7e094 AW |
334 | @example |
335 | (use-modules (web http)) | |
336 | @end example | |
337 | ||
299cd1a2 AW |
338 | The focus of the @code{(web http)} module is to parse and unparse |
339 | standard HTTP headers, representing them to Guile as native data | |
340 | structures. For example, a @code{Date:} header will be represented as a | |
341 | SRFI-19 date record (@pxref{SRFI-19}), rather than as a string. | |
342 | ||
343 | Guile tries to follow RFCs fairly strictly---the road to perdition being | |
344 | paved with compatibility hacks---though some allowances are made for | |
345 | not-too-divergent texts. | |
346 | ||
32de1aa7 AW |
347 | Header names are represented as lower-case symbols. |
348 | ||
2e6f5ea4 | 349 | @deffn {Scheme Procedure} string->header name |
32de1aa7 | 350 | Parse @var{name} to a symbolic header name. |
2e6f5ea4 | 351 | @end deffn |
8db7e094 | 352 | |
2e6f5ea4 | 353 | @deffn {Scheme Procedure} header->string sym |
32de1aa7 | 354 | Return the string form for the header named @var{sym}. |
2e6f5ea4 | 355 | @end deffn |
32de1aa7 AW |
356 | |
357 | For example: | |
358 | ||
359 | @example | |
360 | (string->header "Content-Length") | |
361 | @result{} content-length | |
362 | (header->string 'content-length) | |
363 | @result{} "Content-Length" | |
364 | ||
365 | (string->header "FOO") | |
366 | @result{} foo | |
5ec48b70 | 367 | (header->string 'foo) |
32de1aa7 AW |
368 | @result{} "Foo" |
369 | @end example | |
370 | ||
371 | Guile keeps a registry of known headers, their string names, and some | |
372 | parsing and serialization procedures. If a header is unknown, its | |
373 | string name is simply its symbol name in title-case. | |
374 | ||
2e6f5ea4 | 375 | @deffn {Scheme Procedure} known-header? sym |
a4b4fbbd JE |
376 | Return @code{#t} if @var{sym} is a known header, with associated |
377 | parsers and serialization procedures, or @code{#f} otherwise. | |
2e6f5ea4 | 378 | @end deffn |
32de1aa7 | 379 | |
2e6f5ea4 | 380 | @deffn {Scheme Procedure} header-parser sym |
32de1aa7 AW |
381 | Return the value parser for headers named @var{sym}. The result is a |
382 | procedure that takes one argument, a string, and returns the parsed | |
383 | value. If the header isn't known to Guile, a default parser is returned | |
384 | that passes through the string unchanged. | |
2e6f5ea4 | 385 | @end deffn |
32de1aa7 | 386 | |
2e6f5ea4 | 387 | @deffn {Scheme Procedure} header-validator sym |
32de1aa7 AW |
388 | Return a predicate which returns @code{#t} if the given value is valid |
389 | for headers named @var{sym}. The default validator for unknown headers | |
390 | is @code{string?}. | |
2e6f5ea4 | 391 | @end deffn |
32de1aa7 | 392 | |
2e6f5ea4 | 393 | @deffn {Scheme Procedure} header-writer sym |
32de1aa7 AW |
394 | Return a procedure that writes values for headers named @var{sym} to a |
395 | port. The resulting procedure takes two arguments: a value and a port. | |
396 | The default writer is @code{display}. | |
2e6f5ea4 | 397 | @end deffn |
32de1aa7 AW |
398 | |
399 | For more on the set of headers that Guile knows about out of the box, | |
400 | @pxref{HTTP Headers}. To add your own, use the @code{declare-header!} | |
401 | procedure: | |
402 | ||
dc871261 DH |
403 | @deffn {Scheme Procedure} declare-header! name parser validator writer @ |
404 | [#:multiple?=@code{#f}] | |
32de1aa7 | 405 | Declare a parser, validator, and writer for a given header. |
2e6f5ea4 | 406 | @end deffn |
8db7e094 | 407 | |
929ccf48 AW |
408 | For example, let's say you are running a web server behind some sort of |
409 | proxy, and your proxy adds an @code{X-Client-Address} header, indicating | |
410 | the IPv4 address of the original client. You would like for the HTTP | |
411 | request record to parse out this header to a Scheme value, instead of | |
412 | leaving it as a string. You could register this header with Guile's | |
413 | HTTP stack like this: | |
414 | ||
415 | @example | |
32de1aa7 AW |
416 | (declare-header! "X-Client-Address" |
417 | (lambda (str) | |
418 | (inet-aton str)) | |
419 | (lambda (ip) | |
420 | (and (integer? ip) (exact? ip) (<= 0 ip #xffffffff))) | |
421 | (lambda (ip port) | |
422 | (display (inet-ntoa ip) port))) | |
929ccf48 AW |
423 | @end example |
424 | ||
64ead01d IP |
425 | @deffn {Scheme Procedure} declare-opaque-header! name |
426 | A specialised version of @code{declare-header!} for the case in which | |
427 | you want a header's value to be returned/written ``as-is''. | |
428 | @end deffn | |
429 | ||
2e6f5ea4 | 430 | @deffn {Scheme Procedure} valid-header? sym val |
a4b4fbbd JE |
431 | Return a true value if @var{val} is a valid Scheme value for the header |
432 | with name @var{sym}, or @code{#f} otherwise. | |
2e6f5ea4 | 433 | @end deffn |
8db7e094 | 434 | |
299cd1a2 AW |
435 | Now that we have a generic interface for reading and writing headers, we |
436 | do just that. | |
437 | ||
2e6f5ea4 | 438 | @deffn {Scheme Procedure} read-header port |
929ccf48 | 439 | Read one HTTP header from @var{port}. Return two values: the header |
8db7e094 AW |
440 | name and the parsed Scheme value. May raise an exception if the header |
441 | was known but the value was invalid. | |
442 | ||
929ccf48 AW |
443 | Returns the end-of-file object for both values if the end of the message |
444 | body was reached (i.e., a blank line). | |
2e6f5ea4 | 445 | @end deffn |
8db7e094 | 446 | |
2e6f5ea4 | 447 | @deffn {Scheme Procedure} parse-header name val |
8db7e094 | 448 | Parse @var{val}, a string, with the parser for the header named |
32de1aa7 | 449 | @var{name}. Returns the parsed value. |
2e6f5ea4 | 450 | @end deffn |
8db7e094 | 451 | |
2e6f5ea4 | 452 | @deffn {Scheme Procedure} write-header name val port |
32de1aa7 AW |
453 | Write the given header name and value to @var{port}, using the writer |
454 | from @code{header-writer}. | |
2e6f5ea4 | 455 | @end deffn |
8db7e094 | 456 | |
2e6f5ea4 | 457 | @deffn {Scheme Procedure} read-headers port |
06883ae0 DH |
458 | Read the headers of an HTTP message from @var{port}, returning them |
459 | as an ordered alist. | |
2e6f5ea4 | 460 | @end deffn |
8db7e094 | 461 | |
2e6f5ea4 | 462 | @deffn {Scheme Procedure} write-headers headers port |
8db7e094 | 463 | Write the given header alist to @var{port}. Doesn't write the final |
32de1aa7 | 464 | @samp{\r\n}, as the user might want to add another header. |
2e6f5ea4 | 465 | @end deffn |
8db7e094 | 466 | |
299cd1a2 AW |
467 | The @code{(web http)} module also has some utility procedures to read |
468 | and write request and response lines. | |
469 | ||
2e6f5ea4 | 470 | @deffn {Scheme Procedure} parse-http-method str [start] [end] |
8db7e094 AW |
471 | Parse an HTTP method from @var{str}. The result is an upper-case symbol, |
472 | like @code{GET}. | |
2e6f5ea4 | 473 | @end deffn |
8db7e094 | 474 | |
2e6f5ea4 | 475 | @deffn {Scheme Procedure} parse-http-version str [start] [end] |
dc871261 | 476 | Parse an HTTP version from @var{str}, returning it as a major--minor |
8db7e094 AW |
477 | pair. For example, @code{HTTP/1.1} parses as the pair of integers, |
478 | @code{(1 . 1)}. | |
2e6f5ea4 | 479 | @end deffn |
8db7e094 | 480 | |
2e6f5ea4 | 481 | @deffn {Scheme Procedure} parse-request-uri str [start] [end] |
8db7e094 AW |
482 | Parse a URI from an HTTP request line. Note that URIs in requests do not |
483 | have to have a scheme or host name. The result is a URI object. | |
2e6f5ea4 | 484 | @end deffn |
8db7e094 | 485 | |
2e6f5ea4 | 486 | @deffn {Scheme Procedure} read-request-line port |
8db7e094 AW |
487 | Read the first line of an HTTP request from @var{port}, returning three |
488 | values: the method, the URI, and the version. | |
2e6f5ea4 | 489 | @end deffn |
8db7e094 | 490 | |
2e6f5ea4 | 491 | @deffn {Scheme Procedure} write-request-line method uri version port |
8db7e094 | 492 | Write the first line of an HTTP request to @var{port}. |
2e6f5ea4 | 493 | @end deffn |
8db7e094 | 494 | |
2e6f5ea4 | 495 | @deffn {Scheme Procedure} read-response-line port |
8db7e094 | 496 | Read the first line of an HTTP response from @var{port}, returning three |
dc871261 | 497 | values: the HTTP version, the response code, and the ``reason phrase''. |
2e6f5ea4 | 498 | @end deffn |
8db7e094 | 499 | |
2e6f5ea4 | 500 | @deffn {Scheme Procedure} write-response-line version code reason-phrase port |
8db7e094 | 501 | Write the first line of an HTTP response to @var{port}. |
2e6f5ea4 | 502 | @end deffn |
8db7e094 AW |
503 | |
504 | ||
1148d029 AW |
505 | @node HTTP Headers |
506 | @subsection HTTP Headers | |
507 | ||
ff8339db AW |
508 | In addition to defining the infrastructure to parse headers, the |
509 | @code{(web http)} module defines specific parsers and unparsers for all | |
510 | headers defined in the HTTP/1.1 standard. | |
1148d029 | 511 | |
ff8339db AW |
512 | For example, if you receive a header named @samp{Accept-Language} with a |
513 | value @samp{en, es;q=0.8}, Guile parses it as a quality list (defined | |
514 | below): | |
515 | ||
516 | @example | |
517 | (parse-header 'accept-language "en, es;q=0.8") | |
518 | @result{} ((1000 . "en") (800 . "es")) | |
519 | @end example | |
520 | ||
521 | The format of the value for @samp{Accept-Language} headers is defined | |
522 | below, along with all other headers defined in the HTTP standard. (If | |
523 | the header were unknown, the value would have been returned as a | |
524 | string.) | |
525 | ||
526 | For brevity, the header definitions below are given in the form, | |
527 | @var{Type} @code{@var{name}}, indicating that values for the header | |
528 | @code{@var{name}} will be of the given @var{Type}. Since Guile | |
529 | internally treats header names in lower case, in this document we give | |
530 | types title-cased names. A short description of the each header's | |
531 | purpose and an example follow. | |
532 | ||
533 | For full details on the meanings of all of these headers, see the HTTP | |
534 | 1.1 standard, RFC 2616. | |
535 | ||
536 | @subsubsection HTTP Header Types | |
537 | ||
538 | Here we define the types that are used below, when defining headers. | |
539 | ||
540 | @deftp {HTTP Header Type} Date | |
541 | A SRFI-19 date. | |
542 | @end deftp | |
543 | ||
544 | @deftp {HTTP Header Type} KVList | |
545 | A list whose elements are keys or key-value pairs. Keys are parsed to | |
546 | symbols. Values are strings by default. Non-string values are the | |
547 | exception, and are mentioned explicitly below, as appropriate. | |
548 | @end deftp | |
549 | ||
550 | @deftp {HTTP Header Type} SList | |
551 | A list of strings. | |
552 | @end deftp | |
553 | ||
554 | @deftp {HTTP Header Type} Quality | |
555 | An exact integer between 0 and 1000. Qualities are used to express | |
556 | preference, given multiple options. An option with a quality of 870, | |
557 | for example, is preferred over an option with quality 500. | |
558 | ||
559 | (Qualities are written out over the wire as numbers between 0.0 and | |
560 | 1.0, but since the standard only allows three digits after the decimal, | |
561 | it's equivalent to integers between 0 and 1000, so that's what Guile | |
562 | uses.) | |
563 | @end deftp | |
564 | ||
565 | @deftp {HTTP Header Type} QList | |
566 | A quality list: a list of pairs, the car of which is a quality, and the | |
567 | cdr a string. Used to express a list of options, along with their | |
568 | qualities. | |
569 | @end deftp | |
570 | ||
571 | @deftp {HTTP Header Type} ETag | |
572 | An entity tag, represented as a pair. The car of the pair is an opaque | |
573 | string, and the cdr is @code{#t} if the entity tag is a ``strong'' entity | |
574 | tag, and @code{#f} otherwise. | |
575 | @end deftp | |
1148d029 AW |
576 | |
577 | @subsubsection General Headers | |
578 | ||
ff8339db AW |
579 | General HTTP headers may be present in any HTTP message. |
580 | ||
581 | @deftypevr {HTTP Header} KVList cache-control | |
582 | A key-value list of cache-control directives. See RFC 2616, for more | |
583 | details. | |
1148d029 AW |
584 | |
585 | If present, parameters to @code{max-age}, @code{max-stale}, | |
586 | @code{min-fresh}, and @code{s-maxage} are all parsed as non-negative | |
587 | integers. | |
588 | ||
589 | If present, parameters to @code{private} and @code{no-cache} are parsed | |
ff8339db | 590 | as lists of header names, as symbols. |
1148d029 | 591 | |
ff8339db AW |
592 | @example |
593 | (parse-header 'cache-control "no-cache,no-store" | |
594 | @result{} (no-cache no-store) | |
595 | (parse-header 'cache-control "no-cache=\"Authorization,Date\",no-store" | |
596 | @result{} ((no-cache . (authorization date)) no-store) | |
597 | (parse-header 'cache-control "no-cache=\"Authorization,Date\",max-age=10" | |
598 | @result{} ((no-cache . (authorization date)) (max-age . 10)) | |
599 | @end example | |
600 | @end deftypevr | |
1148d029 | 601 | |
ff8339db AW |
602 | @deftypevr {HTTP Header} List connection |
603 | A list of header names that apply only to this HTTP connection, as | |
604 | symbols. Additionally, the symbol @samp{close} may be present, to | |
605 | indicate that the server should close the connection after responding to | |
606 | the request. | |
607 | @example | |
608 | (parse-header 'connection "close") | |
609 | @result{} (close) | |
610 | @end example | |
611 | @end deftypevr | |
1148d029 | 612 | |
ff8339db AW |
613 | @deftypevr {HTTP Header} Date date |
614 | The date that a given HTTP message was originated. | |
615 | @example | |
616 | (parse-header 'date "Tue, 15 Nov 1994 08:12:31 GMT") | |
617 | @result{} #<date ...> | |
618 | @end example | |
619 | @end deftypevr | |
1148d029 | 620 | |
ff8339db AW |
621 | @deftypevr {HTTP Header} KVList pragma |
622 | A key-value list of implementation-specific directives. | |
623 | @example | |
624 | (parse-header 'pragma "no-cache, broccoli=tasty") | |
625 | @result{} (no-cache (broccoli . "tasty")) | |
626 | @end example | |
627 | @end deftypevr | |
1148d029 | 628 | |
ff8339db AW |
629 | @deftypevr {HTTP Header} List trailer |
630 | A list of header names which will appear after the message body, instead | |
631 | of with the message headers. | |
632 | @example | |
633 | (parse-header 'trailer "ETag") | |
634 | @result{} (etag) | |
635 | @end example | |
636 | @end deftypevr | |
1148d029 | 637 | |
ff8339db AW |
638 | @deftypevr {HTTP Header} List transfer-encoding |
639 | A list of transfer codings, expressed as key-value lists. The only | |
640 | transfer coding defined by the specification is @code{chunked}. | |
641 | @example | |
642 | (parse-header 'transfer-encoding "chunked") | |
07154109 | 643 | @result{} ((chunked)) |
ff8339db AW |
644 | @end example |
645 | @end deftypevr | |
1148d029 | 646 | |
ff8339db AW |
647 | @deftypevr {HTTP Header} List upgrade |
648 | A list of strings, indicating additional protocols that a server could use | |
649 | in response to a request. | |
650 | @example | |
651 | (parse-header 'upgrade "WebSocket") | |
652 | @result{} ("WebSocket") | |
653 | @end example | |
654 | @end deftypevr | |
1148d029 | 655 | |
ff8339db AW |
656 | FIXME: parse out more fully? |
657 | @deftypevr {HTTP Header} List via | |
658 | A list of strings, indicating the protocol versions and hosts of | |
659 | intermediate servers and proxies. There may be multiple @code{via} | |
660 | headers in one message. | |
661 | @example | |
662 | (parse-header 'via "1.0 venus, 1.1 mars") | |
663 | @result{} ("1.0 venus" "1.1 mars") | |
664 | @end example | |
665 | @end deftypevr | |
666 | ||
667 | @deftypevr {HTTP Header} List warning | |
668 | A list of warnings given by a server or intermediate proxy. Each | |
669 | warning is a itself a list of four elements: a code, as an exact integer | |
670 | between 0 and 1000, a host as a string, the warning text as a string, | |
671 | and either @code{#f} or a SRFI-19 date. | |
1148d029 AW |
672 | |
673 | There may be multiple @code{warning} headers in one message. | |
ff8339db AW |
674 | @example |
675 | (parse-header 'warning "123 foo \"core breach imminent\"") | |
676 | @result{} ((123 "foo" "core-breach imminent" #f)) | |
677 | @end example | |
678 | @end deftypevr | |
1148d029 AW |
679 | |
680 | ||
681 | @subsubsection Entity Headers | |
682 | ||
ff8339db AW |
683 | Entity headers may be present in any HTTP message, and refer to the |
684 | resource referenced in the HTTP request or response. | |
1148d029 | 685 | |
ff8339db AW |
686 | @deftypevr {HTTP Header} List allow |
687 | A list of allowed methods on a given resource, as symbols. | |
688 | @example | |
689 | (parse-header 'allow "GET, HEAD") | |
690 | @result{} (GET HEAD) | |
691 | @end example | |
692 | @end deftypevr | |
1148d029 | 693 | |
ff8339db AW |
694 | @deftypevr {HTTP Header} List content-encoding |
695 | A list of content codings, as symbols. | |
696 | @example | |
697 | (parse-header 'content-encoding "gzip") | |
d540a1d6 | 698 | @result{} (gzip) |
ff8339db AW |
699 | @end example |
700 | @end deftypevr | |
1148d029 | 701 | |
ff8339db AW |
702 | @deftypevr {HTTP Header} List content-language |
703 | The languages that a resource is in, as strings. | |
704 | @example | |
705 | (parse-header 'content-language "en") | |
706 | @result{} ("en") | |
707 | @end example | |
708 | @end deftypevr | |
1148d029 | 709 | |
ff8339db AW |
710 | @deftypevr {HTTP Header} UInt content-length |
711 | The number of bytes in a resource, as an exact, non-negative integer. | |
712 | @example | |
713 | (parse-header 'content-length "300") | |
714 | @result{} 300 | |
715 | @end example | |
716 | @end deftypevr | |
1148d029 | 717 | |
ff8339db AW |
718 | @deftypevr {HTTP Header} URI content-location |
719 | The canonical URI for a resource, in the case that it is also accessible | |
720 | from a different URI. | |
721 | @example | |
722 | (parse-header 'content-location "http://example.com/foo") | |
723 | @result{} #<<uri> ...> | |
724 | @end example | |
725 | @end deftypevr | |
1148d029 | 726 | |
ff8339db AW |
727 | @deftypevr {HTTP Header} String content-md5 |
728 | The MD5 digest of a resource. | |
729 | @example | |
730 | (parse-header 'content-md5 "ffaea1a79810785575e29e2bd45e2fa5") | |
731 | @result{} "ffaea1a79810785575e29e2bd45e2fa5" | |
732 | @end example | |
733 | @end deftypevr | |
734 | ||
735 | @deftypevr {HTTP Header} List content-range | |
736 | A range specification, as a list of three elements: the symbol | |
737 | @code{bytes}, either the symbol @code{*} or a pair of integers, | |
738 | indicating the byte rage, and either @code{*} or an integer, for the | |
739 | instance length. Used to indicate that a response only includes part of | |
740 | a resource. | |
741 | @example | |
742 | (parse-header 'content-range "bytes 10-20/*") | |
743 | @result{} (bytes (10 . 20) *) | |
744 | @end example | |
745 | @end deftypevr | |
1148d029 | 746 | |
ff8339db AW |
747 | @deftypevr {HTTP Header} List content-type |
748 | The MIME type of a resource, as a symbol, along with any parameters. | |
749 | @example | |
750 | (parse-header 'content-length "text/plain") | |
751 | @result{} (text/plain) | |
752 | (parse-header 'content-length "text/plain;charset=utf-8") | |
753 | @result{} (text/plain (charset . "utf-8")) | |
754 | @end example | |
755 | Note that the @code{charset} parameter is something is a misnomer, and | |
756 | the HTTP specification admits this. It specifies the @emph{encoding} of | |
757 | the characters, not the character set. | |
758 | @end deftypevr | |
759 | ||
760 | @deftypevr {HTTP Header} Date expires | |
761 | The date/time after which the resource given in a response is considered | |
762 | stale. | |
763 | @example | |
764 | (parse-header 'expires "Tue, 15 Nov 1994 08:12:31 GMT") | |
765 | @result{} #<date ...> | |
766 | @end example | |
767 | @end deftypevr | |
58baff08 | 768 | |
ff8339db AW |
769 | @deftypevr {HTTP Header} Date last-modified |
770 | The date/time on which the resource given in a response was last | |
771 | modified. | |
772 | @example | |
773 | (parse-header 'expires "Tue, 15 Nov 1994 08:12:31 GMT") | |
774 | @result{} #<date ...> | |
775 | @end example | |
776 | @end deftypevr | |
1148d029 AW |
777 | |
778 | ||
779 | @subsubsection Request Headers | |
780 | ||
ff8339db | 781 | Request headers may only appear in an HTTP request, not in a response. |
1148d029 | 782 | |
ff8339db AW |
783 | @deftypevr {HTTP Header} List accept |
784 | A list of preferred media types for a response. Each element of the | |
785 | list is itself a list, in the same format as @code{content-type}. | |
786 | @example | |
787 | (parse-header 'accept "text/html,text/plain;charset=utf-8") | |
788 | @result{} ((text/html) (text/plain (charset . "utf-8"))) | |
789 | @end example | |
ecb87335 | 790 | Preference is expressed with quality values: |
ff8339db AW |
791 | @example |
792 | (parse-header 'accept "text/html;q=0.8,text/plain;q=0.6") | |
793 | @result{} ((text/html (q . 800)) (text/plain (q . 600))) | |
794 | @end example | |
795 | @end deftypevr | |
1148d029 | 796 | |
ff8339db AW |
797 | @deftypevr {HTTP Header} QList accept-charset |
798 | A quality list of acceptable charsets. Note again that what HTTP calls | |
799 | a ``charset'' is what Guile calls a ``character encoding''. | |
800 | @example | |
801 | (parse-header 'accept-charset "iso-8859-5, unicode-1-1;q=0.8") | |
802 | @result{} ((1000 . "iso-8859-5") (800 . "unicode-1-1")) | |
803 | @end example | |
804 | @end deftypevr | |
1148d029 | 805 | |
ff8339db AW |
806 | @deftypevr {HTTP Header} QList accept-encoding |
807 | A quality list of acceptable content codings. | |
808 | @example | |
809 | (parse-header 'accept-encoding "gzip,identity=0.8") | |
810 | @result{} ((1000 . "gzip") (800 . "identity")) | |
811 | @end example | |
812 | @end deftypevr | |
1148d029 | 813 | |
ff8339db AW |
814 | @deftypevr {HTTP Header} QList accept-language |
815 | A quality list of acceptable languages. | |
816 | @example | |
817 | (parse-header 'accept-language "cn,en=0.75") | |
818 | @result{} ((1000 . "cn") (750 . "en")) | |
819 | @end example | |
820 | @end deftypevr | |
821 | ||
822 | @deftypevr {HTTP Header} Pair authorization | |
823 | Authorization credentials. The car of the pair indicates the | |
824 | authentication scheme, like @code{basic}. For basic authentication, the | |
825 | cdr of the pair will be the base64-encoded @samp{@var{user}:@var{pass}} | |
826 | string. For other authentication schemes, like @code{digest}, the cdr | |
827 | will be a key-value list of credentials. | |
828 | @example | |
829 | (parse-header 'authorization "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" | |
830 | @result{} (basic . "QWxhZGRpbjpvcGVuIHNlc2FtZQ==") | |
831 | @end example | |
832 | @end deftypevr | |
1148d029 | 833 | |
ff8339db AW |
834 | @deftypevr {HTTP Header} List expect |
835 | A list of expectations that a client has of a server. The expectations | |
836 | are key-value lists. | |
837 | @example | |
838 | (parse-header 'expect "100-continue") | |
839 | @result{} ((100-continue)) | |
840 | @end example | |
841 | @end deftypevr | |
1148d029 | 842 | |
ff8339db AW |
843 | @deftypevr {HTTP Header} String from |
844 | The email address of a user making an HTTP request. | |
845 | @example | |
846 | (parse-header 'from "bob@@example.com") | |
847 | @result{} "bob@@example.com" | |
848 | @end example | |
849 | @end deftypevr | |
1148d029 | 850 | |
ff8339db AW |
851 | @deftypevr {HTTP Header} Pair host |
852 | The host for the resource being requested, as a hostname-port pair. If | |
853 | no port is given, the port is @code{#f}. | |
854 | @example | |
855 | (parse-header 'host "gnu.org:80") | |
856 | @result{} ("gnu.org" . 80) | |
857 | (parse-header 'host "gnu.org") | |
858 | @result{} ("gnu.org" . #f) | |
859 | @end example | |
860 | @end deftypevr | |
1148d029 | 861 | |
ff8339db AW |
862 | @deftypevr {HTTP Header} *|List if-match |
863 | A set of etags, indicating that the request should proceed if and only | |
864 | if the etag of the resource is in that set. Either the symbol @code{*}, | |
865 | indicating any etag, or a list of entity tags. | |
866 | @example | |
867 | (parse-header 'if-match "*") | |
868 | @result{} * | |
869 | (parse-header 'if-match "asdfadf") | |
870 | @result{} (("asdfadf" . #t)) | |
871 | (parse-header 'if-match W/"asdfadf") | |
872 | @result{} (("asdfadf" . #f)) | |
873 | @end example | |
874 | @end deftypevr | |
1148d029 | 875 | |
ff8339db AW |
876 | @deftypevr {HTTP Header} Date if-modified-since |
877 | Indicates that a response should proceed if and only if the resource has | |
878 | been modified since the given date. | |
879 | @example | |
654ef4cf | 880 | (parse-header 'if-modified-since "Tue, 15 Nov 1994 08:12:31 GMT") |
ff8339db AW |
881 | @result{} #<date ...> |
882 | @end example | |
883 | @end deftypevr | |
1148d029 | 884 | |
ff8339db AW |
885 | @deftypevr {HTTP Header} *|List if-none-match |
886 | A set of etags, indicating that the request should proceed if and only | |
887 | if the etag of the resource is not in the set. Either the symbol | |
888 | @code{*}, indicating any etag, or a list of entity tags. | |
889 | @example | |
890 | (parse-header 'if-none-match "*") | |
891 | @result{} * | |
892 | @end example | |
893 | @end deftypevr | |
1148d029 | 894 | |
ff8339db AW |
895 | @deftypevr {HTTP Header} ETag|Date if-range |
896 | Indicates that the range request should proceed if and only if the | |
897 | resource matches a modification date or an etag. Either an entity tag, | |
898 | or a SRFI-19 date. | |
899 | @example | |
900 | (parse-header 'if-range "\"original-etag\"") | |
901 | @result{} ("original-etag" . #t) | |
902 | @end example | |
903 | @end deftypevr | |
1148d029 | 904 | |
ff8339db AW |
905 | @deftypevr {HTTP Header} Date if-unmodified-since |
906 | Indicates that a response should proceed if and only if the resource has | |
907 | not been modified since the given date. | |
908 | @example | |
909 | (parse-header 'if-not-modified-since "Tue, 15 Nov 1994 08:12:31 GMT") | |
910 | @result{} #<date ...> | |
911 | @end example | |
912 | @end deftypevr | |
1148d029 | 913 | |
ff8339db AW |
914 | @deftypevr {HTTP Header} UInt max-forwards |
915 | The maximum number of proxy or gateway hops that a request should be | |
916 | subject to. | |
917 | @example | |
918 | (parse-header 'max-forwards "10") | |
919 | @result{} 10 | |
920 | @end example | |
921 | @end deftypevr | |
1148d029 | 922 | |
ff8339db AW |
923 | @deftypevr {HTTP Header} Pair proxy-authorization |
924 | Authorization credentials for a proxy connection. See the documentation | |
925 | for @code{authorization} above for more information on the format. | |
926 | @example | |
927 | (parse-header 'proxy-authorization "Digest foo=bar,baz=qux" | |
928 | @result{} (digest (foo . "bar") (baz . "qux")) | |
929 | @end example | |
930 | @end deftypevr | |
931 | ||
932 | @deftypevr {HTTP Header} Pair range | |
933 | A range request, indicating that the client wants only part of a | |
934 | resource. The car of the pair is the symbol @code{bytes}, and the cdr | |
935 | is a list of pairs. Each element of the cdr indicates a range; the car | |
936 | is the first byte position and the cdr is the last byte position, as | |
937 | integers, or @code{#f} if not given. | |
938 | @example | |
939 | (parse-header 'range "bytes=10-30,50-") | |
940 | @result{} (bytes (10 . 30) (50 . #f)) | |
941 | @end example | |
942 | @end deftypevr | |
1148d029 | 943 | |
ff8339db AW |
944 | @deftypevr {HTTP Header} URI referer |
945 | The URI of the resource that referred the user to this resource. The | |
946 | name of the header is a misspelling, but we are stuck with it. | |
947 | @example | |
948 | (parse-header 'referer "http://www.gnu.org/") | |
949 | @result{} #<uri ...> | |
950 | @end example | |
951 | @end deftypevr | |
1148d029 | 952 | |
ff8339db AW |
953 | @deftypevr {HTTP Header} List te |
954 | A list of transfer codings, expressed as key-value lists. A common | |
955 | transfer coding is @code{trailers}. | |
956 | @example | |
957 | (parse-header 'te "trailers") | |
958 | @result{} ((trailers)) | |
959 | @end example | |
960 | @end deftypevr | |
1148d029 | 961 | |
ff8339db AW |
962 | @deftypevr {HTTP Header} String user-agent |
963 | A string indicating the user agent making the request. The | |
964 | specification defines a structured format for this header, but it is | |
965 | widely disregarded, so Guile does not attempt to parse strictly. | |
966 | @example | |
967 | (parse-header 'user-agent "Mozilla/5.0") | |
968 | @result{} "Mozilla/5.0" | |
969 | @end example | |
970 | @end deftypevr | |
1148d029 AW |
971 | |
972 | ||
973 | @subsubsection Response Headers | |
974 | ||
ff8339db AW |
975 | @deftypevr {HTTP Header} List accept-ranges |
976 | A list of range units that the server supports, as symbols. | |
977 | @example | |
978 | (parse-header 'accept-ranges "bytes") | |
979 | @result{} (bytes) | |
980 | @end example | |
981 | @end deftypevr | |
1148d029 | 982 | |
ff8339db AW |
983 | @deftypevr {HTTP Header} UInt age |
984 | The age of a cached response, in seconds. | |
985 | @example | |
986 | (parse-header 'age "3600") | |
987 | @result{} 3600 | |
988 | @end example | |
989 | @end deftypevr | |
1148d029 | 990 | |
ff8339db AW |
991 | @deftypevr {HTTP Header} ETag etag |
992 | The entity-tag of the resource. | |
993 | @example | |
994 | (parse-header 'etag "\"foo\"") | |
995 | @result{} ("foo" . #t) | |
996 | @end example | |
997 | @end deftypevr | |
1148d029 | 998 | |
d64146f2 AW |
999 | @deftypevr {HTTP Header} URI-reference location |
1000 | A URI reference on which a request may be completed. Used in | |
1001 | combination with a redirecting status code to perform client-side | |
1002 | redirection. | |
ff8339db AW |
1003 | @example |
1004 | (parse-header 'location "http://example.com/other") | |
1005 | @result{} #<uri ...> | |
1006 | @end example | |
1007 | @end deftypevr | |
1148d029 | 1008 | |
ff8339db AW |
1009 | @deftypevr {HTTP Header} List proxy-authenticate |
1010 | A list of challenges to a proxy, indicating the need for authentication. | |
1011 | @example | |
1012 | (parse-header 'proxy-authenticate "Basic realm=\"foo\"") | |
1013 | @result{} ((basic (realm . "foo"))) | |
1014 | @end example | |
1015 | @end deftypevr | |
1148d029 | 1016 | |
ff8339db AW |
1017 | @deftypevr {HTTP Header} UInt|Date retry-after |
1018 | Used in combination with a server-busy status code, like 503, to | |
1019 | indicate that a client should retry later. Either a number of seconds, | |
1020 | or a date. | |
1021 | @example | |
1022 | (parse-header 'retry-after "60") | |
1023 | @result{} 60 | |
1024 | @end example | |
1025 | @end deftypevr | |
1148d029 | 1026 | |
ff8339db AW |
1027 | @deftypevr {HTTP Header} String server |
1028 | A string identifying the server. | |
1029 | @example | |
1030 | (parse-header 'server "My first web server") | |
1031 | @result{} "My first web server" | |
1032 | @end example | |
1033 | @end deftypevr | |
1148d029 | 1034 | |
ff8339db AW |
1035 | @deftypevr {HTTP Header} *|List vary |
1036 | A set of request headers that were used in computing this response. | |
ecb87335 | 1037 | Used to indicate that server-side content negotiation was performed, for |
ff8339db AW |
1038 | example in response to the @code{accept-language} header. Can also be |
1039 | the symbol @code{*}, indicating that all headers were considered. | |
1040 | @example | |
1041 | (parse-header 'vary "Accept-Language, Accept") | |
1042 | @result{} (accept-language accept) | |
1043 | @end example | |
1044 | @end deftypevr | |
1148d029 | 1045 | |
ff8339db AW |
1046 | @deftypevr {HTTP Header} List www-authenticate |
1047 | A list of challenges to a user, indicating the need for authentication. | |
1048 | @example | |
1049 | (parse-header 'www-authenticate "Basic realm=\"foo\"") | |
1050 | @result{} ((basic (realm . "foo"))) | |
1051 | @end example | |
1052 | @end deftypevr | |
1148d029 | 1053 | |
312e79f8 IP |
1054 | @node Transfer Codings |
1055 | @subsection Transfer Codings | |
1056 | ||
1057 | HTTP 1.1 allows for various transfer codings to be applied to message | |
1058 | bodies. These include various types of compression, and HTTP chunked | |
1059 | encoding. Currently, only chunked encoding is supported by guile. | |
1060 | ||
1061 | Chunked coding is an optional coding that may be applied to message | |
1062 | bodies, to allow messages whose length is not known beforehand to be | |
1063 | returned. Such messages can be split into chunks, terminated by a final | |
1064 | zero length chunk. | |
1065 | ||
1066 | In order to make dealing with encodings more simple, guile provides | |
1067 | procedures to create ports that ``wrap'' existing ports, applying | |
1068 | transformations transparently under the hood. | |
1069 | ||
32299e49 AW |
1070 | These procedures are in the @code{(web http)} module. |
1071 | ||
1072 | @example | |
1073 | (use-modules (web http)) | |
1074 | @end example | |
1075 | ||
312e79f8 IP |
1076 | @deffn {Scheme Procedure} make-chunked-input-port port [#:keep-alive?=#f] |
1077 | Returns a new port, that transparently reads and decodes chunk-encoded | |
1078 | data from @var{port}. If no more chunk-encoded data is available, it | |
1079 | returns the end-of-file object. When the port is closed, @var{port} will | |
1080 | also be closed, unless @var{keep-alive?} is true. | |
1081 | @end deffn | |
1082 | ||
1083 | @example | |
1084 | (use-modules (ice-9 rdelim)) | |
1085 | ||
1086 | (define s "5\r\nFirst\r\nA\r\n line\n Sec\r\n8\r\nond line\r\n0\r\n") | |
1087 | (define p (make-chunked-input-port (open-input-string s))) | |
1088 | (read-line s) | |
1089 | @result{} "First line" | |
1090 | (read-line s) | |
1091 | @result{} "Second line" | |
1092 | @end example | |
1093 | ||
1094 | @deffn {Scheme Procedure} make-chunked-output-port port [#:keep-alive?=#f] | |
1095 | Returns a new port, which transparently encodes data as chunk-encoded | |
1096 | before writing it to @var{port}. Whenever a write occurs on this port, | |
1097 | it buffers it, until the port is flushed, at which point it writes a | |
1098 | chunk containing all the data written so far. When the port is closed, | |
1099 | the data remaining is written to @var{port}, as is the terminating zero | |
1100 | chunk. It also causes @var{port} to be closed, unless @var{keep-alive?} | |
1101 | is true. | |
1102 | ||
1103 | Note. Forcing a chunked output port when there is no data is buffered | |
1104 | does not write a zero chunk, as this would cause the data to be | |
1105 | interpreted incorrectly by the client. | |
1106 | @end deffn | |
1107 | ||
1108 | @example | |
1109 | (call-with-output-string | |
1110 | (lambda (out) | |
1111 | (define out* (make-chunked-output-port out #:keep-alive? #t)) | |
1112 | (display "first chunk" out*) | |
1113 | (force-output out*) | |
1114 | (force-output out*) ; note this does not write a zero chunk | |
1115 | (display "second chunk" out*) | |
1116 | (close-port out*))) | |
1117 | @result{} "b\r\nfirst chunk\r\nc\r\nsecond chunk\r\n0\r\n" | |
1118 | @end example | |
1148d029 | 1119 | |
8db7e094 AW |
1120 | @node Requests |
1121 | @subsection HTTP Requests | |
1122 | ||
1123 | @example | |
1124 | (use-modules (web request)) | |
1125 | @end example | |
1126 | ||
de54fb6d | 1127 | The request module contains a data type for HTTP requests. |
8db7e094 | 1128 | |
de54fb6d AW |
1129 | @subsubsection An Important Note on Character Sets |
1130 | ||
1131 | HTTP requests consist of two parts: the request proper, consisting of a | |
1132 | request line and a set of headers, and (optionally) a body. The body | |
1133 | might have a binary content-type, and even in the textual case its | |
1134 | length is specified in bytes, not characters. | |
1135 | ||
1136 | Therefore, HTTP is a fundamentally binary protocol. However the request | |
1137 | line and headers are specified to be in a subset of ASCII, so they can | |
1138 | be treated as text, provided that the port's encoding is set to an | |
1139 | ASCII-compatible one-byte-per-character encoding. ISO-8859-1 (latin-1) | |
1140 | is just such an encoding, and happens to be very efficient for Guile. | |
1141 | ||
1142 | So what Guile does when reading requests from the wire, or writing them | |
1143 | out, is to set the port's encoding to latin-1, and treating the request | |
1144 | headers as text. | |
1145 | ||
1146 | The request body is another issue. For binary data, the data is | |
1147 | probably in a bytevector, so we use the R6RS binary output procedures to | |
1148 | write out the binary payload. Textual data usually has to be written | |
1149 | out to some character encoding, usually UTF-8, and then the resulting | |
1150 | bytevector is written out to the port. | |
1151 | ||
1152 | In summary, Guile reads and writes HTTP over latin-1 sockets, without | |
1153 | any loss of generality. | |
1154 | ||
1155 | @subsubsection Request API | |
8db7e094 | 1156 | |
dc871261 DH |
1157 | @deffn {Scheme Procedure} request? obj |
1158 | @deffnx {Scheme Procedure} request-method request | |
1159 | @deffnx {Scheme Procedure} request-uri request | |
1160 | @deffnx {Scheme Procedure} request-version request | |
1161 | @deffnx {Scheme Procedure} request-headers request | |
1162 | @deffnx {Scheme Procedure} request-meta request | |
1163 | @deffnx {Scheme Procedure} request-port request | |
e471a3ee AW |
1164 | A predicate and field accessors for the request type. The fields are as |
1165 | follows: | |
1166 | @table @code | |
1167 | @item method | |
1168 | The HTTP method, for example, @code{GET}. | |
1169 | @item uri | |
1170 | The URI as a URI record. | |
1171 | @item version | |
1172 | The HTTP version pair, like @code{(1 . 1)}. | |
1173 | @item headers | |
1174 | The request headers, as an alist of parsed values. | |
1175 | @item meta | |
1176 | An arbitrary alist of other data, for example information returned in | |
1177 | the @code{sockaddr} from @code{accept} (@pxref{Network Sockets and | |
1178 | Communication}). | |
1179 | @item port | |
1180 | The port on which to read or write a request body, if any. | |
1181 | @end table | |
2e6f5ea4 | 1182 | @end deffn |
8db7e094 | 1183 | |
2e6f5ea4 | 1184 | @deffn {Scheme Procedure} read-request port [meta='()] |
8db7e094 AW |
1185 | Read an HTTP request from @var{port}, optionally attaching the given |
1186 | metadata, @var{meta}. | |
1187 | ||
1188 | As a side effect, sets the encoding on @var{port} to ISO-8859-1 | |
1189 | (latin-1), so that reading one character reads one byte. See the | |
de54fb6d AW |
1190 | discussion of character sets above, for more information. |
1191 | ||
1192 | Note that the body is not part of the request. Once you have read a | |
1193 | request, you may read the body separately, and likewise for writing | |
1194 | requests. | |
2e6f5ea4 | 1195 | @end deffn |
de54fb6d | 1196 | |
dc871261 DH |
1197 | @deffn {Scheme Procedure} build-request uri [#:method='GET] @ |
1198 | [#:version='(1 . 1)] [#:headers='()] [#:port=#f] [#:meta='()] @ | |
1199 | [#:validate-headers?=#t] | |
de54fb6d AW |
1200 | Construct an HTTP request object. If @var{validate-headers?} is true, |
1201 | the headers are each run through their respective validators. | |
2e6f5ea4 | 1202 | @end deffn |
8db7e094 | 1203 | |
2e6f5ea4 | 1204 | @deffn {Scheme Procedure} write-request r port |
8db7e094 AW |
1205 | Write the given HTTP request to @var{port}. |
1206 | ||
de54fb6d | 1207 | Return a new request, whose @code{request-port} will continue writing |
8db7e094 | 1208 | on @var{port}, perhaps using some transfer encoding. |
2e6f5ea4 | 1209 | @end deffn |
8db7e094 | 1210 | |
2e6f5ea4 | 1211 | @deffn {Scheme Procedure} read-request-body r |
de54fb6d | 1212 | Reads the request body from @var{r}, as a bytevector. Return @code{#f} |
8db7e094 | 1213 | if there was no request body. |
2e6f5ea4 | 1214 | @end deffn |
8db7e094 | 1215 | |
2e6f5ea4 | 1216 | @deffn {Scheme Procedure} write-request-body r bv |
64de6db5 | 1217 | Write @var{bv}, a bytevector, to the port corresponding to the HTTP |
8db7e094 | 1218 | request @var{r}. |
2e6f5ea4 | 1219 | @end deffn |
8db7e094 | 1220 | |
e471a3ee AW |
1221 | The various headers that are typically associated with HTTP requests may |
1222 | be accessed with these dedicated accessors. @xref{HTTP Headers}, for | |
1223 | more information on the format of parsed headers. | |
1224 | ||
2e6f5ea4 AW |
1225 | @deffn {Scheme Procedure} request-accept request [default='()] |
1226 | @deffnx {Scheme Procedure} request-accept-charset request [default='()] | |
1227 | @deffnx {Scheme Procedure} request-accept-encoding request [default='()] | |
1228 | @deffnx {Scheme Procedure} request-accept-language request [default='()] | |
1229 | @deffnx {Scheme Procedure} request-allow request [default='()] | |
1230 | @deffnx {Scheme Procedure} request-authorization request [default=#f] | |
1231 | @deffnx {Scheme Procedure} request-cache-control request [default='()] | |
1232 | @deffnx {Scheme Procedure} request-connection request [default='()] | |
1233 | @deffnx {Scheme Procedure} request-content-encoding request [default='()] | |
1234 | @deffnx {Scheme Procedure} request-content-language request [default='()] | |
1235 | @deffnx {Scheme Procedure} request-content-length request [default=#f] | |
1236 | @deffnx {Scheme Procedure} request-content-location request [default=#f] | |
1237 | @deffnx {Scheme Procedure} request-content-md5 request [default=#f] | |
1238 | @deffnx {Scheme Procedure} request-content-range request [default=#f] | |
1239 | @deffnx {Scheme Procedure} request-content-type request [default=#f] | |
1240 | @deffnx {Scheme Procedure} request-date request [default=#f] | |
1241 | @deffnx {Scheme Procedure} request-expect request [default='()] | |
1242 | @deffnx {Scheme Procedure} request-expires request [default=#f] | |
1243 | @deffnx {Scheme Procedure} request-from request [default=#f] | |
1244 | @deffnx {Scheme Procedure} request-host request [default=#f] | |
1245 | @deffnx {Scheme Procedure} request-if-match request [default=#f] | |
1246 | @deffnx {Scheme Procedure} request-if-modified-since request [default=#f] | |
1247 | @deffnx {Scheme Procedure} request-if-none-match request [default=#f] | |
1248 | @deffnx {Scheme Procedure} request-if-range request [default=#f] | |
1249 | @deffnx {Scheme Procedure} request-if-unmodified-since request [default=#f] | |
1250 | @deffnx {Scheme Procedure} request-last-modified request [default=#f] | |
1251 | @deffnx {Scheme Procedure} request-max-forwards request [default=#f] | |
1252 | @deffnx {Scheme Procedure} request-pragma request [default='()] | |
1253 | @deffnx {Scheme Procedure} request-proxy-authorization request [default=#f] | |
1254 | @deffnx {Scheme Procedure} request-range request [default=#f] | |
1255 | @deffnx {Scheme Procedure} request-referer request [default=#f] | |
1256 | @deffnx {Scheme Procedure} request-te request [default=#f] | |
1257 | @deffnx {Scheme Procedure} request-trailer request [default='()] | |
1258 | @deffnx {Scheme Procedure} request-transfer-encoding request [default='()] | |
1259 | @deffnx {Scheme Procedure} request-upgrade request [default='()] | |
1260 | @deffnx {Scheme Procedure} request-user-agent request [default=#f] | |
1261 | @deffnx {Scheme Procedure} request-via request [default='()] | |
1262 | @deffnx {Scheme Procedure} request-warning request [default='()] | |
e471a3ee | 1263 | Return the given request header, or @var{default} if none was present. |
2e6f5ea4 | 1264 | @end deffn |
8db7e094 | 1265 | |
22c9e769 AW |
1266 | @deffn {Scheme Procedure} request-absolute-uri r [default-host=#f] @ |
1267 | [default-port=#f] [default-scheme=#f] | |
e471a3ee | 1268 | A helper routine to determine the absolute URI of a request, using the |
22c9e769 AW |
1269 | @code{host} header and the default scheme, host and port. If there is |
1270 | no default scheme and the URI is not itself absolute, an error is | |
1271 | signalled. | |
2e6f5ea4 | 1272 | @end deffn |
8db7e094 | 1273 | |
8db7e094 AW |
1274 | @node Responses |
1275 | @subsection HTTP Responses | |
1276 | ||
1277 | @example | |
1278 | (use-modules (web response)) | |
1279 | @end example | |
1280 | ||
e471a3ee AW |
1281 | As with requests (@pxref{Requests}), Guile offers a data type for HTTP |
1282 | responses. Again, the body is represented separately from the request. | |
8db7e094 | 1283 | |
dc871261 DH |
1284 | @deffn {Scheme Procedure} response? obj |
1285 | @deffnx {Scheme Procedure} response-version response | |
1286 | @deffnx {Scheme Procedure} response-code response | |
2e6f5ea4 | 1287 | @deffnx {Scheme Procedure} response-reason-phrase response |
dc871261 DH |
1288 | @deffnx {Scheme Procedure} response-headers response |
1289 | @deffnx {Scheme Procedure} response-port response | |
e471a3ee AW |
1290 | A predicate and field accessors for the response type. The fields are as |
1291 | follows: | |
1292 | @table @code | |
1293 | @item version | |
1294 | The HTTP version pair, like @code{(1 . 1)}. | |
1295 | @item code | |
1296 | The HTTP response code, like @code{200}. | |
1297 | @item reason-phrase | |
1298 | The reason phrase, or the standard reason phrase for the response's | |
1299 | code. | |
1300 | @item headers | |
1301 | The response headers, as an alist of parsed values. | |
1302 | @item port | |
1303 | The port on which to read or write a response body, if any. | |
1304 | @end table | |
2e6f5ea4 | 1305 | @end deffn |
8db7e094 | 1306 | |
2e6f5ea4 | 1307 | @deffn {Scheme Procedure} read-response port |
de54fb6d | 1308 | Read an HTTP response from @var{port}. |
8db7e094 AW |
1309 | |
1310 | As a side effect, sets the encoding on @var{port} to ISO-8859-1 | |
1311 | (latin-1), so that reading one character reads one byte. See the | |
de54fb6d | 1312 | discussion of character sets in @ref{Responses}, for more information. |
2e6f5ea4 | 1313 | @end deffn |
8db7e094 | 1314 | |
64de6db5 | 1315 | @deffn {Scheme Procedure} build-response [#:version='(1 . 1)] [#:code=200] [#:reason-phrase=#f] [#:headers='()] [#:port=#f] [#:validate-headers?=#t] |
8db7e094 AW |
1316 | Construct an HTTP response object. If @var{validate-headers?} is true, |
1317 | the headers are each run through their respective validators. | |
2e6f5ea4 | 1318 | @end deffn |
8db7e094 | 1319 | |
2e6f5ea4 | 1320 | @deffn {Scheme Procedure} adapt-response-version response version |
de54fb6d | 1321 | Adapt the given response to a different HTTP version. Return a new HTTP |
8db7e094 AW |
1322 | response. |
1323 | ||
1324 | The idea is that many applications might just build a response for the | |
1325 | default HTTP version, and this method could handle a number of | |
1326 | programmatic transformations to respond to older HTTP versions (0.9 and | |
1327 | 1.0). But currently this function is a bit heavy-handed, just updating | |
1328 | the version field. | |
2e6f5ea4 | 1329 | @end deffn |
8db7e094 | 1330 | |
2e6f5ea4 | 1331 | @deffn {Scheme Procedure} write-response r port |
8db7e094 AW |
1332 | Write the given HTTP response to @var{port}. |
1333 | ||
de54fb6d | 1334 | Return a new response, whose @code{response-port} will continue writing |
8db7e094 | 1335 | on @var{port}, perhaps using some transfer encoding. |
2e6f5ea4 | 1336 | @end deffn |
8db7e094 | 1337 | |
164a78b3 AW |
1338 | @deffn {Scheme Procedure} response-must-not-include-body? r |
1339 | Some responses, like those with status code 304, are specified as never | |
1340 | having bodies. This predicate returns @code{#t} for those responses. | |
1341 | ||
1342 | Note also, though, that responses to @code{HEAD} requests must also not | |
1343 | have a body. | |
1344 | @end deffn | |
1345 | ||
75d6c59f LC |
1346 | @deffn {Scheme Procedure} response-body-port r [#:decode?=#t] [#:keep-alive?=#t] |
1347 | Return an input port from which the body of @var{r} can be read. The encoding | |
1348 | of the returned port is set according to @var{r}'s @code{content-type} header, | |
1349 | when it's textual, except if @var{decode?} is @code{#f}. Return @code{#f} | |
1350 | when no body is available. | |
1351 | ||
1352 | When @var{keep-alive?} is @code{#f}, closing the returned port also closes | |
1353 | @var{r}'s response port. | |
1354 | @end deffn | |
1355 | ||
2e6f5ea4 | 1356 | @deffn {Scheme Procedure} read-response-body r |
de54fb6d | 1357 | Read the response body from @var{r}, as a bytevector. Returns @code{#f} |
8db7e094 | 1358 | if there was no response body. |
2e6f5ea4 | 1359 | @end deffn |
8db7e094 | 1360 | |
2e6f5ea4 | 1361 | @deffn {Scheme Procedure} write-response-body r bv |
64de6db5 | 1362 | Write @var{bv}, a bytevector, to the port corresponding to the HTTP |
8db7e094 | 1363 | response @var{r}. |
2e6f5ea4 | 1364 | @end deffn |
8db7e094 | 1365 | |
e471a3ee AW |
1366 | As with requests, the various headers that are typically associated with |
1367 | HTTP responses may be accessed with these dedicated accessors. | |
1368 | @xref{HTTP Headers}, for more information on the format of parsed | |
1369 | headers. | |
1370 | ||
2e6f5ea4 AW |
1371 | @deffn {Scheme Procedure} response-accept-ranges response [default=#f] |
1372 | @deffnx {Scheme Procedure} response-age response [default='()] | |
1373 | @deffnx {Scheme Procedure} response-allow response [default='()] | |
1374 | @deffnx {Scheme Procedure} response-cache-control response [default='()] | |
1375 | @deffnx {Scheme Procedure} response-connection response [default='()] | |
1376 | @deffnx {Scheme Procedure} response-content-encoding response [default='()] | |
1377 | @deffnx {Scheme Procedure} response-content-language response [default='()] | |
1378 | @deffnx {Scheme Procedure} response-content-length response [default=#f] | |
1379 | @deffnx {Scheme Procedure} response-content-location response [default=#f] | |
1380 | @deffnx {Scheme Procedure} response-content-md5 response [default=#f] | |
1381 | @deffnx {Scheme Procedure} response-content-range response [default=#f] | |
1382 | @deffnx {Scheme Procedure} response-content-type response [default=#f] | |
1383 | @deffnx {Scheme Procedure} response-date response [default=#f] | |
1384 | @deffnx {Scheme Procedure} response-etag response [default=#f] | |
1385 | @deffnx {Scheme Procedure} response-expires response [default=#f] | |
1386 | @deffnx {Scheme Procedure} response-last-modified response [default=#f] | |
1387 | @deffnx {Scheme Procedure} response-location response [default=#f] | |
1388 | @deffnx {Scheme Procedure} response-pragma response [default='()] | |
1389 | @deffnx {Scheme Procedure} response-proxy-authenticate response [default=#f] | |
1390 | @deffnx {Scheme Procedure} response-retry-after response [default=#f] | |
1391 | @deffnx {Scheme Procedure} response-server response [default=#f] | |
1392 | @deffnx {Scheme Procedure} response-trailer response [default='()] | |
1393 | @deffnx {Scheme Procedure} response-transfer-encoding response [default='()] | |
1394 | @deffnx {Scheme Procedure} response-upgrade response [default='()] | |
1395 | @deffnx {Scheme Procedure} response-vary response [default='()] | |
1396 | @deffnx {Scheme Procedure} response-via response [default='()] | |
1397 | @deffnx {Scheme Procedure} response-warning response [default='()] | |
1398 | @deffnx {Scheme Procedure} response-www-authenticate response [default=#f] | |
de54fb6d | 1399 | Return the given response header, or @var{default} if none was present. |
2e6f5ea4 | 1400 | @end deffn |
8db7e094 | 1401 | |
ee2d8741 LC |
1402 | @deffn {Scheme Procedure} text-content-type? @var{type} |
1403 | Return @code{#t} if @var{type}, a symbol as returned by | |
1404 | @code{response-content-type}, represents a textual type such as | |
1405 | @code{text/plain}. | |
1406 | @end deffn | |
1407 | ||
8db7e094 | 1408 | |
ec811439 AW |
1409 | @node Web Client |
1410 | @subsection Web Client | |
1411 | ||
1412 | @code{(web client)} provides a simple, synchronous HTTP client, built on | |
1413 | the lower-level HTTP, request, and response modules. | |
1414 | ||
dc871261 DH |
1415 | @example |
1416 | (use-modules (web client)) | |
1417 | @end example | |
1418 | ||
ec811439 | 1419 | @deffn {Scheme Procedure} open-socket-for-uri uri |
06883ae0 | 1420 | Return an open input/output port for a connection to URI. |
ec811439 AW |
1421 | @end deffn |
1422 | ||
990b11c5 AW |
1423 | @deffn {Scheme Procedure} http-get uri arg... |
1424 | @deffnx {Scheme Procedure} http-head uri arg... | |
1425 | @deffnx {Scheme Procedure} http-post uri arg... | |
1426 | @deffnx {Scheme Procedure} http-put uri arg... | |
1427 | @deffnx {Scheme Procedure} http-delete uri arg... | |
1428 | @deffnx {Scheme Procedure} http-trace uri arg... | |
1429 | @deffnx {Scheme Procedure} http-options uri arg... | |
1430 | ||
1431 | Connect to the server corresponding to @var{uri} and make a request over | |
1432 | HTTP, using the appropriate method (@code{GET}, @code{HEAD}, etc.). | |
1433 | ||
1434 | All of these procedures have the same prototype: a URI followed by an | |
1435 | optional sequence of keyword arguments. These keyword arguments allow | |
1436 | you to modify the requests in various ways, for example attaching a body | |
1437 | to the request, or setting specific headers. The following table lists | |
1438 | the keyword arguments and their default values. | |
1439 | ||
1440 | @table @code | |
1441 | @item #:body #f | |
1442 | @item #:port (open-socket-for-uri @var{uri})] | |
1443 | @item #:version '(1 . 1) | |
1444 | @item #:keep-alive? #f | |
1445 | @item #:headers '() | |
1446 | @item #:decode-body? #t | |
1447 | @item #:streaming? #f | |
1448 | @end table | |
1449 | ||
1450 | If you already have a port open, pass it as @var{port}. Otherwise, a | |
1451 | connection will be opened to the server corresponding to @var{uri}. Any | |
1452 | extra headers in the alist @var{headers} will be added to the request. | |
1453 | ||
dc871261 DH |
1454 | If @var{body} is not @code{#f}, a message body will also be sent with |
1455 | the HTTP request. If @var{body} is a string, it is encoded according to | |
1456 | the content-type in @var{headers}, defaulting to UTF-8. Otherwise | |
990b11c5 AW |
1457 | @var{body} should be a bytevector, or @code{#f} for no body. Although a |
1458 | message body may be sent with any request, usually only @code{POST} and | |
1459 | @code{PUT} requests have bodies. | |
ec811439 AW |
1460 | |
1461 | If @var{decode-body?} is true, as is the default, the body of the | |
1462 | response will be decoded to string, if it is a textual content-type. | |
1463 | Otherwise it will be returned as a bytevector. | |
ec811439 | 1464 | |
990b11c5 AW |
1465 | However, if @var{streaming?} is true, instead of eagerly reading the |
1466 | response body from the server, this function only reads off the headers. | |
1467 | The response body will be returned as a port on which the data may be | |
1468 | read. | |
1469 | ||
1470 | Unless @var{keep-alive?} is true, the port will be closed after the full | |
1471 | response body has been read. | |
1472 | ||
1473 | Returns two values: the response read from the server, and the response | |
1474 | body as a string, bytevector, #f value, or as a port (if | |
1475 | @var{streaming?} is true). | |
91e693a8 LC |
1476 | @end deffn |
1477 | ||
ec811439 AW |
1478 | @code{http-get} is useful for making one-off requests to web sites. If |
1479 | you are writing a web spider or some other client that needs to handle a | |
1480 | number of requests in parallel, it's better to build an event-driven URL | |
1481 | fetcher, similar in structure to the web server (@pxref{Web Server}). | |
1482 | ||
1483 | Another option, good but not as performant, would be to use threads, | |
1484 | possibly via par-map or futures. | |
1485 | ||
23cf330c MW |
1486 | @deffn {Scheme Parameter} current-http-proxy |
1487 | Either @code{#f} or a non-empty string containing the URL of the HTTP | |
1488 | proxy server to be used by the procedures in the @code{(web client)} | |
1489 | module, including @code{open-socket-for-uri}. Its initial value is | |
1490 | based on the @env{http_proxy} environment variable. | |
1491 | ||
1492 | @example | |
1493 | (current-http-proxy) @result{} "http://localhost:8123/" | |
1494 | (parameterize ((current-http-proxy #f)) | |
1495 | (http-get "http://example.com/")) ; temporarily bypass proxy | |
1496 | (current-http-proxy) @result{} "http://localhost:8123/" | |
1497 | @end example | |
1498 | @end deffn | |
1499 | ||
ec811439 | 1500 | |
8db7e094 AW |
1501 | @node Web Server |
1502 | @subsection Web Server | |
1503 | ||
1504 | @code{(web server)} is a generic web server interface, along with a main | |
1505 | loop implementation for web servers controlled by Guile. | |
1506 | ||
5cdab8b8 AW |
1507 | @example |
1508 | (use-modules (web server)) | |
1509 | @end example | |
1510 | ||
1511 | The lowest layer is the @code{<server-impl>} object, which defines a set | |
1512 | of hooks to open a server, read a request from a client, write a | |
1513 | response to a client, and close a server. These hooks -- @code{open}, | |
1514 | @code{read}, @code{write}, and @code{close}, respectively -- are bound | |
1515 | together in a @code{<server-impl>} object. Procedures in this module take a | |
1516 | @code{<server-impl>} object, if needed. | |
1517 | ||
1518 | A @code{<server-impl>} may also be looked up by name. If you pass the | |
1519 | @code{http} symbol to @code{run-server}, Guile looks for a variable | |
1520 | named @code{http} in the @code{(web server http)} module, which should | |
1521 | be bound to a @code{<server-impl>} object. Such a binding is made by | |
1522 | instantiation of the @code{define-server-impl} syntax. In this way the | |
1523 | run-server loop can automatically load other backends if available. | |
8db7e094 AW |
1524 | |
1525 | The life cycle of a server goes as follows: | |
1526 | ||
1527 | @enumerate | |
1528 | @item | |
dc871261 DH |
1529 | The @code{open} hook is called, to open the server. @code{open} takes |
1530 | zero or more arguments, depending on the backend, and returns an opaque | |
8db7e094 AW |
1531 | server socket object, or signals an error. |
1532 | ||
1533 | @item | |
1534 | The @code{read} hook is called, to read a request from a new client. | |
5cdab8b8 AW |
1535 | The @code{read} hook takes one argument, the server socket. It should |
1536 | return three values: an opaque client socket, the request, and the | |
1537 | request body. The request should be a @code{<request>} object, from | |
1538 | @code{(web request)}. The body should be a string or a bytevector, or | |
1539 | @code{#f} if there is no body. | |
8db7e094 AW |
1540 | |
1541 | If the read failed, the @code{read} hook may return #f for the client | |
1542 | socket, request, and body. | |
1543 | ||
1544 | @item | |
09b7459b AW |
1545 | A user-provided handler procedure is called, with the request and body |
1546 | as its arguments. The handler should return two values: the response, | |
1547 | as a @code{<response>} record from @code{(web response)}, and the | |
1548 | response body as bytevector, or @code{#f} if not present. | |
1549 | ||
1550 | The respose and response body are run through @code{sanitize-response}, | |
1551 | documented below. This allows the handler writer to take some | |
1552 | convenient shortcuts: for example, instead of a @code{<response>}, the | |
1553 | handler can simply return an alist of headers, in which case a default | |
1554 | response object is constructed with those headers. Instead of a | |
1555 | bytevector for the body, the handler can return a string, which will be | |
1556 | serialized into an appropriate encoding; or it can return a procedure, | |
1557 | which will be called on a port to write out the data. See the | |
1558 | @code{sanitize-response} documentation, for more. | |
8db7e094 AW |
1559 | |
1560 | @item | |
1561 | The @code{write} hook is called with three arguments: the client | |
1562 | socket, the response, and the body. The @code{write} hook returns no | |
1563 | values. | |
1564 | ||
1565 | @item | |
1566 | At this point the request handling is complete. For a loop, we | |
1567 | loop back and try to read a new request. | |
1568 | ||
1569 | @item | |
1570 | If the user interrupts the loop, the @code{close} hook is called on | |
1571 | the server socket. | |
1572 | @end enumerate | |
1573 | ||
5cdab8b8 AW |
1574 | A user may define a server implementation with the following form: |
1575 | ||
06883ae0 | 1576 | @deffn {Scheme Syntax} define-server-impl name open read write close |
5cdab8b8 AW |
1577 | Make a @code{<server-impl>} object with the hooks @var{open}, |
1578 | @var{read}, @var{write}, and @var{close}, and bind it to the symbol | |
1579 | @var{name} in the current module. | |
2e6f5ea4 | 1580 | @end deffn |
8db7e094 | 1581 | |
2e6f5ea4 | 1582 | @deffn {Scheme Procedure} lookup-server-impl impl |
06883ae0 DH |
1583 | Look up a server implementation. If @var{impl} is a server |
1584 | implementation already, it is returned directly. If it is a symbol, the | |
8db7e094 | 1585 | binding named @var{impl} in the @code{(web server @var{impl})} module is |
06883ae0 | 1586 | looked up. Otherwise an error is signaled. |
8db7e094 AW |
1587 | |
1588 | Currently a server implementation is a somewhat opaque type, useful only | |
1589 | for passing to other procedures in this module, like @code{read-client}. | |
2e6f5ea4 | 1590 | @end deffn |
8db7e094 | 1591 | |
5cdab8b8 AW |
1592 | The @code{(web server)} module defines a number of routines that use |
1593 | @code{<server-impl>} objects to implement parts of a web server. Given | |
1594 | that we don't expose the accessors for the various fields of a | |
1595 | @code{<server-impl>}, indeed these routines are the only procedures with | |
1596 | any access to the impl objects. | |
1597 | ||
2e6f5ea4 | 1598 | @deffn {Scheme Procedure} open-server impl open-params |
f4ec6877 | 1599 | Open a server for the given implementation. Return one value, the new |
06883ae0 | 1600 | server object. The implementation's @code{open} procedure is applied to |
8db7e094 | 1601 | @var{open-params}, which should be a list. |
2e6f5ea4 | 1602 | @end deffn |
8db7e094 | 1603 | |
2e6f5ea4 | 1604 | @deffn {Scheme Procedure} read-client impl server |
8db7e094 | 1605 | Read a new client from @var{server}, by applying the implementation's |
f4ec6877 | 1606 | @code{read} procedure to the server. If successful, return three |
8db7e094 | 1607 | values: an object corresponding to the client, a request object, and the |
06883ae0 | 1608 | request body. If any exception occurs, return @code{#f} for all three |
8db7e094 | 1609 | values. |
2e6f5ea4 | 1610 | @end deffn |
8db7e094 | 1611 | |
2e6f5ea4 | 1612 | @deffn {Scheme Procedure} handle-request handler request body state |
8db7e094 AW |
1613 | Handle a given request, returning the response and body. |
1614 | ||
1615 | The response and response body are produced by calling the given | |
1616 | @var{handler} with @var{request} and @var{body} as arguments. | |
1617 | ||
1618 | The elements of @var{state} are also passed to @var{handler} as | |
06883ae0 | 1619 | arguments, and may be returned as additional values. The new |
8db7e094 | 1620 | @var{state}, collected from the @var{handler}'s return values, is then |
06883ae0 | 1621 | returned as a list. The idea is that a server loop receives a handler |
8db7e094 AW |
1622 | from the user, along with whatever state values the user is interested |
1623 | in, allowing the user's handler to explicitly manage its state. | |
2e6f5ea4 | 1624 | @end deffn |
8db7e094 | 1625 | |
2e6f5ea4 | 1626 | @deffn {Scheme Procedure} sanitize-response request response body |
dc871261 DH |
1627 | ``Sanitize'' the given response and body, making them appropriate for |
1628 | the given request. | |
8db7e094 AW |
1629 | |
1630 | As a convenience to web handler authors, @var{response} may be given as | |
1631 | an alist of headers, in which case it is used to construct a default | |
06883ae0 DH |
1632 | response. Ensures that the response version corresponds to the request |
1633 | version. If @var{body} is a string, encodes the string to a bytevector, | |
1634 | in an encoding appropriate for @var{response}. Adds a | |
8db7e094 AW |
1635 | @code{content-length} and @code{content-type} header, as necessary. |
1636 | ||
1637 | If @var{body} is a procedure, it is called with a port as an argument, | |
06883ae0 | 1638 | and the output collected as a bytevector. In the future we might try to |
8db7e094 | 1639 | instead use a compressing, chunk-encoded port, and call this procedure |
06883ae0 | 1640 | later, in the write-client procedure. Authors are advised not to rely on |
8db7e094 | 1641 | the procedure being called at any particular time. |
2e6f5ea4 | 1642 | @end deffn |
8db7e094 | 1643 | |
2e6f5ea4 | 1644 | @deffn {Scheme Procedure} write-client impl server client response body |
06883ae0 | 1645 | Write an HTTP response and body to @var{client}. If the server and |
8db7e094 AW |
1646 | client support persistent connections, it is the implementation's |
1647 | responsibility to keep track of the client thereafter, presumably by | |
1648 | attaching it to the @var{server} argument somehow. | |
2e6f5ea4 | 1649 | @end deffn |
8db7e094 | 1650 | |
2e6f5ea4 | 1651 | @deffn {Scheme Procedure} close-server impl server |
8db7e094 AW |
1652 | Release resources allocated by a previous invocation of |
1653 | @code{open-server}. | |
2e6f5ea4 | 1654 | @end deffn |
8db7e094 | 1655 | |
5cdab8b8 AW |
1656 | Given the procedures above, it is a small matter to make a web server: |
1657 | ||
2e6f5ea4 | 1658 | @deffn {Scheme Procedure} serve-one-client handler impl server state |
8db7e094 | 1659 | Read one request from @var{server}, call @var{handler} on the request |
f4ec6877 | 1660 | and body, and write the response to the client. Return the new state |
8db7e094 | 1661 | produced by the handler procedure. |
2e6f5ea4 | 1662 | @end deffn |
8db7e094 | 1663 | |
994d87be BT |
1664 | @deffn {Scheme Procedure} run-server handler @ |
1665 | [impl='http] [open-params='()] @ | |
1666 | arg @dots{} | |
8db7e094 AW |
1667 | Run Guile's built-in web server. |
1668 | ||
1669 | @var{handler} should be a procedure that takes two or more arguments, | |
1670 | the HTTP request and request body, and returns two or more values, the | |
1671 | response and response body. | |
1672 | ||
f4ec6877 | 1673 | For examples, skip ahead to the next section, @ref{Web Examples}. |
8db7e094 AW |
1674 | |
1675 | The response and body will be run through @code{sanitize-response} | |
1676 | before sending back to the client. | |
1677 | ||
994d87be BT |
1678 | Additional arguments to @var{handler} are taken from @var{arg} |
1679 | @enddots{}. These arguments comprise a @dfn{state}. Additional return | |
1680 | values are accumulated into a new state, which will be used for | |
1681 | subsequent requests. In this way a handler can explicitly manage its | |
1682 | state. | |
2e6f5ea4 | 1683 | @end deffn |
8db7e094 | 1684 | |
f4ec6877 AW |
1685 | The default web server implementation is @code{http}, which binds to a |
1686 | socket, listening for request on that port. | |
1687 | ||
994d87be BT |
1688 | @deffn {HTTP Implementation} http [#:host=#f] @ |
1689 | [#:family=AF_INET] @ | |
1690 | [#:addr=INADDR_LOOPBACK] @ | |
1691 | [#:port 8080] [#:socket] | |
f4ec6877 AW |
1692 | The default HTTP implementation. We document it as a function with |
1693 | keyword arguments, because that is precisely the way that it is -- all | |
1694 | of the @var{open-params} to @code{run-server} get passed to the | |
1695 | implementation's open function. | |
1696 | ||
1697 | @example | |
1698 | ;; The defaults: localhost:8080 | |
1699 | (run-server handler) | |
1700 | ;; Same thing | |
1701 | (run-server handler 'http '()) | |
1702 | ;; On a different port | |
1703 | (run-server handler 'http '(#:port 8081)) | |
1704 | ;; IPv6 | |
1705 | (run-server handler 'http '(#:family AF_INET6 #:port 8081)) | |
1706 | ;; Custom socket | |
1707 | (run-server handler 'http `(#:socket ,(sudo-make-me-a-socket))) | |
1708 | @end example | |
1709 | @end deffn | |
5cdab8b8 AW |
1710 | |
1711 | @node Web Examples | |
1712 | @subsection Web Examples | |
1713 | ||
1714 | Well, enough about the tedious internals. Let's make a web application! | |
1715 | ||
1716 | @subsubsection Hello, World! | |
1717 | ||
1718 | The first program we have to write, of course, is ``Hello, World!''. | |
1719 | This means that we have to implement a web handler that does what we | |
1720 | want. | |
1721 | ||
1722 | Now we define a handler, a function of two arguments and two return | |
1723 | values: | |
1724 | ||
1725 | @example | |
1726 | (define (handler request request-body) | |
1727 | (values @var{response} @var{response-body})) | |
1728 | @end example | |
1729 | ||
1730 | In this first example, we take advantage of a short-cut, returning an | |
1731 | alist of headers instead of a proper response object. The response body | |
1732 | is our payload: | |
1733 | ||
1734 | @example | |
1735 | (define (hello-world-handler request request-body) | |
f4ec6877 | 1736 | (values '((content-type . (text/plain))) |
5cdab8b8 AW |
1737 | "Hello World!")) |
1738 | @end example | |
1739 | ||
1740 | Now let's test it, by running a server with this handler. Load up the | |
1741 | web server module if you haven't yet done so, and run a server with this | |
1742 | handler: | |
1743 | ||
8db7e094 AW |
1744 | @example |
1745 | (use-modules (web server)) | |
5cdab8b8 | 1746 | (run-server hello-world-handler) |
8db7e094 AW |
1747 | @end example |
1748 | ||
5cdab8b8 AW |
1749 | By default, the web server listens for requests on |
1750 | @code{localhost:8080}. Visit that address in your web browser to | |
1751 | test. If you see the string, @code{Hello World!}, sweet! | |
8db7e094 | 1752 | |
5cdab8b8 | 1753 | @subsubsection Inspecting the Request |
e471a3ee | 1754 | |
5cdab8b8 AW |
1755 | The Hello World program above is a general greeter, responding to all |
1756 | URIs. To make a more exclusive greeter, we need to inspect the request | |
1757 | object, and conditionally produce different results. So let's load up | |
1758 | the request, response, and URI modules, and do just that. | |
e471a3ee | 1759 | |
5cdab8b8 AW |
1760 | @example |
1761 | (use-modules (web server)) ; you probably did this already | |
1762 | (use-modules (web request) | |
1763 | (web response) | |
1764 | (web uri)) | |
1765 | ||
1766 | (define (request-path-components request) | |
1767 | (split-and-decode-uri-path (uri-path (request-uri request)))) | |
1768 | ||
1769 | (define (hello-hacker-handler request body) | |
1770 | (if (equal? (request-path-components request) | |
1771 | '("hacker")) | |
f4ec6877 | 1772 | (values '((content-type . (text/plain))) |
5cdab8b8 AW |
1773 | "Hello hacker!") |
1774 | (not-found request))) | |
1775 | ||
1776 | (run-server hello-hacker-handler) | |
1777 | @end example | |
e471a3ee | 1778 | |
5cdab8b8 AW |
1779 | Here we see that we have defined a helper to return the components of |
1780 | the URI path as a list of strings, and used that to check for a request | |
1781 | to @code{/hacker/}. Then the success case is just as before -- visit | |
1782 | @code{http://localhost:8080/hacker/} in your browser to check. | |
1783 | ||
1784 | You should always match against URI path components as decoded by | |
1785 | @code{split-and-decode-uri-path}. The above example will work for | |
1786 | @code{/hacker/}, @code{//hacker///}, and @code{/h%61ck%65r}. | |
1787 | ||
1788 | But we forgot to define @code{not-found}! If you are pasting these | |
1789 | examples into a REPL, accessing any other URI in your web browser will | |
1790 | drop your Guile console into the debugger: | |
1791 | ||
1792 | @example | |
1793 | <unnamed port>:38:7: In procedure module-lookup: | |
1794 | <unnamed port>:38:7: Unbound variable: not-found | |
1795 | ||
1796 | Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue. | |
1797 | scheme@@(guile-user) [1]> | |
1798 | @end example | |
1799 | ||
1800 | So let's define the function, right there in the debugger. As you | |
1801 | probably know, we'll want to return a 404 response. | |
1802 | ||
1803 | @example | |
1804 | ;; Paste this in your REPL | |
1805 | (define (not-found request) | |
1806 | (values (build-response #:code 404) | |
1807 | (string-append "Resource not found: " | |
2ebdf6b5 | 1808 | (uri->string (request-uri request))))) |
5cdab8b8 AW |
1809 | |
1810 | ;; Now paste this to let the web server keep going: | |
1811 | ,continue | |
1812 | @end example | |
1813 | ||
1814 | Now if you access @code{http://localhost/foo/}, you get this error | |
1815 | message. (Note that some popular web browsers won't show | |
1816 | server-generated 404 messages, showing their own instead, unless the 404 | |
1817 | message body is long enough.) | |
1818 | ||
1819 | @subsubsection Higher-Level Interfaces | |
1820 | ||
1821 | The web handler interface is a common baseline that all kinds of Guile | |
1822 | web applications can use. You will usually want to build something on | |
1823 | top of it, however, especially when producing HTML. Here is a simple | |
3e31e75a | 1824 | example that builds up HTML output using SXML (@pxref{SXML}). |
5cdab8b8 AW |
1825 | |
1826 | First, load up the modules: | |
1827 | ||
1828 | @example | |
1829 | (use-modules (web server) | |
1830 | (web request) | |
1831 | (web response) | |
1832 | (sxml simple)) | |
1833 | @end example | |
1834 | ||
1835 | Now we define a simple templating function that takes a list of HTML | |
1836 | body elements, as SXML, and puts them in our super template: | |
1837 | ||
1838 | @example | |
1839 | (define (templatize title body) | |
1840 | `(html (head (title ,title)) | |
1841 | (body ,@@body))) | |
e471a3ee AW |
1842 | @end example |
1843 | ||
5cdab8b8 AW |
1844 | For example, the simplest Hello HTML can be produced like this: |
1845 | ||
1846 | @example | |
1847 | (sxml->xml (templatize "Hello!" '((b "Hi!")))) | |
1848 | @print{} | |
1849 | <html><head><title>Hello!</title></head><body><b>Hi!</b></body></html> | |
1850 | @end example | |
1851 | ||
1852 | Much better to work with Scheme data types than to work with HTML as | |
1853 | strings. Now we define a little response helper: | |
1854 | ||
1855 | @example | |
1856 | (define* (respond #:optional body #:key | |
1857 | (status 200) | |
1858 | (title "Hello hello!") | |
1859 | (doctype "<!DOCTYPE html>\n") | |
f4ec6877 AW |
1860 | (content-type-params '((charset . "utf-8"))) |
1861 | (content-type 'text/html) | |
5cdab8b8 AW |
1862 | (extra-headers '()) |
1863 | (sxml (and body (templatize title body)))) | |
1864 | (values (build-response | |
1865 | #:code status | |
1866 | #:headers `((content-type | |
1867 | . (,content-type ,@@content-type-params)) | |
1868 | ,@@extra-headers)) | |
1869 | (lambda (port) | |
1870 | (if sxml | |
1871 | (begin | |
1872 | (if doctype (display doctype port)) | |
1873 | (sxml->xml sxml port)))))) | |
1874 | @end example | |
1875 | ||
1876 | Here we see the power of keyword arguments with default initializers. By | |
1877 | the time the arguments are fully parsed, the @code{sxml} local variable | |
1878 | will hold the templated SXML, ready for sending out to the client. | |
1879 | ||
f4ec6877 AW |
1880 | Also, instead of returning the body as a string, @code{respond} gives a |
1881 | procedure, which will be called by the web server to write out the | |
1882 | response to the client. | |
5cdab8b8 AW |
1883 | |
1884 | Now, a simple example using this responder, which lays out the incoming | |
1885 | headers in an HTML table. | |
1886 | ||
1887 | @example | |
1888 | (define (debug-page request body) | |
1889 | (respond | |
1890 | `((h1 "hello world!") | |
1891 | (table | |
1892 | (tr (th "header") (th "value")) | |
1893 | ,@@(map (lambda (pair) | |
1894 | `(tr (td (tt ,(with-output-to-string | |
1895 | (lambda () (display (car pair)))))) | |
1896 | (td (tt ,(with-output-to-string | |
1897 | (lambda () | |
1898 | (write (cdr pair)))))))) | |
1899 | (request-headers request)))))) | |
1900 | ||
1901 | (run-server debug-page) | |
1902 | @end example | |
1903 | ||
1904 | Now if you visit any local address in your web browser, we actually see | |
1905 | some HTML, finally. | |
1906 | ||
1907 | @subsubsection Conclusion | |
e471a3ee | 1908 | |
5cdab8b8 AW |
1909 | Well, this is about as far as Guile's built-in web support goes, for |
1910 | now. There are many ways to make a web application, but hopefully by | |
1911 | standardizing the most fundamental data types, users will be able to | |
1912 | choose the approach that suits them best, while also being able to | |
1913 | switch between implementations of the server. This is a relatively new | |
1914 | part of Guile, so if you have feedback, let us know, and we can take it | |
1915 | into account. Happy hacking on the web! | |
e471a3ee | 1916 | |
8db7e094 AW |
1917 | @c Local Variables: |
1918 | @c TeX-master: "guile.texi" | |
1919 | @c End: |