index.xml 1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <?xml-stylesheet type="text/xsl" href="clixdoc.xsl" ?>
3
4 <clix:documentation xmlns='http://www.w3.org/1999/xhtml' xmlns:clix='http://bknr.net/clixdoc'>
5 <clix:title>Hunchentoot - The Common Lisp web server formerly known as TBNL</clix:title>
6 <clix:short-description>
7 A full-featured web server written in Common Lisp offering things
8 like HTTP/1.1 chunking, persistent connections, and SSL. Includes
9 a framework for building dynamic websites interactively.
10 </clix:short-description>
11
12 <h2>
13 <a href="http://www.htg1.de/hunchentoot/hunchentoot.html"
14 title="Click here for the Hunchentoot logo"
15 class="noborder">
16 <img align="top" width="93" height="45" border="0" src="hunchentoot.gif" />
17 </a>
18 Hunchentoot - The Common Lisp web server formerly known as TBNL
19 </h2>
20
21 <blockquote>
22 <clix:chapter name='abstract' title='Abstract'>
23 <p>
24 Hunchentoot is a web server written in Common Lisp and at the
25 same time a toolkit for building dynamic websites. As a
26 stand-alone web server, Hunchentoot is capable of HTTP/1.1
27 chunking (both directions), persistent connections
28 (keep-alive), and SSL.
29 </p>
30 <p>
31 Hunchentoot provides facilities like automatic session
32 handling (with and without cookies), logging, customizable
33 error handling, and easy access to GET and POST parameters
34 sent by the client. It does <em>not</em> include functionality
35 to programmatically generate HTML output. For this task you
36 can use any library you like, e.g. (shameless self-plug)
37 <a href="http://weitz.de/cl-who/">CL-WHO</a> or
38 <a href="http://weitz.de/html-template/">HTML-TEMPLATE</a>.
39 </p>
40 <p>
41 Hunchentoot talks with its front-end or with the client over
42 TCP/IP sockets and optionally uses multiprocessing to handle
43 several requests at the same time. Therefore, it cannot be
44 implemented completely in <a
45 href="http://www.lispworks.com/documentation/HyperSpec/Front/index.htm">portable
46 Common Lisp</a>. It currently works with <a
47 href="http://www.lispworks.com/">LispWorks</a> and all Lisps
48 which are supported by the compatibility layers <a
49 href="http://common-lisp.net/project/usocket/">usocket</a> and
50 <a
51 href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux
52 Threads</a>.
53 </p>
54 <p>
55 Hunchentoot comes with a
56 <a href="http://www.opensource.org/licenses/bsd-license.php">BSD-style
57 license</a> so you can basically do with it whatever you want.
58 </p>
59 <p>
60 Hunchentoot is (or was) for example used by
61 <a href="http://quickhoney.com/">QuickHoney</a>,
62 <a href="http://www.city-farming.de/">City Farming</a>,
63 <a href="http://heikestephan.de/">Heike Stephan</a>.
64 </p>
65 <p>
66 <font color="red">Download shortcut:</font>
67 <a href="http://weitz.de/files/hunchentoot.tar.gz">http://weitz.de/files/hunchentoot.tar.gz</a>.
68 </p>
69 </clix:chapter>
70 </blockquote>
71
72 <clix:chapter name='contents' title='Contents'></clix:chapter>
73 <clix:contents></clix:contents>
74
75 <clix:chapter name="install" title="Download and installation">
76 Hunchentoot depends on a couple of other Lisp libraries which you'll need
77 to install first:
78 <ul>
79 <li>Pierre R. Mai's <a href="http://www.cliki.net/md5">MD5</a>,</li>
80 <li>Kevin Rosenberg's <a href="http://www.cliki.net/cl-base64">CL-BASE64</a>,</li>
81 <li>Janis Dzerins' <a href="http://common-lisp.net/project/rfc2388/">RFC2388</a>,</li>
82 <li>Peter Seibel's <a href="http://weitz.de/cl-fad/">CL-FAD</a>,</li>
83 <li>Gary King's <a href="http://common-lisp.net/project/trivial-backtrace/">trivial-backtrace</a>,</li>
84 <li>Erik Huelsmann's <a href="http://common-lisp.net/project/usocket">usocket</a> (unless you're using LispWorks),</li>
85 <li>Greg Pfeil's <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux Threads</a> (unless you're using LispWorks),
86 </li>
87 <li>
88 David Lichteblau's <a href="http://common-lisp.net/project/cl-plus-ssl/">CL+SSL</a>
89 (unless you're using LispWorks),
90 </li>
91 <li>
92 and my own <a href="http://weitz.de/flexi-streams/">FLEXI-STREAMS</a> (0.12.0 or higher),
93 <a href="http://weitz.de/chunga/">Chunga</a> (1.0.0 or
94 higher), and <a href="http://weitz.de/cl-ppcre/">
95 CL-PPCRE</a> (plus
96 <a href="http://weitz.de/cl-who/">CL-WHO</a> for the <a href="#teen-age">example code</a>
97 and <a href="http://weitz.de/drakma/">Drakma</a> for the <a href="#testing">tests</a>).
98 </li>
99 </ul>
100
101 Make sure to use the <em>newest</em> versions of all of these
102 libraries (which might themselves depend on other libraries) - try
103 the repository versions if you're in doubt. Note: You can compile
104 Hunchentoot without SSL support - and thus without the need to
105 have CL+SSL - if you add <code>:HUNCHENTOOT-NO-SSL</code> to
106 <a href="http://www.lispworks.com/documentation/HyperSpec/Body/v_featur.htm">
107 <code>*FEATURES*</code></a> <em>before</em> you compile it.
108 <p>
109 Hunchentoot will only work with Lisps where
110 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#character_code">character
111 codes</a> of
112 all <a href="http://en.wikipedia.org/wiki/ISO/IEC_8859-1">Latin-1</a>
113 characters coincide with their
114 Unicode <a href="http://en.wikipedia.org/wiki/Code_point">code
115 points</a> (which is the case for all current implementations I
116 know).
117 </p>
118 <p>
119 Hunchentoot itself together with this documentation can be
120 downloaded from
121 <a href="http://weitz.de/files/hunchentoot.tar.gz">http://weitz.de/files/hunchentoot.tar.gz</a>.
122 The current version is <clix:library-version/>.
123 </p>
124 <p>
125 The preferred method to compile and load Hunchentoot is via <a
126 href="http://www.cliki.net/asdf">ASDF</a>. If you want to avoid
127 downloading and installing all the dependencies manually, give
128 Zach Beane's excellent <a
129 href="http://www.quicklisp.org/">Quicklisp</a> system a try.
130 </p>
131 <p>
132 Hunchentoot and its dependencies can also be installed with <a
133 href="http://common-lisp.net/project/clbuild/">clbuild</a>.
134 There's also a port for <a
135 href="http://www.gentoo.org/proj/en/lisp/common-lisp/index.xml">Gentoo
136 Linux</a> thanks to Matthew Kennedy.
137 </p>
138 <p>
139 The current development version of Hunchentoot can be found
140 at <a href="https://github.com/edicl/hunchentoot">https://github.com/edicl/hunchentoot</a>.
141 If you want to send patches, please fork the github repository and send pull requests.
142 </p>
143
144 <clix:subchapter name="port80" title="Running Hunchentoot on port 80">
145
146 Hunchentoot does not come with code to help with running it on a
147 privileged port (i.e. port 80 or 443) on Unix-like operating
148 systems. Modern Unix-like systems have specific, non-portable
149 ways to allow non-root users to listen to privileged ports, so
150 including such functionality in Hunchentoot was considered
151 unnecessary. Please refer to online resources for help. At the
152 time of this writing, the YAWS documentation has a <a
153 href="http://yaws.hyber.org/privbind.yaws">comprehensive
154 writeup</a> on the topic.
155 </clix:subchapter>
156
157 <clix:subchapter name="proxy" title="Hunchentoot behind a proxy">
158
159 If you're feeling unsecure about exposing Hunchentoot to the wild,
160 wild Internet or if your Lisp web application is part of a larger
161 website, you can hide it behind a
162 <a href="http://en.wikipedia.org/wiki/Proxy_server">proxy server</a>.
163 One approach that I have used several times is to employ Apache's
164 <a href="http://httpd.apache.org/docs/current/mod/mod_proxy.html">mod_proxy</a>
165 module with a configuration that looks like this:
166
167 <pre><a href="http://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypass" class="noborder">ProxyPass</a> /hunchentoot http://127.0.0.1:3000/hunchentoot
168 <a href="http://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypassreverse" class="noborder">ProxyPassReverse</a> /hunchentoot http://127.0.0.1:3000/hunchentoot</pre>
169
170 This will tunnel all requests where the URI path begins with
171 <code>"/hunchentoot"</code> to a (Hunchentoot) server listening on
172 port 3000 on the same machine.
173
174 <p>
175 Of course, there are
176 <a href="http://www.red-bean.com/pipermail/lispweb/2006-October/001342.html">several
177 other</a> (more lightweight) web proxies that you could use
178 instead of Apache.
179 </p>
180 </clix:subchapter>
181 </clix:chapter>
182
183 <clix:chapter name="support" title="Support">
184 <p>
185 The development version of Hunchentoot can be found <a
186 href="https://github.com/edicl/hunchentoot" target="_new">on
187 github</a>. Please use the github issue tracking system to
188 submit bug reports. Patches are welcome, please use <a
189 href="https://github.com/edicl/hunchentoot/pulls">GitHub pull
190 requests</a>. If you want to make a change, please <a
191 href="http://weitz.de/patches.html" target="_new">read this
192 first</a>.
193 </p>
194 </clix:chapter>
195
196 <clix:chapter name="teen-age" title="Your own webserver (the easy teen-age New York version)">
197 Starting your own web server is pretty easy. Do something like this:
198 <pre>(hunchentoot:<a class="noborder" href="#teen-age">start</a> (make-instance 'hunchentoot:<a class="noborder" href="#acceptor">easy-acceptor</a> :port 4242))</pre>
199 That's it. Now you should be able to enter the address
200 "<a href='http://127.0.0.1:4242/'><code>http://127.0.0.1:4242/</code></a>" in
201 your browser and see something, albeit nothing very interesting
202 for now.
203
204 <p>
205 By default, Hunchentoot serves the files from the
206 <code><i>www/</i></code> directory in its source tree. In the
207 distribution, that directory contains a HTML version of the
208 documentation as well as the error templates. The location of
209 the document root directory can be specified when creating a new
210 <clix:ref>ACCEPTOR</clix:ref> instance by the way of the
211 <clix:ref>ACCEPTOR-DOCUMENT-ROOT</clix:ref>. Likewise, the
212 location of the error template directory can be specified by the
213 <clix:ref>ACCEPTOR-ERROR-TEMPLATE-DIRECTORY</clix:ref>. Both
214 <clix:ref>ACCEPTOR-DOCUMENT-ROOT</clix:ref> and
215 <clix:ref>ACCEPTOR-ERROR-TEMPLATE-DIRECTORY</clix:ref> can be
216 specified using a logical pathname, which will be translated
217 once when the <clix:ref>ACCEPTOR</clix:ref> is instantiated.
218 </p>
219
220 <p>
221 The <clix:ref>EASY-ACCEPTOR</clix:ref> class implements a
222 framework for developing web applications. Handlers are defined
223 using the <clix:ref>DEFINE-EASY-HANDLER</clix:ref> macro.
224 Request dispatching is performed according to the list of
225 dispatch functions in <clix:ref>*DISPATCH-TABLE*</clix:ref>.
226 Each of the functions on that list is called to determine
227 whether it wants to handle the request, provided as single
228 argument. If a dispatcher function wants to handle the request,
229 it returns another function to actually create the desired page.
230 </p>
231
232 <p>
233 <clix:ref>DEFINE-EASY-HANDLER</clix:ref> is accompanied by a set
234 of dispatcher creation functions that can be used to create
235 dispatchers for standard tasks. These are documented in the <a
236 class="noborder" href="#easy-handlers">subchapter on easy
237 handlers</a>
238 </p>
239
240 <p>
241 Now be a bit more adventurous, try this
242 <pre>(hunchentoot:<a class="noborder" href="#define-easy-handler">define-easy-handler</a> (say-yo :uri "/yo") (name)
243 (setf (hunchentoot:<a class="noborder" href="#content-type*">content-type*</a>) "text/plain")
244 (format nil "Hey~@[ ~A~]!" name))</pre>
245 and see what happens at "<a href='http://127.0.0.1:4242/yo'><code>http://127.0.0.1:4242/yo</code></a>" or
246 "<a href='http://127.0.0.1:4242/yo?name=Dude'><code>http://127.0.0.1:4242/yo?name=Dude</code></a>" .
247 </p>
248
249 <p>
250 Hunchentoot comes with a little example website which you can use
251 to see if it works and which should also demonstrate a couple of
252 the things you can do with Hunchentoot. To start the example
253 website, enter the following code into your listener:
254
255 <pre>(<a class="noborder" href="http://common-lisp.net/~mmommer/asdf-howto.shtml#sec11">asdf:oos</a> 'asdf:load-op :hunchentoot-test)</pre>
256
257 Now go to "<a href='http://127.0.0.1:4242/hunchentoot/test'><code>http://127.0.0.1:4242/hunchentoot/test</code></a>" and play a bit.
258 </p>
259 </clix:chapter>
260
261 <clix:chapter name="extras" title="Third party documentation and add-ons">
262 <p>
263 Adam Petersen has written a book called <a
264 href="http://www.adampetersen.se/articles/lispweb.htm">"Lisp for
265 the Web"</a> which explains how Hunchentoot and some other
266 libraries can be used to build web sites.
267 </p>
268 <p>
269 Here is some software which extends Hunchentoot or is based on it:
270 </p>
271 <ul>
272 <li>
273 <a href="http://weblocks-framework.info/">Weblocks</a> by
274 Slava Akhmechet is a "continuations-based web framework" which
275 is based on Hunchentoot.
276 </li>
277 <li>
278 <a href="https://github.com/slyrus/hunchentoot-cgi">hunchentoot-cgi</a>
279 (by Cyrus Harmon) provides
280 <a href="http://en.wikipedia.org/wiki/Common_Gateway_Interface">CGI</a>
281 handlers for Hunchentoot.
282 </li>
283 <li>
284 <a href="http://weitz.de/cl-webdav/">CL-WEBDAV</a> is a <a href="http://webdav.org/">WebDAV</a>
285 server based on Hunchentoot.
286 </li>
287 <li>
288 <a href="http://restas.lisper.ru/">RESTAS</a> is a web
289 framework based on Hunchentoot.
290 </li>
291 </ul>
292 </clix:chapter>
293
294 <clix:chapter name="reference" title="Function and variable reference">
295
296 <clix:subchapter name="acceptors" title="Acceptors">
297
298 If you want Hunchentoot to actually do something, you have to create and
299 <a href="#teen-age">start</a> an <a href="#acceptor">acceptor</a>.
300 You can also run several acceptors in one image, each one
301 listening on a different different port.
302
303 <clix:class name='acceptor'>
304 <clix:description>
305 To create a Hunchentoot webserver, you make an instance of
306 this class or one of its subclasses and use the generic
307 function <clix:ref>START</clix:ref> to start it (and
308 <clix:ref>STOP</clix:ref> to stop it). Use the
309 <code>:port</code> initarg if you don't want to listen
310 on the default http port 80. If 0 is specified for the
311 port, the system chooses a random port to listen on. The
312 port number choosen can be retrieved using the
313 <clix:ref>ACCEPTOR-PORT</clix:ref> accessor. The port
314 number chosen is retained across stopping and starting the
315 acceptor.
316 <p>
317 There are other initargs most of which you probably
318 won't need very often. They are explained in detail
319 in the docstrings of the slot definitions.
320 </p>
321 <p>
322 Unless you are in a Lisp without MP capabilities, you can
323 have several active instances of
324 <clix:ref>ACCEPTOR</clix:ref> (listening on different
325 ports) at the same time.
326 </p>
327 </clix:description>
328 </clix:class>
329
330 <clix:class name='ssl-acceptor'>
331 <clix:description>Create and <clix:ref>START</clix:ref> an instance of this class
332 (instead of <clix:ref>ACCEPTOR</clix:ref>) if you want an https server. There are two
333 required initargs, <code>:SSL-CERTIFICATE-FILE</code> and <code>:SSL-PRIVATEKEY-FILE</code>, for
334 pathname designators denoting the certificate file and the key file in
335 PEM format. On LispWorks, you can have both in one file in which case
336 the second initarg is optional. You can also use the
337 <code>:SSL-PRIVATEKEY-PASSWORD</code> initarg to provide a password
338 (as a string) for the key file (or <code>NIL</code>, the default, for
339 no password).
340 <p>
341 The default port for <clix:ref>SSL-ACCEPTOR</clix:ref> instances is 443 instead of 80
342 </p>
343 </clix:description>
344 </clix:class>
345
346 <clix:function generic='true' name='start'>
347 <clix:lambda-list>acceptor
348 </clix:lambda-list>
349 <clix:returns>acceptor
350 </clix:returns>
351 <clix:description>Starts <clix:arg>acceptor</clix:arg> so that it begins accepting
352 connections. Returns the acceptor.
353 </clix:description>
354 </clix:function>
355
356 <clix:function generic='true' name='stop'>
357 <clix:lambda-list>acceptor &key soft</clix:lambda-list>
358 <clix:returns>acceptor
359 </clix:returns>
360 <clix:description>Stops the <clix:arg>acceptor</clix:arg> so
361 that it no longer accepts requests. If
362 <clix:arg>soft</clix:arg> is true, and there are any requests
363 in progress, wait until all requests are fully processed, but
364 meanwhile do not accept new requests. Note that
365 <clix:arg>soft</clix:arg> must not be set when calling
366 <clix:ref>stop</clix:ref> from within a request handler, as
367 that will deadlock.
368 </clix:description>
369 </clix:function>
370
371 <clix:special-variable name='*acceptor*'>
372 <clix:description>The current ACCEPTOR object in the context of a request.
373 </clix:description>
374 </clix:special-variable>
375
376 <clix:function generic='true' name='acceptor-listen-backlog'>
377 <clix:lambda-list>listen-backlog
378 </clix:lambda-list>
379 <clix:returns>number-of-pending-connections
380 </clix:returns>
381 <clix:description>
382 Number of pending connections allowed in the listen socket
383 before the kernel rejects further incoming connections.
384 Non-LispWorks only.
385 </clix:description>
386 </clix:function>
387
388 <clix:readers generic='true'>
389 <clix:listed-reader generic='true' name='acceptor-address'>
390 <clix:lambda-list>acceptor
391 </clix:lambda-list>
392 <clix:returns>address
393 </clix:returns>
394 </clix:listed-reader>
395
396 <clix:listed-reader generic='true' name='acceptor-port'>
397 <clix:lambda-list>acceptor
398 </clix:lambda-list>
399 <clix:returns>port
400 </clix:returns>
401 </clix:listed-reader>
402
403 <clix:listed-reader generic='true' name='acceptor-read-timeout'>
404 <clix:lambda-list>acceptor
405 </clix:lambda-list>
406 <clix:returns>read-timeout
407 </clix:returns>
408 </clix:listed-reader>
409
410 <clix:listed-reader generic='true' name='acceptor-ssl-certificate-file'>
411 <clix:lambda-list>ssl-acceptor
412 </clix:lambda-list>
413 <clix:returns>ssl-certificate-file
414 </clix:returns>
415 </clix:listed-reader>
416
417 <clix:listed-reader generic='true' name='acceptor-ssl-privatekey-file'>
418 <clix:lambda-list>ssl-acceptor
419 </clix:lambda-list>
420 <clix:returns>ssl-privatekey-file
421 </clix:returns>
422 </clix:listed-reader>
423
424 <clix:listed-reader generic='true' name='acceptor-ssl-privatekey-password'>
425 <clix:lambda-list>ssl-acceptor
426 </clix:lambda-list>
427 <clix:returns>ssl-privatekey-password
428 </clix:returns>
429 </clix:listed-reader>
430
431 <clix:listed-reader generic='true' name='acceptor-write-timeout'>
432 <clix:lambda-list>acceptor
433 </clix:lambda-list>
434 <clix:returns>write-timeout
435 </clix:returns>
436 </clix:listed-reader>
437
438 <clix:description>
439 These are readers for various slots of <clix:ref>ACCEPTOR</clix:ref>
440 objects (and some of them obviously only make sense
441 for <clix:ref>SSL-ACCEPTOR</clix:ref> objects). See the docstrings of
442 these slots for more information and note that there are corresponding
443 initargs for all of them.
444 </clix:description>
445 </clix:readers>
446
447 <clix:accessors generic='true'>
448 <clix:listed-accessor generic='true' name='acceptor-access-log-destination'>
449 <clix:lambda-list>acceptor
450 </clix:lambda-list>
451 <clix:returns>(or pathname null)
452 </clix:returns>
453 </clix:listed-accessor>
454
455 <clix:listed-accessor generic='true' name='acceptor-document-root'>
456 <clix:lambda-list>acceptor
457 </clix:lambda-list>
458 <clix:returns>(or pathname null)
459 </clix:returns>
460 </clix:listed-accessor>
461
462 <clix:listed-accessor generic='true' name='acceptor-error-template-directory'>
463 <clix:lambda-list>acceptor
464 </clix:lambda-list>
465 <clix:returns>(or pathname null)
466 </clix:returns>
467 </clix:listed-accessor>
468
469 <clix:listed-accessor generic='true' name='acceptor-input-chunking-p'>
470 <clix:lambda-list>acceptor
471 </clix:lambda-list>
472 <clix:returns>input-chunking-p
473 </clix:returns>
474 </clix:listed-accessor>
475
476 <clix:listed-accessor generic='true' name='acceptor-message-log-destination'>
477 <clix:lambda-list>acceptor
478 </clix:lambda-list>
479 <clix:returns>(or pathname null)
480 </clix:returns>
481 </clix:listed-accessor>
482
483 <clix:listed-accessor generic='true' name='acceptor-name'>
484 <clix:lambda-list>acceptor
485 </clix:lambda-list>
486 <clix:returns>name
487 </clix:returns>
488 </clix:listed-accessor>
489
490 <clix:listed-accessor generic='true' name='acceptor-output-chunking-p'>
491 <clix:lambda-list>acceptor
492 </clix:lambda-list>
493 <clix:returns>output-chunking-p
494 </clix:returns>
495 </clix:listed-accessor>
496
497 <clix:listed-accessor generic='true' name='acceptor-persistent-connections-p'>
498 <clix:lambda-list>acceptor
499 </clix:lambda-list>
500 <clix:returns>persistent-connections-p
501 </clix:returns>
502 </clix:listed-accessor>
503
504 <clix:listed-accessor generic='true' name='acceptor-reply-class'>
505 <clix:lambda-list>acceptor
506 </clix:lambda-list>
507 <clix:returns>reply-class
508 </clix:returns>
509 </clix:listed-accessor>
510
511 <clix:listed-accessor generic='true' name='acceptor-request-class'>
512 <clix:lambda-list>acceptor
513 </clix:lambda-list>
514 <clix:returns>request-class
515 </clix:returns>
516 </clix:listed-accessor>
517
518 <clix:description>
519 These are accessors for various slots of <clix:ref>ACCEPTOR</clix:ref>
520 objects. See the docstrings of these slots for more information and
521 note that there are corresponding initargs for all of them.
522 </clix:description>
523 </clix:accessors>
524
525 <clix:function generic='true' name='acceptor-ssl-p'>
526 <clix:lambda-list>acceptor
527 </clix:lambda-list>
528 <clix:returns>generalized-boolean
529 </clix:returns>
530 <clix:description>Returns a true value if <clix:arg>acceptor</clix:arg> uses SSL
531 connections. The default is to unconditionally return <code>NIL</code> and
532 subclasses of <clix:ref>ACCEPTOR</clix:ref> must specialize this method to signal that
533 they're using secure connections - see the <clix:ref>SSL-ACCEPTOR</clix:ref> class.
534 </clix:description>
535 </clix:function>
536
537 <clix:special-variable name='*default-connection-timeout*'>
538 <clix:description>The default connection timeout used when an
539 acceptor is reading from and writing to a socket stream. Note that
540 some Lisps allow you to set different timeouts for reading and writing
541 and you can specify both values via initargs when you create
542 an <a href="#acceptors">acceptor</a>.
543 </clix:description>
544 </clix:special-variable>
545
546 <clix:function generic='true' name='acceptor-remove-session'>
547 <clix:lambda-list>acceptor session
548 </clix:lambda-list>
549 <clix:returns>|
550 </clix:returns>
551 <clix:description>
552 This function is called whenever a session in
553 <clix:ref>ACCEPTOR</clix:ref> is being destroyed because of
554 a session timout or an explicit
555 <clix:ref>REMOVE-SESSION</clix:ref> call.
556 </clix:description>
557 </clix:function>
558
559 </clix:subchapter>
560
561 <clix:subchapter name="acceptor-behaviour" title="Customizing acceptor behaviour">
562
563 If you want to modify what acceptors do, you should subclass
564 <clix:ref>ACCEPTOR</clix:ref> (or <clix:ref>SSL-ACCEPTOR</clix:ref>) and
565 specialize the generic functions that constitute their behaviour (see
566 example below). The life of an acceptor looks like this: It is started
567 with the function <clix:ref>START</clix:ref> which immediately calls
568 <clix:ref>START-LISTENING</clix:ref> and then applies the function
569 <clix:ref>EXECUTE-ACCEPTOR</clix:ref> to its <a
570 href="#taskmasters">taskmaster</a>. This function will eventually call
571 <clix:ref>ACCEPT-CONNECTIONS</clix:ref> which is responsible for setting
572 things up to wait for clients to connect. For each incoming connection
573 which comes in, <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref> is applied
574 to the taskmaster which will either call
575 <clix:ref>PROCESS-CONNECTION</clix:ref> directly, or will create a thread
576 to call it. <clix:ref>PROCESS-CONNECTION</clix:ref> calls
577 <clix:ref>INITIALIZE-CONNECTION-STREAM</clix:ref> before it does anything
578 else, then it selects and calls a function which handles the <a
579 href="#requests">request</a>, and finally it sends the <a
580 href="#replies">reply</a> to the client before it calls
581 <clix:ref>RESET-CONNECTION-STREAM</clix:ref>. If the connection is
582 persistent, this procedure is repeated (except for the intialization step)
583 in a loop until the connection is closed. The acceptor is stopped with
584 <clix:ref>STOP</clix:ref>.
585
586 <p>
587 If you just want to use the standard acceptors that come with
588 Hunchentoot, you don't need to know anything about the functions
589 listed in this section.
590 </p>
591
592 <clix:function generic='true' name='start-listening'>
593 <clix:lambda-list>acceptor
594 </clix:lambda-list>
595 <clix:returns>|
596 </clix:returns>
597 <clix:description>Sets up a listen socket for the given acceptor and
598 enables it to listen to incoming connections. This function is called
599 from the thread that starts the acceptor initially and may return
600 errors resulting from the listening operation (like 'address in use'
601 or similar).
602 </clix:description>
603 </clix:function>
604
605 <clix:function generic='true' name='accept-connections'>
606 <clix:lambda-list>acceptor
607 </clix:lambda-list>
608 <clix:returns>nil
609 </clix:returns>
610 <clix:description>In a loop, accepts a connection and hands it over
611 to the acceptor's taskmaster for processing using
612 <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref>. On LispWorks, this
613 function returns immediately, on other Lisps it returns only once the
614 acceptor has been stopped.
615 </clix:description>
616 </clix:function>
617
618 <clix:function generic='true' name='process-connection'>
619 <clix:lambda-list>acceptor socket
620 </clix:lambda-list>
621 <clix:returns>nil
622 </clix:returns>
623 <clix:description>
624 This function is called by the taskmaster when a new client
625 connection has been established. Its arguments are the
626 <clix:ref>ACCEPTOR</clix:ref> object and a LispWorks socket
627 handle or a usocket socket stream object in
628 <clix:arg>socket</clix:arg>. It reads the request headers,
629 sets up the <a href="#requests">request</a> and <a
630 href="#replies">reply</a> objects, and hands over to
631 <clix:ref>PROCESS-REQUEST</clix:ref> which calls
632 <clix:ref>HANDLE-REQUEST</clix:ref> to select and call a
633 handler for the request and sends its reply to the client.
634 This is done in a loop until the stream has to be closed or
635 until a connection timeout occurs. It is probably not a
636 good idea to re-implement this method until you really,
637 really know what you're doing.
638 <p>
639 Handlers may call to the
640 <clix:ref>DETACH-SOCKET</clix:ref> generic function to
641 indicate that no further requests should be handled on
642 the connection by Hunchentoot, and that responsibility for
643 the socket is assumed by third-party software. This can
644 be used by specialized handlers that wish to hand over
645 connection polling or processing to functions outside of
646 Hunchentoot, i.e. for connection multiplexing or
647 implementing specialized client protocols. Hunchentoot
648 will finish processing the request and the
649 <clix:ref>PROCESS-CONNECTION</clix:ref> function will
650 return without closing the connection. At that point,
651 the acceptor may interact with the socket in whatever
652 fashion required.
653 </p>
654 </clix:description>
655 </clix:function>
656
657 <clix:function generic='true' name='detach-socket'>
658 <clix:lambda-list>acceptor
659 </clix:lambda-list>
660 <clix:returns>stream
661 </clix:returns>
662 <clix:description>
663 Indicate to Hunchentoot that it should stop serving requests
664 on the current request's socket. Hunchentoot will finish
665 processing the current request and then return from
666 <clix:ref>PROCESS-CONNECTION</clix:ref> without closing the
667 connection to the client.
668 <clix:ref>DETACH-SOCKET</clix:ref> can only be called from
669 within a request handler function.
670 </clix:description>
671 </clix:function>
672
673 <clix:function generic='true' name='initialize-connection-stream'>
674 <clix:lambda-list>acceptor stream
675 </clix:lambda-list>
676 <clix:returns>stream
677 </clix:returns>
678 <clix:description>
679 Can be used to modify the stream which is used to
680 communicate between client and server before the request is
681 read. The default method of <clix:ref>ACCEPTOR</clix:ref>
682 does nothing, but see for example the method defined for
683 <clix:ref>SSL-ACCEPTOR</clix:ref>. All methods of this
684 generic function <em>must</em> return the stream to use.
685 </clix:description>
686 </clix:function>
687
688 <clix:function generic='true' name='reset-connection-stream'>
689 <clix:lambda-list>acceptor stream
690 </clix:lambda-list>
691 <clix:returns>stream
692 </clix:returns>
693 <clix:description>
694 Resets the stream which is used to communicate
695 between client and server after one request has been served so that it
696 can be used to process the next request. This generic function is
697 called after a request has been processed and <em>must</em> return the
698 stream.
699 </clix:description>
700 </clix:function>
701
702 <clix:function name="acceptor-log-access" generic="true">
703 <clix:lambda-list>acceptor &key return-code</clix:lambda-list>
704 <clix:description>
705 Function to call to log access to the acceptor. The
706 <clix:arg>return-code</clix:arg> keyword argument contains additional
707 information about the request to log. In addition, it can use the
708 standard request and reply accessor functions that are available to
709 handler functions to find out more information about the request.
710 </clix:description>
711 </clix:function>
712
713 <clix:function name="acceptor-log-message" generic="true">
714 <clix:lambda-list>acceptor log-level format-string &rest format-arguments</clix:lambda-list>
715 <clix:description>
716 Function to call to log messages by the <clix:arg>acceptor</clix:arg>. It must accept
717 a severity level for the message, which will be one of :ERROR, :INFO,
718 or :WARNING, a format string and an arbitary number of formatting
719 arguments.
720 </clix:description>
721 </clix:function>
722
723 <clix:function name="acceptor-status-message" generic="true">
724 <clix:lambda-list>acceptor http-return-code &key &allow-other-keys</clix:lambda-list>
725 <clix:description>
726 This function is called when a request's handler has been
727 called but failed to provide content to send back to the
728 client. It converts the
729 <clix:arg>HTTP-STATUS-CODE</clix:arg> to some request
730 contents, typically a human readable description of the
731 status code to be displayed to the user.
732
733 If an ERROR-TEMPLATE-DIRECTORY is set in the current
734 acceptor and the directory contains a file corresponding to
735 HTTP-STATUS-CODE named <code>.html, that file is sent
736 to the client after variable substitution. Variables are
737 referenced by ${<variable-name>}.
738
739 Additional keyword arguments may be provided which are made
740 available to the templating logic as substitution variables.
741 These variables can be interpolated into error message
742 templates in, which contains the current URL relative to the
743 server and without GET parameters.
744
745 In addition to the variables corresponding to keyword
746 arguments, the script-name, lisp-implementation-type,
747 lisp-implementation-version and hunchentoot-version
748 variables are available.
749 </clix:description>
750 </clix:function>
751 </clix:subchapter>
752
753 <clix:subchapter name="subclassing-acceptors"
754 title="An example of how to subclass ACCEPTOR">
755
756 This example shows how to subclass <clix:ref>ACCEPTOR</clix:ref> in order to
757 provide Hunchentoot with basic virtual host support.  It assumes
758 Hunchentoot is sitting behind an Internet-facing reverse-proxy web server
759 that maps the host (or domain) part of incoming HTTP requests to unique
760 localhost ports.
761
762 <pre>(asdf:load-system "hunchentoot")
763 (asdf:load-system "drakma")
764
765 ;;; Subclass ACCEPTOR
766 (defclass vhost (tbnl:acceptor)
767 ;; slots
768 ((dispatch-table
769 :initform '()
770 :accessor dispatch-table
771 :documentation "List of dispatch functions"))
772 ;; options
773 (:default-initargs ; default-initargs must be used
774 :address "127.0.0.1")) ; because ACCEPTOR uses it
775
776 ;;; Specialise ACCEPTOR-DISPATCH-REQUEST for VHOSTs
777 (defmethod tbnl:acceptor-dispatch-request ((vhost vhost) request)
778 ;; try REQUEST on each dispatcher in turn
779 (mapc (lambda (dispatcher)
780 (let ((handler (funcall dispatcher request)))
781 (when handler ; Handler found. FUNCALL it and return result
782 (return-from tbnl:acceptor-dispatch-request (funcall handler)))))
783 (dispatch-table vhost))
784 (call-next-method))
785
786 ;;; ======================================================================
787 ;;; Now all we need to do is test it
788
789 ;;; Instantiate VHOSTs
790 (defvar vhost1 (make-instance 'vhost :port 50001))
791 (defvar vhost2 (make-instance 'vhost :port 50002))
792
793 ;;; Populate each dispatch table
794 (push
795 (tbnl:create-prefix-dispatcher "/foo" 'foo1)
796 (dispatch-table vhost1))
797 (push
798 (tbnl:create-prefix-dispatcher "/foo" 'foo2)
799 (dispatch-table vhost2))
800
801 ;;; Define handlers
802 (defun foo1 () "Hello")
803 (defun foo2 () "Goodbye")
804
805 ;;; Start VHOSTs
806 (tbnl:start vhost1)
807 (tbnl:start vhost2)
808
809 ;;; Make some requests
810 (drakma:http-request "http://127.0.0.1:50001/foo")
811 ;;; =|
812 ;;; 127.0.0.1 - [2012-06-08 14:30:39] "GET /foo HTTP/1.1" 200 5 "-" "Drakma/1.2.6 (SBCL 1.0.56; Linux; 2.6.32-5-686; http://weitz.de/drakma/)"
813 ;;; =>
814 ;;; "Hello"
815 ;;; 200
816 ;;; ((:CONTENT-LENGTH . "5") (:DATE . "Fri, 08 Jun 2012 14:30:39 GMT")
817 ;;; (:SERVER . "Hunchentoot 1.2.3") (:CONNECTION . "Close")
818 ;;; (:CONTENT-TYPE . "text/html; charset=utf-8"))
819 ;;; #<PURI:URI http://127.0.0.1:50001/foo>
820 ;;; #<FLEXI-STREAMS:FLEXI-IO-STREAM {CA90059}>
821 ;;; T
822 ;;; "OK"
823 (drakma:http-request "http://127.0.0.1:50002/foo")
824 ;;; =|
825 ;;; 127.0.0.1 - [2012-06-08 14:30:47] "GET /foo HTTP/1.1" 200 7 "-" "Drakma/1.2.6 (SBCL 1.0.56; Linux; 2.6.32-5-686; http://weitz.de/drakma/)"
826 ;;; =>
827 ;;; "Goodbye"
828 ;;; 200
829 ;;; ((:CONTENT-LENGTH . "7") (:DATE . "Fri, 08 Jun 2012 14:30:47 GMT")
830 ;;; (:SERVER . "Hunchentoot 1.2.3") (:CONNECTION . "Close")
831 ;;; (:CONTENT-TYPE . "text/html; charset=utf-8"))
832 ;;; #<PURI:URI http://127.0.0.1:50002/foo>
833 ;;; #<FLEXI-STREAMS:FLEXI-IO-STREAM {CAE8059}>
834 ;;; T
835 ;;; "OK"</pre>
836
837 How to make each VHOST write to separate access log streams (or files) is
838 left as an exercise to the reader.
839
840 </clix:subchapter>
841
842 <clix:subchapter name="taskmasters" title="Taskmasters">
843 As a "normal" Hunchentoot user, you can completely ignore
844 taskmasters and skip this section. But if you're still reading,
845 here are the dirty details: Each <a
846 href="#acceptors">acceptor</a> has a taskmaster associated with
847 it at creation time. It is the taskmaster's job to distribute
848 the work of accepting and handling incoming connections. The
849 acceptor calls the taskmaster if appropriate and the taskmaster
850 calls back into the acceptor. This is done using the generic
851 functions described in this and the <a
852 href="#acceptor-behaviour">previous</a> section. Hunchentoot
853 comes with two standard taskmaster implementations - one (which
854 is the default used on multi-threaded Lisps) which starts a new
855 thread for each incoming connection and one which handles all
856 requests sequentially. It should for example be relatively
857 straightforward to create a taskmaster which allocates threads
858 from a fixed pool instead of creating a new one for each
859 connection.
860
861 <p>
862 You can control the resources consumed by a threaded taskmaster via
863 two initargs. <code>:max-thread-count</code> lets you set the maximum
864 number of request threads that can be processes simultaneously. If
865 this is <code>nil</code>, the is no thread limit imposed.
866
867 <code>:max-accept-count</code> lets you set the maximum number of requests
868 that can be outstanding (i.e. being processed or queued for processing).
869
870 If <code>:max-thread-count</code> is supplied and <code>:max-accept-count</code>
871 is <code>NIL</code>, then a <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>
872 error will be generated if there are more than the max-thread-count
873 threads processing requests. If both <code>:max-thread-count</code>
874 and <code>:max-accept-count</code> are supplied, then max-thread-count
875 must be less than max-accept-count; if more than max-thread-count
876 requests are being processed, then requests up to max-accept-count
877 will be queued until a thread becomes available. If more than
878 max-accept-count requests are outstanding, then a <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>
879 error will be generated.
880
881 In a load-balanced environment with multiple Hunchentoot servers, it's
882 reasonable to provide <code>:max-thread-count</code> but leave
883 <code>:max-accept-count</code> null. This will immediately result
884 in <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref> when one server is
885 out of resources, so the load balancer can try to find another server.
886
887 In an environment with a single Hunchentoot server, it's reasonable
888 to provide both <code>:max-thread-count</code> and a somewhat larger value
889 for <code>:max-accept-count</code>. This will cause a server that's almost
890 out of resources to wait a bit; if the server is completely out of resources,
891 then the reply will be <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>.
892 The default for these values is 100 and 120, respectively.
893 </p>
894
895 <p>
896 If you want to implement your own taskmasters, you should subclass
897 <clix:ref>TASKMASTER</clix:ref> or one of its subclasses,
898 <clix:ref>SINGLE-THREADED-TASKMASTER</clix:ref> or
899 <clix:ref>ONE-THREAD-PER-CONNECTION-TASKMASTER</clix:ref>, and
900 specialize the generic functions in this section.
901 </p>
902
903 <clix:class name='taskmaster'>
904 <clix:description>
905 An instance of this class is responsible for distributing
906 the work of handling requests for its acceptor. This is an
907 "abstract" class in the sense that usually only instances of
908 subclasses of <clix:ref>TASKMASTER</clix:ref> will be used.
909 </clix:description>
910 </clix:class>
911
912 <clix:class name='one-thread-per-connection-taskmaster'>
913 <clix:description>
914 A taskmaster that starts one thread for listening to
915 incoming requests and one thread for each incoming
916 connection.
917 <p>
918 This is the default taskmaster implementation for multi-threaded Lisp
919 implementations.
920 </p>
921 </clix:description>
922 </clix:class>
923
924 <clix:class name='single-threaded-taskmaster'>
925 <clix:description>
926 A taskmaster that runs synchronously in the
927 thread where the <clix:ref>START</clix:ref> function was invoked (or
928 in the case of LispWorks in the thread started
929 by <a href="http://www.lispworks.com/documentation/lw51/LWRM/html/lwref-61.htm#marker-910861"><code>COMM:START-UP-SERVER</code></a>).
930 This is the simplest possible taskmaster implementation in that its
931 methods do nothing but calling their acceptor "sister"
932 methods - <clix:ref>EXECUTE-ACCEPTOR</clix:ref> calls <clix:ref>ACCEPT-CONNECTIONS</clix:ref>,
933 <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref> calls <clix:ref>PROCESS-CONNECTION</clix:ref>.
934 </clix:description>
935 </clix:class>
936
937 <clix:class name='multi-threaded-taskmaster'>
938 <clix:description>
939 This is an abstract class for taskmasters that use multiple threads;
940 it is not a concrete class and you should not instantiate it with
941 <code>MAKE-INSTANCE</code>.
942 Instead, you should instantiate its subclass
943 <clix:ref>ONE-THREAD-PER-CONNECTION-TASKMASTER</clix:ref> described above.
944 <clix:ref>MULTI-THREADED-TASKMASTER</clix:ref>
945 is intended to be inherited from by extensions to Hunchentoot,
946 such as <a href="http://common-lisp.net/project/qitab/">quux-hunchentoot</a>'s
947 <code>THREAD-POOLING-TASKMASTER</code>,
948 though at the moment, doing so only inherits one slot and one method,
949 on <clix:ref>EXECUTE-ACCEPTOR</clix:ref>,
950 to have it start a new thread for the acceptor,
951 then saved in said slot.
952 </clix:description>
953 </clix:class>
954
955 <clix:function generic='true' name='execute-acceptor'>
956 <clix:lambda-list>taskmaster
957 </clix:lambda-list>
958 <clix:returns>result
959 </clix:returns>
960 <clix:description>This is a callback called by the acceptor once it
961 has performed all initial processing to start listening for incoming
962 connections (see <clix:ref>START-LISTENING</clix:ref>). It usually calls the
963 <clix:ref>ACCEPT-CONNECTIONS</clix:ref> method of the acceptor, but depending on the
964 taskmaster instance the method might be called from a new thread.
965 </clix:description>
966 </clix:function>
967
968 <clix:function generic='true' name='handle-incoming-connection'>
969 <clix:lambda-list>taskmaster socket
970 </clix:lambda-list>
971 <clix:returns>result
972 </clix:returns>
973 <clix:description>
974 This function is called by the acceptor to start
975 processing of requests on a new incoming connection. <clix:arg>socket</clix:arg> is the
976 usocket instance that represents the new connection (or a socket
977 handle on LispWorks). The taskmaster starts processing requests on
978 the incoming connection by calling the <clix:ref>PROCESS-CONNECTION</clix:ref>
979 method of the acceptor instance. The <clix:arg>socket</clix:arg> argument is passed to
980 <clix:ref>PROCESS-CONNECTION</clix:ref> as an argument.
981
982 If the taskmaster is a multi-threaded taskmaster, <clix:ref>HANDLE-INCOMING-THREAD</clix:ref>
983 will call <clix:ref>CREATE-REQUEST-HANDLER-THREAD</clix:ref>, which will call
984 <clix:ref>PROCESS-CONNECTION</clix:ref> in a new thread.
985 <clix:ref>HANDLE-INCOMING-THREAD</clix:ref> might issue a
986 <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref> error
987 if there are too many request threads or it might block waiting for a
988 request thread to finish.
989 </clix:description>
990 </clix:function>
991
992 <clix:function generic='true' name='start-thread'>
993 <clix:lambda-list>taskmaster thunk &key
994 </clix:lambda-list>
995 <clix:returns>thread
996 </clix:returns>
997 <clix:description>This function is a callback that
998 starts a new thread that will call the given <clix:arg>thunk</clix:arg>
999 in the context of the proper <clix:arg>taskmaster</clix:arg>,
1000 with appropriate context-dependent keyword arguments.
1001 <clix:ref>ONE-THREAD-PER-CONNECTION-TASKMASTER</clix:ref> uses it in
1002 <clix:ref>EXECUTE-ACCEPTOR</clix:ref>
1003 and <clix:ref>CREATE-REQUEST-HANDLER-THREAD</clix:ref>,
1004 but specialized taskmasters may define more functions that use it.
1005 By default, it just creates a thread calling the thunk
1006 with a specified <clix:arg>name</clix:arg> keyword argument.
1007 Specialized taskmasters may wrap special bindings and condition handlers
1008 around the thunk call, register the thread in a management table, etc.
1009 </clix:description>
1010 </clix:function>
1011
1012 <clix:function generic='true' name='create-request-handler-thread'>
1013 <clix:lambda-list>taskmaster socket
1014 </clix:lambda-list>
1015 <clix:returns>thread
1016 </clix:returns>
1017 <clix:description>This function is called by <clix:ref>HANDLE-INCOMING-THREAD</clix:ref>
1018 to create a new thread which calls <clix:ref>PROCESS-CONNECTION</clix:ref>.
1019 If you specialize this function, you must be careful to have the thread
1020 call <clix:ref>DECREMENT-TASKMASTER-REQUEST-COUNT</clix:ref> before
1021 it exits. A typical method will look like this:
1022
1023 <pre>(defmethod create-request-handler-thread ((taskmaster monitor-taskmaster) socket)
1024 (bt:make-thread
1025 (lambda ()
1026 (with-monitor-error-handlers
1027 (unwind-protect
1028 (with-monitor-variable-bindings
1029 (process-connection (taskmaster-acceptor taskmaster) socket))
1030 (decrement-taskmaster-request-count taskmaster))))))</pre>
1031
1032
1033
1034
1035
1036
1037
1038 </clix:description>
1039 </clix:function>
1040
1041 <clix:function generic='true' name='shutdown'>
1042 <clix:lambda-list>taskmaster
1043 </clix:lambda-list>
1044 <clix:returns>taskmaster
1045 </clix:returns>
1046 <clix:description>Shuts down the taskmaster, i.e. frees all resources
1047 that were set up by it. For example, a multi-threaded taskmaster
1048 might terminate all threads that are currently associated with it.
1049 This function is called by the acceptor's <clix:ref>STOP</clix:ref> method.
1050 </clix:description>
1051 </clix:function>
1052
1053 <clix:accessor generic='true' name='taskmaster-acceptor'>
1054 <clix:lambda-list>taskmaster
1055 </clix:lambda-list>
1056 <clix:returns>acceptor
1057 </clix:returns>
1058 <clix:description>
1059 This is an accessor for the slot of a <clix:ref>TASKMASTER</clix:ref>
1060 object that links back to the <a href="#acceptors">acceptor</a> it is
1061 associated with.
1062 </clix:description>
1063 </clix:accessor>
1064
1065 </clix:subchapter>
1066
1067 <clix:subchapter name="request-dispatch" title="Request dispatch and handling">
1068
1069 The main job of <clix:ref>HANDLE-REQUEST</clix:ref> is to select
1070 and call a function which handles the request, i.e. which looks
1071 at the data the client has sent and prepares an appropriate
1072 reply to send back. This is by default implemented as follows:
1073 <p>
1074 The ACCEPTOR class defines a
1075 <clix:ref>ACCEPTOR-DISPATCH-REQUEST</clix:ref> generic
1076 function which is used to actually dispatch the request. This
1077 function is called by the default method of
1078 <clix:ref>HANDLE-REQUEST</clix:ref>. Each
1079 <clix:ref>ACCEPTOR-DISPATCH-REQUEST</clix:ref> method looks at
1080 the request object and depending on its contents decides to
1081 either handle the request or call the next method.
1082 </p>
1083 <p>
1084 In order to dispatch a request, Hunchentoot calls the
1085 <clix:ref>ACCEPTOR-DISPATCH-REQUEST</clix:ref> generic
1086 functions. The method for <clix:ref>ACCEPTOR</clix:ref> tries
1087 to serve a static file relative to it's
1088 <clix:ref>ACCEPTOR-DOCUMENT-ROOT</clix:ref>. Application
1089 specific acceptor subclasses will typically perform URL
1090 parsing and dispatching according to the policy that is
1091 required.
1092 </p>
1093 <p>
1094 The default method of <clix:ref>HANDLE-REQUEST</clix:ref> sets
1095 up <a href="#logging">standard logging and error handling</a>
1096 before it calls the acceptor's request dispatcher.
1097 </p>
1098 <p>
1099 Request handlers do their work by modifying
1100 the <a href="#replies">reply object</a> if necessary and by eventually
1101 returning the response body in the form of a string or a binary
1102 sequence. As an alternative, they can also
1103 call <clix:ref>SEND-HEADERS</clix:ref> and write directly to a stream.
1104 </p>
1105 </clix:subchapter>
1106
1107 <clix:subchapter name="easy-handlers" title="Using the easy-handler framework">
1108 <p>
1109 The <clix:ref>EASY-ACCEPTOR</clix:ref> class defines a method
1110 for <clix:ref>ACCEPTOR-DISPATCH-REQUEST</clix:ref> that walks
1111 through the list <clix:ref>*DISPATCH-TABLE*</clix:ref> which
1112 consists of <em>dispatch functions</em>. Each of these
1113 functions accepts the request object as its only argument and
1114 either returns a request handler to handle the request or
1115 <code>NIL</code> which means that the next dispatcher in the
1116 list will be tried. A <em>request handler</em> is a function
1117 of zero arguments which relies on the special variable
1118 <clix:ref>*REQUEST*</clix:ref> to access the request instance
1119 being serviced. If all dispatch functions return
1120 <code>NIL</code>, the next
1121 <clix:ref>ACCEPTOR-DISPATCH-REQUEST</clix:ref> will be called.
1122 </p>
1123 <p>
1124 <strong>N.B.</strong> All functions and variables in this
1125 section are related to the easy request dispatch mechanism and
1126 are meaningless if you're using your own request dispatcher.
1127 </p>
1128
1129 <clix:class name='easy-acceptor'>
1130 <clix:description>
1131 This class defines no additional slots with respect to
1132 <clix:ref>ACCEPTOR</clix:ref>. It only serves as an
1133 additional type for dispatching calls to
1134 <clix:ref>ACCEPTOR-DISPATCH-REQUEST</clix:ref>. In order to
1135 use the easy handler framework, acceptors of this class or
1136 one of its subclasses must be used.
1137 </clix:description>
1138 </clix:class>
1139
1140 <clix:class name='easy-ssl-acceptor'>
1141 <clix:description>
1142 This class mixes the <clix:ref>SSL-ACCEPTOR</clix:ref> and
1143 the <clix:ref>EASY-ACCEPTOR</clix:ref> classes. It is used
1144 when both ssl and the easy handler framework are required.
1145 </clix:description>
1146 </clix:class>
1147
1148 <clix:special-variable name='*dispatch-table*'>
1149 <clix:description>
1150 A global list of dispatch functions. The initial value is a
1151 list consisting of the symbol
1152 <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>.
1153 </clix:description>
1154 </clix:special-variable>
1155
1156 <clix:function name="create-prefix-dispatcher">
1157 <clix:lambda-list>prefix handler</clix:lambda-list>
1158 <clix:returns>dispatch-fn</clix:returns>
1159 <clix:description>
1160 A convenience function which will return a dispatcher that
1161 returns <clix:arg>handler</clix:arg> whenever the path part of
1162 the request URI starts with the
1163 string <clix:arg>prefix</clix:arg>.
1164 </clix:description>
1165 </clix:function>
1166
1167 <clix:function name="create-regex-dispatcher">
1168 <clix:lambda-list>regex handler</clix:lambda-list>
1169 <clix:returns>dispatch-fn</clix:returns>
1170 <clix:description>
1171 A convenience function which will return a dispatcher that
1172 returns <clix:arg>handler</clix:arg> whenever the path part of
1173 the request URI matches
1174 the <a href="http://weitz.de/cl-ppcre/">CL-PPCRE</a> regular
1175 expression <clix:arg>regex</clix:arg> (which can be a string, an
1176 s-expression, or a scanner).
1177 </clix:description>
1178 </clix:function>
1179
1180 <clix:function name="create-folder-dispatcher-and-handler">
1181 <clix:lambda-list>uri-prefix base-path <clix:lkw>optional</clix:lkw> content-type</clix:lambda-list>
1182 <clix:returns>dispatch-fn</clix:returns>
1183 <clix:description>
1184 Creates and returns a dispatch function which will dispatch to
1185 a handler function which emits the file relative
1186 to <clix:arg>base-path</clix:arg> that is denoted by the URI of
1187 the request relative
1188 to <clix:arg>uri-prefix</clix:arg>. <clix:arg>uri-prefix</clix:arg>
1189 must be a string ending with a
1190 slash, <clix:arg>base-path</clix:arg> must be a pathname
1191 designator for an existing directory.
1192 Uses <clix:ref>HANDLE-STATIC-FILE</clix:ref> internally.
1193 <p>
1194 If <clix:arg>content-type</clix:arg> is <em>not</em>
1195 <code>NIL</code>, it will be used as a the content type for
1196 all files in the folder. Otherwise (which is the default)
1197 the content type of each file will be
1198 determined <a href="#handle-static-file">as usual</a>.
1199 </p>
1200 </clix:description>
1201 </clix:function>
1202
1203 <clix:function name='create-static-file-dispatcher-and-handler'>
1204 <clix:lambda-list>uri path
1205 <clix:lkw>optional
1206 </clix:lkw> content-type
1207 </clix:lambda-list>
1208 <clix:returns>result
1209 </clix:returns>
1210 <clix:description>
1211 Creates and returns a request dispatch function which will
1212 dispatch to a handler function which emits the file denoted
1213 by the pathname designator PATH with content type
1214 CONTENT-TYPE if the SCRIPT-NAME of the request matches the
1215 string URI. If CONTENT-TYPE is NIL, tries to determine the
1216 content type via the file's suffix.
1217 </clix:description>
1218 </clix:function>
1219
1220 <clix:function macro="true" name="define-easy-handler">
1221 <clix:lambda-list>description lambda-list [[declaration* | documentation]] form*</clix:lambda-list>
1222 <clix:description>
1223 Defines a handler as if
1224 by <a href="http://www.lispworks.com/documentation/HyperSpec/Body/m_defun.htm">
1225 <code>DEFUN</code></a> and optionally registers it with a
1226 URI so that it will be found
1227 by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>.
1228 <p>
1229 <clix:arg>description</clix:arg> is either a
1230 symbol <clix:arg>name</clix:arg> or a list matching the
1231 <a href="http://www.lispworks.com/documentation/HyperSpec/Body/03_de.htm">destructuring
1232 lambda list</a>
1233 </p>
1234 <pre>(name &key uri acceptor-names default-parameter-type default-request-type).</pre>
1235 <clix:arg>lambda-list</clix:arg> is a list the elements of which
1236 are either a symbol <clix:arg>var</clix:arg> or a list matching
1237 the destructuring lambda list
1238 <pre>(var &key real-name parameter-type init-form request-type).</pre>
1239 The resulting handler will be a Lisp function with the
1240 name <clix:arg>name</clix:arg> and keyword parameters named by
1241 the <clix:arg>var</clix:arg> symbols.
1242 Each <clix:arg>var</clix:arg> will be bound to the value of the
1243 GET or POST parameter called <clix:arg>real-name</clix:arg> (a
1244 string) before the body of the function is executed.
1245 If <clix:arg>real-name</clix:arg> is not provided, it will be
1246 computed
1247 by <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_stg_up.htm#string-downcase">downcasing</a>
1248 the symbol name of <clix:arg>var</clix:arg>.
1249 <p>
1250 If <clix:arg>uri</clix:arg> (which is evaluated) is provided,
1251 then it must be a string or
1252 a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_f.htm#function_designator">function
1253 designator</a> for a unary function. In this case, the
1254 handler will be returned
1255 by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>,
1256 if <clix:arg>uri</clix:arg> is a string and
1257 the <a href="#script-name">script name</a> of the current
1258 request is <clix:arg>uri</clix:arg>, or
1259 if <clix:arg>uri</clix:arg> designates a function and applying
1260 this function to
1261 the <a href="#*request*">current <code>REQUEST</code>
1262 object</a> returns a true value.
1263 </p>
1264 <p>
1265 <clix:arg>acceptor-names</clix:arg> (which is evaluated) can be a
1266 list of symbols which means that the handler will only be
1267 returned by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref> in
1268 acceptors which have one of these names
1269 (see <clix:ref>ACCEPTOR-NAME</clix:ref>). <clix:arg>acceptor-names</clix:arg> can also be the
1270 symbol <code>T</code> which means that the handler will be
1271 returned by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>
1272 in <em>every</em> acceptor.
1273 </p>
1274 <p>
1275 Whether the GET or POST parameter (or both) will be taken into
1276 consideration, depends on <clix:arg>request-type</clix:arg>
1277 which can
1278 be <code>:GET</code>, <code>:POST</code>, <code>:BOTH</code>,
1279 or <code>NIL</code>. In the last case, the value of
1280 <clix:arg>default-request-type</clix:arg> (the default of which
1281 is <code>:BOTH</code>) will be used.
1282 </p>
1283 <p>
1284 The value of <clix:arg>var</clix:arg> will usually be a string
1285 (unless it resulted from a <a href="#upload">file upload</a>
1286 in which case it won't be converted at all), but
1287 if <clix:arg>parameter-type</clix:arg> (which is evaluated) is
1288 provided, the string will be converted to another Lisp type by
1289 the following rules:
1290 </p>
1291 <p>
1292 If the corresponding GET or POST parameter wasn't provided by
1293 the client, <clix:arg>var</clix:arg>'s value will
1294 be <code>NIL</code>. If <clix:arg>parameter-type</clix:arg>
1295 is <code>'STRING</code>,
1296 <clix:arg>var</clix:arg>'s value remains as is.
1297 If <clix:arg>parameter-type</clix:arg> is <code>'INTEGER</code>
1298 and the parameter string consists solely of decimal
1299 digits, <clix:arg>var</clix:arg>'s value will be the
1300 corresponding integer, otherwise <code>NIL</code>.
1301 If <clix:arg>parameter-type</clix:arg> is
1302 <code>'KEYWORD</code>, <clix:arg>var</clix:arg>'s value will be
1303 the keyword obtained
1304 by <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_intern.htm">interning</a>
1305 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_stg_up.htm#string-upcase">upcased</a>
1306 parameter string into
1307 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/11_abc.htm">keyword
1308 package</a>. If <clix:arg>parameter-type</clix:arg>
1309 is <code>'CHARACTER</code> and the parameter string is of
1310 length one, <clix:arg>var</clix:arg>'s value will be the single
1311 character of this string, otherwise <code>NIL</code>.
1312 If <clix:arg>parameter-type</clix:arg>
1313 is <code>'BOOLEAN</code>, <clix:arg>var</clix:arg>'s value will
1314 always be <code>T</code> (unless it is <code>NIL</code> by the
1315 first rule above, of course).
1316 If <clix:arg>parameter-type</clix:arg> is any other atom, it is
1317 supposed to be
1318 a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_f.htm#function_designator">function
1319 designator</a> for a unary function which will be called to
1320 convert the string to something else.
1321 </p>
1322 <p>
1323 Those were the rules for <em>simple</em> parameter types, but
1324 <clix:arg>parameter-type</clix:arg> can also be a list starting
1325 with one of the symbols
1326 <code>LIST</code>, <code>ARRAY</code>,
1327 or <code>HASH-TABLE</code>. The second value of the list must
1328 always be a simple parameter type as in the last paragraph -
1329 we'll call it the <em>inner type</em> below.
1330 </p>
1331 <p>
1332 In the case of <code>'LIST</code>, all GET/POST parameters
1333 called <clix:arg>real-name</clix:arg> will be collected,
1334 converted to the inner type as by the rules above, and
1335 assembled into a list which will be the value of
1336 <clix:arg>var</clix:arg>.
1337 </p>
1338 <p>
1339 In the case of <code>'ARRAY</code>, all GET/POST parameters
1340 which have a name like the result of
1341 </p>
1342 <pre>(format nil "~A[~A]" real-name n)</pre>
1343 where <clix:arg>n</clix:arg> is a non-negative integer, will be
1344 assembled into an array where the <clix:arg>n</clix:arg>th element
1345 will be set accordingly, after conversion to the inner type.
1346 The array, which will become the value
1347 of <clix:arg>var</clix:arg>, will be big enough to hold all
1348 matching parameters, but not bigger. Array elements not set as
1349 described above will be <code>NIL</code>. Note
1350 that <code>VAR</code> will always be bound to an array, which
1351 may be empty, so it will never be <code>NIL</code>, even if no
1352 appropriate GET/POST parameters are found.
1353 <p>
1354 The full form of a <code>'HASH-TABLE</code> parameter type is
1355 </p>
1356 <pre>(hash-table inner-type key-type test-function)</pre>
1357 but <clix:arg>key-type</clix:arg>
1358 and <clix:arg>test-function</clix:arg> can be left out in which
1359 case they default to <code>'STRING</code>
1360 and <code>'EQUAL</code>, respectively. For this parameter type,
1361 all GET/POST parameters which have a name like the result of
1362 <pre>(format nil "~A{~A}" real-name key)</pre>
1363 (where <clix:arg>key</clix:arg> is a string that doesn't contain
1364 curly brackets) will become the values (after conversion
1365 to <clix:arg>inner-type</clix:arg>) of a hash table with test
1366 function <clix:arg>test-function</clix:arg>
1367 where <clix:arg>key</clix:arg> (after conversion
1368 to <clix:arg>key-type</clix:arg>) will be the corresponding key.
1369 Note that <clix:arg>var</clix:arg> will always be bound to a hash
1370 table, which may be empty, so it will never be <code>NIL</code>,
1371 even if no appropriate GET/POST parameters are found.
1372 <p>
1373 To make matters even more complicated, the three compound
1374 parameter types also have an abbreviated form - just one of
1375 the symbols <code>LIST</code>, <code>ARRAY</code>,
1376 or <code>HASH-TABLE</code>. In this case, the inner type will
1377 default to <code>'STRING</code>.
1378 </p>
1379 <p>
1380 If <clix:arg>parameter-type</clix:arg> is not provided
1381 or <code>NIL</code>, <clix:arg>default-parameter-type</clix:arg>
1382 (the default of which is <code>'STRING</code>) will be used
1383 instead.
1384 </p>
1385 <p>
1386 If the result of the computations above would be
1387 that <clix:arg>var</clix:arg> would be bound
1388 to <code>NIL</code>, then <clix:arg>init-form</clix:arg> (if
1389 provided) will be evaluated instead,
1390 and <clix:arg>var</clix:arg> will be bound to the result of this
1391 evaluation.
1392 </p>
1393 <p>
1394 Handlers built with this macro are constructed in such a way
1395 that the resulting Lisp function is useful even outside of
1396 Hunchentoot. Specifically, all the parameter computations
1397 above will only happen if <clix:ref>*REQUEST*</clix:ref> is
1398 bound, i.e. if we're within a Hunchentoot request.
1399 Otherwise, <clix:arg>var</clix:arg> will always be bound to the
1400 result of evaluating <clix:arg>init-form</clix:arg> unless a
1401 corresponding keyword argument is provided.
1402 </p>
1403 <p>
1404 The <a href="#example">example code</a> that comes with
1405 Hunchentoot contains an example which demonstrates some of the
1406 features of <clix:ref>DEFINE-EASY-HANDLER</clix:ref>.
1407 </p>
1408 </clix:description>
1409 </clix:function>
1410
1411 <clix:function name='dispatch-easy-handlers'>
1412 <clix:lambda-list>request
1413 </clix:lambda-list>
1414 <clix:returns>result
1415 </clix:returns>
1416 <clix:description>This is a dispatcher which returns the appropriate handler
1417 defined with <clix:ref>DEFINE-EASY-HANDLER</clix:ref>, if there is one.
1418 </clix:description>
1419 </clix:function>
1420
1421 </clix:subchapter>
1422
1423 <clix:subchapter name="requests" title="Request objects">
1424
1425 For each incoming request, the <a href="#acceptors">acceptor</a> (in
1426 <clix:ref>PROCESS-CONNECTION</clix:ref>) creates a
1427 <clix:ref>REQUEST</clix:ref> object and makes it available to <a
1428 href="#request-dispatch">handlers</a> via the special variable
1429 <clix:ref>*REQUEST*</clix:ref>. This object contains all relevant
1430 information about the request and this section collects the functions
1431 which can be used to query such an object. In all function where
1432 <clix:arg>request</clix:arg> is an optional or keyword parameter, the
1433 default is <clix:ref>*REQUEST*</clix:ref>.
1434
1435 <p>
1436 If you need more fine-grained control over the behaviour of request
1437 objects, you can subclass <clix:ref>REQUEST</clix:ref> and initialize
1438 the <a href="#acceptor-request-class"><code>REQUEST-CLASS</code></a>
1439 slot of the <clix:ref>ACCEPTOR</clix:ref> class accordingly. The
1440 acceptor will generate request objects of the class named by this
1441 slot.
1442 </p>
1443
1444 <clix:class name='request'>
1445 <clix:description>
1446 Objects of this class hold all the information
1447 about an incoming request. They are created automatically by
1448 acceptors and can be accessed by the
1449 corresponding <a href="#request-dispatch">handler</a>.
1450
1451 You should not mess with the slots of these objects directly, but you
1452 can subclass <clix:ref>REQUEST</clix:ref> in order to implement your
1453 own behaviour. See
1454 the <a href="#acceptor-request-class"><code>REQUEST-CLASS</code></a>
1455 slot of the <clix:ref>ACCEPTOR</clix:ref> class.
1456 </clix:description>
1457 </clix:class>
1458
1459 <clix:special-variable name='*request*'>
1460 <clix:description>The current REQUEST object while in the context of a request.
1461 </clix:description>
1462 </clix:special-variable>
1463
1464 <clix:function name='real-remote-addr'>
1465 <clix:lambda-list>
1466 <clix:lkw>optional
1467 </clix:lkw> request
1468 </clix:lambda-list>
1469 <clix:returns>string{, list}
1470 </clix:returns>
1471 <clix:description>
1472 Returns the '<code>X-Forwarded-For</code>' incoming http header as the
1473 second value in the form of a list of IP addresses and the first
1474 element of this list as the first value if this header exists.
1475 Otherwise returns the value of <clix:ref>REMOTE-ADDR</clix:ref> as the only value.
1476 </clix:description>
1477 </clix:function>
1478
1479 <clix:function name='parameter'>
1480 <clix:lambda-list>name
1481 <clix:lkw>optional
1482 </clix:lkw> request
1483 </clix:lambda-list>
1484 <clix:returns>string
1485 </clix:returns>
1486 <clix:description>
1487 Returns the GET or the POST parameter with name
1488 <clix:arg>name</clix:arg> (a string) - or <code>NIL</code>
1489 if there is none. If both a GET and a POST parameter with
1490 the same name exist the GET parameter is returned. Search
1491 is case-sensitive. See also
1492 <clix:ref>GET-PARAMETER</clix:ref> and
1493 <clix:ref>POST-PARAMETER</clix:ref>.
1494 </clix:description>
1495 </clix:function>
1496
1497 <clix:function name="get-parameter">
1498 <clix:lambda-list>name <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1499 <clix:returns>string</clix:returns>
1500 <clix:description>
1501 Returns the value of the GET parameter (as provided via the
1502 request URI) named by the string <clix:arg>name</clix:arg> as a
1503 string (or <code>NIL</code> if there ain't no GET parameter
1504 with this name). Note that only the first value will be
1505 returned if the client provided more than one GET parameter
1506 with the name <clix:arg>name</clix:arg>. See
1507 also <clix:ref>GET-PARAMETERS*</clix:ref>.
1508 </clix:description>
1509 </clix:function>
1510
1511 <clix:function name="post-parameter">
1512 <clix:lambda-list>name <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1513 <clix:returns>string</clix:returns>
1514 <clix:description>
1515 Returns the value of the POST parameter (as provided in the
1516 request's body) named by the
1517 string <clix:arg>name</clix:arg>. Note that only the first value
1518 will be returned if the client provided more than one POST
1519 parameter with the name <clix:arg>name</clix:arg>. This value
1520 will usually be a string (or <code>NIL</code> if there ain't
1521 no POST parameter with this name). If, however, the browser
1522 sent a <a class="none" name="upload">file</a> through
1523 a <a href="http://www.faqs.org/rfcs/rfc2388.html">
1524 <code>multipart/form-data</code>
1525 </a> form, the value of this function is a three-element list
1526 <pre>(path file-name content-type)</pre>
1527 where <clix:arg>path</clix:arg> is a pathname denoting the place
1528 were the uploaded file was
1529 stored, <clix:arg>file-name</clix:arg> (a string) is the file
1530 name sent by the browser, and <clix:arg>content-type</clix:arg>
1531 (also a string) is the content type sent by the browser. The
1532 file denoted by <clix:arg>path</clix:arg> will be deleted after
1533 the request has been handled - you have to move or copy it
1534 somewhere else if you want to keep it.
1535 <p>
1536 POST parameters will only be computed if the content type of
1537 the request body was <code>multipart/form-data</code>
1538 or <code>application/x-www-form-urlencoded</code>. Although
1539 this function is called <code>POST-PARAMETER</code>, you can
1540 instruct Hunchentoot to compute these parameters for other
1541 request methods by
1542 setting <clix:ref>*METHODS-FOR-POST-PARAMETERS*</clix:ref>.
1543 </p>
1544 <p>
1545 See also <clix:ref>POST-PARAMETERS</clix:ref>
1546 and <clix:ref>*TMP-DIRECTORY*</clix:ref>.
1547 </p>
1548 </clix:description>
1549 </clix:function>
1550
1551 <clix:function name="get-parameters*">
1552 <clix:lambda-list><clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1553 <clix:returns>alist</clix:returns>
1554 <clix:description>
1555 Returns
1556 an <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_a.htm#alist">alist</a>
1557 of all GET parameters (as provided via the request
1558 URI). The <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#car">car</a>
1559 of each element of this list is the parameter's name while
1560 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#cdr">cdr</a>
1561 is its value (as a string). The elements of this list are in
1562 the same order as they were within the request URI. See
1563 also <clix:ref>GET-PARAMETER</clix:ref>.
1564 </clix:description>
1565 </clix:function>
1566
1567 <clix:function name="post-parameters*">
1568 <clix:lambda-list><clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1569 <clix:returns>alist</clix:returns>
1570 <clix:description>
1571 Returns
1572 an <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_a.htm#alist">alist</a>
1573 of all POST parameters (as provided via the request's
1574 body). The <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#car">car</a>
1575 of each element of this list is the parameter's name while
1576 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#cdr">cdr</a>
1577 is its value. The elements of this list are in the same order
1578 as they were within the request's body.
1579 <p>
1580 See also <clix:ref>POST-PARAMETER</clix:ref>.
1581 </p>
1582 </clix:description>
1583 </clix:function>
1584
1585 <clix:special-variable name='*methods-for-post-parameters*'>
1586 <clix:description>A list of the request method types (as keywords) for which
1587 Hunchentoot will try to compute <clix:arg>post-parameters</clix:arg>.
1588 </clix:description>
1589 </clix:special-variable>
1590
1591 <clix:function name='cookie-in'>
1592 <clix:lambda-list>name
1593 <clix:lkw>optional
1594 </clix:lkw> request
1595 </clix:lambda-list>
1596 <clix:returns>string
1597 </clix:returns>
1598 <clix:description>
1599 Returns the cookie with the name <clix:arg>name</clix:arg> (a string) as sent by the
1600 browser - or <code>NIL</code> if there is none.
1601 </clix:description>
1602 </clix:function>
1603
1604 <clix:function name='cookies-in*'>
1605 <clix:lambda-list>
1606 <clix:lkw>optional
1607 </clix:lkw> request
1608 </clix:lambda-list>
1609 <clix:returns>alist
1610 </clix:returns>
1611 <clix:description>Returns an alist of all cookies associated with the <clix:ref>REQUEST</clix:ref> object
1612 <clix:arg>request</clix:arg>.
1613 </clix:description>
1614 </clix:function>
1615
1616 <clix:function name='host'>
1617 <clix:lambda-list>
1618 <clix:lkw>optional
1619 </clix:lkw> request
1620 </clix:lambda-list>
1621 <clix:returns>host
1622 </clix:returns>
1623 <clix:description>Returns the 'Host' incoming http header value.
1624 </clix:description>
1625 </clix:function>
1626
1627 <clix:function name='query-string*'>
1628 <clix:lambda-list>
1629 <clix:lkw>optional
1630 </clix:lkw> request
1631 </clix:lambda-list>
1632 <clix:returns>string
1633 </clix:returns>
1634 <clix:description>
1635 Returns the query string of the <clix:ref>REQUEST</clix:ref> object <clix:arg>request</clix:arg>. That's
1636 the part behind the question mark (i.e. the GET parameters).
1637 </clix:description>
1638 </clix:function>
1639
1640 <clix:function name='referer'>
1641 <clix:lambda-list>
1642 <clix:lkw>optional
1643 </clix:lkw> request
1644 </clix:lambda-list>
1645 <clix:returns>result
1646 </clix:returns>
1647 <clix:description>
1648 Returns the 'Referer' (sic!) http header.
1649 </clix:description>
1650 </clix:function>
1651
1652 <clix:function name='request-method*'>
1653 <clix:lambda-list>
1654 <clix:lkw>optional
1655 </clix:lkw> request
1656 </clix:lambda-list>
1657 <clix:returns>keyword
1658 </clix:returns>
1659 <clix:description>
1660 Returns the request method as a Lisp keyword.
1661 </clix:description>
1662 </clix:function>
1663
1664 <clix:function name='request-uri*'>
1665 <clix:lambda-list>
1666 <clix:lkw>optional
1667 </clix:lkw> request
1668 </clix:lambda-list>
1669 <clix:returns>uri
1670 </clix:returns>
1671 <clix:description>
1672 Returns the request URI.
1673 </clix:description>
1674 </clix:function>
1675
1676 <clix:function name='server-protocol*'>
1677 <clix:lambda-list>
1678 <clix:lkw>optional
1679 </clix:lkw> request
1680 </clix:lambda-list>
1681 <clix:returns>keyword
1682 </clix:returns>
1683 <clix:description>
1684 Returns the request protocol as a Lisp keyword.
1685 </clix:description>
1686 </clix:function>
1687
1688 <clix:function name='user-agent'>
1689 <clix:lambda-list>
1690 <clix:lkw>optional
1691 </clix:lkw> request
1692 </clix:lambda-list>
1693 <clix:returns>result
1694 </clix:returns>
1695 <clix:description>
1696 Returns the 'User-Agent' http header.
1697 </clix:description>
1698 </clix:function>
1699
1700 <clix:function name='header-in*'>
1701 <clix:lambda-list>name
1702 <clix:lkw>optional
1703 </clix:lkw> request
1704 </clix:lambda-list>
1705 <clix:returns>header
1706 </clix:returns>
1707 <clix:description>
1708 Returns the incoming header with name
1709 <clix:arg>name</clix:arg>. <clix:arg>name</clix:arg> can be
1710 a keyword (recommended) or a string.
1711 </clix:description>
1712 </clix:function>
1713
1714 <clix:function name='headers-in*'>
1715 <clix:lambda-list>
1716 <clix:lkw>optional
1717 </clix:lkw> request
1718 </clix:lambda-list>
1719 <clix:returns>alist
1720 </clix:returns>
1721 <clix:description>
1722 Returns an alist of the incoming headers associated with the
1723 <clix:ref>REQUEST</clix:ref> object
1724 <clix:arg>request</clix:arg>.
1725 </clix:description>
1726 </clix:function>
1727
1728 <clix:function name='remote-addr*'>
1729 <clix:lambda-list>
1730 <clix:lkw>optional
1731 </clix:lkw> request
1732 </clix:lambda-list>
1733 <clix:returns>address
1734 </clix:returns>
1735 <clix:description>
1736 Returns the address the current request originated from.
1737 </clix:description>
1738 </clix:function>
1739
1740 <clix:function name='remote-port*'>
1741 <clix:lambda-list>
1742 <clix:lkw>optional
1743 </clix:lkw> request
1744 </clix:lambda-list>
1745 <clix:returns>port
1746 </clix:returns>
1747 <clix:description>
1748 Returns the port the current request originated from.
1749 </clix:description>
1750 </clix:function>
1751
1752 <clix:function name='local-addr*'>
1753 <clix:lambda-list>
1754 <clix:lkw>optional
1755 </clix:lkw> request
1756 </clix:lambda-list>
1757 <clix:returns>address
1758 </clix:returns>
1759 <clix:description>
1760 The IP address of the local system that the client connected to.
1761 </clix:description>
1762 </clix:function>
1763
1764 <clix:function name='local-port*'>
1765 <clix:lambda-list>
1766 <clix:lkw>optional
1767 </clix:lkw> request
1768 </clix:lambda-list>
1769 <clix:returns>port
1770 </clix:returns>
1771 <clix:description>
1772 The TCP port number of the local system that the client connected to.
1773 </clix:description>
1774 </clix:function>
1775
1776 <clix:function name='script-name*'>
1777 <clix:lambda-list>
1778 <clix:lkw>optional
1779 </clix:lkw> request
1780 </clix:lambda-list>
1781 <clix:returns>script-name
1782 </clix:returns>
1783 <clix:description>
1784 Returns the file name of the <clix:ref>REQUEST</clix:ref>
1785 object <clix:arg>request</clix:arg>. That's the
1786 requested URI without the query string (i.e the GET
1787 parameters).
1788 </clix:description>
1789 </clix:function>
1790
1791 <clix:accessor name='aux-request-value'>
1792 <clix:lambda-list>symbol
1793 <clix:lkw>optional
1794 </clix:lkw> request
1795 </clix:lambda-list>
1796 <clix:returns>value, present-p
1797 </clix:returns>
1798 <clix:description>
1799 This accessor can be used to associate arbitrary
1800 data with the the symbol <clix:arg>symbol</clix:arg> in the <clix:ref>REQUEST</clix:ref> object
1801 <clix:arg>request</clix:arg>. <clix:arg>present-p</clix:arg> is true if such data was found, otherwise <code>NIL</code>.
1802 </clix:description>
1803 </clix:accessor>
1804
1805 <clix:function name='delete-aux-request-value'>
1806 <clix:lambda-list>symbol
1807 <clix:lkw>optional
1808 </clix:lkw> request
1809 </clix:lambda-list>
1810 <clix:returns>|
1811 </clix:returns>
1812 <clix:description>
1813 Removes the value associated with <clix:arg>symbol</clix:arg> from the <clix:ref>REQUEST</clix:ref> object
1814 <clix:arg>request</clix:arg>.
1815 </clix:description>
1816 </clix:function>
1817
1818 <clix:function name='authorization'>
1819 <clix:lambda-list>
1820 <clix:lkw>optional
1821 </clix:lkw> request
1822 </clix:lambda-list>
1823 <clix:returns>result
1824 </clix:returns>
1825 <clix:description>
1826 Returns as two values the user and password (if any) as
1827 encoded in the 'AUTHORIZATION' header. Returns
1828 <code>NIL</code> if there is no such header.
1829 </clix:description>
1830 </clix:function>
1831
1832 <clix:special-variable name='*hunchentoot-default-external-format*'>
1833 <clix:description>
1834 The external format used to compute the <clix:ref>REQUEST</clix:ref> object.
1835 </clix:description>
1836 </clix:special-variable>
1837
1838 <clix:special-variable name='*file-upload-hook*'>
1839 <clix:description>
1840 If this is not <code>NIL</code>, it should be a unary
1841 function which will be called with a pathname for each file
1842 which is <a href="#upload">uploaded</a> to Hunchentoot. The
1843 pathname denotes the temporary file to which the uploaded
1844 file is written. The hook is called directly before the
1845 file is created. At this point,
1846 <clix:ref>*REQUEST*</clix:ref> is already bound to the
1847 current <clix:ref>REQUEST</clix:ref> object, but obviously
1848 you can't access the post parameters yet.
1849 </clix:description>
1850 </clix:special-variable>
1851
1852 <clix:function name="raw-post-data">
1853 <clix:lambda-list>
1854 <clix:lkw>key</clix:lkw>
1855 request external-format force-text force-binary want-stream
1856 </clix:lambda-list>
1857 <clix:returns>raw-body-or-stream</clix:returns>
1858 <clix:description>
1859 Returns the content sent by the client in the request body if
1860 there was any (unless the content type
1861 was <code>multipart/form-data</code> in which
1862 case <code>NIL</code> is returned). By default, the result is
1863 a string if the type of the <code>Content-Type</code>
1864 <a href="http://www.faqs.org/rfcs/rfc1590.html">media type</a>
1865 is <code>"text"</code>, and a vector of octets otherwise. In
1866 the case of a string, the external format to be used to decode
1867 the content will be determined from the <code>charset</code>
1868 parameter sent by the client (or
1869 otherwise <clix:ref>*HUNCHENTOOT-DEFAULT-EXTERNAL-FORMAT*</clix:ref>
1870 will be used).
1871 <p>
1872 You can also provide an external format explicitly (through
1873 <clix:arg>external-format</clix:arg>) in which case the result
1874 will unconditionally be a string. Likewise, you can provide
1875 a true value for <clix:arg>force-text</clix:arg> which will
1876 force Hunchentoot to act as if the type of the media type
1877 had been <code>"text"</code>
1878 (with <clix:arg>external-format</clix:arg> taking precedence
1879 if provided). Or you can provide a true value
1880 for <clix:arg>force-binary</clix:arg> which means that you
1881 want a vector of octets at any rate. (If both
1882 <clix:arg>force-text</clix:arg>
1883 and <clix:arg>force-binary</clix:arg> are true, an error will
1884 be signaled.)
1885 </p>
1886 <p>
1887 If, however, you provide a true value
1888 for <clix:arg>want-stream</clix:arg>, the other parameters are
1889 ignored and you'll get the content (flexi) stream to read
1890 from it yourself. It is then your responsibility to read
1891 the correct amount of data, because otherwise you won't be
1892 able to return a response to the client. The stream will
1893 have
1894 its <a href="http://weitz.de/flexi-streams/#flexi-streams">octet
1895 position</a> set to <code>0</code>. If the client provided
1896 a <code>Content-Length</code> header, the stream will also
1897 have a
1898 corresponding <a href="http://weitz.de/flexi-streams/#flexi-streams">bound</a>,
1899 so no matter whether the client used chunked encoding or
1900 not, you can always read until EOF.
1901 </p>
1902 <p>
1903 If the content type of the request
1904 was <code>multipart/form-data</code>
1905 or <code>application/x-www-form-urlencoded</code>, the
1906 content has been read by Hunchentoot already and you can't
1907 read from the stream anymore.
1908 </p>
1909 <p>
1910 You can call <clix:ref>RAW-POST-DATA</clix:ref> more than once
1911 per request, but you can't mix calls which have different
1912 values for <clix:arg>want-stream</clix:arg>.
1913 </p>
1914 <p>
1915 Note that this function is slightly misnamed because a
1916 client can send content even if the request method is not
1917 POST.
1918 </p>
1919 </clix:description>
1920 </clix:function>
1921
1922
1923 <clix:function name='recompute-request-parameters'>
1924 <clix:lambda-list>
1925 <clix:lkw>key
1926 </clix:lkw> request external-format
1927 </clix:lambda-list>
1928 <clix:returns>|
1929 </clix:returns>
1930 <clix:description>
1931 Recomputes the GET and POST parameters for the <clix:ref>REQUEST</clix:ref> object
1932 <clix:arg>request</clix:arg>. This only makes sense if you're switching external formats
1933 during the request.
1934 </clix:description>
1935 </clix:function>
1936
1937 <clix:function generic='true' name='process-request'>
1938 <clix:lambda-list>request
1939 </clix:lambda-list>
1940 <clix:returns>nil
1941 </clix:returns>
1942 <clix:description>
1943 This function is called by <clix:ref>PROCESS-CONNECTION</clix:ref>
1944 after the incoming headers have been read. It
1945 calls <clix:ref>HANDLE-REQUEST</clix:ref> (and is more or less just a
1946 thin wrapper around it) to select and call a
1947 <a href="#request-dispatch">handler</a> and send the output of this handler to
1948 the client. Note that <clix:ref>PROCESS-CONNECTION</clix:ref> is
1949 called once per connection and loops in case of a persistent
1950 connection while <clix:ref>PROCESS-REQUEST</clix:ref> is called anew
1951 for each request.
1952 <p>
1953 The return value of this function is ignored.
1954 </p>
1955 <p>
1956 Like <clix:ref>PROCESS-CONNECTION</clix:ref>, this is another function
1957 the behaviour of which you should only modify if you really, really
1958 know what you're doing.
1959 </p>
1960 </clix:description>
1961 </clix:function>
1962
1963 <clix:function generic='true' name='handle-request'>
1964 <clix:lambda-list>acceptor request
1965 </clix:lambda-list>
1966 <clix:returns>content
1967 </clix:returns>
1968 <clix:description>
1969 This function is called by <clix:ref>PROCESS-REQUEST</clix:ref> once
1970 the request has been read and a <clix:ref>REQUEST</clix:ref> object
1971 has been created. Its job is to actually handle the request, i.e. to
1972 return something to the client.
1973 <p>
1974 The default method calls the
1975 acceptor's <a href="#request-dispatch">request dispatcher</a>, but you
1976 can of course implement a different behaviour. The default method
1977 also sets up <a href="#logging">standard error handling</a> for
1978 the <a href="#request-dispatch">handler</a>.
1979 </p>
1980 <p>
1981 Might be a good place to bind or rebind special variables which can
1982 then be accessed by your <a href="#request-dispatch">handlers</a>.
1983 </p>
1984 </clix:description>
1985 </clix:function>
1986
1987 <clix:function generic='true' name='acceptor-dispatch-request'>
1988 <clix:lambda-list>acceptor request
1989 </clix:lambda-list>
1990 <clix:returns>content
1991 </clix:returns>
1992 <clix:description>
1993 This function is called to actually dispatch the request
1994 once the standard logging and error handling has been set
1995 up. <clix:ref>ACCEPTOR</clix:ref> subclasses implement
1996 methods for this function in order to perform their own
1997 request routing. If a method does not want to handle the
1998 request, it is supposed to invoke <a
1999 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_call_n.htm">CALL-NEXT-METHOD</a>
2000 so that the next <clix:ref>ACCEPTOR</clix:ref> in the
2001 inheritance chain gets a chance to handle the request.
2002 </clix:description>
2003 </clix:function>
2004
2005 <clix:readers generic='true'>
2006 <clix:listed-reader generic='true' name='cookies-in'>
2007 <clix:lambda-list>request
2008 </clix:lambda-list>
2009 <clix:returns>cookies
2010 </clix:returns>
2011 </clix:listed-reader>
2012
2013 <clix:listed-reader generic='true' name='get-parameters'>
2014 <clix:lambda-list>request
2015 </clix:lambda-list>
2016 <clix:returns>get-parameters
2017 </clix:returns>
2018 </clix:listed-reader>
2019
2020 <clix:listed-reader generic='true' name='header-in'>
2021 <clix:lambda-list>name request
2022 </clix:lambda-list>
2023 <clix:returns>result
2024 </clix:returns>
2025 <clix:description>
2026 </clix:description>
2027 </clix:listed-reader>
2028
2029 <clix:listed-reader generic='true' name='headers-in'>
2030 <clix:lambda-list>request
2031 </clix:lambda-list>
2032 <clix:returns>headers
2033 </clix:returns>
2034 </clix:listed-reader>
2035
2036 <clix:listed-reader generic='true' name='post-parameters'>
2037 <clix:lambda-list>request
2038 </clix:lambda-list>
2039 <clix:returns>post-parameters
2040 </clix:returns>
2041 </clix:listed-reader>
2042
2043 <clix:listed-reader generic='true' name='query-string'>
2044 <clix:lambda-list>request
2045 </clix:lambda-list>
2046 <clix:returns>query-string
2047 </clix:returns>
2048 </clix:listed-reader>
2049
2050 <clix:listed-reader generic='true' name='remote-addr'>
2051 <clix:lambda-list>request
2052 </clix:lambda-list>
2053 <clix:returns>address
2054 </clix:returns>
2055 </clix:listed-reader>
2056
2057 <clix:listed-reader generic='true' name='remote-port'>
2058 <clix:lambda-list>request
2059 </clix:lambda-list>
2060 <clix:returns>port
2061 </clix:returns>
2062 </clix:listed-reader>
2063
2064 <clix:listed-reader generic='true' name='local-addr'>
2065 <clix:lambda-list>request
2066 </clix:lambda-list>
2067 <clix:returns>address
2068 </clix:returns>
2069 </clix:listed-reader>
2070
2071 <clix:listed-reader generic='true' name='local-port'>
2072 <clix:lambda-list>request
2073 </clix:lambda-list>
2074 <clix:returns>port
2075 </clix:returns>
2076 </clix:listed-reader>
2077
2078 <clix:listed-reader generic='true' name='request-acceptor'>
2079 <clix:lambda-list>request
2080 </clix:lambda-list>
2081 <clix:returns>acceptor
2082 </clix:returns>
2083 </clix:listed-reader>
2084
2085 <clix:listed-reader generic='true' name='request-method'>
2086 <clix:lambda-list>request
2087 </clix:lambda-list>
2088 <clix:returns>method
2089 </clix:returns>
2090 </clix:listed-reader>
2091
2092 <clix:listed-reader generic='true' name='request-uri'>
2093 <clix:lambda-list>request
2094 </clix:lambda-list>
2095 <clix:returns>uri
2096 </clix:returns>
2097 </clix:listed-reader>
2098
2099 <clix:listed-reader generic='true' name='server-protocol'>
2100 <clix:lambda-list>request
2101 </clix:lambda-list>
2102 <clix:returns>protocol
2103 </clix:returns>
2104 </clix:listed-reader>
2105
2106 <clix:listed-reader generic='true' name='script-name'>
2107 <clix:lambda-list>request
2108 </clix:lambda-list>
2109 <clix:returns>result
2110 </clix:returns>
2111 </clix:listed-reader>
2112
2113 <clix:description>
2114 These are various generic readers which are used
2115 to read information about a <clix:ref>REQUEST</clix:ref> object. If you are writing a
2116 <a href="#request-dispatch">handler</a>, you should <em>not</em> use these readers but instead utilize the
2117 corresponding functions with an asterisk at the end of their name,
2118 also listed in this section. These generic readers are only
2119 exported for users who want to create their own subclasses of
2120 <clix:ref>REQUEST</clix:ref>.
2121 </clix:description>
2122
2123 </clix:readers>
2124
2125 </clix:subchapter>
2126
2127 <clix:subchapter name="replies" title="Reply objects">
2128
2129 For each incoming request, the <a href="#acceptors">acceptor</a>
2130 (in <clix:ref>PROCESS-CONNECTION</clix:ref>) creates
2131 a <clix:ref>REPLY</clix:ref> object and makes it available
2132 to <a href="#request-dispatch">handlers</a> via the special variable
2133 <clix:ref>*REPLY*</clix:ref>. This object contains all relevant
2134 information (except for the content body) about the reply that will be
2135 sent to the client and this section collects the functions which can
2136 be used to query and modify such an object. In all function
2137 where <clix:arg>reply</clix:arg> is an optional or keyword parameter,
2138 the default is <clix:ref>*REPLY*</clix:ref>.
2139
2140 <p>
2141 If you need more fine-grained control over the behaviour of reply
2142 objects, you can subclass <clix:ref>REPLY</clix:ref> and initialize
2143 the <a href="#acceptor-reply-class"><code>REPLY-CLASS</code></a>
2144 slot of the <clix:ref>ACCEPTOR</clix:ref> class accordingly. The
2145 acceptor will generate reply objects of the class named by this
2146 slot.
2147 </p>
2148
2149 <clix:class name='reply'>
2150 <clix:description>
2151 Objects of this class hold all the information about an
2152 outgoing reply. They are created automatically by
2153 Hunchentoot and can be accessed and modified by the
2154 corresponding <a href="#request-dispatch">handler</a>.
2155 <p>
2156 You should not mess with the slots of these objects directly, but you
2157 can subclass <clix:ref>REPLY</clix:ref> in order to implement your own behaviour. See the
2158 <a href="#acceptor-reply-class"><code>:reply-class</code></a> initarg
2159 of the <clix:ref>ACCEPTOR</clix:ref> class.
2160 </p>
2161 </clix:description>
2162 </clix:class>
2163
2164 <clix:special-variable name='*reply*'>
2165 <clix:description>
2166 The current <clix:ref>REPLY</clix:ref> object in the context of a request.
2167 </clix:description>
2168 </clix:special-variable>
2169
2170 <clix:accessor name='header-out'>
2171 <clix:lambda-list>name
2172 <clix:lkw>optional
2173 </clix:lkw> reply
2174 </clix:lambda-list>
2175 <clix:returns>string
2176 </clix:returns>
2177 <clix:description>
2178 <clix:ref>HEADER-OUT</clix:ref> returns the outgoing http
2179 header named by the keyword <clix:arg>name</clix:arg> if
2180 there is one, otherwise <code>NIL</code>. <code>SETF</code>
2181 of <clix:ref>HEADER-OUT</clix:ref> changes the current value
2182 of the header named <clix:arg>name</clix:arg>. If no header
2183 named <clix:arg>name</clix:arg> exists, it is created. For
2184 backwards compatibility, <clix:arg>name</clix:arg> can also
2185 be a string in which case the association between a header
2186 and its name is case-insensitive.
2187 <p>
2188 Note that the header 'Set-Cookie' cannot be queried by
2189 <clix:ref>HEADER-OUT</clix:ref> and must not be set by
2190 <code>SETF</code> of <clix:ref>HEADER-OUT</clix:ref>. See
2191 also <clix:ref>HEADERS-OUT*</clix:ref>,
2192 <clix:ref>CONTENT-TYPE*</clix:ref>,
2193 <clix:ref>CONTENT-LENGTH*</clix:ref>,
2194 <clix:ref>COOKIES-OUT*</clix:ref>, and
2195 <clix:ref>COOKIE-OUT</clix:ref>.
2196 </p>
2197 </clix:description>
2198 </clix:accessor>
2199
2200 <clix:function name='headers-out*'>
2201 <clix:lambda-list>
2202 <clix:lkw>optional
2203 </clix:lkw> reply
2204 </clix:lambda-list>
2205 <clix:returns>alist
2206 </clix:returns>
2207 <clix:description>Returns an alist of the outgoing headers associated with the
2208 <clix:ref>REPLY</clix:ref> object <clix:arg>reply</clix:arg>. See also <clix:ref>HEADER-OUT</clix:ref>.
2209 </clix:description>
2210 </clix:function>
2211
2212 <clix:accessor name='content-length*'>
2213 <clix:lambda-list>
2214 <clix:lkw>optional
2215 </clix:lkw> reply
2216 </clix:lambda-list>
2217 <clix:returns>content-length
2218 </clix:returns>
2219 <clix:description>
2220 The outgoing 'Content-Length' http header of <clix:arg>reply</clix:arg>.
2221 </clix:description>
2222 </clix:accessor>
2223
2224 <clix:accessor name='content-type*'>
2225 <clix:lambda-list>
2226 <clix:lkw>optional
2227 </clix:lkw> reply
2228 </clix:lambda-list>
2229 <clix:returns>content-type
2230 </clix:returns>
2231 <clix:description>
2232 The outgoing 'Content-Type' http header of <clix:arg>reply</clix:arg>.
2233 </clix:description>
2234 </clix:accessor>
2235
2236 <clix:function name='cookie-out'>
2237 <clix:lambda-list>name
2238 <clix:lkw>optional
2239 </clix:lkw> reply
2240 </clix:lambda-list>
2241 <clix:returns>result
2242 </clix:returns>
2243 <clix:description>
2244 Returns the current value of the outgoing <a
2245 href="#cookies">cookie</a> named
2246 <clix:arg>name</clix:arg>. Search is case-sensitive.
2247 </clix:description>
2248 </clix:function>
2249
2250 <clix:accessor name='cookies-out*'>
2251 <clix:lambda-list>
2252 <clix:lkw>optional
2253 </clix:lkw> reply
2254 </clix:lambda-list>
2255 <clix:returns>alist
2256 </clix:returns>
2257 <clix:description>
2258 Returns or sets an alist of the outgoing <a
2259 href="#cookies">cookies</a> associated with the
2260 <clix:ref>REPLY</clix:ref> object
2261 <clix:arg>reply</clix:arg>.
2262 </clix:description>
2263 </clix:accessor>
2264
2265 <clix:accessor name='return-code*'>
2266 <clix:lambda-list>
2267 <clix:lkw>optional
2268 </clix:lkw> reply
2269 </clix:lambda-list>
2270 <clix:returns>return-code
2271 </clix:returns>
2272 <clix:description>
2273 Gets or sets the http return code of
2274 <clix:arg>reply</clix:arg>. The return code of each
2275 <clix:ref>REPLY</clix:ref> object is initially set to
2276 <clix:ref>+HTTP-OK+</clix:ref>.
2277 </clix:description>
2278 </clix:accessor>
2279
2280 <clix:function name="send-headers">
2281 <clix:returns>stream</clix:returns>
2282 <clix:description>
2283 Sends the initial status line and all headers as determined
2284 by the <clix:ref>REPLY</clix:ref>
2285 object <clix:ref>*REPLY*</clix:ref>. Returns
2286 a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_b.htm#binary">binary</a>
2287 stream to which the body of the reply can be written. Once
2288 this function has been called, further changes
2289 to <clix:ref>*REPLY*</clix:ref> don't have any effect.
2290 Also, automatic handling of errors (i.e. sending the
2291 corresponding status code to the browser, etc.) is turned
2292 off for this request and functions
2293 like <clix:ref>REDIRECT</clix:ref> or
2294 to <clix:ref>ABORT-REQUEST-HANDLER</clix:ref> won't have the
2295 desired effect once the headers are sent.
2296 <p>
2297 If your handlers return the full body as a string or as an
2298 array of octets, you should <em>not</em> call this function.
2299 If a handler calls <clix:ref>SEND-HEADERS</clix:ref> , its
2300 return value is ignored.
2301 </p>
2302 </clix:description>
2303 </clix:function>
2304
2305 <clix:accessor name='reply-external-format*'>
2306 <clix:lambda-list>
2307 <clix:lkw>optional
2308 </clix:lkw> reply
2309 </clix:lambda-list>
2310 <clix:returns>external-format
2311 </clix:returns>
2312 <clix:description>
2313 Gets or sets the external format of <clix:arg>reply</clix:arg> which is used for character output.
2314 </clix:description>
2315 </clix:accessor>
2316
2317 <clix:special-variable name='*default-content-type*'>
2318 <clix:description>
2319 The default content-type header which is returned to the client.
2320 </clix:description>
2321 </clix:special-variable>
2322
2323 <clix:constants>
2324 <clix:listed-constant name="+http-continue+"/>
2325 <clix:listed-constant name="+http-switching-protocols+"/>
2326 <clix:listed-constant name="+http-ok+"/>
2327 <clix:listed-constant name="+http-created+"/>
2328 <clix:listed-constant name="+http-accepted+"/>
2329 <clix:listed-constant name="+http-non-authoritative-information+"/>
2330 <clix:listed-constant name="+http-no-content+"/>
2331 <clix:listed-constant name="+http-reset-content+"/>
2332 <clix:listed-constant name="+http-partial-content+"/>
2333 <clix:listed-constant name="+http-multi-status+"/>
2334 <clix:listed-constant name="+http-multiple-choices+"/>
2335 <clix:listed-constant name="+http-moved-permanently+"/>
2336 <clix:listed-constant name="+http-moved-temporarily+"/>
2337 <clix:listed-constant name="+http-see-other+"/>
2338 <clix:listed-constant name="+http-not-modified+"/>
2339 <clix:listed-constant name="+http-use-proxy+"/>
2340 <clix:listed-constant name="+http-temporary-redirect+"/>
2341 <clix:listed-constant name="+http-bad-request+"/>
2342 <clix:listed-constant name="+http-authorization-required+"/>
2343 <clix:listed-constant name="+http-payment-required+"/>
2344 <clix:listed-constant name="+http-forbidden+"/>
2345 <clix:listed-constant name="+http-not-found+"/>
2346 <clix:listed-constant name="+http-method-not-allowed+"/>
2347 <clix:listed-constant name="+http-not-acceptable+"/>
2348 <clix:listed-constant name="+http-proxy-authentication-required+"/>
2349 <clix:listed-constant name="+http-request-time-out+"/>
2350 <clix:listed-constant name="+http-conflict+"/>
2351 <clix:listed-constant name="+http-gone+"/>
2352 <clix:listed-constant name="+http-length-required+"/>
2353 <clix:listed-constant name="+http-precondition-failed+"/>
2354 <clix:listed-constant name="+http-request-entity-too-large+"/>
2355 <clix:listed-constant name="+http-request-uri-too-large+"/>
2356 <clix:listed-constant name="+http-unsupported-media-type+"/>
2357 <clix:listed-constant name="+http-requested-range-not-satisfiable+"/>
2358 <clix:listed-constant name="+http-expectation-failed+"/>
2359 <clix:listed-constant name="+http-failed-dependency+"/>
2360 <clix:listed-constant name="+http-internal-server-error+"/>
2361 <clix:listed-constant name="+http-not-implemented+"/>
2362 <clix:listed-constant name="+http-bad-gateway+"/>
2363 <clix:listed-constant name="+http-service-unavailable+"/>
2364 <clix:listed-constant name="+http-gateway-time-out+"/>
2365 <clix:listed-constant name="+http-version-not-supported+"/>
2366 <clix:description>
2367 The values of these constants are 100, 101, 200, 201, 202,
2368 203, 204, 205, 206, 207, 300, 301, 302, 303, 304, 305, 307,
2369 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411,
2370 412, 413, 414, 415, 416, 417, 424, 500, 501, 502, 503, 504,
2371 and 505. See <clix:ref>RETURN-CODE</clix:ref>.
2372 </clix:description>
2373 </clix:constants>
2374
2375 <clix:readers generic='true'>
2376 <clix:listed-reader generic='true' name='content-length'>
2377 <clix:lambda-list>reply
2378 </clix:lambda-list>
2379 <clix:returns>content-length
2380 </clix:returns>
2381 </clix:listed-reader>
2382
2383 <clix:listed-reader generic='true' name='content-type'>
2384 <clix:lambda-list>reply
2385 </clix:lambda-list>
2386 <clix:returns>content-type
2387 </clix:returns>
2388 </clix:listed-reader>
2389
2390 <clix:listed-reader generic='true' name='headers-out'>
2391 <clix:lambda-list>reply
2392 </clix:lambda-list>
2393 <clix:returns>headers-out
2394 </clix:returns>
2395 </clix:listed-reader>
2396
2397 <clix:description>
2398 These are various generic readers which are used
2399 to read information about a <clix:ref>REPLY</clix:ref> object. If you are writing a
2400 <a href="#request-dispatch">handler</a>, you should <em>not</em> use these readers but instead utilize the
2401 corresponding functions with an asterisk at the end of their name,
2402 also listed in this section. These generic readers are only
2403 exported for users who want to create their own subclasses of
2404 <clix:ref>REPLY</clix:ref>.
2405 </clix:description>
2406 </clix:readers>
2407
2408 <clix:accessors generic='true'>
2409 <clix:listed-accessor generic='true' name='cookies-out'>
2410 <clix:lambda-list>reply
2411 </clix:lambda-list>
2412 <clix:returns>result
2413 </clix:returns>
2414 </clix:listed-accessor>
2415
2416 <clix:listed-accessor generic='true' name='return-code'>
2417 <clix:lambda-list>reply
2418 </clix:lambda-list>
2419 <clix:returns>result
2420 </clix:returns>
2421 </clix:listed-accessor>
2422
2423 <clix:listed-accessor generic='true' name='reply-external-format'>
2424 <clix:lambda-list>reply
2425 </clix:lambda-list>
2426 <clix:returns>result
2427 </clix:returns>
2428 </clix:listed-accessor>
2429
2430 <clix:description>
2431 These are various generic accessors which are
2432 used to query and modify a <clix:ref>REPLY</clix:ref> objects. If
2433 you are writing a
2434 <a href="#request-dispatch">handler</a>, you should <em>not</em> use these
2435 accessors but instead utilize the corresponding functions with an
2436 asterisk at the end of their name, also listed in this section.
2437 These generic accessors are only exported for users who want to
2438 create their own subclasses of
2439 <clix:ref>REPLY</clix:ref>.
2440 </clix:description>
2441 </clix:accessors>
2442
2443
2444 </clix:subchapter>
2445
2446 <clix:subchapter name="sessions" title="Sessions">
2447 Hunchentoot supports <em>sessions</em>: Once a <a href="#request-dispatch">request
2448 handler</a> has called <clix:ref>START-SESSION</clix:ref>, Hunchentoot
2449 uses either cookies or (if the client doesn't send the cookies
2450 back) <a href="#*rewrite-for-session-urls*">rewrites URLs</a> to keep
2451 track of this client, i.e. to provide a kind of 'state' for the
2452 stateless http protocol. The session associated with the client is a
2453 <a href="#session">CLOS object</a> which can be used
2454 to <a href="#session-value">store arbitrary data</a> between requests.
2455 <p>
2456 Hunchentoot makes some reasonable effort to prevent eavesdroppers from
2457 hijacking sessions (see below), but this should not be considered
2458 really secure. Don't store sensitive data in sessions and rely solely
2459 on the session mechanism as a safeguard against malicious users who
2460 want to get at this data!
2461 </p>
2462 <p>
2463 For each request there's one <clix:ref>SESSION</clix:ref> object which is accessible to the
2464 <a href="#handler">handler</a> via the special
2465 variable <clix:ref>*SESSION*</clix:ref>. This object holds all the
2466 information available about the session and can be accessed with the
2467 functions described in this chapter. Note that the internal structure
2468 of <clix:ref>SESSION</clix:ref> objects should be considered opaque
2469 and may change in future releases of Hunchentoot.
2470 </p>
2471 <p>
2472 Sessions are automatically <a href="#session-verify">verified</a> for
2473 validity and age when the <clix:ref>REQUEST</clix:ref> object is
2474 instantiated, i.e. if <clix:ref>*SESSION*</clix:ref> is not NIL then
2475 this session is valid (as far as Hunchentoot is concerned) and
2476 not <a href="#session-too-old-p">too old</a>. Old sessions
2477 are <a href="#session-gc">automatically removed</a>.
2478 </p>
2479 <p>
2480 Hunchentoot also provides a <clix:ref>SESSION-REGENERATE-COOKIE-VALUE</clix:ref>
2481 function that creates a new cookie value. This helps to prevent against
2482 <a href="https://www.owasp.org/index.php/Session_fixation">session fixation
2483 attacks</a>, and should be used when a user logs in according to the application.
2484 </p>
2485
2486 <clix:class name='session'>
2487 <clix:description>
2488 <clix:ref>SESSION</clix:ref> objects are
2489 automatically maintained by Hunchentoot. They should not be created
2490 explicitly with <code>MAKE-INSTANCE</code> but implicitly
2491 with <clix:ref>START-SESSION</clix:ref> and they should be treated as
2492 opaque objects.
2493 <p>
2494 You can ignore Hunchentoot's <clix:ref>SESSION</clix:ref> objects and
2495 <a href="#session-behaviour">implement your own sessions</a> if you provide corresponding methods for
2496 <clix:ref>SESSION-COOKIE-VALUE</clix:ref>
2497 and <clix:ref>SESSION-VERIFY</clix:ref>.
2498 </p>
2499 </clix:description>
2500 </clix:class>
2501
2502 <clix:function name='start-session'>
2503 <clix:lambda-list>
2504 </clix:lambda-list>
2505 <clix:returns>session
2506 </clix:returns>
2507 <clix:description>
2508 Returns the current <clix:ref>SESSION</clix:ref>
2509 object. If there is no current session, creates one and updates the
2510 corresponding data structures. In this case the function will also
2511 send a session cookie to the browser.
2512 </clix:description>
2513 </clix:function>
2514
2515 <clix:accessor name='session-value'>
2516 <clix:lambda-list>symbol
2517 <clix:lkw>optional
2518 </clix:lkw> session
2519 </clix:lambda-list>
2520 <clix:returns>value, present-p
2521 </clix:returns>
2522 <clix:description>
2523 This accessor can be used to associate arbitrary data with the the
2524 symbol <clix:arg>symbol</clix:arg> in the <clix:ref>SESSION</clix:ref>
2525 object <clix:arg>session</clix:arg>. <clix:arg>present-p</clix:arg> is
2526 true if such data was found, otherwise <code>NIL</code>. The default
2527 value for <clix:arg>session</clix:arg> is
2528 <clix:ref>*SESSION*</clix:ref>.
2529 <p>
2530 If <code>SETF</code> of <clix:ref>SESSION-VALUE</clix:ref> is called
2531 with <clix:arg>session</clix:arg> being <code>NIL</code> then a
2532 session is automatically instantiated
2533 with <clix:ref>START-SESSION</clix:ref>.
2534 </p>
2535 </clix:description>
2536 </clix:accessor>
2537
2538 <clix:function name='delete-session-value'>
2539 <clix:lambda-list>symbol
2540 <clix:lkw>optional
2541 </clix:lkw> session
2542 </clix:lambda-list>
2543 <clix:returns>|
2544 </clix:returns>
2545 <clix:description>
2546 Removes the value associated with
2547 <clix:arg>symbol</clix:arg> from
2548 <clix:arg>session</clix:arg> if there is one.
2549 </clix:description>
2550 </clix:function>
2551
2552 <clix:special-variable name='*session*'>
2553 <clix:description>
2554 The current session while in the context of a request, or
2555 <code>NIL</code>.
2556 </clix:description>
2557 </clix:special-variable>
2558
2559 <clix:function name='remove-session'>
2560 <clix:lambda-list>session
2561 </clix:lambda-list>
2562 <clix:returns>|
2563 </clix:returns>
2564 <clix:description>
2565 Completely removes the <clix:ref>SESSION</clix:ref> object
2566 <clix:arg>session</clix:arg> from Hunchentoot's
2567 internal <a href="#session-db">session database</a>.
2568 </clix:description>
2569 </clix:function>
2570
2571 <clix:function name='reset-sessions'>
2572 <clix:lambda-list>
2573 <clix:lkw>optional
2574 </clix:lkw> acceptor
2575 </clix:lambda-list>
2576 <clix:returns>|
2577 </clix:returns>
2578 <clix:description>
2579 Removes <em>all</em> stored sessions of
2580 <clix:arg>acceptor</clix:arg>. The default for
2581 <clix:arg>acceptor</clix:arg> is
2582 <clix:ref>*ACCEPTOR*</clix:ref>.
2583 </clix:description>
2584 </clix:function>
2585
2586 <clix:function name='regenerate-session-cookie-value'>
2587 <clix:lambda-list>session
2588 </clix:lambda-list>
2589 <clix:returns>cookie
2590 </clix:returns>
2591 <clix:description>
2592 Regenerates the session cookie value. This should be used
2593 when a user logs in according to the application to prevent
2594 against session fixation attacks. The cookie value being
2595 dependent on ID, USER-AGENT, REMOTE-ADDR, START, and
2596 *SESSION-SECRET*, the only value we can change is START to
2597 regenerate a new value. Since we're generating a new cookie,
2598 it makes sense to have the session being restarted, in
2599 time. That said, because of this fact, calling this function
2600 twice in the same second will regenerate twice the same
2601 value.
2602 </clix:description>
2603 </clix:function>
2604
2605 <clix:special-variable name='*rewrite-for-session-urls*'>
2606 <clix:description>
2607 Whether HTML pages should possibly be rewritten for cookie-less
2608 session-management.
2609 </clix:description>
2610 </clix:special-variable>
2611
2612 <clix:special-variable name='*content-types-for-url-rewrite*'>
2613 <clix:description>
2614 The content types for which url-rewriting is OK. See
2615 <clix:ref>*REWRITE-FOR-SESSION-URLS*</clix:ref>.
2616 </clix:description>
2617 </clix:special-variable>
2618
2619 <clix:special-variable name='*use-remote-addr-for-sessions*'>
2620 <clix:description>
2621 Whether the client's remote IP (as returned by <clix:ref>REAL-REMOTE-ADDR</clix:ref>)
2622 should be encoded into the session string. If this value is true, a
2623 session will cease to be accessible if the client's remote IP changes.
2624 <p>
2625 This might for example be an issue if the client uses a proxy server
2626 which doesn't send correct 'X-Forwarded-For' headers.
2627 </p>
2628 </clix:description>
2629 </clix:special-variable>
2630
2631 <clix:function generic='true' name='session-remote-addr'>
2632 <clix:lambda-list>session
2633 </clix:lambda-list>
2634 <clix:returns>remote-addr
2635 </clix:returns>
2636 <clix:description>
2637 The remote IP address of the client when this session was started (as
2638 returned by <clix:ref>REAL-REMOTE-ADDR</clix:ref>).
2639 </clix:description>
2640 </clix:function>
2641
2642 <clix:special-variable name='*use-user-agent-for-sessions*'>
2643 <clix:description>Whether the 'User-Agent' header should
2644 be encoded into the session string. If this value is true, a session
2645 will cease to be accessible if the client sends a different
2646 'User-Agent' header.
2647 </clix:description>
2648 </clix:special-variable>
2649
2650 <clix:function generic='true' name='session-user-agent'>
2651 <clix:lambda-list>session
2652 </clix:lambda-list>
2653 <clix:returns>user-agent
2654 </clix:returns>
2655 <clix:description>
2656 The incoming 'User-Agent' header that
2657 was sent when this session was created.
2658 </clix:description>
2659 </clix:function>
2660
2661 <clix:accessor generic='true' name='session-max-time'>
2662 <clix:lambda-list>session
2663 </clix:lambda-list>
2664 <clix:returns>max-time
2665 </clix:returns>
2666 <clix:description>
2667 Gets or sets the time (in seconds) after
2668 which <clix:arg>session</clix:arg> expires if it's not used.
2669 </clix:description>
2670 </clix:accessor>
2671
2672
2673 <clix:special-variable name='*session-max-time*'>
2674 <clix:description>
2675 The default time (in seconds) after which a session times out.
2676 </clix:description>
2677 </clix:special-variable>
2678
2679 <clix:special-variable name='*session-gc-frequency*'>
2680 <clix:description>
2681 A session GC (see function <clix:ref>SESSION-GC</clix:ref>) will happen every
2682 <clix:ref>*SESSION-GC-FREQUENCY*</clix:ref> requests (counting only
2683 requests which create a new session) if this variable is
2684 not <code>NIL</code>. See <clix:ref>SESSION-CREATED</clix:ref>.
2685 </clix:description>
2686 </clix:special-variable>
2687
2688 <clix:function name='session-gc'>
2689 <clix:lambda-list>
2690 </clix:lambda-list>
2691 <clix:returns>|
2692 </clix:returns>
2693 <clix:description>
2694 Removes sessions from the current session database which are
2695 too old - see <clix:ref>SESSION-TOO-OLD-P</clix:ref>.
2696 </clix:description>
2697 </clix:function>
2698
2699 <clix:function name='session-too-old-p'>
2700 <clix:lambda-list>session
2701 </clix:lambda-list>
2702 <clix:returns>generalized-boolean
2703 </clix:returns>
2704 <clix:description>
2705 Returns true if the <clix:ref>SESSION</clix:ref> object <clix:arg>session</clix:arg> has not been active in
2706 the last <code>(session-max-time session)</code> seconds.
2707 </clix:description>
2708 </clix:function>
2709
2710 <clix:function generic='true' name='session-id'>
2711 <clix:lambda-list>session
2712 </clix:lambda-list>
2713 <clix:returns>session-id
2714 </clix:returns>
2715 <clix:description>
2716 The unique ID (an INTEGER) of the session.
2717 </clix:description>
2718 </clix:function>
2719
2720 <clix:function generic='true' name='session-start'>
2721 <clix:lambda-list>session
2722 </clix:lambda-list>
2723 <clix:returns>universal-time
2724 </clix:returns>
2725 <clix:description>
2726 The time this session was started.
2727 </clix:description>
2728 </clix:function>
2729
2730 </clix:subchapter>
2731
2732 <clix:subchapter name="session-behaviour" title="Customizing session behaviour">
2733
2734 For everyday session usage, you will probably just
2735 use <clix:ref>START-SESSION</clix:ref>,
2736 <clix:ref>SESSION-VALUE</clix:ref>,
2737 and maybe <clix:ref>DELETE-SESSION-VALUE</clix:ref>
2738 and <clix:ref>*SESSION*</clix:ref>. However, there are two ways to
2739 customize the way Hunchentoot maintains sessions.
2740 <p>
2741 One way is to mostly leave the session mechanism intact but to tweak
2742 it a bit:
2743 <ul>
2744 <li>The publicly visible part of a session is encoded using a
2745 <a href="#*session-secret*">secret</a> which you can set yourself.</li>
2746 <li>And it is stored using a cookie (or GET
2747 parameter) <a href="#session-cookie-name">name</a> that you can
2748 override.</li>
2749 <li>Each session receives a <a href="#next-session-id">new ID</a> when
2750 it is created and you can implement a more robust way to do that.</li>
2751 <li>You can arrange to be called whenever a session
2752 is <a href="#session-created">created</a> to trigger some action. You
2753 might also do this to invent your own
2754 session <a href="#session-gc">garbage collection</a>.</li>
2755 <li>By default, all sessions are stored in a global alist in memory.
2756 You can't change the alist part, but you can distribute your sessions
2757 over different <a href="#session-db">"databases"</a>.</li>
2758 <li>By default, every operation which modifies sessions or one of the
2759 session databases is guarded by a global lock, but you can arrange to
2760 <a href="#session-db-lock">provide</a> different locks for this.</li>
2761 </ul>
2762 </p>
2763 <p>
2764 The other way to customize Hunchentoot's sessions is to completely
2765 replace them. This is actually pretty easy: Create your own class to
2766 store state (which doesn't have to and probably shouldn't inherit
2767 from <clix:ref>SESSION</clix:ref>) and implement methods for
2768 <clix:ref>SESSION-VERIFY</clix:ref>
2769 and <clix:ref>SESSION-COOKIE-VALUE</clix:ref> - that's it.
2770 Hunchentoot will continue to use cookies and/or to rewrite URLs to
2771 keep track of session state and it will store "the current session"
2772 (whatever that is in your implementation)
2773 in <clix:ref>*SESSION*</clix:ref>. Everything else (like persisting
2774 sessions, GC, getting and setting values) you'll have to take care of
2775 yourself and the other session functions
2776 (like <clix:ref>START-SESSION</clix:ref> or
2777 <clix:ref>SESSION-VALUE</clix:ref>) won't work anymore. (Almost)
2778 total freedom, but a lot of responsibility as well... :)
2779 </p>
2780
2781 <clix:special-variable name='*session-secret*'>
2782 <clix:description>
2783 A random ASCII string that's used to encode the public
2784 session data. This variable is initially unbound and will
2785 be set (using <clix:ref>RESET-SESSION-SECRET</clix:ref>) the
2786 first time a session is created, if necessary. You can
2787 prevent this from happening if you set the value yourself
2788 before starting <a href="#acceptors">acceptors</a>.
2789 </clix:description>
2790 </clix:special-variable>
2791
2792 <clix:function name='reset-session-secret'>
2793 <clix:lambda-list>
2794 </clix:lambda-list>
2795 <clix:returns>secret
2796 </clix:returns>
2797 <clix:description>
2798 Sets <clix:ref>*SESSION-SECRET*</clix:ref> to a
2799 new random value. All old sessions will cease to be valid.
2800 </clix:description>
2801 </clix:function>
2802
2803 <clix:function generic='true' name='session-cookie-name'>
2804 <clix:lambda-list>acceptor
2805 </clix:lambda-list>
2806 <clix:returns>name
2807 </clix:returns>
2808 <clix:description>
2809 Returns the name (a string) of the cookie (or
2810 the GET parameter) which is used to store a session on the client
2811 side. The default is to use the
2812 string <code>"hunchentoot-session"</code>, but you can
2813 specialize this function if you want another name.
2814 </clix:description>
2815 </clix:function>
2816
2817 <clix:function generic='true' name='session-created'>
2818 <clix:lambda-list>acceptor new-session
2819 </clix:lambda-list>
2820 <clix:returns>result
2821 </clix:returns>
2822 <clix:description>
2823 This function is called whenever a new session
2824 has been created. There's a default method which might trigger
2825 a <a href="#session-gc">session GC</a> based on the value of
2826 <clix:ref>*SESSION-GC-FREQUENCY*</clix:ref>.
2827 <p>
2828 The return value is ignored.
2829 </p>
2830 </clix:description>
2831 </clix:function>
2832
2833 <clix:function generic='true' name='next-session-id'>
2834 <clix:lambda-list>acceptor
2835 </clix:lambda-list>
2836 <clix:returns>id
2837 </clix:returns>
2838 <clix:description>
2839 Returns the next sequential session ID, an
2840 integer, which should be unique per session. The default method uses
2841 a simple global counter and isn't guarded by a lock. For a
2842 high-performance production environment you might consider using a
2843 more robust implementation.
2844 </clix:description>
2845 </clix:function>
2846
2847 <clix:accessor generic='true' name='session-db'>
2848 <clix:lambda-list>acceptor
2849 </clix:lambda-list>
2850 <clix:returns>database
2851 </clix:returns>
2852 <clix:description>
2853 Returns the current session database which is an
2854 alist where each car is a session's ID and the cdr is the
2855 corresponding <clix:ref>SESSION</clix:ref> object itself. The default
2856 is to use a global list for all acceptors.
2857 </clix:description>
2858 </clix:accessor>
2859
2860 <clix:function generic='true' name='session-db-lock'>
2861 <clix:lambda-list>acceptor
2862 <clix:lkw>key
2863 </clix:lkw> whole-db-p
2864 </clix:lambda-list>
2865 <clix:returns>lock
2866 </clix:returns>
2867 <clix:description>
2868 A function which returns a lock that will be
2869 used to prevent concurrent access to sessions. The first argument
2870 will be the <a href="#acceptors">acceptor</a> that handles the
2871 current <a href="#requests">request</a>, the second argument is true
2872 if the whole (current) session database is modified. If it
2873 is <code>NIL</code>, only one existing session in the database is
2874 modified.
2875 <p>
2876 This function can return <code>NIL</code> which means that sessions or
2877 session databases will be modified without a lock held (for example
2878 for single-threaded environments). The default is to always return a
2879 global lock (ignoring the <clix:arg>acceptor</clix:arg> argument) for
2880 Lisps that support threads and <code>NIL</code> otherwise.
2881 </p>
2882 </clix:description>
2883 </clix:function>
2884
2885 <clix:function generic='true' name='session-verify'>
2886 <clix:lambda-list>request
2887 </clix:lambda-list>
2888 <clix:returns>session-or-nil
2889 </clix:returns>
2890 <clix:description>
2891 Tries to get a session identifier from the cookies
2892 (or alternatively from the GET parameters) sent by the client (see
2893 <clix:ref>SESSION-COOKIE-NAME</clix:ref>
2894 and <clix:ref>SESSION-COOKIE-VALUE</clix:ref>). This identifier is
2895 then checked for validity against the <clix:ref>REQUEST</clix:ref>
2896 object
2897 <clix:arg>request</clix:arg>. On success the corresponding session object (if not too
2898 old) is returned (and updated). Otherwise <code>NIL</code> is returned.
2899 <p>
2900 A default method is provided and you only need to write your own one
2901 if you want to maintain your own sessions.
2902 </p>
2903 </clix:description>
2904 </clix:function>
2905
2906 <clix:function generic='true' name='session-cookie-value'>
2907 <clix:lambda-list>session
2908 </clix:lambda-list>
2909 <clix:returns>string
2910 </clix:returns>
2911 <clix:description>
2912 Returns a string which can be used to safely
2913 restore the session <clix:arg>session</clix:arg> if as session has
2914 already been established. This is used as the value stored in the
2915 session cookie or in the corresponding GET parameter and verified
2916 by <clix:ref>SESSION-VERIFY</clix:ref>.
2917 <p>
2918 A default
2919 method is provided and there's no reason to change it unless you
2920 want to use your own session objects.
2921 </p>
2922 </clix:description>
2923 </clix:function>
2924
2925 </clix:subchapter>
2926
2927 <clix:subchapter name="cookies" title="Cookies">
2928
2929 Outgoing cookies are stored in the request's <clix:ref>REPLY</clix:ref>
2930 object (see <clix:ref>COOKIE-OUT</clix:ref>
2931 and <clix:ref>COOKIES-OUT*</clix:ref>). They are CLOS objects
2932 defined like this:
2933
2934 <pre>(defclass cookie ()
2935 ((name :initarg :name
2936 :reader <a class="noborder" name="cookie-name">cookie-name</a>
2937 :type string
2938 :documentation "The name of the cookie - a string.")
2939 (value :initarg :value
2940 :accessor <a class="noborder" name="cookie-value">cookie-value</a>
2941 :initform ""
2942 :documentation "The value of the cookie. Will be URL-encoded when sent to the browser.")
2943 (expires :initarg :expires
2944 :initform nil
2945 :accessor <a class="noborder" name="cookie-expires">cookie-expires</a>
2946 :documentation "The time (a universal time) when the cookie expires (or NIL).")
2947 (max-age :initarg :max-age
2948 :initform nil
2949 :accessor <a class="noborder" name="cookie-max-age">cookie-max-age</a>
2950 :documentation "The time delta (in seconds) after which the cookie expires (or NIL).")
2951 (path :initarg :path
2952 :initform nil
2953 :accessor <a class="noborder" name="cookie-path">cookie-path</a>
2954 :documentation "The path this cookie is valid for (or NIL).")
2955 (domain :initarg :domain
2956 :initform nil
2957 :accessor <a class="noborder" name="cookie-domain">cookie-domain</a>
2958 :documentation "The domain this cookie is valid for (or NIL).")
2959 (secure :initarg :secure
2960 :initform nil
2961 :accessor <a class="noborder" name="cookie-secure">cookie-secure</a>
2962 :documentation "A generalized boolean denoting whether this is a secure cookie.")
2963 (http-only :initarg :http-only
2964 :initform nil
2965 :accessor <a class="noborder" name="cookie-http-only">cookie-http-only</a>
2966 :documentation "A generalized boolean denoting whether this is a <a href="http://msdn2.microsoft.com/en-us/library/ms533046.aspx">HttpOnly</a> cookie.")))
2967 </pre>
2968
2969 The <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_r.htm#reader">reader</a>
2970 <clix:ref>COOKIE-NAME</clix:ref> and
2971 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_a.htm#accessor">accessors</a>
2972 <clix:ref>COOKIE-VALUE</clix:ref>, <clix:ref>COOKIE-EXPIRES</clix:ref>, <clix:ref>COOKIE-MAX-AGE</clix:ref>,
2973 <clix:ref>COOKIE-PATH</clix:ref>, <clix:ref>COOKIE-DOMAIN</clix:ref>, <clix:ref>COOKIE-SECURE</clix:ref>,
2974 and <clix:ref>COOKIE-HTTP-ONLY</clix:ref> are all exported from
2975 the <code>HUNCHENTOOT</code> package. For now, the class name itself is <em>not</em> exported.
2976
2977 <clix:function name="set-cookie">
2978 <clix:lambda-list>
2979 name <clix:lkw>key</clix:lkw> value expires path
2980 domain secure http-only reply
2981 </clix:lambda-list>
2982 <clix:returns>cookie</clix:returns>
2983 <clix:description>
2984 Creates a <code>COOKIE</code> object from the parameters
2985 provided to this function and adds it to the outgoing cookies
2986 of the <a href="#replies"><code>REPLY</code> object</a>
2987 <clix:arg>reply</clix:arg>. If a cookie with the same name
2988 (case-sensitive) already exists, it is replaced. The default
2989 for <clix:arg>reply</clix:arg>
2990 is <clix:ref>*REPLY*</clix:ref>. The default
2991 for <clix:arg>value</clix:arg> is the empty string.
2992 </clix:description>
2993 </clix:function>
2994
2995 <clix:function name="set-cookie*">
2996 <clix:lambda-list>cookie <clix:lkw>optional</clix:lkw> reply</clix:lambda-list>
2997 <clix:returns>cookie</clix:returns>
2998 <clix:description>
2999 Adds the <code>COOKIE</code> object <clix:arg>cookie</clix:arg>
3000 to the outgoing cookies of
3001 the <a href="#replies"><code>REPLY</code> object</a>
3002 <clix:arg>reply</clix:arg>. If a cookie with the same name
3003 (case-sensitive) already exists, it is replaced. The default
3004 for <clix:arg>reply</clix:arg> is <clix:ref>*REPLY*</clix:ref>.
3005 </clix:description>
3006 </clix:function>
3007 </clix:subchapter>
3008
3009 <clix:subchapter name="logging" title="Logging">
3010 Hunchentoot can log accesses and diagnostic messages to two
3011 separate destinations, which can be either files in the file
3012 system or streams. Logging can also be disabled by setting the
3013 <clix:code>ACCESS-LOG-DESTINATION</clix:code> and
3014 <clix:code>MESSAGE-LOG-DESTINATION</clix:code> slots in the
3015 <clix:ref>ACCEPTOR</clix:ref> to <code>NIL</code>. The two
3016 slots can be initialized by providing the
3017 :ACCESS-LOG-DESTINATION and :MESSAGE-LOG-DESTINATION
3018 initialization arguments when creating the acceptor or set by
3019 setting the slots through its
3020 <clix:ref>ACCEPTOR-MESSAGE-LOG-DESTINATION</clix:ref> and
3021 <clix:ref>ACCEPTOR-ACCESS-LOG-DESTINATION</clix:ref> accessors.
3022 <p>
3023 When the path for the message or accept log is set to a
3024 variable holding an output stream, hunchentoots writes
3025 corresponding log entries to that stream. By default,
3026 Hunchentoot logs to *STANDARD-ERROR*.
3027 </p>
3028 <p>
3029 Access logging is done in a format similar to what
3030 the Apache web server can write so that logfile analysis using
3031 standard tools is possible. Errors during request processing are
3032 logged to a separate file.
3033 </p>
3034 <p>
3035 The standard logging mechanism is deliberately simple and slow. The
3036 log files are opened for each log entry and closed again after
3037 writing, and access to them is protected by a global lock. Derived
3038 acceptor classes can implement methods for the
3039 <clix:ref>ACCEPTOR-LOG-MESSAGE</clix:ref> and
3040 <clix:ref>ACCEPTOR-LOG-ACCESS</clix:ref> generic functions in order to
3041 log differently (e.g. to a central logging server or in a different
3042 file format.
3043 </p>
3044 <p>
3045 Errors happening within a <a href="#request-dispatch">handler</a>
3046 which are not caught by the handler itself are handled by
3047 Hunchentoot by logging them to the established
3048 <clix:ref>ACCEPTOR-MESSAGE-LOG-DESTINATION</clix:ref>.
3049 </p>
3050
3051 <clix:function name='log-message*'>
3052 <clix:lambda-list>log-level format-string
3053 <clix:lkw>rest
3054 </clix:lkw> format-arguments
3055 </clix:lambda-list>
3056 <clix:returns>result
3057 </clix:returns>
3058 <clix:description>
3059 Convenience function which calls the message
3060 logger of the current acceptor (if there is one) with the same
3061 arguments it accepts. Returns <code>NIL</code> if there is no message
3062 logger or whatever the message logger returns.
3063 <p>
3064 This is the function which Hunchentoot itself uses to log errors it
3065 catches during request processing.
3066 </p>
3067 </clix:description>
3068 </clix:function>
3069
3070 <clix:special-variable name='*log-lisp-errors-p*'>
3071 <clix:description>
3072 Whether Lisp errors in request handlers should be logged.
3073 </clix:description>
3074 </clix:special-variable>
3075
3076 <clix:special-variable name='*log-lisp-backtraces-p*'>
3077 <clix:description>
3078 Whether Lisp backtraces should be logged. Only
3079 has an effect if <clix:ref>*LOG-LISP-ERRORS-P*</clix:ref> is true
3080 as well.
3081 </clix:description>
3082 </clix:special-variable>
3083
3084 <clix:special-variable name='*log-lisp-warnings-p*'>
3085 <clix:description>
3086 Whether Lisp warnings in request handlers should be logged.
3087 </clix:description>
3088 </clix:special-variable>
3089
3090 <clix:special-variable name='*lisp-errors-log-level*'>
3091 <clix:description>
3092 Log level for Lisp errors. Should be one
3093 of <code>:ERROR</code> (the default), <code>:WARNING</code>,
3094 or <code>:INFO</code>.
3095 </clix:description>
3096 </clix:special-variable>
3097
3098 <clix:special-variable name='*lisp-warnings-log-level*'>
3099 <clix:description>
3100 Log level for Lisp warnings.
3101 Should be one of <code>:ERROR</code>, <code>:WARNING</code>
3102 (the default), or <code>:INFO</code>.
3103 </clix:description>
3104 </clix:special-variable>
3105 </clix:subchapter>
3106
3107 <clix:subchapter name="conditions" title="Conditions and error handling">
3108 <p>
3109 This section describes how Hunchentoot deals with exceptional
3110 situations. See also the secion about <a href="#logging">logging</a>.
3111 </p>
3112 <p>
3113 When an error occurs while processing a request, Hunchentoot's
3114 default behavior is to catch the error, log it and
3115 optionally display it to the client in the HTML response.
3116 This behavior can be customized through the values of a number
3117 of special variables, which are documented below.
3118 </p>
3119
3120 <clix:special-variable name='*catch-errors-p*'>
3121 <clix:description>
3122 If the value of this variable is <code>NIL</code>
3123 (the default is <code>T</code>), then errors which happen while a
3124 request is handled aren't <a href="#logging">caught as usual</a>, but
3125 instead your
3126 Lisp's <a
3127 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_d.htm#debugger">debugger</a>
3128 is <a
3129 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_invoke.htm">invoked</a>.
3130 This variable should obviously always be set to a <em>true</em> value
3131 in a production environment.
3132 See <clix:ref>MAYBE-INVOKE-DEBUGGER</clix:ref>
3133 if you want to fine-tune this behaviour.
3134 </clix:description>
3135 </clix:special-variable>
3136
3137 <clix:special-variable name='*show-lisp-errors-p*'>
3138 <clix:description>
3139 Whether Lisp errors should be shown in HTML output. Note
3140 that this only affects canned responses generated by Lisp.
3141 If an error template is present for the "internal server
3142 error" status code, this special variable is not used (see
3143 <clix:ref>acceptor-status-message</clix:ref>).
3144 </clix:description>
3145 </clix:special-variable>
3146
3147 <clix:special-variable name='*show-lisp-backtraces-p*'>
3148 <clix:description>
3149 Whether Lisp backtraces should be shown in HTML output if
3150 <clix:ref>*SHOW-LISP-ERRORS-P*</clix:ref> is true and an error occurs.
3151 </clix:description>
3152 </clix:special-variable>
3153
3154 <clix:function generic='true' name='maybe-invoke-debugger'>
3155 <clix:lambda-list>condition
3156 </clix:lambda-list>
3157 <clix:returns>|
3158 </clix:returns>
3159 <clix:description>
3160 This generic function is called whenever a
3161 <a
3162 href="http://www.lispworks.com/documentation/HyperSpec/Body/09_.htm">condition</a> <code><i>condition</i></code>
3163 is signaled in Hunchentoot. You might want to specialize it on
3164 specific condition classes for debugging purposes. The default
3165 method <a
3166 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_invoke.htm">invokes
3167 the debugger</a> with <clix:arg>condition</clix:arg> if
3168 <clix:ref>*CATCH-ERRORS-P*</clix:ref> is <code>NIL</code>.
3169 </clix:description>
3170 </clix:function>
3171
3172 <clix:condition name='hunchentoot-condition'>
3173 <clix:description>
3174 Superclass for all conditions related to Hunchentoot.
3175 </clix:description>
3176 </clix:condition>
3177
3178 <clix:condition name='hunchentoot-error'>
3179 <clix:description>
3180 Superclass for all errors related to Hunchentoot and a subclass of <clix:ref>HUNCHENTOOT-CONDITION</clix:ref>.
3181 </clix:description>
3182 </clix:condition>
3183
3184 <clix:condition name='parameter-error'>
3185 <clix:description>
3186 Signalled if a function was called with incosistent or illegal parameters. A subclass of <clix:ref>HUNCHENTOOT-ERROR</clix:ref>.
3187 </clix:description>
3188 </clix:condition>
3189
3190 <clix:condition name='hunchentoot-warning'>
3191 <clix:description>
3192 Superclass for all warnings related to Hunchentoot and a subclass of <clix:ref>HUNCHENTOOT-CONDITION</clix:ref>.
3193 </clix:description>
3194 </clix:condition>
3195
3196 </clix:subchapter>
3197
3198 <clix:subchapter name="misc" title="Miscellaneous">
3199
3200 Various functions and variables which didn't fit into one of the
3201 other categories.
3202
3203 <clix:function name='abort-request-handler'>
3204 <clix:lambda-list>
3205 <clix:lkw>optional
3206 </clix:lkw> result
3207 </clix:lambda-list>
3208 <clix:returns>result
3209 </clix:returns>
3210 <clix:description>
3211 This function can be called by a request handler
3212 at any time to immediately abort handling the request. This works as
3213 if the handler had returned <clix:arg>result</clix:arg>. See the
3214 source code of <clix:ref>REDIRECT</clix:ref> for an example.
3215 </clix:description>
3216 </clix:function>
3217
3218 <clix:function name="handle-if-modified-since">
3219 <clix:lambda-list>time <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
3220 <clix:returns>|</clix:returns>
3221 <clix:description>
3222 This function is designed to be used inside
3223 a <a href="#request-dispatch">handler</a>. If the client has sent an
3224 'If-Modified-Since' header
3225 (see <a href="http://www.faqs.org/rfcs/rfc2616.html">RFC 2616</a>,
3226 section 14.25) and the time specified matches the universal
3227 time
3228 <clix:arg>time</clix:arg> then the
3229 header <clix:ref>+HTTP-NOT-MODIFIED+</clix:ref> with no content
3230 is immediately returned to the client.
3231 <p>
3232 Note that for this function to be useful you should usually
3233 send 'Last-Modified' headers back to the client. See the
3234 code
3235 of <clix:ref>CREATE-STATIC-FILE-DISPATCHER-AND-HANDLER</clix:ref>
3236 for an example.
3237 </p>
3238 </clix:description>
3239 </clix:function>
3240
3241 <clix:function name="handle-static-file">
3242 <clix:lambda-list>path <clix:lkw>optional</clix:lkw> content-type</clix:lambda-list>
3243 <clix:returns>nil</clix:returns>
3244 <clix:description>
3245 Sends the file denoted by the pathname designator
3246 <clix:arg>path</clix:arg> with content type
3247 <clix:arg>content-type</clix:arg> to the client. Sets the
3248 necessary handlers. In particular the function employs
3249 <clix:ref>HANDLE-IF-MODIFIED-SINCE</clix:ref>.
3250 <p>
3251 If <clix:arg>content-type</clix:arg> is <code>NIL</code> the
3252 function tries to determine the correct content type from
3253 the file's suffix or falls back
3254 to <code>"application/octet-stream"</code> as a last resort.
3255 </p>
3256 <p>
3257 Note that this function
3258 calls <clix:ref>SEND-HEADERS</clix:ref> internally, so after
3259 you've called it, the headers are sent and the return value
3260 of your handler is ignored.
3261 </p>
3262 </clix:description>
3263 </clix:function>
3264
3265 <clix:function name="redirect">
3266 <clix:lambda-list>target <clix:lkw>key</clix:lkw> host port protocol add-session-id code</clix:lambda-list>
3267 <clix:returns>|</clix:returns>
3268 <clix:description>
3269 Sends back appropriate headers to redirect the client
3270 to <clix:arg>target</clix:arg> (a string).
3271 <p>
3272 If <clix:arg>target</clix:arg> is a full URL starting with a
3273 scheme, <clix:arg>host</clix:arg>, <clix:arg>port</clix:arg>,
3274 and <clix:arg>protocol</clix:arg> are ignored.
3275 Otherwise, <clix:arg>target</clix:arg> should denote the path
3276 part of a URL, <clix:arg>protocol</clix:arg> must be one of
3277 the keywords <code>:HTTP</code> or <code>:HTTPS</code>, and
3278 the URL to redirect to will be constructed
3279 from <clix:arg>host</clix:arg>, <clix:arg>port</clix:arg>, <clix:arg>protocol</clix:arg>,
3280 and <clix:arg>target</clix:arg>.
3281 </p>
3282 <p>
3283 <clix:arg>code</clix:arg> must be a 3xx HTTP redirection
3284 status code to send to the client. It defaults to 302
3285 ("Found"). If <clix:arg>host</clix:arg> is not provided,
3286 the current host (see <clix:ref>HOST</clix:ref>) will be
3287 used. If <clix:arg>protocol</clix:arg> is the keyword
3288 <code>:HTTPS</code>, the client will be redirected to a
3289 https URL, if it's <code>:HTTP</code> it'll be sent to a
3290 http URL. If both <clix:arg>host</clix:arg> and
3291 <clix:arg>protocol</clix:arg> aren't provided, then the
3292 value of <clix:arg>protocol</clix:arg> will match the
3293 current request.
3294 </p>
3295 </clix:description>
3296 </clix:function>
3297
3298 <clix:function name="require-authorization">
3299 <clix:lambda-list><clix:lkw>optional</clix:lkw> realm</clix:lambda-list>
3300 <clix:returns>|</clix:returns>
3301 <clix:description>
3302 Sends back appropriate headers to require basic HTTP
3303 authentication
3304 (see <a href="http://www.faqs.org/rfcs/rfc2617.html">RFC 2617</a>)
3305 for the realm <clix:arg>realm</clix:arg>. The default value
3306 for <clix:arg>realm</clix:arg> is <code>"Hunchentoot"</code>.
3307 </clix:description>
3308 </clix:function>
3309
3310 <clix:function name='no-cache'>
3311 <clix:lambda-list>
3312 </clix:lambda-list>
3313 <clix:returns>|
3314 </clix:returns>
3315 <clix:description>
3316 Adds appropriate headers to completely prevent caching on most browsers.
3317 </clix:description>
3318 </clix:function>
3319
3320 <clix:function name='ssl-p'>
3321 <clix:lambda-list>
3322 <clix:lkw>optional
3323 </clix:lkw> acceptor
3324 </clix:lambda-list>
3325 <clix:returns>generalized-boolean
3326 </clix:returns>
3327 <clix:description>
3328 Whether the current connection to the client is secure. See <clix:ref>ACCEPTOR-SSL-P</clix:ref>.
3329 </clix:description>
3330 </clix:function>
3331
3332 <clix:function name='reason-phrase'>
3333 <clix:lambda-list>return-code
3334 </clix:lambda-list>
3335 <clix:returns>string
3336 </clix:returns>
3337 <clix:description>
3338 Returns a reason phrase for the HTTP return code <clix:arg>return-code</clix:arg>
3339 (which should be an integer) or <code>NIL</code> for return codes Hunchentoot
3340 doesn't know.
3341 </clix:description>
3342 </clix:function>
3343
3344 <clix:function name='rfc-1123-date'>
3345 <clix:lambda-list>
3346 <clix:lkw>optional
3347 </clix:lkw> time
3348 </clix:lambda-list>
3349 <clix:returns>string
3350 </clix:returns>
3351 <clix:description>
3352 Generates a time string according to <a href="http://www.faqs.org/rfcs/rfc1123.html">RFC 1123</a>. Default is current time.
3353 This can be used to send a 'Last-Modified' header - see <clix:ref>HANDLE-IF-MODIFIED-SINCE</clix:ref>.
3354 </clix:description>
3355 </clix:function>
3356
3357 <clix:function name='url-encode'>
3358 <clix:lambda-list>string
3359 <clix:lkw>optional
3360 </clix:lkw> external-format
3361 </clix:lambda-list>
3362 <clix:returns>string
3363 </clix:returns>
3364 <clix:description>
3365 URL-encodes a string using the external format <clix:arg>external-format</clix:arg>. The default for <clix:arg>external-format</clix:arg> is the value of <clix:ref>*HUNCHENTOOT-DEFAULT-EXTERNAL-FORMAT*</clix:ref>.
3366 </clix:description>
3367 </clix:function>
3368
3369 <clix:function name='url-decode'>
3370 <clix:lambda-list>string
3371 <clix:lkw>optional
3372 </clix:lkw> external-format
3373 </clix:lambda-list>
3374 <clix:returns>string
3375 </clix:returns>
3376 <clix:description>
3377 Decodes a URL-encoded string which is assumed to
3378 be encoded using the external
3379 format <clix:arg>external-format</clix:arg>, i.e. this is the inverse
3380 of <clix:ref>URL-ENCODE</clix:ref>. It is assumed that you'll rarely
3381 need this function, if ever. But just in case - here it is. The
3382 default for <clix:arg>external-format</clix:arg> is the value
3383 of <clix:ref>*HUNCHENTOOT-DEFAULT-EXTERNAL-FORMAT*</clix:ref>.
3384 </clix:description>
3385 </clix:function>
3386
3387 <clix:function name='escape-for-html'>
3388 <clix:lambda-list>string
3389 </clix:lambda-list>
3390 <clix:returns>result
3391 </clix:returns>
3392 <clix:description>
3393 Escapes the characters #\<, #\>, #\', #\", and #\& for HTML output.
3394 </clix:description>
3395 </clix:function>
3396
3397 <clix:function name="http-token-p">
3398 <clix:lambda-list>object</clix:lambda-list>
3399 <clix:returns>generalized-boolean</clix:returns>
3400 <clix:description>
3401 This function tests whether <clix:arg>object</clix:arg> is a
3402 non-empty string which is a <em>token</em> according
3403 to <a href="http://www.faqs.org/rfcs/rfc2068.html">RFC
3404 2068</a> (i.e. whether it may be used for, say, cookie names).
3405 </clix:description>
3406 </clix:function>
3407
3408 <clix:function name='mime-type'>
3409 <clix:lambda-list>pathspec
3410 </clix:lambda-list>
3411 <clix:returns>result
3412 </clix:returns>
3413 <clix:description>
3414 Given a pathname designator <clix:arg>pathspec</clix:arg> returns the <a href="http://en.wikipedia.org/wiki/Internet_media_type">MIME type</a>
3415 (as a string) corresponding to the suffix of the file denoted by
3416 <clix:arg>pathspec</clix:arg> (or <code>NIL</code>).
3417 </clix:description>
3418 </clix:function>
3419
3420 <clix:function name='within-request-p'>
3421 <clix:lambda-list>
3422 </clix:lambda-list>
3423 <clix:returns>generalized-boolean
3424 </clix:returns>
3425 <clix:description>
3426 Returns true if in the context of a request. Otherwise, <code>NIL</code>.
3427 </clix:description>
3428 </clix:function>
3429
3430 <clix:special-variable name="*tmp-directory*">
3431 <clix:description>
3432 This should be a pathname denoting a directory where temporary
3433 files can be stored. It is used for <a href="#upload">file
3434 uploads</a>.
3435 </clix:description>
3436 </clix:special-variable>
3437
3438 <clix:special-variable name='*header-stream*'>
3439 <clix:description>
3440 If this variable is not <code>NIL</code>, it should be bound to a stream to
3441 which incoming and outgoing headers will be written for debugging
3442 purposes.
3443 </clix:description>
3444 </clix:special-variable>
3445
3446
3447 <clix:special-variable name='*cleanup-function*'>
3448 <clix:description>
3449 A designator for a function without arguments which is called on a
3450 regular basis if <clix:ref>*CLEANUP-INTERVAL*</clix:ref> is not <code>NIL</code>. The initial value is
3451 the name of a function which invokes a garbage collection on 32-bit
3452 versions of LispWorks.
3453 <p>
3454 This variable is only available on LispWorks.
3455 </p>
3456 </clix:description>
3457 </clix:special-variable>
3458
3459 <clix:special-variable name='*cleanup-interval*'>
3460 <clix:description>
3461 Should be <code>NIL</code> or a positive integer. The system calls
3462 <clix:ref>*CLEANUP-FUNCTION*</clix:ref>
3463 whenever <clix:ref>*CLEANUP-INTERVAL*</clix:ref> new worker threads
3464 (counted globally across all acceptors) have been created unless the
3465 value is <code>NIL</code>. The initial value is 100.
3466 <p>
3467 This variable is only available on LispWorks.
3468 </p>
3469 </clix:description>
3470 </clix:special-variable>
3471 </clix:subchapter>
3472 </clix:chapter>
3473
3474 <clix:chapter name="testing" title="Testing">
3475 Hunchentoot comes with a test script which verifies that the
3476 example web server responds as expected. This test script uses the
3477 <a href="http://weitz.de/drakma/">Drakma</a> HTTP client library
3478 and thus shares a significant amount of its base code with
3479 Hunchentoot itself. Still, running the test script is a useful
3480 confidence test, and it is also possible to run the script across
3481 machines in order to verify a new Hunchentoot (or, for that matter
3482 Drakma) port.
3483 <p>
3484 To run the confidence test, <a href="#teen-age">start
3485 the example web server</a>. Then, in your Lisp
3486 listener, type
3487 <pre>(<a class="noborder" href="hunchentoot-test:test-hunchentoot">hunchentoot-test:test-hunchentoot</a> "http://localhost:4242")</pre>
3488 You will see some diagnostic output and a summary line that
3489 reports whether any tests have failed. (You can also use the
3490 example certificate and key files in the test directory and
3491 start and test an https server instead.)
3492 </p>
3493
3494 <clix:function name="hunchentoot-test:test-hunchentoot">
3495 <clix:lambda-list>base-url <clix:lkw>key</clix:lkw></clix:lambda-list>
3496 <clix:returns>|</clix:returns>
3497 <clix:description>
3498 Runs the built-in confidence
3499 test. <clix:arg>base-url</clix:arg> is the base URL to use
3500 for testing, it should not have a trailing slash. The keyword
3501 arguments accepted are for future extension and should not
3502 currently be used.
3503 <p>
3504 The script expects the Hunchentoot example test server to be
3505 running at the given <clix:arg>base-url</clix:arg> and
3506 retrieves various pages from that server, expecting certain
3507 responses.
3508 </p>
3509 </clix:description>
3510 </clix:function>
3511 </clix:chapter>
3512
3513 <clix:chapter name="debugging" title="Debugging">
3514 By default, Hunchentoot intercepts all errors that occur while
3515 executing request handlers, logs them to the log file and displays
3516 a static error page to the user. While developing applications,
3517 you may want to change that behavior so that the debugger is
3518 invoked when an error occurs. You can set
3519 the <clix:ref>*CATCH-ERRORS-P*</clix:ref> to <code>NIL</code> to
3520 make that happen. Alternatively, you may want to have Hunchentoot
3521 display detailed error information in the error response page.
3522 You can set the <clix:ref>*SHOW-LISP-ERRORS-P*</clix:ref> to a
3523 true value to make that happen. If you don't want to see Lisp
3524 backtraces in these error pages, you can
3525 set <clix:ref>*SHOW-LISP-BACKTRACES-P*</clix:ref>
3526 to <code>NIL</code>.
3527 </clix:chapter>
3528
3529 <clix:chapter name="history" title="History">
3530
3531 Hunchentoot's predecessor <a href="http://weitz.de/tbnl/">TBNL</a>
3532 (which is short for "To Be Named Later") grew over the years as a
3533 toolkit that I used for various commercial and private
3534 projects. In August 2003, Daniel Barlow started
3535 a <a href="http://article.gmane.org/gmane.lisp.web/148">review of
3536 web APIs</a> on
3537 the <a href="http://www.red-bean.com/lispweb/">lispweb</a> mailing
3538 list and
3539 I <a href="http://article.gmane.org/gmane.lisp.web/153">described</a>
3540 the API of my hitherto-unreleased bunch of code (and christened it
3541 "TBNL").
3542 <p>
3543 It turned out that
3544 <a href="http://www.jeffcaldwell.com/">Jeff Caldwell</a> had
3545 worked on something similar so he emailed me and proposed to
3546 join our efforts. As I had no immediate plans to release my code
3547 (which was poorly organized, undocumented, and mostly
3548 CMUCL-specific), I gave it to Jeff and he worked towards a
3549 release. He added docstrings, refactored, added some stuff, and
3550 based it on KMRCL to make it portable across several Lisp
3551 implementations.
3552 </p>
3553 <p>
3554 Unfortunately, Jeff is at least as busy as I am so he didn't
3555 find the time to finish a full release. But in spring 2004 I
3556 needed a documented version of the code for a client of mine who
3557 thought it would be good if the toolkit were publicly available
3558 under an open source license. So I took Jeff's code, refactored
3559 again (to sync with the changes I had done in the meantime), and
3560 added documentation. This resulted in TBNL 0.1.0 (which
3561 initially required mod_lisp as its front-end).
3562 </p>
3563 <p>
3564 In March 2005, Bob Hutchinson sent patches which enabled TBNL to
3565 use other front-ends than mod_lisp. This made me aware that
3566 TBNL was already <em>almost</em> a full web server, so
3567 eventually I wrote Hunchentoot which <em>was</em> a full web
3568 server, implemented as a wrapper around TBNL. Hunchentoot 0.1.0
3569 was released at the end of 2005 and was originally
3570 LispWorks-only.
3571 </p>
3572 <p>
3573 Hunchentoot 0.4.0, released in October 2006, was the first
3574 release which also worked with other Common Lisp
3575 implementations. It is a major rewrite and also incorporates
3576 most of TBNL and replaces it completely.
3577 </p>
3578 <p>
3579 Hunchentoot 1.0.0, released in February 2009, is again a major
3580 rewrite and should be considered work in progress. It moved to
3581 using
3582 the <a href="http://common-lisp.net/project/usocket/">usocket</a>
3583 and <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux
3584 Threads</a> libraries for non-LispWorks Lisps, thereby removing most of
3585 the platform dependent code. Threading behaviour was made
3586 controllable through the introduction of
3587 taskmasters. <a href="http://www.cliki.net/mod_lisp">mod_lisp</a>
3588 support and several other things were removed in this release to
3589 simplify the code base (and partly due to the lack of interest).
3590 Several architectural changes (lots of them not
3591 backwards-compatible) were made to ease customization of
3592 Hunchentoot's behaviour. A significant part of the 1.0.0
3593 redesign was done
3594 by <a href="http://netzhansa.blogspot.com/">Hans Hubner</a>.
3595 </p>
3596 </clix:chapter>
3597
3598 <clix:chapter name="index" title="Symbol index">
3599
3600 Here are all exported symbols of the <code>HUNCHENTOOT</code>
3601 package in alphabetical order linked to their corresponding
3602 documentation entries:
3603
3604 <clix:index/>
3605
3606 </clix:chapter>
3607
3608 <clix:chapter name="ack" title="Acknowledgements">
3609
3610 Thanks to Jeff Caldwell - TBNL would not have been released
3611 without his efforts. Thanks
3612 to <a href="http://www.cliki.net/Stefan%20Scholl">Stefan
3613 Scholl</a> and Travis Cross for various additions and fixes to
3614 TBNL, to <a href="http://www.foldr.org/~michaelw/">Michael
3615 Weber</a> for initial file upload code, and
3616 to <a href="http://www.ltn.lv/~jonis/">Janis Dzerins</a> for
3617 his <a href="http://common-lisp.net/project/rfc2388/">RFC 2388
3618 code</a>. Thanks to Bob Hutchison for his code for multiple
3619 front-ends (which made me realize that TBNL was already pretty
3620 close to a "real" web server) and the initial UTF-8 example.
3621 Thanks to <a href="http://netzhansa.blogspot.com/">Hans Hubner</a>
3622 for a lot of architectural and implementation enhancements for the
3623 1.0.0 release and also for transferring the documentation to sane
3624 XHTML. Thanks to John
3625 Foderaro's <a href="http://opensource.franz.com/aserve/index.html">AllegroServe</a>
3626 for inspiration. Thanks to <a href="http://www.htg1.de/">Uwe von
3627 Loh</a> for
3628 the <a href="http://www.htg1.de/hunchentoot/hunchentoot.html">Hunchentoot
3629 logo</a>.
3630
3631 <p>
3632 Hunchentoot originally used code
3633 from <a href="http://www.cliki.net/ACL-COMPAT">ACL-COMPAT</a>,
3634 specifically the chunking code from Jochen Schmidt. (This has been
3635 replaced by <a href="http://weitz.de/chunga/">Chunga</a>.) When I ported
3636 Hunchentoot to other Lisps than LispWorks, I stole code from
3637 ACL-COMPAT, <a href="http://www.cliki.net/kmrcl">KMRCL</a>,
3638 and <a href="http://www.cliki.net/trivial-sockets">trivial-sockets</a> for
3639 implementation-dependent stuff like sockets and MP. (This has been replaced by
3640 <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux
3641 Threads</a>
3642 and <a href="http://common-lisp.net/project/usocket/">usocket</a>.)
3643 </p>
3644 <p>
3645 Parts of this documentation were prepared
3646 with <a href="http://weitz.de/documentation-template/">DOCUMENTATION-TEMPLATE</a>,
3647 no animals were harmed.
3648 </p>
3649 </clix:chapter>
3650 <p>
3651 <a href='http://weitz.de/index.html'>BACK TO MY HOMEPAGE
3652 </a>
3653 </p>
3654 </clix:documentation>