1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <?xml-stylesheet type="text/xsl" href="clixdoc.xsl" ?>
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>
13 <a href="http://www.htg1.de/hunchentoot/hunchentoot.html"
14 title="Click here for the Hunchentoot logo"
16 <img align="top" width="93" height="45" border="0" src="hunchentoot.gif" />
18 HUNCHENTOOT - The Common Lisp web server formerly known as TBNL
22 <clix:chapter name='abstract' title='Abstract'>
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.
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>.
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
45 <a href="http://www.lispworks.com/documentation/HyperSpec/Front/index.htm">portable
46 Common Lisp</a>. It currently works "natively" with
47 <a href="http://www.lispworks.com/">LispWorks</a> (which is the
48 main development and testing platform), and additionally on all
49 Lisps which are supported by the compatibility
50 layers <a href="http://common-lisp.net/project/usocket/">usocket</a>
51 and <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux
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.
60 Hunchentoot is (or was) for example used by
61 <a href="http://quickhoney.com/">QuickHoney</a>,
62 <a href="http://postabon.com/">Postabon</a>,
63 <a href="http://www.city-farming.de/">City Farming</a>,
64 <a href="http://www.thoughtcrime.us/tp/">Trip Planner</a>,
65 <a href="http://www.jalat.com/">Jalat</a>,
66 <a href="http://heikestephan.de/">Heike Stephan</a>,
67 <a href="http://www.memetrics.com/">xOs</a>, and
68 <a href="http://syseng.nist.gov/moss">the</a>
69 <a href="http://syseng.nist.gov/se-interop">NIST</a>.
72 <font color="red">Download shortcut:</font>
73 <a href="http://weitz.de/files/hunchentoot.tar.gz">http://weitz.de/files/hunchentoot.tar.gz</a>.
78 <clix:chapter name='contents' title='Contents'></clix:chapter>
79 <clix:contents></clix:contents>
81 <clix:chapter name="install" title="Download and installation">
82 Hunchentoot depends on a couple of other Lisp libraries which you'll need
85 <li>Pierre R. Mai's <a href="http://www.cliki.net/md5">MD5</a>,</li>
86 <li>Kevin Rosenberg's <a href="http://www.cliki.net/cl-base64">CL-BASE64</a>,</li>
87 <li>Janis Dzerins' <a href="http://common-lisp.net/project/rfc2388/">RFC2388</a>,</li>
88 <li>Peter Seibel's <a href="http://weitz.de/cl-fad/">CL-FAD</a>,</li>
89 <li>Gary King's <a href="http://common-lisp.net/project/trivial-backtrace/">trivial-backtrace</a>,</li>
90 <li>Erik Huelsmann's <a href="http://common-lisp.net/project/usocket">usocket</a> (unless you're using LispWorks),</li>
91 <li>Greg Pfeil's <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux Threads</a> (unless you're using LispWorks),
94 David Lichteblau's <a href="http://common-lisp.net/project/cl-plus-ssl/">CL+SSL</a>
95 (unless you're using LispWorks),
98 and my own <a href="http://weitz.de/flexi-streams/">FLEXI-STREAMS</a> (0.12.0 or higher),
99 <a href="http://weitz.de/chunga/">Chunga</a> (1.0.0 or
100 higher), and <a href="http://weitz.de/cl-ppcre/">
102 <a href="http://weitz.de/cl-who/">CL-WHO</a> for the <a href="#start">example code</a>
103 and <a href="http://weitz.de/drakma/">Drakma</a> for the <a href="#testing">tests</a>).
107 Make sure to use the <em>newest</em> versions of all of these
108 libraries (which might themselves depend on other libraries) - try
109 the repository versions if you're in doubt. Note: You can compile
110 Hunchentoot without SSL support - and thus without the need to
111 have CL+SSL - if you add <code>:HUNCHENTOOT-NO-SSL</code> to
112 <a href="http://www.lispworks.com/documentation/HyperSpec/Body/v_featur.htm">
113 <code>*FEATURES*</code></a> <em>before</em> you compile it.
115 Hunchentoot will only work with Lisps where
116 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#character_code">character
118 all <a href="http://en.wikipedia.org/wiki/ISO_8859-1">Latin-1</a>
119 characters coincide with their
120 Unicode <a href="http://en.wikipedia.org/wiki/Code_point">code
121 points</a> (which is the case for all current implementations I
125 Hunchentoot itself together with this documentation can be
127 <a href="http://weitz.de/files/hunchentoot.tar.gz">http://weitz.de/files/hunchentoot.tar.gz</a>.
128 The current version is <clix:library-version/>.
131 The preferred method to compile and load Hunchentoot is via <a
132 href="http://www.cliki.net/asdf">ASDF</a>. If you want to avoid
133 downloading and installing all the dependencies manually, give
134 Zach Beane's excellent <a
135 href="http://www.quicklisp.org/">Quicklisp</a> system a try.
138 Hunchentoot and its dependencies can also be installed with <a
139 href="http://common-lisp.net/project/asdf-install/">ASDF-INSTALL</a>,
140 <a href="http://common-lisp.net/project/clbuild/">clbuild</a>,
141 or my own <a href="http://weitz.de/starter-pack/">Starter
142 Pack</a>. There's also a port for <a
143 href="http://www.gentoo.org/proj/en/lisp/common-lisp/index.xml">Gentoo
144 Linux</a> thanks to Matthew Kennedy.
147 The current development version of Hunchentoot can be found
148 at <a href="https://github.com/edicl/hunchentoot">https://github.com/edicl/hunchentoot</a>.
149 If you want to send patches, please fork the github repository and send pull requests.
152 Luís Oliveira maintains an
153 unofficial <a href="http://darcs.net/">darcs</a> repository of
155 <a href="http://common-lisp.net/~loliveira/ediware/">http://common-lisp.net/~loliveira/ediware/</a>.
158 <clix:subchapter name="port80" title="Running Hunchentoot on port 80">
160 Hunchentoot does not come with code to help with running it on a
161 privileged port (i.e. port 80 or 443) on Unix-like operating
162 systems. Modern Unix-like systems have specific, non-portable
163 ways to allow non-root users to listen to privileged ports, so
164 including such functionality in Hunchentoot was considered
165 unnecessary. Please refer to online resources for help. At the
166 time of this writing, the YAWS documentation has a <a
167 href="http://yaws.hyber.org/privbind.yaws">comprehensive
168 writeup</a> on the topic.
171 <clix:subchapter name="proxy" title="Hunchentoot behind a proxy">
173 If you're feeling unsecure about exposing Hunchentoot to the wild,
174 wild Internet or if your Lisp web application is part of a larger
175 website, you can hide it behind a
176 <a href="http://en.wikipedia.org/wiki/Proxy_server">proxy server</a>.
177 One approach that I have used several times is to employ Apache's
178 <a href="http://httpd.apache.org/docs/2.0/mod/mod_proxy.html">mod_proxy</a>
179 module with a configuration that looks like this:
181 <pre><a href="http://httpd.apache.org/docs/2.0/mod/mod_proxy.html#proxypass" class="noborder">ProxyPass</a> /hunchentoot http://127.0.0.1:3000/hunchentoot
182 <a href="http://httpd.apache.org/docs/2.0/mod/mod_proxy.html#proxypassreverse" class="noborder">ProxyPassReverse</a> /hunchentoot http://127.0.0.1:3000/hunchentoot</pre>
184 This will tunnel all requests where the URI path begins with
185 <code>"/hunchentoot"</code> to a (Hunchentoot) server listening on
186 port 3000 on the same machine.
190 <a href="http://www.red-bean.com/pipermail/lispweb/2006-October/001342.html">several
191 other</a> (more lightweight) web proxies that you could use
197 <clix:chapter name="mail" title="Support and mailing lists">
199 For questions, bug reports, feature requests, improvements, or
200 patches please use the
201 <a href="http://common-lisp.net/mailman/listinfo/tbnl-devel">tbnl-devel
202 mailing list</a>. If you want to be notified about future
203 releases subscribe to the
204 <a href="http://common-lisp.net/mailman/listinfo/tbnl-announce">tbnl-announce
205 mailing list</a>. These mailing lists were made available thanks
207 <a href="http://common-lisp.net/">common-lisp.net</a>. You can
208 <b>search</b> the devel mailing list
209 <a href="http://google.com/coop/cse?cx=002927904911724867201%3A0l5rif_cxj0">here</a>
210 (thanks to Tiarnán Ó Corráin).
212 If you want to send patches, please
213 <a href="http://weitz.de/patches.html">read this first</a>.
217 <clix:chapter name="start" title="Your own webserver (the easy teen-age New York version)">
218 Starting your own web server is pretty easy. Do something like this:
219 <pre>(hunchentoot:<a class="noborder" href="#start">start</a> (make-instance 'hunchentoot:<a class="noborder" href="#acceptor">easy-acceptor</a> :port 4242))</pre>
220 That's it. Now you should be able to enter the address
221 "<a href='http://127.0.0.1:4242/'><code>http://127.0.0.1:4242/</code></a>" in
222 your browser and see something, albeit nothing very interesting
226 By default, Hunchentoot serves the files from the
227 <code><i>www/</i></code> directory in its source tree. In the
228 distribution, that directory contains a HTML version of the
229 documentation as well as the error templates. The location of
230 the document root directory can be specified when creating a new
231 <clix:ref>ACCEPTOR</clix:ref> instance by the way of the
232 <clix:ref>ACCEPTOR-DOCUMENT-ROOT</clix:ref>. Likewise, the
233 location of the error template directory can be specified by the
234 <clix:ref>ACCEPTOR-ERROR-TEMPLATE-DIRECTORY</clix:ref>.
238 The <clix:ref>EASY-ACCEPTOR</clix:ref> class implements a
239 framework for developing web applications. Handlers are defined
240 using the <clix:ref>DEFINE-EASY-HANDLER</clix:ref> macro.
241 Request dispatching is performed according to the list of
242 dispatch functions in <clix:ref>*DISPATCH-TABLE*</clix:ref>.
243 Each of the functions on that list is called to determine
244 whether it wants to handle the request, provided as single
245 argument. If a dispatcher function wants to handle the request,
246 it returns another function to actually create the desired page.
250 <clix:ref>DEFINE-EASY-HANDLER</clix:ref> is accompanied by a set
251 of dispatcher creation functions that can be used to create
252 dispatchers for standard tasks. These are documented in the <a
253 class="noborder" href="#easy-handlers">subchapter on easy
258 Now be a bit more adventurous, try this
259 <pre>(hunchentoot:<a class="noborder" href="#define-easy-handler">define-easy-handler</a> (say-yo :uri "/yo") (name)
260 (setf (hunchentoot:<a class="noborder" href="#content-type*">content-type*</a>) "text/plain")
261 (format nil "Hey~@[ ~A~]!" name))</pre>
262 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
263 "<a href='http://127.0.0.1:4242/yo?name=Dude'><code>http://127.0.0.1:4242/yo?name=Dude</code></a>" .
267 Hunchentoot comes with a little example website which you can use
268 to see if it works and which should also demonstrate a couple of
269 the things you can do with Hunchentoot. To start the example
270 website, enter the following code into your listener:
272 <pre>(<a class="noborder" href="http://common-lisp.net/~mmommer/asdf-howto.shtml#sec11">asdf:oos</a> 'asdf:load-op :hunchentoot-test)</pre>
274 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.
278 <clix:chapter name="tutorials" title="Tutorials and add-ons">
280 Here are some Hunchentoot tutorials done by others:
284 <a href="http://www.adampetersen.se/articles/lispweb.htm">"Lisp for the Web"</a> by Adam Petersen.
287 Two <a href="http://myblog.rsynnott.com/2007/09/getting-started-with-hunchento.html">getting</a>
288 <a href="http://myblog.rsynnott.com/2007/10/doing-more-with-hunchentoot-cl-server.html">started</a>
289 articles by Robert Synnott.
292 <a href="http://newartisans.com/2007/11/running-common-lisp-behind-apache/">Running Common Lisp
293 behind Apache</a> by John Wiegley. (And there's a
294 <a href="http://newartisans.com/2007/11/a-quick-hunchentoot-primer/">second part</a>.)
297 A <a href="http://www.lispcast.com/index.php/2007/10/lispcast-writing-a-simple-reddit-clone-in-common-lisp/">"LispCast"</a>
298 by Eric Normand about writing a <a href="http://reddit.com/">Reddit</a> clone using
299 Hunchentoot. Apparently the first part of a
300 <a href="http://bc.tech.coop/blog/071028.html">series</a>.
303 A <a href="http://roeim.net/vetle/docs/cl-webapp-intro/">tutorial</a> about
304 implementing a blog in Common Lisp by Vetle Roeim.
307 A <a href="http://www.jalat.com/blogs/lisp?id=3">tutorial</a> for (an older version of)
308 Hunchentoot by Asbjørn Bjørnstad.
311 A <a href="http://www.frank-buss.de/lisp/tbnl.html">TBNL tutorial</a> from Frank Buss.
312 (Hunchentoot is not <a href="http://weitz.de/tbnl/">TBNL</a>, but the two are similar enough
313 to make the tutorial worthwhile.)
317 Clementson <a href="http://bc.tech.coop/blog/041105.html">explains</a>
318 how to set up Hunchentoot's
319 predecessor <a href="http://weitz.de/tbnl/">TBNL</a> with
321 also <a href="http://bc.tech.coop/blog/061013.html">http://bc.tech.coop/blog/061013.html</a>.
325 Check the dates of these tutorials! Many of them might not be a
326 perfect fit with the latest release of Hunchentoot as there have
327 been several changes to its API recently, especially in 2009.
328 Also, the fact that these tutorials are listed here doesn't
329 necessarily mean that I endorse them or think that they show
330 idiomatic Lisp code. You'll have to decide yourself if they're
331 helpful to you or not.
334 Here is some software which extends Hunchentoot or is based on it:
337 <li>Tomo Matsumoto's web application
338 framework <a href="http://web4r.org/en/">web4r</a>.
341 <a href="http://common-lisp.net/project/cl-weblocks/">Weblocks</a>
342 by Slava Akhmechet is a "continuations-based web framework" which is
343 based on Hunchentoot.
346 <a href="http://common-lisp.net/project/ht-ajax/ht-ajax.html">HT-AJAX</a> is
347 an <a href="http://en.wikipedia.org/wiki/Ajax_%28programming%29">Ajax</a>
348 framework for Hunchentoot by Ury Marshak.
352 href="http://martin-loetzsch.de/ht-simple-ajax/">HT-SIMPLE-AJAX</a>
353 is a simplified version of HT-AJAX.
357 <a href="http://common-lisp.net/pipermail/tbnl-devel/2007-May/001324.html">has
358 ported <a href="http://lemonodor.com/">John Wiseman</a>'s
359 <a href="http://www.lemonodor.com/archives/000128.html">Lisp
360 Server Pages</a> to Hunchentoot.</a>
363 <a href="http://site.znain.com/dl/lisp/hunchentoot-dir-lister/">hunchentoot-dir-lister</a>
364 is a directory listing addition for Hunchentoot by Dimitre Liotev.
368 <a href="http://cyrusharmon.org/blog/display?id=64">nuclblog</a> is a
369 <a href="http://en.wikipedia.org/wiki/Blog">blog</a> engine which uses Hunchentoot.
372 <a href="http://cyrusharmon.org/projects?project=hunchentoot-cgi">hunchentoot-cgi</a>
373 (also by Cyrus Harmon) provides
374 <a href="http://en.wikipedia.org/wiki/Common_Gateway_Interface">CGI</a>
375 handlers for Hunchentoot.
378 <a href="http://weitz.de/cl-webdav/">CL-WEBDAV</a> is a <a href="http://webdav.org/">WebDAV</a>
379 server based on Hunchentoot.
382 <a href="http://restas.lisper.ru/">RESTAS</a> is a web
383 framework based on Hunchentoot.
388 <clix:chapter name="reference" title="Function and variable reference">
390 <clix:subchapter name="acceptors" title="Acceptors">
392 If you want Hunchentoot to actually do something, you have to create and
393 <a href="#start">start</a> an <a href="#acceptor">acceptor</a>.
394 You can also run several acceptors in one image, each one
395 listening on a different different port.
397 <clix:class name='acceptor'>
399 To create a Hunchentoot webserver, you make an instance of
400 this class or one of its subclasses and use the generic
401 function <clix:ref>START</clix:ref> to start it (and
402 <clix:ref>STOP</clix:ref> to stop it). Use the
403 <code>:port</code> initarg if you don't want to listen
404 on the default http port 80. There are other initargs most
405 of which you probably won't need very often. They are
406 explained in detail in the docstrings of the slot
407 definitions for this class.
409 Unless you are in a Lisp without MP capabilities, you can
410 have several active instances of
411 <clix:ref>ACCEPTOR</clix:ref> (listening on different
412 ports) at the same time.
417 <clix:class name='ssl-acceptor'>
418 <clix:description>Create and <clix:ref>START</clix:ref> an instance of this class
419 (instead of <clix:ref>ACCEPTOR</clix:ref>) if you want an https server. There are two
420 required initargs, <code>:SSL-CERTIFICATE-FILE</code> and <code>:SSL-PRIVATEKEY-FILE</code>, for
421 pathname designators denoting the certificate file and the key file in
422 PEM format. On LispWorks, you can have both in one file in which case
423 the second initarg is optional. You can also use the
424 <code>:SSL-PRIVATEKEY-PASSWORD</code> initarg to provide a password
425 (as a string) for the key file (or <code>NIL</code>, the default, for
428 The default port for <clix:ref>SSL-ACCEPTOR</clix:ref> instances is 443 instead of 80
433 <clix:function generic='true' name='start'>
434 <clix:lambda-list>acceptor
436 <clix:returns>acceptor
438 <clix:description>Starts <clix:arg>acceptor</clix:arg> so that it begins accepting
439 connections. Returns the acceptor.
443 <clix:function generic='true' name='stop'>
444 <clix:lambda-list>acceptor &key soft</clix:lambda-list>
445 <clix:returns>acceptor
447 <clix:description>Stops the <clix:arg>acceptor</clix:arg> so
448 that it no longer accepts requests. If
449 <clix:arg>soft</clix:arg> is true, and there are any requests
450 in progress, wait until all requests are fully processed, but
451 meanwhile do not accept new requests. Note that
452 <clix:arg>soft</clix:arg> must not be set when calling
453 <clix:ref>stop</clix:ref> from within a request handler, as
458 <clix:special-variable name='*acceptor*'>
459 <clix:description>The current ACCEPTOR object in the context of a request.
461 </clix:special-variable>
463 <clix:function generic='true' name='acceptor-listen-backlog'>
464 <clix:lambda-list>listen-backlog
466 <clix:returns>number-of-pending-connections
469 Number of pending connections allowed in the listen socket
470 before the kernel rejects further incoming connections.
475 <clix:readers generic='true'>
476 <clix:listed-reader generic='true' name='acceptor-address'>
477 <clix:lambda-list>acceptor
479 <clix:returns>address
481 </clix:listed-reader>
483 <clix:listed-reader generic='true' name='acceptor-port'>
484 <clix:lambda-list>acceptor
488 </clix:listed-reader>
490 <clix:listed-reader generic='true' name='acceptor-read-timeout'>
491 <clix:lambda-list>acceptor
493 <clix:returns>read-timeout
495 </clix:listed-reader>
497 <clix:listed-reader generic='true' name='acceptor-ssl-certificate-file'>
498 <clix:lambda-list>ssl-acceptor
500 <clix:returns>ssl-certificate-file
502 </clix:listed-reader>
504 <clix:listed-reader generic='true' name='acceptor-ssl-privatekey-file'>
505 <clix:lambda-list>ssl-acceptor
507 <clix:returns>ssl-privatekey-file
509 </clix:listed-reader>
511 <clix:listed-reader generic='true' name='acceptor-ssl-privatekey-password'>
512 <clix:lambda-list>ssl-acceptor
514 <clix:returns>ssl-privatekey-password
516 </clix:listed-reader>
518 <clix:listed-reader generic='true' name='acceptor-write-timeout'>
519 <clix:lambda-list>acceptor
521 <clix:returns>write-timeout
523 </clix:listed-reader>
526 These are readers for various slots of <clix:ref>ACCEPTOR</clix:ref>
527 objects (and some of them obviously only make sense
528 for <clix:ref>SSL-ACCEPTOR</clix:ref> objects). See the docstrings of
529 these slots for more information and note that there are corresponding
530 initargs for all of them.
534 <clix:accessors generic='true'>
535 <clix:listed-accessor generic='true' name='acceptor-access-log-destination'>
536 <clix:lambda-list>acceptor
538 <clix:returns>(or pathname null)
540 </clix:listed-accessor>
542 <clix:listed-accessor generic='true' name='acceptor-document-root'>
543 <clix:lambda-list>acceptor
545 <clix:returns>(or pathname null)
547 </clix:listed-accessor>
549 <clix:listed-accessor generic='true' name='acceptor-error-template-directory'>
550 <clix:lambda-list>acceptor
552 <clix:returns>(or pathname null)
554 </clix:listed-accessor>
556 <clix:listed-accessor generic='true' name='acceptor-input-chunking-p'>
557 <clix:lambda-list>acceptor
559 <clix:returns>input-chunking-p
561 </clix:listed-accessor>
563 <clix:listed-accessor generic='true' name='acceptor-message-log-destination'>
564 <clix:lambda-list>acceptor
566 <clix:returns>(or pathname null)
568 </clix:listed-accessor>
570 <clix:listed-accessor generic='true' name='acceptor-name'>
571 <clix:lambda-list>acceptor
575 </clix:listed-accessor>
577 <clix:listed-accessor generic='true' name='acceptor-output-chunking-p'>
578 <clix:lambda-list>acceptor
580 <clix:returns>output-chunking-p
582 </clix:listed-accessor>
584 <clix:listed-accessor generic='true' name='acceptor-persistent-connections-p'>
585 <clix:lambda-list>acceptor
587 <clix:returns>persistent-connections-p
589 </clix:listed-accessor>
591 <clix:listed-accessor generic='true' name='acceptor-reply-class'>
592 <clix:lambda-list>acceptor
594 <clix:returns>reply-class
596 </clix:listed-accessor>
598 <clix:listed-accessor generic='true' name='acceptor-request-class'>
599 <clix:lambda-list>acceptor
601 <clix:returns>request-class
603 </clix:listed-accessor>
606 These are accessors for various slots of <clix:ref>ACCEPTOR</clix:ref>
607 objects. See the docstrings of these slots for more information and
608 note that there are corresponding initargs for all of them.
612 <clix:function generic='true' name='acceptor-ssl-p'>
613 <clix:lambda-list>acceptor
615 <clix:returns>generalized-boolean
617 <clix:description>Returns a true value if <clix:arg>acceptor</clix:arg> uses SSL
618 connections. The default is to unconditionally return <code>NIL</code> and
619 subclasses of <clix:ref>ACCEPTOR</clix:ref> must specialize this method to signal that
620 they're using secure connections - see the <clix:ref>SSL-ACCEPTOR</clix:ref> class.
624 <clix:special-variable name='*default-connection-timeout*'>
625 <clix:description>The default connection timeout used when an
626 acceptor is reading from and writing to a socket stream. Note that
627 some Lisps allow you to set different timeouts for reading and writing
628 and you can specify both values via initargs when you create
629 an <a href="#acceptors">acceptor</a>.
631 </clix:special-variable>
633 <clix:function generic='true' name='acceptor-remove-session'>
634 <clix:lambda-list>acceptor session
639 This function is called whenever a session in
640 <clix:ref>ACCEPTOR</clix:ref> is being destroyed because of
641 a session timout or an explicit
642 <clix:ref>REMOVE-SESSION</clix:ref> call.
648 <clix:subchapter name="acceptor-behaviour" title="Customizing acceptor behaviour">
650 If you want to modify what acceptors do, you should subclass
651 <clix:ref>ACCEPTOR</clix:ref> (or <clix:ref>SSL-ACCEPTOR</clix:ref>) and
652 specialize the generic functions that constitute their behaviour (see
653 example below). The life of an acceptor looks like this: It is started
654 with the function <clix:ref>START</clix:ref> which immediately calls
655 <clix:ref>START-LISTENING</clix:ref> and then applies the function
656 <clix:ref>EXECUTE-ACCEPTOR</clix:ref> to its <a
657 href="#taskmasters">taskmaster</a>. This function will eventually call
658 <clix:ref>ACCEPT-CONNECTIONS</clix:ref> which is responsible for setting
659 things up to wait for clients to connect. For each incoming connection
660 which comes in, <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref> is applied
661 to the taskmaster which will either call
662 <clix:ref>PROCESS-CONNECTION</clix:ref> directly, or will create a thread
663 to call it. <clix:ref>PROCESS-CONNECTION</clix:ref> calls
664 <clix:ref>INITIALIZE-CONNECTION-STREAM</clix:ref> before it does anything
665 else, then it selects and calls a function which handles the <a
666 href="#requests">request</a>, and finally it sends the <a
667 href="#replies">reply</a> to the client before it calls
668 <clix:ref>RESET-CONNECTION-STREAM</clix:ref>. If the connection is
669 persistent, this procedure is repeated (except for the intialization step)
670 in a loop until the connection is closed. The acceptor is stopped with
671 <clix:ref>STOP</clix:ref>.
674 If you just want to use the standard acceptors that come with
675 Hunchentoot, you don't need to know anything about the functions
676 listed in this section.
679 <clix:function generic='true' name='start-listening'>
680 <clix:lambda-list>acceptor
684 <clix:description>Sets up a listen socket for the given acceptor and
685 enables it to listen to incoming connections. This function is called
686 from the thread that starts the acceptor initially and may return
687 errors resulting from the listening operation (like 'address in use'
692 <clix:function generic='true' name='accept-connections'>
693 <clix:lambda-list>acceptor
697 <clix:description>In a loop, accepts a connection and hands it over
698 to the acceptor's taskmaster for processing using
699 <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref>. On LispWorks, this
700 function returns immediately, on other Lisps it returns only once the
701 acceptor has been stopped.
705 <clix:function generic='true' name='process-connection'>
706 <clix:lambda-list>acceptor socket
711 This function is called by the taskmaster when a new client
712 connection has been established. Its arguments are the
713 <clix:ref>ACCEPTOR</clix:ref> object and a LispWorks socket
714 handle or a usocket socket stream object in
715 <clix:arg>socket</clix:arg>. It reads the request headers,
716 sets up the <a href="#requests">request</a> and <a
717 href="#replies">reply</a> objects, and hands over to
718 <clix:ref>PROCESS-REQUEST</clix:ref> which calls
719 <clix:ref>HANDLE-REQUEST</clix:ref> to select and call a
720 handler for the request and sends its reply to the client.
721 This is done in a loop until the stream has to be closed or
722 until a connection timeout occurs. It is probably not a
723 good idea to re-implement this method until you really,
724 really know what you're doing.
728 <clix:function generic='true' name='initialize-connection-stream'>
729 <clix:lambda-list>acceptor stream
734 Can be used to modify the stream which is used to
735 communicate between client and server before the request is
736 read. The default method of <clix:ref>ACCEPTOR</clix:ref>
737 does nothing, but see for example the method defined for
738 <clix:ref>SSL-ACCEPTOR</clix:ref>. All methods of this
739 generic function <em>must</em> return the stream to use.
743 <clix:function generic='true' name='reset-connection-stream'>
744 <clix:lambda-list>acceptor stream
749 Resets the stream which is used to communicate
750 between client and server after one request has been served so that it
751 can be used to process the next request. This generic function is
752 called after a request has been processed and <em>must</em> return the
757 <clix:function name="acceptor-log-access" generic="true">
758 <clix:lambda-list>acceptor &key return-code</clix:lambda-list>
760 Function to call to log access to the acceptor. The
761 <clix:arg>return-code</clix:arg> keyword argument contains additional
762 information about the request to log. In addition, it can use the
763 standard request and reply accessor functions that are available to
764 handler functions to find out more information about the request.
768 <clix:function name="acceptor-log-message" generic="true">
769 <clix:lambda-list>acceptor log-level format-string &rest format-arguments</clix:lambda-list>
771 Function to call to log messages by the <clix:arg>acceptor</clix:arg>. It must accept
772 a severity level for the message, which will be one of :ERROR, :INFO,
773 or :WARNING, a format string and an arbitary number of formatting
778 <clix:function name="acceptor-status-message" generic="true">
779 <clix:lambda-list>acceptor http-return-code &key &allow-other-keys</clix:lambda-list>
781 This function is called when a request's handler has been
782 called but failed to provide content to send back to the
783 client. It converts the
784 <clix:arg>HTTP-STATUS-CODE</clix:arg> to some request
785 contents, typically a human readable description of the
786 status code to be displayed to the user.
788 If an ERROR-TEMPLATE-DIRECTORY is set in the current
789 acceptor and the directory contains a file corresponding to
790 HTTP-STATUS-CODE named <code>.html, that file is sent
791 to the client after variable substitution. Variables are
792 referenced by ${<variable-name>}.
794 Additional keyword arguments may be provided which are made
795 available to the templating logic as substitution variables.
796 These variables can be interpolated into error message
797 templates in, which contains the current URL relative to the
798 server and without GET parameters.
800 In addition to the variables corresponding to keyword
801 arguments, the script-name, lisp-implementation-type,
802 lisp-implementation-version and hunchentoot-version
803 variables are available.
808 <clix:subchapter name="subclassing-acceptors"
809 title="An example of how to subclass ACCEPTOR">
811 This example shows how to subclass <clix:ref>ACCEPTOR</clix:ref> in order to
812 provide Hunchentoot with basic virtual host support.  It assumes
813 Hunchentoot is sitting behind an Internet-facing reverse-proxy web server
814 that maps the host (or domain) part of incoming HTTP requests to unique
817 <pre>(asdf:load-system "hunchentoot")
818 (asdf:load-system "drakma")
820 ;;; Subclass ACCEPTOR
821 (defclass vhost (tbnl:acceptor)
825 :accessor dispatch-table
826 :documentation "List of dispatch functions"))
828 (:default-initargs ; default-initargs must be used
829 :address "127.0.0.1")) ; because ACCEPTOR uses it
831 ;;; Specialise ACCEPTOR-DISPATCH-REQUEST for VHOSTs
832 (defmethod tbnl:acceptor-dispatch-request ((vhost vhost) request)
833 ;; try REQUEST on each dispatcher in turn
834 (mapc (lambda (dispatcher)
835 (let ((handler (funcall dispatcher request)))
836 (when handler ; Handler found. FUNCALL it and return result
837 (return-from tbnl:acceptor-dispatch-request (funcall handler)))))
838 (dispatch-table vhost))
841 ;;; ======================================================================
842 ;;; Now all we need to do is test it
844 ;;; Instantiate VHOSTs
845 (defvar vhost1 (make-instance 'vhost :port 50001))
846 (defvar vhost2 (make-instance 'vhost :port 50002))
848 ;;; Populate each dispatch table
850 (tbnl:create-prefix-dispatcher "/foo" 'foo1)
851 (dispatch-table vhost1))
853 (tbnl:create-prefix-dispatcher "/foo" 'foo2)
854 (dispatch-table vhost2))
857 (defun foo1 () "Hello")
858 (defun foo2 () "Goodbye")
864 ;;; Make some requests
865 (drakma:http-request "http://127.0.0.1:50001/foo")
867 ;;; 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/)"
871 ;;; ((:CONTENT-LENGTH . "5") (:DATE . "Fri, 08 Jun 2012 14:30:39 GMT")
872 ;;; (:SERVER . "Hunchentoot 1.2.3") (:CONNECTION . "Close")
873 ;;; (:CONTENT-TYPE . "text/html; charset=utf-8"))
874 ;;; #<PURI:URI http://127.0.0.1:50001/foo>
875 ;;; #<FLEXI-STREAMS:FLEXI-IO-STREAM {CA90059}>
878 (drakma:http-request "http://127.0.0.1:50002/foo")
880 ;;; 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/)"
884 ;;; ((:CONTENT-LENGTH . "7") (:DATE . "Fri, 08 Jun 2012 14:30:47 GMT")
885 ;;; (:SERVER . "Hunchentoot 1.2.3") (:CONNECTION . "Close")
886 ;;; (:CONTENT-TYPE . "text/html; charset=utf-8"))
887 ;;; #<PURI:URI http://127.0.0.1:50002/foo>
888 ;;; #<FLEXI-STREAMS:FLEXI-IO-STREAM {CAE8059}>
892 How to make each VHOST write to separate access log streams (or files) is
893 left as an exercise to the reader.
897 <clix:subchapter name="taskmasters" title="Taskmasters">
898 As a "normal" Hunchentoot user, you can completely ignore
899 taskmasters and skip this section. But if you're still reading,
900 here are the dirty details: Each <a
901 href="#acceptors">acceptor</a> has a taskmaster associated with
902 it at creation time. It is the taskmaster's job to distribute
903 the work of accepting and handling incoming connections. The
904 acceptor calls the taskmaster if appropriate and the taskmaster
905 calls back into the acceptor. This is done using the generic
906 functions described in this and the <a
907 href="#acceptor-behaviour">previous</a> section. Hunchentoot
908 comes with two standard taskmaster implementations - one (which
909 is the default used on multi-threaded Lisps) which starts a new
910 thread for each incoming connection and one which handles all
911 requests sequentially. It should for example be relatively
912 straightforward to create a taskmaster which allocates threads
913 from a fixed pool instead of creating a new one for each
917 You can control the resources consumed by a threaded taskmaster via
918 two initargs. <code>:max-thread-count</code> lets you set the maximum
919 number of request threads that can be processes simultaneously. If
920 this is <code>nil</code>, the is no thread limit imposed.
922 <code>:max-accept-count</code> lets you set the maximum number of requests
923 that can be outstanding (i.e. being processed or queued for processing).
925 If <code>:max-thread-count</code> is supplied and <code>:max-accept-count</code>
926 is <code>NIL</code>, then a <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>
927 error will be generated if there are more than the max-thread-count
928 threads processing requests. If both <code>:max-thread-count</code>
929 and <code>:max-accept-count</code> are supplied, then max-thread-count
930 must be less than max-accept-count; if more than max-thread-count
931 requests are being processed, then requests up to max-accept-count
932 will be queued until a thread becomes available. If more than
933 max-accept-count requests are outstanding, then a <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>
934 error will be generated.
936 In a load-balanced environment with multiple Hunchentoot servers, it's
937 reasonable to provide <code>:max-thread-count</code> but leave
938 <code>:max-accept-count</code> null. This will immediately result
939 in <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref> when one server is
940 out of resources, so the load balancer can try to find another server.
942 In an environment with a single Hunchentoot server, it's reasonable
943 to provide both <code>:max-thread-count</code> and a somewhat larger value
944 for <code>:max-accept-count</code>. This will cause a server that's almost
945 out of resources to wait a bit; if the server is completely out of resources,
946 then the reply will be <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>.
947 The default for these values is 100 and 120, respectively.
951 If you want to implement your own taskmasters, you should subclass
952 <clix:ref>TASKMASTER</clix:ref> or one of its subclasses,
953 <clix:ref>SINGLE-THREADED-TASKMASTER</clix:ref> or
954 <clix:ref>ONE-THREAD-PER-CONNECTION-TASKMASTER</clix:ref>, and
955 specialize the generic functions in this section.
958 <clix:class name='taskmaster'>
960 An instance of this class is responsible for distributing
961 the work of handling requests for its acceptor. This is an
962 "abstract" class in the sense that usually only instances of
963 subclasses of <clix:ref>TASKMASTER</clix:ref> will be used.
967 <clix:class name='one-thread-per-connection-taskmaster'>
969 A taskmaster that starts one thread for listening to
970 incoming requests and one thread for each incoming
973 This is the default taskmaster implementation for multi-threaded Lisp
979 <clix:class name='single-threaded-taskmaster'>
981 A taskmaster that runs synchronously in the
982 thread where the <clix:ref>START</clix:ref> function was invoked (or
983 in the case of LispWorks in the thread started
984 by <a href="http://www.lispworks.com/documentation/lw51/LWRM/html/lwref-61.htm#marker-910861"><code>COMM:START-UP-SERVER</code></a>).
985 This is the simplest possible taskmaster implementation in that its
986 methods do nothing but calling their acceptor "sister"
987 methods - <clix:ref>EXECUTE-ACCEPTOR</clix:ref> calls <clix:ref>ACCEPT-CONNECTIONS</clix:ref>,
988 <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref> calls <clix:ref>PROCESS-CONNECTION</clix:ref>.
992 <clix:class name='multi-threaded-taskmaster'>
994 This is an abstract class for taskmasters that use multiple threads;
995 it is not a concrete class and you should not instantiate it with
996 <code>MAKE-INSTANCE</code>.
997 Instead, you should instantiate its subclass
998 <clix:ref>ONE-THREAD-PER-CONNECTION-TASKMASTER</clix:ref> described above.
999 <clix:ref>MULTI-THREADED-TASKMASTER</clix:ref>
1000 is intended to be inherited from by extensions to Hunchentoot,
1001 such as <a href="http://common-lisp.net/project/qitab/">quux-hunchentoot</a>'s
1002 <code>THREAD-POOLING-TASKMASTER</code>,
1003 though at the moment, doing so only inherits one slot and one method,
1004 on <clix:ref>EXECUTE-ACCEPTOR</clix:ref>,
1005 to have it start a new thread for the acceptor,
1006 then saved in said slot.
1010 <clix:function generic='true' name='execute-acceptor'>
1011 <clix:lambda-list>taskmaster
1013 <clix:returns>result
1015 <clix:description>This is a callback called by the acceptor once it
1016 has performed all initial processing to start listening for incoming
1017 connections (see <clix:ref>START-LISTENING</clix:ref>). It usually calls the
1018 <clix:ref>ACCEPT-CONNECTIONS</clix:ref> method of the acceptor, but depending on the
1019 taskmaster instance the method might be called from a new thread.
1023 <clix:function generic='true' name='handle-incoming-connection'>
1024 <clix:lambda-list>taskmaster socket
1026 <clix:returns>result
1029 This function is called by the acceptor to start
1030 processing of requests on a new incoming connection. <clix:arg>socket</clix:arg> is the
1031 usocket instance that represents the new connection (or a socket
1032 handle on LispWorks). The taskmaster starts processing requests on
1033 the incoming connection by calling the <clix:ref>PROCESS-CONNECTION</clix:ref>
1034 method of the acceptor instance. The <clix:arg>socket</clix:arg> argument is passed to
1035 <clix:ref>PROCESS-CONNECTION</clix:ref> as an argument.
1037 If the taskmaster is a multi-threaded taskmaster, <clix:ref>HANDLE-INCOMING-THREAD</clix:ref>
1038 will call <clix:ref>CREATE-REQUEST-HANDLER-THREAD</clix:ref>, which will call
1039 <clix:ref>PROCESS-CONNECTION</clix:ref> in a new thread.
1040 <clix:ref>HANDLE-INCOMING-THREAD</clix:ref> might issue a
1041 <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref> error
1042 if there are too many request threads or it might block waiting for a
1043 request thread to finish.
1047 <clix:function generic='true' name='start-thread'>
1048 <clix:lambda-list>taskmaster thunk &key
1050 <clix:returns>thread
1052 <clix:description>This function is a callback that
1053 starts a new thread that will call the given <clix:arg>thunk</clix:arg>
1054 in the context of the proper <clix:arg>taskmaster</clix:arg>,
1055 with appropriate context-dependent keyword arguments.
1056 <clix:ref>ONE-THREAD-PER-CONNECTION-TASKMASTER</clix:ref> uses it in
1057 <clix:ref>EXECUTE-ACCEPTOR</clix:ref>
1058 and <clix:ref>CREATE-REQUEST-HANDLER-THREAD</clix:ref>,
1059 but specialized taskmasters may define more functions that use it.
1060 By default, it just creates a thread calling the thunk
1061 with a specified <clix:arg>name</clix:arg> keyword argument.
1062 Specialized taskmasters may wrap special bindings and condition handlers
1063 around the thunk call, register the thread in a management table, etc.
1067 <clix:function generic='true' name='create-request-handler-thread'>
1068 <clix:lambda-list>taskmaster socket
1070 <clix:returns>thread
1072 <clix:description>This function is called by <clix:ref>HANDLE-INCOMING-THREAD</clix:ref>
1073 to create a new thread which calls <clix:ref>PROCESS-CONNECTION</clix:ref>.
1074 If you specialize this function, you must be careful to have the thread
1075 call <clix:ref>DECREMENT-TASKMASTER-REQUEST-COUNT</clix:ref> before
1076 it exits. A typical method will look like this:
1078 <pre>(defmethod create-request-handler-thread ((taskmaster monitor-taskmaster) socket)
1081 (with-monitor-error-handlers
1083 (with-monitor-variable-bindings
1084 (process-connection (taskmaster-acceptor taskmaster) socket))
1085 (decrement-taskmaster-request-count taskmaster))))))</pre>
1096 <clix:function generic='true' name='shutdown'>
1097 <clix:lambda-list>taskmaster
1099 <clix:returns>taskmaster
1101 <clix:description>Shuts down the taskmaster, i.e. frees all resources
1102 that were set up by it. For example, a multi-threaded taskmaster
1103 might terminate all threads that are currently associated with it.
1104 This function is called by the acceptor's <clix:ref>STOP</clix:ref> method.
1108 <clix:accessor generic='true' name='taskmaster-acceptor'>
1109 <clix:lambda-list>taskmaster
1111 <clix:returns>acceptor
1114 This is an accessor for the slot of a <clix:ref>TASKMASTER</clix:ref>
1115 object that links back to the <a href="#acceptors">acceptor</a> it is
1122 <clix:subchapter name="request-dispatch" title="Request dispatch and handling">
1124 The main job of <clix:ref>HANDLE-REQUEST</clix:ref> is to select
1125 and call a function which handles the request, i.e. which looks
1126 at the data the client has sent and prepares an appropriate
1127 reply to send back. This is by default implemented as follows:
1129 The ACCEPTOR class defines a
1130 <clix:ref>ACCEPTOR-DISPATCH-REQUEST</clix:ref> generic
1131 function which is used to actually dispatch the request. This
1132 function is called by the default method of
1133 <clix:ref>HANDLE-REQUEST</clix:ref>. Each
1134 <clix:ref>ACCEPTOR-DISPATCH-REQUEST</clix:ref> method looks at
1135 the request object and depending on its contents decides to
1136 either handle the request or call the next method.
1139 In order to dispatch a request, Hunchentoot calls the
1140 <clix:ref>ACCEPTOR-DISPATCH-REQUEST</clix:ref> generic
1141 functions. The method for <clix:ref>ACCEPTOR</clix:ref> tries
1142 to serve a static file relative to it's
1143 <clix:ref>ACCEPTOR-DOCUMENT-ROOT</clix:ref>. Application
1144 specific acceptor subclasses will typically perform URL
1145 parsing and dispatching according to the policy that is
1149 The default method of <clix:ref>HANDLE-REQUEST</clix:ref> sets
1150 up <a href="#logging">standard logging and error handling</a>
1151 before it calls the acceptor's request dispatcher.
1154 Request handlers do their work by modifying
1155 the <a href="#replies">reply object</a> if necessary and by eventually
1156 returning the response body in the form of a string or a binary
1157 sequence. As an alternative, they can also
1158 call <clix:ref>SEND-HEADERS</clix:ref> and write directly to a stream.
1162 <clix:subchapter name="easy-handlers" title="Using the easy-handler framework">
1164 The <clix:ref>EASY-ACCEPTOR</clix:ref> class defines a method
1165 for <clix:ref>ACCEPTOR-DISPATCH-REQUEST</clix:ref> that walks
1166 through the list <clix:ref>*DISPATCH-TABLE*</clix:ref> which
1167 consists of <em>dispatch functions</em>. Each of these
1168 functions accepts the request object as its only argument and
1169 either returns a request handler to handle the request or
1170 <code>NIL</code> which means that the next dispatcher in the
1171 list will be tried. If all dispatch functions return
1172 <code>NIL</code>, the next
1173 <clix:ref>ACCEPTOR-DISPATCH-REQUEST</clix:ref> will be called.
1176 All functions and variables in this section are related to the
1177 easy request dispatch mechanism and are meaningless if you're
1178 using your own request dispatcher.
1181 <clix:class name='easy-acceptor'>
1183 This class defines no additional slots with respect to
1184 <clix:ref>ACCEPTOR</clix:ref>. It only serves as an
1185 additional type for dispatching calls to
1186 <clix:ref>ACCEPTOR-DISPATCH-REQUEST</clix:ref>. In order to
1187 use the easy handler framework, acceptors of this class or
1188 one of its subclasses must be used.
1192 <clix:class name='easy-ssl-acceptor'>
1194 This class mixes the <clix:ref>SSL-ACCEPTOR</clix:ref> and
1195 the <clix:ref>EASY-ACCEPTOR</clix:ref> classes. It is used
1196 when both ssl and the easy handler framework are required.
1200 <clix:special-variable name='*dispatch-table*'>
1202 A global list of dispatch functions. The initial value is a
1203 list consisting of the symbol
1204 <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>.
1206 </clix:special-variable>
1208 <clix:function name="create-prefix-dispatcher">
1209 <clix:lambda-list>prefix handler</clix:lambda-list>
1210 <clix:returns>dispatch-fn</clix:returns>
1212 A convenience function which will return a dispatcher that
1213 returns <clix:arg>handler</clix:arg> whenever the path part of
1214 the request URI starts with the
1215 string <clix:arg>prefix</clix:arg>.
1219 <clix:function name="create-regex-dispatcher">
1220 <clix:lambda-list>regex handler</clix:lambda-list>
1221 <clix:returns>dispatch-fn</clix:returns>
1223 A convenience function which will return a dispatcher that
1224 returns <clix:arg>handler</clix:arg> whenever the path part of
1225 the request URI matches
1226 the <a href="http://weitz.de/cl-ppcre/">CL-PPCRE</a> regular
1227 expression <clix:arg>regex</clix:arg> (which can be a string, an
1228 s-expression, or a scanner).
1232 <clix:function name="create-folder-dispatcher-and-handler">
1233 <clix:lambda-list>uri-prefix base-path <clix:lkw>optional</clix:lkw> content-type</clix:lambda-list>
1234 <clix:returns>dispatch-fn</clix:returns>
1236 Creates and returns a dispatch function which will dispatch to
1237 a handler function which emits the file relative
1238 to <clix:arg>base-path</clix:arg> that is denoted by the URI of
1239 the request relative
1240 to <clix:arg>uri-prefix</clix:arg>. <clix:arg>uri-prefix</clix:arg>
1241 must be a string ending with a
1242 slash, <clix:arg>base-path</clix:arg> must be a pathname
1243 designator for an existing directory.
1244 Uses <clix:ref>HANDLE-STATIC-FILE</clix:ref> internally.
1246 If <clix:arg>content-type</clix:arg> is <em>not</em>
1247 <code>NIL</code>, it will be used as a the content type for
1248 all files in the folder. Otherwise (which is the default)
1249 the content type of each file will be
1250 determined <a href="#handle-static-file">as usual</a>.
1255 <clix:function name='create-static-file-dispatcher-and-handler'>
1256 <clix:lambda-list>uri path
1258 </clix:lkw> content-type
1260 <clix:returns>result
1263 Creates and returns a request dispatch function which will
1264 dispatch to a handler function which emits the file denoted
1265 by the pathname designator PATH with content type
1266 CONTENT-TYPE if the SCRIPT-NAME of the request matches the
1267 string URI. If CONTENT-TYPE is NIL, tries to determine the
1268 content type via the file's suffix.
1272 <clix:function macro="true" name="define-easy-handler">
1273 <clix:lambda-list>description lambda-list [[declaration* | documentation]] form*</clix:lambda-list>
1275 Defines a handler as if
1276 by <a href="http://www.lispworks.com/documentation/HyperSpec/Body/m_defun.htm">
1277 <code>DEFUN</code></a> and optionally registers it with a
1278 URI so that it will be found
1279 by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>.
1281 <clix:arg>description</clix:arg> is either a
1282 symbol <clix:arg>name</clix:arg> or a list matching the
1283 <a href="http://www.lispworks.com/documentation/HyperSpec/Body/03_de.htm">destructuring
1286 <pre>(name &key uri acceptor-names default-parameter-type default-request-type).</pre>
1287 <clix:arg>lambda-list</clix:arg> is a list the elements of which
1288 are either a symbol <clix:arg>var</clix:arg> or a list matching
1289 the destructuring lambda list
1290 <pre>(var &key real-name parameter-type init-form request-type).</pre>
1291 The resulting handler will be a Lisp function with the
1292 name <clix:arg>name</clix:arg> and keyword parameters named by
1293 the <clix:arg>var</clix:arg> symbols.
1294 Each <clix:arg>var</clix:arg> will be bound to the value of the
1295 GET or POST parameter called <clix:arg>real-name</clix:arg> (a
1296 string) before the body of the function is executed.
1297 If <clix:arg>real-name</clix:arg> is not provided, it will be
1299 by <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_stg_up.htm#string-downcase">downcasing</a>
1300 the symbol name of <clix:arg>var</clix:arg>.
1302 If <clix:arg>uri</clix:arg> (which is evaluated) is provided,
1303 then it must be a string or
1304 a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_f.htm#function_designator">function
1305 designator</a> for a unary function. In this case, the
1306 handler will be returned
1307 by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>,
1308 if <clix:arg>uri</clix:arg> is a string and
1309 the <a href="#script-name">script name</a> of the current
1310 request is <clix:arg>uri</clix:arg>, or
1311 if <clix:arg>uri</clix:arg> designates a function and applying
1313 the <a href="#*request*">current <code>REQUEST</code>
1314 object</a> returns a true value.
1317 <clix:arg>acceptor-names</clix:arg> (which is evaluated) can be a
1318 list of symbols which means that the handler will only be
1319 returned by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref> in
1320 acceptors which have one of these names
1321 (see <clix:ref>ACCEPTOR-NAME</clix:ref>). <clix:arg>acceptor-names</clix:arg> can also be the
1322 symbol <code>T</code> which means that the handler will be
1323 returned by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>
1324 in <em>every</em> acceptor.
1327 Whether the GET or POST parameter (or both) will be taken into
1328 consideration, depends on <clix:arg>request-type</clix:arg>
1330 be <code>:GET</code>, <code>:POST</code>, <code>:BOTH</code>,
1331 or <code>NIL</code>. In the last case, the value of
1332 <clix:arg>default-request-type</clix:arg> (the default of which
1333 is <code>:BOTH</code>) will be used.
1336 The value of <clix:arg>var</clix:arg> will usually be a string
1337 (unless it resulted from a <a href="#upload">file upload</a>
1338 in which case it won't be converted at all), but
1339 if <clix:arg>parameter-type</clix:arg> (which is evaluated) is
1340 provided, the string will be converted to another Lisp type by
1341 the following rules:
1344 If the corresponding GET or POST parameter wasn't provided by
1345 the client, <clix:arg>var</clix:arg>'s value will
1346 be <code>NIL</code>. If <clix:arg>parameter-type</clix:arg>
1347 is <code>'STRING</code>,
1348 <clix:arg>var</clix:arg>'s value remains as is.
1349 If <clix:arg>parameter-type</clix:arg> is <code>'INTEGER</code>
1350 and the parameter string consists solely of decimal
1351 digits, <clix:arg>var</clix:arg>'s value will be the
1352 corresponding integer, otherwise <code>NIL</code>.
1353 If <clix:arg>parameter-type</clix:arg> is
1354 <code>'KEYWORD</code>, <clix:arg>var</clix:arg>'s value will be
1355 the keyword obtained
1356 by <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_intern.htm">interning</a>
1357 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_stg_up.htm#string-upcase">upcased</a>
1358 parameter string into
1359 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/11_abc.htm">keyword
1360 package</a>. If <clix:arg>parameter-type</clix:arg>
1361 is <code>'CHARACTER</code> and the parameter string is of
1362 length one, <clix:arg>var</clix:arg>'s value will be the single
1363 character of this string, otherwise <code>NIL</code>.
1364 If <clix:arg>parameter-type</clix:arg>
1365 is <code>'BOOLEAN</code>, <clix:arg>var</clix:arg>'s value will
1366 always be <code>T</code> (unless it is <code>NIL</code> by the
1367 first rule above, of course).
1368 If <clix:arg>parameter-type</clix:arg> is any other atom, it is
1370 a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_f.htm#function_designator">function
1371 designator</a> for a unary function which will be called to
1372 convert the string to something else.
1375 Those were the rules for <em>simple</em> parameter types, but
1376 <clix:arg>parameter-type</clix:arg> can also be a list starting
1377 with one of the symbols
1378 <code>LIST</code>, <code>ARRAY</code>,
1379 or <code>HASH-TABLE</code>. The second value of the list must
1380 always be a simple parameter type as in the last paragraph -
1381 we'll call it the <em>inner type</em> below.
1384 In the case of <code>'LIST</code>, all GET/POST parameters
1385 called <clix:arg>real-name</clix:arg> will be collected,
1386 converted to the inner type as by the rules above, and
1387 assembled into a list which will be the value of
1388 <clix:arg>var</clix:arg>.
1391 In the case of <code>'ARRAY</code>, all GET/POST parameters
1392 which have a name like the result of
1394 <pre>(format nil "~A[~A]" real-name n)</pre>
1395 where <clix:arg>n</clix:arg> is a non-negative integer, will be
1396 assembled into an array where the <clix:arg>n</clix:arg>th element
1397 will be set accordingly, after conversion to the inner type.
1398 The array, which will become the value
1399 of <clix:arg>var</clix:arg>, will be big enough to hold all
1400 matching parameters, but not bigger. Array elements not set as
1401 described above will be <code>NIL</code>. Note
1402 that <code>VAR</code> will always be bound to an array, which
1403 may be empty, so it will never be <code>NIL</code>, even if no
1404 appropriate GET/POST parameters are found.
1406 The full form of a <code>'HASH-TABLE</code> parameter type is
1408 <pre>(hash-table inner-type key-type test-function)</pre>
1409 but <clix:arg>key-type</clix:arg>
1410 and <clix:arg>test-function</clix:arg> can be left out in which
1411 case they default to <code>'STRING</code>
1412 and <code>'EQUAL</code>, respectively. For this parameter type,
1413 all GET/POST parameters which have a name like the result of
1414 <pre>(format nil "~A{~A}" real-name key)</pre>
1415 (where <clix:arg>key</clix:arg> is a string that doesn't contain
1416 curly brackets) will become the values (after conversion
1417 to <clix:arg>inner-type</clix:arg>) of a hash table with test
1418 function <clix:arg>test-function</clix:arg>
1419 where <clix:arg>key</clix:arg> (after conversion
1420 to <clix:arg>key-type</clix:arg>) will be the corresponding key.
1421 Note that <clix:arg>var</clix:arg> will always be bound to a hash
1422 table, which may be empty, so it will never be <code>NIL</code>,
1423 even if no appropriate GET/POST parameters are found.
1425 To make matters even more complicated, the three compound
1426 parameter types also have an abbreviated form - just one of
1427 the symbols <code>LIST</code>, <code>ARRAY</code>,
1428 or <code>HASH-TABLE</code>. In this case, the inner type will
1429 default to <code>'STRING</code>.
1432 If <clix:arg>parameter-type</clix:arg> is not provided
1433 or <code>NIL</code>, <clix:arg>default-parameter-type</clix:arg>
1434 (the default of which is <code>'STRING</code>) will be used
1438 If the result of the computations above would be
1439 that <clix:arg>var</clix:arg> would be bound
1440 to <code>NIL</code>, then <clix:arg>init-form</clix:arg> (if
1441 provided) will be evaluated instead,
1442 and <clix:arg>var</clix:arg> will be bound to the result of this
1446 Handlers built with this macro are constructed in such a way
1447 that the resulting Lisp function is useful even outside of
1448 Hunchentoot. Specifically, all the parameter computations
1449 above will only happen if <clix:ref>*REQUEST*</clix:ref> is
1450 bound, i.e. if we're within a Hunchentoot request.
1451 Otherwise, <clix:arg>var</clix:arg> will always be bound to the
1452 result of evaluating <clix:arg>init-form</clix:arg> unless a
1453 corresponding keyword argument is provided.
1456 The <a href="#example">example code</a> that comes with
1457 Hunchentoot contains an example which demonstrates some of the
1458 features of <clix:ref>DEFINE-EASY-HANDLER</clix:ref>.
1463 <clix:function name='dispatch-easy-handlers'>
1464 <clix:lambda-list>request
1466 <clix:returns>result
1468 <clix:description>This is a dispatcher which returns the appropriate handler
1469 defined with <clix:ref>DEFINE-EASY-HANDLER</clix:ref>, if there is one.
1475 <clix:subchapter name="requests" title="Request objects">
1477 For each incoming request, the <a href="#acceptors">acceptor</a> (in
1478 <clix:ref>PROCESS-CONNECTION</clix:ref>) creates a
1479 <clix:ref>REQUEST</clix:ref> object and makes it available to <a
1480 href="#request-dispatch">handlers</a> via the special variable
1481 <clix:ref>*REQUEST*</clix:ref>. This object contains all relevant
1482 information about the request and this section collects the functions
1483 which can be used to query such an object. In all function where
1484 <clix:arg>request</clix:arg> is an optional or keyword parameter, the
1485 default is <clix:ref>*REQUEST*</clix:ref>.
1488 If you need more fine-grained control over the behaviour of request
1489 objects, you can subclass <clix:ref>REQUEST</clix:ref> and initialize
1490 the <a href="#acceptor-request-class"><code>REQUEST-CLASS</code></a>
1491 slot of the <clix:ref>ACCEPTOR</clix:ref> class accordingly. The
1492 acceptor will generate request objects of the class named by this
1496 <clix:class name='request'>
1498 Objects of this class hold all the information
1499 about an incoming request. They are created automatically by
1500 acceptors and can be accessed by the
1501 corresponding <a href="#request-dispatch">handler</a>.
1503 You should not mess with the slots of these objects directly, but you
1504 can subclass <clix:ref>REQUEST</clix:ref> in order to implement your
1506 the <a href="#acceptor-request-class"><code>REQUEST-CLASS</code></a>
1507 slot of the <clix:ref>ACCEPTOR</clix:ref> class.
1511 <clix:special-variable name='*request*'>
1512 <clix:description>The current REQUEST object while in the context of a request.
1514 </clix:special-variable>
1516 <clix:function name='real-remote-addr'>
1521 <clix:returns>string{, list}
1524 Returns the '<code>X-Forwarded-For</code>' incoming http header as the
1525 second value in the form of a list of IP addresses and the first
1526 element of this list as the first value if this header exists.
1527 Otherwise returns the value of <clix:ref>REMOTE-ADDR</clix:ref> as the only value.
1531 <clix:function name='parameter'>
1532 <clix:lambda-list>name
1536 <clix:returns>string
1539 Returns the GET or the POST parameter with name
1540 <clix:arg>name</clix:arg> (a string) - or <code>NIL</code>
1541 if there is none. If both a GET and a POST parameter with
1542 the same name exist the GET parameter is returned. Search
1543 is case-sensitive. See also
1544 <clix:ref>GET-PARAMETER</clix:ref> and
1545 <clix:ref>POST-PARAMETER</clix:ref>.
1549 <clix:function name="get-parameter">
1550 <clix:lambda-list>name <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1551 <clix:returns>string</clix:returns>
1553 Returns the value of the GET parameter (as provided via the
1554 request URI) named by the string <clix:arg>name</clix:arg> as a
1555 string (or <code>NIL</code> if there ain't no GET parameter
1556 with this name). Note that only the first value will be
1557 returned if the client provided more than one GET parameter
1558 with the name <clix:arg>name</clix:arg>. See
1559 also <clix:ref>GET-PARAMETERS*</clix:ref>.
1563 <clix:function name="post-parameter">
1564 <clix:lambda-list>name <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1565 <clix:returns>string</clix:returns>
1567 Returns the value of the POST parameter (as provided in the
1568 request's body) named by the
1569 string <clix:arg>name</clix:arg>. Note that only the first value
1570 will be returned if the client provided more than one POST
1571 parameter with the name <clix:arg>name</clix:arg>. This value
1572 will usually be a string (or <code>NIL</code> if there ain't
1573 no POST parameter with this name). If, however, the browser
1574 sent a <a class="none" name="upload">file</a> through
1575 a <a href="http://www.faqs.org/rfcs/rfc2388.html">
1576 <code>multipart/form-data</code>
1577 </a> form, the value of this function is a three-element list
1578 <pre>(path file-name content-type)</pre>
1579 where <clix:arg>path</clix:arg> is a pathname denoting the place
1580 were the uploaded file was
1581 stored, <clix:arg>file-name</clix:arg> (a string) is the file
1582 name sent by the browser, and <clix:arg>content-type</clix:arg>
1583 (also a string) is the content type sent by the browser. The
1584 file denoted by <clix:arg>path</clix:arg> will be deleted after
1585 the request has been handled - you have to move or copy it
1586 somewhere else if you want to keep it.
1588 POST parameters will only be computed if the content type of
1589 the request body was <code>multipart/form-data</code>
1590 or <code>application/x-www-form-urlencoded</code>. Although
1591 this function is called <code>POST-PARAMETER</code>, you can
1592 instruct Hunchentoot to compute these parameters for other
1594 setting <clix:ref>*METHODS-FOR-POST-PARAMETERS*</clix:ref>.
1597 See also <clix:ref>POST-PARAMETERS</clix:ref>
1598 and <clix:ref>*TMP-DIRECTORY*</clix:ref>.
1603 <clix:function name="get-parameters*">
1604 <clix:lambda-list><clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1605 <clix:returns>alist</clix:returns>
1608 an <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_a.htm#alist">alist</a>
1609 of all GET parameters (as provided via the request
1610 URI). The <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#car">car</a>
1611 of each element of this list is the parameter's name while
1612 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#cdr">cdr</a>
1613 is its value (as a string). The elements of this list are in
1614 the same order as they were within the request URI. See
1615 also <clix:ref>GET-PARAMETER</clix:ref>.
1619 <clix:function name="post-parameters*">
1620 <clix:lambda-list><clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1621 <clix:returns>alist</clix:returns>
1624 an <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_a.htm#alist">alist</a>
1625 of all POST parameters (as provided via the request's
1626 body). The <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#car">car</a>
1627 of each element of this list is the parameter's name while
1628 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#cdr">cdr</a>
1629 is its value. The elements of this list are in the same order
1630 as they were within the request's body.
1632 See also <clix:ref>POST-PARAMETER</clix:ref>.
1637 <clix:special-variable name='*methods-for-post-parameters*'>
1638 <clix:description>A list of the request method types (as keywords) for which
1639 Hunchentoot will try to compute <clix:arg>post-parameters</clix:arg>.
1641 </clix:special-variable>
1643 <clix:function name='cookie-in'>
1644 <clix:lambda-list>name
1648 <clix:returns>string
1651 Returns the cookie with the name <clix:arg>name</clix:arg> (a string) as sent by the
1652 browser - or <code>NIL</code> if there is none.
1656 <clix:function name='cookies-in*'>
1663 <clix:description>Returns an alist of all cookies associated with the <clix:ref>REQUEST</clix:ref> object
1664 <clix:arg>request</clix:arg>.
1668 <clix:function name='host'>
1675 <clix:description>Returns the 'Host' incoming http header value.
1679 <clix:function name='query-string*'>
1684 <clix:returns>string
1687 Returns the query string of the <clix:ref>REQUEST</clix:ref> object <clix:arg>request</clix:arg>. That's
1688 the part behind the question mark (i.e. the GET parameters).
1692 <clix:function name='referer'>
1697 <clix:returns>result
1700 Returns the 'Referer' (sic!) http header.
1704 <clix:function name='request-method*'>
1709 <clix:returns>keyword
1712 Returns the request method as a Lisp keyword.
1716 <clix:function name='request-uri*'>
1724 Returns the request URI.
1728 <clix:function name='server-protocol*'>
1733 <clix:returns>keyword
1736 Returns the request protocol as a Lisp keyword.
1740 <clix:function name='user-agent'>
1745 <clix:returns>result
1748 Returns the 'User-Agent' http header.
1752 <clix:function name='header-in*'>
1753 <clix:lambda-list>name
1757 <clix:returns>header
1760 Returns the incoming header with name
1761 <clix:arg>name</clix:arg>. <clix:arg>name</clix:arg> can be
1762 a keyword (recommended) or a string.
1766 <clix:function name='headers-in*'>
1774 Returns an alist of the incoming headers associated with the
1775 <clix:ref>REQUEST</clix:ref> object
1776 <clix:arg>request</clix:arg>.
1780 <clix:function name='remote-addr*'>
1785 <clix:returns>address
1788 Returns the address the current request originated from.
1792 <clix:function name='remote-port*'>
1800 Returns the port the current request originated from.
1804 <clix:function name='local-addr*'>
1809 <clix:returns>address
1812 The IP address of the local system that the client connected to.
1816 <clix:function name='local-port*'>
1824 The TCP port number of the local system that the client connected to.
1828 <clix:function name='script-name*'>
1833 <clix:returns>script-name
1836 Returns the file name of the <clix:ref>REQUEST</clix:ref>
1837 object <clix:arg>request</clix:arg>. That's the
1838 requested URI without the query string (i.e the GET
1843 <clix:accessor name='aux-request-value'>
1844 <clix:lambda-list>symbol
1848 <clix:returns>value, present-p
1851 This accessor can be used to associate arbitrary
1852 data with the the symbol <clix:arg>symbol</clix:arg> in the <clix:ref>REQUEST</clix:ref> object
1853 <clix:arg>request</clix:arg>. <clix:arg>present-p</clix:arg> is true if such data was found, otherwise <code>NIL</code>.
1857 <clix:function name='delete-aux-request-value'>
1858 <clix:lambda-list>symbol
1865 Removes the value associated with <clix:arg>symbol</clix:arg> from the <clix:ref>REQUEST</clix:ref> object
1866 <clix:arg>request</clix:arg>.
1870 <clix:function name='authorization'>
1875 <clix:returns>result
1878 Returns as two values the user and password (if any) as
1879 encoded in the 'AUTHORIZATION' header. Returns
1880 <code>NIL</code> if there is no such header.
1884 <clix:special-variable name='*hunchentoot-default-external-format*'>
1886 The external format used to compute the <clix:ref>REQUEST</clix:ref> object.
1888 </clix:special-variable>
1890 <clix:special-variable name='*file-upload-hook*'>
1892 If this is not <code>NIL</code>, it should be a unary
1893 function which will be called with a pathname for each file
1894 which is <a href="#upload">uploaded</a> to Hunchentoot. The
1895 pathname denotes the temporary file to which the uploaded
1896 file is written. The hook is called directly before the
1897 file is created. At this point,
1898 <clix:ref>*REQUEST*</clix:ref> is already bound to the
1899 current <clix:ref>REQUEST</clix:ref> object, but obviously
1900 you can't access the post parameters yet.
1902 </clix:special-variable>
1904 <clix:function name="raw-post-data">
1906 <clix:lkw>key</clix:lkw>
1907 request external-format force-text force-binary want-stream
1909 <clix:returns>raw-body-or-stream</clix:returns>
1911 Returns the content sent by the client in the request body if
1912 there was any (unless the content type
1913 was <code>multipart/form-data</code> in which
1914 case <code>NIL</code> is returned). By default, the result is
1915 a string if the type of the <code>Content-Type</code>
1916 <a href="http://www.faqs.org/rfcs/rfc1590.html">media type</a>
1917 is <code>"text"</code>, and a vector of octets otherwise. In
1918 the case of a string, the external format to be used to decode
1919 the content will be determined from the <code>charset</code>
1920 parameter sent by the client (or
1921 otherwise <clix:ref>*HUNCHENTOOT-DEFAULT-EXTERNAL-FORMAT*</clix:ref>
1924 You can also provide an external format explicitly (through
1925 <clix:arg>external-format</clix:arg>) in which case the result
1926 will unconditionally be a string. Likewise, you can provide
1927 a true value for <clix:arg>force-text</clix:arg> which will
1928 force Hunchentoot to act as if the type of the media type
1929 had been <code>"text"</code>
1930 (with <clix:arg>external-format</clix:arg> taking precedence
1931 if provided). Or you can provide a true value
1932 for <clix:arg>force-binary</clix:arg> which means that you
1933 want a vector of octets at any rate. (If both
1934 <clix:arg>force-text</clix:arg>
1935 and <clix:arg>force-binary</clix:arg> are true, an error will
1939 If, however, you provide a true value
1940 for <clix:arg>want-stream</clix:arg>, the other parameters are
1941 ignored and you'll get the content (flexi) stream to read
1942 from it yourself. It is then your responsibility to read
1943 the correct amount of data, because otherwise you won't be
1944 able to return a response to the client. The stream will
1946 its <a href="http://weitz.de/flexi-streams/#flexi-streams">octet
1947 position</a> set to <code>0</code>. If the client provided
1948 a <code>Content-Length</code> header, the stream will also
1950 corresponding <a href="http://weitz.de/flexi-streams/#flexi-streams">bound</a>,
1951 so no matter whether the client used chunked encoding or
1952 not, you can always read until EOF.
1955 If the content type of the request
1956 was <code>multipart/form-data</code>
1957 or <code>application/x-www-form-urlencoded</code>, the
1958 content has been read by Hunchentoot already and you can't
1959 read from the stream anymore.
1962 You can call <clix:ref>RAW-POST-DATA</clix:ref> more than once
1963 per request, but you can't mix calls which have different
1964 values for <clix:arg>want-stream</clix:arg>.
1967 Note that this function is slightly misnamed because a
1968 client can send content even if the request method is not
1975 <clix:function name='recompute-request-parameters'>
1978 </clix:lkw> request external-format
1983 Recomputes the GET and POST parameters for the <clix:ref>REQUEST</clix:ref> object
1984 <clix:arg>request</clix:arg>. This only makes sense if you're switching external formats
1989 <clix:function generic='true' name='process-request'>
1990 <clix:lambda-list>request
1995 This function is called by <clix:ref>PROCESS-CONNECTION</clix:ref>
1996 after the incoming headers have been read. It
1997 calls <clix:ref>HANDLE-REQUEST</clix:ref> (and is more or less just a
1998 thin wrapper around it) to select and call a
1999 <a href="#request-dispatch">handler</a> and send the output of this handler to
2000 the client. Note that <clix:ref>PROCESS-CONNECTION</clix:ref> is
2001 called once per connection and loops in case of a persistent
2002 connection while <clix:ref>PROCESS-REQUEST</clix:ref> is called anew
2005 The return value of this function is ignored.
2008 Like <clix:ref>PROCESS-CONNECTION</clix:ref>, this is another function
2009 the behaviour of which you should only modify if you really, really
2010 know what you're doing.
2015 <clix:function generic='true' name='handle-request'>
2016 <clix:lambda-list>acceptor request
2018 <clix:returns>content
2021 This function is called by <clix:ref>PROCESS-REQUEST</clix:ref> once
2022 the request has been read and a <clix:ref>REQUEST</clix:ref> object
2023 has been created. Its job is to actually handle the request, i.e. to
2024 return something to the client.
2026 The default method calls the
2027 acceptor's <a href="#request-dispatch">request dispatcher</a>, but you
2028 can of course implement a different behaviour. The default method
2029 also sets up <a href="#logging">standard error handling</a> for
2030 the <a href="#request-dispatch">handler</a>.
2033 Might be a good place to bind or rebind special variables which can
2034 then be accessed by your <a href="#request-dispatch">handlers</a>.
2039 <clix:function generic='true' name='acceptor-dispatch-request'>
2040 <clix:lambda-list>acceptor request
2042 <clix:returns>content
2045 This function is called to actually dispatch the request
2046 once the standard logging and error handling has been set
2047 up. <clix:ref>ACCEPTOR</clix:ref> subclasses implement
2048 methods for this function in order to perform their own
2049 request routing. If a method does not want to handle the
2050 request, it is supposed to invoke <a
2051 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_call_n.htm">CALL-NEXT-METHOD</a>
2052 so that the next <clix:ref>ACCEPTOR</clix:ref> in the
2053 inheritance chain gets a chance to handle the request.
2057 <clix:readers generic='true'>
2058 <clix:listed-reader generic='true' name='cookies-in'>
2059 <clix:lambda-list>request
2061 <clix:returns>cookies
2063 </clix:listed-reader>
2065 <clix:listed-reader generic='true' name='get-parameters'>
2066 <clix:lambda-list>request
2068 <clix:returns>get-parameters
2070 </clix:listed-reader>
2072 <clix:listed-reader generic='true' name='header-in'>
2073 <clix:lambda-list>name request
2075 <clix:returns>result
2079 </clix:listed-reader>
2081 <clix:listed-reader generic='true' name='headers-in'>
2082 <clix:lambda-list>request
2084 <clix:returns>headers
2086 </clix:listed-reader>
2088 <clix:listed-reader generic='true' name='post-parameters'>
2089 <clix:lambda-list>request
2091 <clix:returns>post-parameters
2093 </clix:listed-reader>
2095 <clix:listed-reader generic='true' name='query-string'>
2096 <clix:lambda-list>request
2098 <clix:returns>query-string
2100 </clix:listed-reader>
2102 <clix:listed-reader generic='true' name='remote-addr'>
2103 <clix:lambda-list>request
2105 <clix:returns>address
2107 </clix:listed-reader>
2109 <clix:listed-reader generic='true' name='remote-port'>
2110 <clix:lambda-list>request
2114 </clix:listed-reader>
2116 <clix:listed-reader generic='true' name='local-addr'>
2117 <clix:lambda-list>request
2119 <clix:returns>address
2121 </clix:listed-reader>
2123 <clix:listed-reader generic='true' name='local-port'>
2124 <clix:lambda-list>request
2128 </clix:listed-reader>
2130 <clix:listed-reader generic='true' name='request-acceptor'>
2131 <clix:lambda-list>request
2133 <clix:returns>acceptor
2135 </clix:listed-reader>
2137 <clix:listed-reader generic='true' name='request-method'>
2138 <clix:lambda-list>request
2140 <clix:returns>method
2142 </clix:listed-reader>
2144 <clix:listed-reader generic='true' name='request-uri'>
2145 <clix:lambda-list>request
2149 </clix:listed-reader>
2151 <clix:listed-reader generic='true' name='server-protocol'>
2152 <clix:lambda-list>request
2154 <clix:returns>protocol
2156 </clix:listed-reader>
2158 <clix:listed-reader generic='true' name='script-name'>
2159 <clix:lambda-list>request
2161 <clix:returns>result
2163 </clix:listed-reader>
2166 These are various generic readers which are used
2167 to read information about a <clix:ref>REQUEST</clix:ref> object. If you are writing a
2168 <a href="#request-dispatch">handler</a>, you should <em>not</em> use these readers but instead utilize the
2169 corresponding functions with an asterisk at the end of their name,
2170 also listed in this section. These generic readers are only
2171 exported for users who want to create their own subclasses of
2172 <clix:ref>REQUEST</clix:ref>.
2179 <clix:subchapter name="replies" title="Reply objects">
2181 For each incoming request, the <a href="#acceptors">acceptor</a>
2182 (in <clix:ref>PROCESS-CONNECTION</clix:ref>) creates
2183 a <clix:ref>REPLY</clix:ref> object and makes it available
2184 to <a href="#request-dispatch">handlers</a> via the special variable
2185 <clix:ref>*REPLY*</clix:ref>. This object contains all relevant
2186 information (except for the content body) about the reply that will be
2187 sent to the client and this section collects the functions which can
2188 be used to query and modify such an object. In all function
2189 where <clix:arg>reply</clix:arg> is an optional or keyword parameter,
2190 the default is <clix:ref>*REPLY*</clix:ref>.
2193 If you need more fine-grained control over the behaviour of reply
2194 objects, you can subclass <clix:ref>REPLY</clix:ref> and initialize
2195 the <a href="#acceptor-reply-class"><code>REPLY-CLASS</code></a>
2196 slot of the <clix:ref>ACCEPTOR</clix:ref> class accordingly. The
2197 acceptor will generate reply objects of the class named by this
2201 <clix:class name='reply'>
2203 Objects of this class hold all the information about an
2204 outgoing reply. They are created automatically by
2205 Hunchentoot and can be accessed and modified by the
2206 corresponding <a href="#request-dispatch">handler</a>.
2208 You should not mess with the slots of these objects directly, but you
2209 can subclass <clix:ref>REPLY</clix:ref> in order to implement your own behaviour. See the
2210 <a href="#acceptor-reply-class"><code>:reply-class</code></a> initarg
2211 of the <clix:ref>ACCEPTOR</clix:ref> class.
2216 <clix:special-variable name='*reply*'>
2218 The current <clix:ref>REPLY</clix:ref> object in the context of a request.
2220 </clix:special-variable>
2222 <clix:accessor name='header-out'>
2223 <clix:lambda-list>name
2227 <clix:returns>string
2230 <clix:ref>HEADER-OUT</clix:ref> returns the outgoing http header named by the keyword <clix:arg>name</clix:arg> if there is one, otherwise <code>NIL</code>. <code>SETF</code> of <clix:ref>HEADER-OUT</clix:ref> changes the current value of the header named <clix:arg>name</clix:arg>. If no header named <clix:arg>name</clix:arg> exists, it is created. For backwards compatibility, <clix:arg>name</clix:arg> can also be a string in which case the association between a header and its name is case-insensitive.
2232 Note that the header 'Set-Cookie' cannot be queried by <clix:ref>HEADER-OUT</clix:ref> and must not be set by <code>SETF</code> of <clix:ref>HEADER-OUT</clix:ref>.
2233 See also <clix:ref>HEADERS-OUT*</clix:ref>, <clix:ref>CONTENT-TYPE*</clix:ref>, <clix:ref>CONTENT-LENGTH*</clix:ref>, <clix:ref>COOKIES-OUT*</clix:ref>, and <clix:ref>COOKIE-OUT</clix:ref>.
2238 <clix:function name='headers-out*'>
2245 <clix:description>Returns an alist of the outgoing headers associated with the
2246 <clix:ref>REPLY</clix:ref> object <clix:arg>reply</clix:arg>. See also <clix:ref>HEADER-OUT</clix:ref>.
2250 <clix:accessor name='content-length*'>
2255 <clix:returns>content-length
2258 The outgoing 'Content-Length' http header of <clix:arg>reply</clix:arg>.
2262 <clix:accessor name='content-type*'>
2267 <clix:returns>content-type
2270 The outgoing 'Content-Type' http header of <clix:arg>reply</clix:arg>.
2274 <clix:function name='cookie-out'>
2275 <clix:lambda-list>name
2279 <clix:returns>result
2282 Returns the current value of the outgoing <a
2283 href="#cookies">cookie</a> named
2284 <clix:arg>name</clix:arg>. Search is case-sensitive.
2288 <clix:accessor name='cookies-out*'>
2296 Returns or sets an alist of the outgoing <a
2297 href="#cookies">cookies</a> associated with the
2298 <clix:ref>REPLY</clix:ref> object
2299 <clix:arg>reply</clix:arg>.
2303 <clix:accessor name='return-code*'>
2308 <clix:returns>return-code
2311 Gets or sets the http return code of
2312 <clix:arg>reply</clix:arg>. The return code of each
2313 <clix:ref>REPLY</clix:ref> object is initially set to
2314 <clix:ref>+HTTP-OK+</clix:ref>.
2318 <clix:function name="send-headers">
2319 <clix:returns>stream</clix:returns>
2321 Sends the initial status line and all headers as determined
2322 by the <clix:ref>REPLY</clix:ref>
2323 object <clix:ref>*REPLY*</clix:ref>. Returns
2324 a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_b.htm#binary">binary</a>
2325 stream to which the body of the reply can be written. Once
2326 this function has been called, further changes
2327 to <clix:ref>*REPLY*</clix:ref> don't have any effect.
2328 Also, automatic handling of errors (i.e. sending the
2329 corresponding status code to the browser, etc.) is turned
2330 off for this request and functions
2331 like <clix:ref>REDIRECT</clix:ref> or
2332 to <clix:ref>ABORT-REQUEST-HANDLER</clix:ref> won't have the
2333 desired effect once the headers are sent.
2335 If your handlers return the full body as a string or as an
2336 array of octets, you should <em>not</em> call this function.
2337 If a handler calls <clix:ref>SEND-HEADERS</clix:ref> , its
2338 return value is ignored.
2343 <clix:accessor name='reply-external-format*'>
2348 <clix:returns>external-format
2351 Gets or sets the external format of <clix:arg>reply</clix:arg> which is used for character output.
2355 <clix:special-variable name='*default-content-type*'>
2357 The default content-type header which is returned to the client.
2359 </clix:special-variable>
2362 <clix:listed-constant name="+http-continue+"/>
2363 <clix:listed-constant name="+http-switching-protocols+"/>
2364 <clix:listed-constant name="+http-ok+"/>
2365 <clix:listed-constant name="+http-created+"/>
2366 <clix:listed-constant name="+http-accepted+"/>
2367 <clix:listed-constant name="+http-non-authoritative-information+"/>
2368 <clix:listed-constant name="+http-no-content+"/>
2369 <clix:listed-constant name="+http-reset-content+"/>
2370 <clix:listed-constant name="+http-partial-content+"/>
2371 <clix:listed-constant name="+http-multi-status+"/>
2372 <clix:listed-constant name="+http-multiple-choices+"/>
2373 <clix:listed-constant name="+http-moved-permanently+"/>
2374 <clix:listed-constant name="+http-moved-temporarily+"/>
2375 <clix:listed-constant name="+http-see-other+"/>
2376 <clix:listed-constant name="+http-not-modified+"/>
2377 <clix:listed-constant name="+http-use-proxy+"/>
2378 <clix:listed-constant name="+http-temporary-redirect+"/>
2379 <clix:listed-constant name="+http-bad-request+"/>
2380 <clix:listed-constant name="+http-authorization-required+"/>
2381 <clix:listed-constant name="+http-payment-required+"/>
2382 <clix:listed-constant name="+http-forbidden+"/>
2383 <clix:listed-constant name="+http-not-found+"/>
2384 <clix:listed-constant name="+http-method-not-allowed+"/>
2385 <clix:listed-constant name="+http-not-acceptable+"/>
2386 <clix:listed-constant name="+http-proxy-authentication-required+"/>
2387 <clix:listed-constant name="+http-request-time-out+"/>
2388 <clix:listed-constant name="+http-conflict+"/>
2389 <clix:listed-constant name="+http-gone+"/>
2390 <clix:listed-constant name="+http-length-required+"/>
2391 <clix:listed-constant name="+http-precondition-failed+"/>
2392 <clix:listed-constant name="+http-request-entity-too-large+"/>
2393 <clix:listed-constant name="+http-request-uri-too-large+"/>
2394 <clix:listed-constant name="+http-unsupported-media-type+"/>
2395 <clix:listed-constant name="+http-requested-range-not-satisfiable+"/>
2396 <clix:listed-constant name="+http-expectation-failed+"/>
2397 <clix:listed-constant name="+http-failed-dependency+"/>
2398 <clix:listed-constant name="+http-internal-server-error+"/>
2399 <clix:listed-constant name="+http-not-implemented+"/>
2400 <clix:listed-constant name="+http-bad-gateway+"/>
2401 <clix:listed-constant name="+http-service-unavailable+"/>
2402 <clix:listed-constant name="+http-gateway-time-out+"/>
2403 <clix:listed-constant name="+http-version-not-supported+"/>
2405 The values of these constants are 100, 101, 200, 201, 202,
2406 203, 204, 205, 206, 207, 300, 301, 302, 303, 304, 305, 307,
2407 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411,
2408 412, 413, 414, 415, 416, 417, 424, 500, 501, 502, 503, 504,
2409 and 505. See <clix:ref>RETURN-CODE</clix:ref>.
2413 <clix:readers generic='true'>
2414 <clix:listed-reader generic='true' name='content-length'>
2415 <clix:lambda-list>reply
2417 <clix:returns>content-length
2419 </clix:listed-reader>
2421 <clix:listed-reader generic='true' name='content-type'>
2422 <clix:lambda-list>reply
2424 <clix:returns>content-type
2426 </clix:listed-reader>
2428 <clix:listed-reader generic='true' name='headers-out'>
2429 <clix:lambda-list>reply
2431 <clix:returns>headers-out
2433 </clix:listed-reader>
2436 These are various generic readers which are used
2437 to read information about a <clix:ref>REPLY</clix:ref> object. If you are writing a
2438 <a href="#request-dispatch">handler</a>, you should <em>not</em> use these readers but instead utilize the
2439 corresponding functions with an asterisk at the end of their name,
2440 also listed in this section. These generic readers are only
2441 exported for users who want to create their own subclasses of
2442 <clix:ref>REPLY</clix:ref>.
2446 <clix:accessors generic='true'>
2447 <clix:listed-accessor generic='true' name='cookies-out'>
2448 <clix:lambda-list>reply
2450 <clix:returns>result
2452 </clix:listed-accessor>
2454 <clix:listed-accessor generic='true' name='return-code'>
2455 <clix:lambda-list>reply
2457 <clix:returns>result
2459 </clix:listed-accessor>
2461 <clix:listed-accessor generic='true' name='reply-external-format'>
2462 <clix:lambda-list>reply
2464 <clix:returns>result
2466 </clix:listed-accessor>
2469 These are various generic accessors which are
2470 used to query and modify a <clix:ref>REPLY</clix:ref> objects. If
2472 <a href="#request-dispatch">handler</a>, you should <em>not</em> use these
2473 accessors but instead utilize the corresponding functions with an
2474 asterisk at the end of their name, also listed in this section.
2475 These generic accessors are only exported for users who want to
2476 create their own subclasses of
2477 <clix:ref>REPLY</clix:ref>.
2484 <clix:subchapter name="sessions" title="Sessions">
2485 Hunchentoot supports <em>sessions</em>: Once a <a href="#request-dispatch">request
2486 handler</a> has called <clix:ref>START-SESSION</clix:ref>, Hunchentoot
2487 uses either cookies or (if the client doesn't send the cookies
2488 back) <a href="#*rewrite-for-session-urls*">rewrites URLs</a> to keep
2489 track of this client, i.e. to provide a kind of 'state' for the
2490 stateless http protocol. The session associated with the client is a
2491 <a href="#session">CLOS object</a> which can be used
2492 to <a href="#session-value">store arbitrary data</a> between requests.
2494 Hunchentoot makes some reasonable effort to prevent eavesdroppers from
2495 hijacking sessions (see below), but this should not be considered
2496 really secure. Don't store sensitive data in sessions and rely solely
2497 on the session mechanism as a safeguard against malicious users who
2498 want to get at this data!
2501 For each request there's one <clix:ref>SESSION</clix:ref> object which is accessible to the
2502 <a href="#handler">handler</a> via the special
2503 variable <clix:ref>*SESSION*</clix:ref>. This object holds all the
2504 information available about the session and can be accessed with the
2505 functions described in this chapter. Note that the internal structure
2506 of <clix:ref>SESSION</clix:ref> objects should be considered opaque
2507 and may change in future releases of Hunchentoot.
2510 Sessions are automatically <a href="#session-verify">verified</a> for
2511 validity and age when the <clix:ref>REQUEST</clix:ref> object is
2512 instantiated, i.e. if <clix:ref>*SESSION*</clix:ref> is not NIL then
2513 this session is valid (as far as Hunchentoot is concerned) and
2514 not <a href="#session-too-old-p">too old</a>. Old sessions
2515 are <a href="#session-gc">automatically removed</a>.
2518 <clix:class name='session'>
2520 <clix:ref>SESSION</clix:ref> objects are
2521 automatically maintained by Hunchentoot. They should not be created
2522 explicitly with <code>MAKE-INSTANCE</code> but implicitly
2523 with <clix:ref>START-SESSION</clix:ref> and they should be treated as
2526 You can ignore Hunchentoot's <clix:ref>SESSION</clix:ref> objects and
2527 <a href="#session-behaviour">implement your own sessions</a> if you provide corresponding methods for
2528 <clix:ref>SESSION-COOKIE-VALUE</clix:ref>
2529 and <clix:ref>SESSION-VERIFY</clix:ref>.
2534 <clix:function name='start-session'>
2537 <clix:returns>session
2540 Returns the current <clix:ref>SESSION</clix:ref>
2541 object. If there is no current session, creates one and updates the
2542 corresponding data structures. In this case the function will also
2543 send a session cookie to the browser.
2547 <clix:accessor name='session-value'>
2548 <clix:lambda-list>symbol
2552 <clix:returns>value, present-p
2555 This accessor can be used to associate arbitrary data with the the
2556 symbol <clix:arg>symbol</clix:arg> in the <clix:ref>SESSION</clix:ref>
2557 object <clix:arg>session</clix:arg>. <clix:arg>present-p</clix:arg> is
2558 true if such data was found, otherwise <code>NIL</code>. The default
2559 value for <clix:arg>session</clix:arg> is
2560 <clix:ref>*SESSION*</clix:ref>.
2562 If <code>SETF</code> of <clix:ref>SESSION-VALUE</clix:ref> is called
2563 with <clix:arg>session</clix:arg> being <code>NIL</code> then a
2564 session is automatically instantiated
2565 with <clix:ref>START-SESSION</clix:ref>.
2570 <clix:function name='delete-session-value'>
2571 <clix:lambda-list>symbol
2578 Removes the value associated with
2579 <clix:arg>symbol</clix:arg> from
2580 <clix:arg>session</clix:arg> if there is one.
2584 <clix:special-variable name='*session*'>
2586 The current session while in the context of a request, or
2589 </clix:special-variable>
2591 <clix:function name='remove-session'>
2592 <clix:lambda-list>session
2597 Completely removes the <clix:ref>SESSION</clix:ref> object
2598 <clix:arg>session</clix:arg> from Hunchentoot's
2599 internal <a href="#session-db">session database</a>.
2603 <clix:function name='reset-sessions'>
2606 </clix:lkw> acceptor
2611 Removes <em>all</em> stored sessions of
2612 <clix:arg>acceptor</clix:arg>. The default for
2613 <clix:arg>acceptor</clix:arg> is
2614 <clix:ref>*ACCEPTOR*</clix:ref>.
2618 <clix:special-variable name='*rewrite-for-session-urls*'>
2620 Whether HTML pages should possibly be rewritten for cookie-less
2623 </clix:special-variable>
2625 <clix:special-variable name='*content-types-for-url-rewrite*'>
2627 The content types for which url-rewriting is OK. See
2628 <clix:ref>*REWRITE-FOR-SESSION-URLS*</clix:ref>.
2630 </clix:special-variable>
2632 <clix:special-variable name='*use-remote-addr-for-sessions*'>
2634 Whether the client's remote IP (as returned by <clix:ref>REAL-REMOTE-ADDR</clix:ref>)
2635 should be encoded into the session string. If this value is true, a
2636 session will cease to be accessible if the client's remote IP changes.
2638 This might for example be an issue if the client uses a proxy server
2639 which doesn't send correct 'X-Forwarded-For' headers.
2642 </clix:special-variable>
2644 <clix:function generic='true' name='session-remote-addr'>
2645 <clix:lambda-list>session
2647 <clix:returns>remote-addr
2650 The remote IP address of the client when this session was started (as
2651 returned by <clix:ref>REAL-REMOTE-ADDR</clix:ref>).
2655 <clix:special-variable name='*use-user-agent-for-sessions*'>
2656 <clix:description>Whether the 'User-Agent' header should
2657 be encoded into the session string. If this value is true, a session
2658 will cease to be accessible if the client sends a different
2659 'User-Agent' header.
2661 </clix:special-variable>
2663 <clix:function generic='true' name='session-user-agent'>
2664 <clix:lambda-list>session
2666 <clix:returns>user-agent
2669 The incoming 'User-Agent' header that
2670 was sent when this session was created.
2674 <clix:accessor generic='true' name='session-max-time'>
2675 <clix:lambda-list>session
2677 <clix:returns>max-time
2680 Gets or sets the time (in seconds) after
2681 which <clix:arg>session</clix:arg> expires if it's not used.
2686 <clix:special-variable name='*session-max-time*'>
2688 The default time (in seconds) after which a session times out.
2690 </clix:special-variable>
2692 <clix:special-variable name='*session-gc-frequency*'>
2694 A session GC (see function <clix:ref>SESSION-GC</clix:ref>) will happen every
2695 <clix:ref>*SESSION-GC-FREQUENCY*</clix:ref> requests (counting only
2696 requests which create a new session) if this variable is
2697 not <code>NIL</code>. See <clix:ref>SESSION-CREATED</clix:ref>.
2699 </clix:special-variable>
2701 <clix:function name='session-gc'>
2707 Removes sessions from the current session database which are
2708 too old - see <clix:ref>SESSION-TOO-OLD-P</clix:ref>.
2712 <clix:function name='session-too-old-p'>
2713 <clix:lambda-list>session
2715 <clix:returns>generalized-boolean
2718 Returns true if the <clix:ref>SESSION</clix:ref> object <clix:arg>session</clix:arg> has not been active in
2719 the last <code>(session-max-time session)</code> seconds.
2723 <clix:function generic='true' name='session-id'>
2724 <clix:lambda-list>session
2726 <clix:returns>session-id
2729 The unique ID (an INTEGER) of the session.
2733 <clix:function generic='true' name='session-start'>
2734 <clix:lambda-list>session
2736 <clix:returns>universal-time
2739 The time this session was started.
2746 <clix:subchapter name="session-behaviour" title="Customizing session behaviour">
2748 For everyday session usage, you will probably just
2749 use <clix:ref>START-SESSION</clix:ref>,
2750 <clix:ref>SESSION-VALUE</clix:ref>,
2751 and maybe <clix:ref>DELETE-SESSION-VALUE</clix:ref>
2752 and <clix:ref>*SESSION*</clix:ref>. However, there are two ways to
2753 customize the way Hunchentoot maintains sessions.
2755 One way is to mostly leave the session mechanism intact but to tweak
2758 <li>The publicly visible part of a session is encoded using a
2759 <a href="#*session-secret*">secret</a> which you can set yourself.</li>
2760 <li>And it is stored using a cookie (or GET
2761 parameter) <a href="#session-cookie-name">name</a> that you can
2763 <li>Each session receives a <a href="#next-session-id">new ID</a> when
2764 it is created and you can implement a more robust way to do that.</li>
2765 <li>You can arrange to be called whenever a session
2766 is <a href="#session-created">created</a> to trigger some action. You
2767 might also do this to invent your own
2768 session <a href="#session-gc">garbage collection</a>.</li>
2769 <li>By default, all sessions are stored in a global alist in memory.
2770 You can't change the alist part, but you can distribute your sessions
2771 over different <a href="#session-db">"databases"</a>.</li>
2772 <li>By default, every operation which modifies sessions or one of the
2773 session databases is guarded by a global lock, but you can arrange to
2774 <a href="#session-db-lock">provide</a> different locks for this.</li>
2778 The other way to customize Hunchentoot's sessions is to completely
2779 replace them. This is actually pretty easy: Create your own class to
2780 store state (which doesn't have to and probably shouldn't inherit
2781 from <clix:ref>SESSION</clix:ref>) and implement methods for
2782 <clix:ref>SESSION-VERIFY</clix:ref>
2783 and <clix:ref>SESSION-COOKIE-VALUE</clix:ref> - that's it.
2784 Hunchentoot will continue to use cookies and/or to rewrite URLs to
2785 keep track of session state and it will store "the current session"
2786 (whatever that is in your implementation)
2787 in <clix:ref>*SESSION*</clix:ref>. Everything else (like persisting
2788 sessions, GC, getting and setting values) you'll have to take care of
2789 yourself and the other session functions
2790 (like <clix:ref>START-SESSION</clix:ref> or
2791 <clix:ref>SESSION-VALUE</clix:ref>) won't work anymore. (Almost)
2792 total freedom, but a lot of responsibility as well... :)
2795 <clix:special-variable name='*session-secret*'>
2797 A random ASCII string that's used to encode the public
2798 session data. This variable is initially unbound and will
2799 be set (using <clix:ref>RESET-SESSION-SECRET</clix:ref>) the
2800 first time a session is created, if necessary. You can
2801 prevent this from happening if you set the value yourself
2802 before starting <a href="#acceptors">acceptors</a>.
2804 </clix:special-variable>
2806 <clix:function name='reset-session-secret'>
2809 <clix:returns>secret
2812 Sets <clix:ref>*SESSION-SECRET*</clix:ref> to a
2813 new random value. All old sessions will cease to be valid.
2817 <clix:function generic='true' name='session-cookie-name'>
2818 <clix:lambda-list>acceptor
2823 Returns the name (a string) of the cookie (or
2824 the GET parameter) which is used to store a session on the client
2825 side. The default is to use the
2826 string <code>"hunchentoot-session"</code>, but you can
2827 specialize this function if you want another name.
2831 <clix:function generic='true' name='session-created'>
2832 <clix:lambda-list>acceptor new-session
2834 <clix:returns>result
2837 This function is called whenever a new session
2838 has been created. There's a default method which might trigger
2839 a <a href="#session-gc">session GC</a> based on the value of
2840 <clix:ref>*SESSION-GC-FREQUENCY*</clix:ref>.
2842 The return value is ignored.
2847 <clix:function generic='true' name='next-session-id'>
2848 <clix:lambda-list>acceptor
2853 Returns the next sequential session ID, an
2854 integer, which should be unique per session. The default method uses
2855 a simple global counter and isn't guarded by a lock. For a
2856 high-performance production environment you might consider using a
2857 more robust implementation.
2861 <clix:accessor generic='true' name='session-db'>
2862 <clix:lambda-list>acceptor
2864 <clix:returns>database
2867 Returns the current session database which is an
2868 alist where each car is a session's ID and the cdr is the
2869 corresponding <clix:ref>SESSION</clix:ref> object itself. The default
2870 is to use a global list for all acceptors.
2874 <clix:function generic='true' name='session-db-lock'>
2875 <clix:lambda-list>acceptor
2877 </clix:lkw> whole-db-p
2882 A function which returns a lock that will be
2883 used to prevent concurrent access to sessions. The first argument
2884 will be the <a href="#acceptors">acceptor</a> that handles the
2885 current <a href="#requests">request</a>, the second argument is true
2886 if the whole (current) session database is modified. If it
2887 is <code>NIL</code>, only one existing session in the database is
2890 This function can return <code>NIL</code> which means that sessions or
2891 session databases will be modified without a lock held (for example
2892 for single-threaded environments). The default is to always return a
2893 global lock (ignoring the <clix:arg>acceptor</clix:arg> argument) for
2894 Lisps that support threads and <code>NIL</code> otherwise.
2899 <clix:function generic='true' name='session-verify'>
2900 <clix:lambda-list>request
2902 <clix:returns>session-or-nil
2905 Tries to get a session identifier from the cookies
2906 (or alternatively from the GET parameters) sent by the client (see
2907 <clix:ref>SESSION-COOKIE-NAME</clix:ref>
2908 and <clix:ref>SESSION-COOKIE-VALUE</clix:ref>). This identifier is
2909 then checked for validity against the <clix:ref>REQUEST</clix:ref>
2911 <clix:arg>request</clix:arg>. On success the corresponding session object (if not too
2912 old) is returned (and updated). Otherwise <code>NIL</code> is returned.
2914 A default method is provided and you only need to write your own one
2915 if you want to maintain your own sessions.
2920 <clix:function generic='true' name='session-cookie-value'>
2921 <clix:lambda-list>session
2923 <clix:returns>string
2926 Returns a string which can be used to safely
2927 restore the session <clix:arg>session</clix:arg> if as session has
2928 already been established. This is used as the value stored in the
2929 session cookie or in the corresponding GET parameter and verified
2930 by <clix:ref>SESSION-VERIFY</clix:ref>.
2933 method is provided and there's no reason to change it unless you
2934 want to use your own session objects.
2941 <clix:subchapter name="cookies" title="Cookies">
2943 Outgoing cookies are stored in the request's <clix:ref>REPLY</clix:ref>
2944 object (see <clix:ref>COOKIE-OUT</clix:ref>
2945 and <clix:ref>COOKIES-OUT*</clix:ref>). They are CLOS objects
2948 <pre>(defclass cookie ()
2949 ((name :initarg :name
2950 :reader <a class="noborder" name="cookie-name">cookie-name</a>
2952 :documentation "The name of the cookie - a string.")
2953 (value :initarg :value
2954 :accessor <a class="noborder" name="cookie-value">cookie-value</a>
2956 :documentation "The value of the cookie. Will be URL-encoded when sent to the browser.")
2957 (expires :initarg :expires
2959 :accessor <a class="noborder" name="cookie-expires">cookie-expires</a>
2960 :documentation "The time (a universal time) when the cookie expires (or NIL).")
2961 (max-age :initarg :max-age
2963 :accessor <a class="noborder" name="cookie-max-age">cookie-max-age</a>
2964 :documentation "The time delta (in seconds) after which the cookie expires (or NIL).")
2965 (path :initarg :path
2967 :accessor <a class="noborder" name="cookie-path">cookie-path</a>
2968 :documentation "The path this cookie is valid for (or NIL).")
2969 (domain :initarg :domain
2971 :accessor <a class="noborder" name="cookie-domain">cookie-domain</a>
2972 :documentation "The domain this cookie is valid for (or NIL).")
2973 (secure :initarg :secure
2975 :accessor <a class="noborder" name="cookie-secure">cookie-secure</a>
2976 :documentation "A generalized boolean denoting whether this is a secure cookie.")
2977 (http-only :initarg :http-only
2979 :accessor <a class="noborder" name="cookie-http-only">cookie-http-only</a>
2980 :documentation "A generalized boolean denoting whether this is a <a href="http://msdn2.microsoft.com/en-us/library/ms533046.aspx">HttpOnly</a> cookie.")))
2983 The <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_r.htm#reader">reader</a>
2984 <clix:ref>COOKIE-NAME</clix:ref> and
2985 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_a.htm#accessor">accessors</a>
2986 <clix:ref>COOKIE-VALUE</clix:ref>, <clix:ref>COOKIE-EXPIRES</clix:ref>, <clix:ref>COOKIE-MAX-AGE</clix:ref>,
2987 <clix:ref>COOKIE-PATH</clix:ref>, <clix:ref>COOKIE-DOMAIN</clix:ref>, <clix:ref>COOKIE-SECURE</clix:ref>,
2988 and <clix:ref>COOKIE-HTTP-ONLY</clix:ref> are all exported from
2989 the <code>HUNCHENTOOT</code> package. For now, the class name itself is <em>not</em> exported.
2991 <clix:function name="set-cookie">
2993 name <clix:lkw>key</clix:lkw> value expires path
2994 domain secure http-only reply
2996 <clix:returns>cookie</clix:returns>
2998 Creates a <code>COOKIE</code> object from the parameters
2999 provided to this function and adds it to the outgoing cookies
3000 of the <a href="#replies"><code>REPLY</code> object</a>
3001 <clix:arg>reply</clix:arg>. If a cookie with the same name
3002 (case-sensitive) already exists, it is replaced. The default
3003 for <clix:arg>reply</clix:arg>
3004 is <clix:ref>*REPLY*</clix:ref>. The default
3005 for <clix:arg>value</clix:arg> is the empty string.
3009 <clix:function name="set-cookie*">
3010 <clix:lambda-list>cookie <clix:lkw>optional</clix:lkw> reply</clix:lambda-list>
3011 <clix:returns>cookie</clix:returns>
3013 Adds the <code>COOKIE</code> object <clix:arg>cookie</clix:arg>
3014 to the outgoing cookies of
3015 the <a href="#replies"><code>REPLY</code> object</a>
3016 <clix:arg>reply</clix:arg>. If a cookie with the same name
3017 (case-sensitive) already exists, it is replaced. The default
3018 for <clix:arg>reply</clix:arg> is <clix:ref>*REPLY*</clix:ref>.
3023 <clix:subchapter name="logging" title="Logging">
3024 Hunchentoot can log accesses and diagnostic messages to two
3025 separate destinations, which can be either files in the file
3026 system or streams. Logging can also be disabled by setting the
3027 <clix:code>ACCESS-LOG-DESTINATION</clix:code> and
3028 <clix:code>MESSAGE-LOG-DESTINATION</clix:code> slots in the
3029 <clix:ref>ACCEPTOR</clix:ref> to <code>NIL</code>. The two
3030 slots can be initialized by providing the
3031 :ACCESS-LOG-DESTINATION and :MESSAGE-LOG-DESTINATION
3032 initialization arguments when creating the acceptor or set by
3033 setting the slots through its
3034 <clix:ref>ACCEPTOR-MESSAGE-LOG-DESTINATION</clix:ref> and
3035 <clix:ref>ACCEPTOR-ACCESS-LOG-DESTINATION</clix:ref> accessors.
3037 When the path for the message or accept log is set to a
3038 variable holding an output stream, hunchentoots writes
3039 corresponding log entries to that stream. By default,
3040 Hunchentoot logs to *STANDARD-ERROR*.
3043 Access logging is done in a format similar to what
3044 the Apache web server can write so that logfile analysis using
3045 standard tools is possible. Errors during request processing are
3046 logged to a separate file.
3049 The standard logging mechanism is deliberately simple and slow. The
3050 log files are opened for each log entry and closed again after
3051 writing, and access to them is protected by a global lock. Derived
3052 acceptor classes can implement methods for the
3053 <clix:ref>ACCEPTOR-LOG-MESSAGE</clix:ref> and
3054 <clix:ref>ACCEPTOR-LOG-ACCESS</clix:ref> generic functions in order to
3055 log differently (e.g. to a central logging server or in a different
3059 Errors happening within a <a href="#request-dispatch">handler</a>
3060 which are not caught by the handler itself are handled by
3061 Hunchentoot by logging them to the established
3062 <clix:ref>ACCEPTOR-MESSAGE-LOG-DESTINATION</clix:ref>.
3065 <clix:function name='log-message*'>
3066 <clix:lambda-list>log-level format-string
3068 </clix:lkw> format-arguments
3070 <clix:returns>result
3073 Convenience function which calls the message
3074 logger of the current acceptor (if there is one) with the same
3075 arguments it accepts. Returns <code>NIL</code> if there is no message
3076 logger or whatever the message logger returns.
3078 This is the function which Hunchentoot itself uses to log errors it
3079 catches during request processing.
3084 <clix:special-variable name='*log-lisp-errors-p*'>
3086 Whether Lisp errors in request handlers should be logged.
3088 </clix:special-variable>
3090 <clix:special-variable name='*log-lisp-backtraces-p*'>
3092 Whether Lisp backtraces should be logged. Only
3093 has an effect if <clix:ref>*LOG-LISP-ERRORS-P*</clix:ref> is true
3096 </clix:special-variable>
3098 <clix:special-variable name='*log-lisp-warnings-p*'>
3100 Whether Lisp warnings in request handlers should be logged.
3102 </clix:special-variable>
3104 <clix:special-variable name='*lisp-errors-log-level*'>
3106 Log level for Lisp errors. Should be one
3107 of <code>:ERROR</code> (the default), <code>:WARNING</code>,
3108 or <code>:INFO</code>.
3110 </clix:special-variable>
3112 <clix:special-variable name='*lisp-warnings-log-level*'>
3114 Log level for Lisp warnings.
3115 Should be one of <code>:ERROR</code>, <code>:WARNING</code>
3116 (the default), or <code>:INFO</code>.
3118 </clix:special-variable>
3121 <clix:subchapter name="conditions" title="Conditions and error handling">
3123 This section describes how Hunchentoot deals with exceptional
3124 situations. See also the secion about <a href="#logging">logging</a>.
3127 When an error occurs while processing a request, Hunchentoot's
3128 default behavior is to catch catch the error, log it and
3129 optionally display it to the client in the HTML response.
3130 This behavior can be customized through the values of a number
3131 of special variables, which are documented below.
3134 <clix:special-variable name='*catch-errors-p*'>
3136 If the value of this variable is <code>NIL</code>
3137 (the default is <code>T</code>), then errors which happen while a
3138 request is handled aren't <a href="#logging">caught as usual</a>, but
3141 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_d.htm#debugger">debugger</a>
3143 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_invoke.htm">invoked</a>.
3144 This variable should obviously always be set to a <em>true</em> value
3145 in a production environment.
3146 See <clix:ref>MAYBE-INVOKE-DEBUGGER</clix:ref>
3147 if you want to fine-tune this behaviour.
3149 </clix:special-variable>
3151 <clix:special-variable name='*show-lisp-errors-p*'>
3153 Whether Lisp errors should be shown in HTML output. Note
3154 that this only affects canned responses generated by Lisp.
3155 If an error template is present for the "internal server
3156 error" status code, this special variable is not used (see
3157 <clix:ref>acceptor-status-message</clix:ref>).
3159 </clix:special-variable>
3161 <clix:special-variable name='*show-lisp-backtraces-p*'>
3163 Whether Lisp backtraces should be shown in HTML output if
3164 <clix:ref>*SHOW-LISP-ERRORS-P*</clix:ref> is true and an error occurs.
3166 </clix:special-variable>
3168 <clix:function generic='true' name='maybe-invoke-debugger'>
3169 <clix:lambda-list>condition
3174 This generic function is called whenever a
3176 href="http://www.lispworks.com/documentation/HyperSpec/Body/09_.htm">condition</a> <code><i>condition</i></code>
3177 is signaled in Hunchentoot. You might want to specialize it on
3178 specific condition classes for debugging purposes. The default
3180 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_invoke.htm">invokes
3181 the debugger</a> with <clix:arg>condition</clix:arg> if
3182 <clix:ref>*CATCH-ERRORS-P*</clix:ref> is <code>NIL</code>.
3186 <clix:condition name='hunchentoot-condition'>
3188 Superclass for all conditions related to Hunchentoot.
3192 <clix:condition name='hunchentoot-error'>
3194 Superclass for all errors related to Hunchentoot and a subclass of <clix:ref>HUNCHENTOOT-CONDITION</clix:ref>.
3198 <clix:condition name='parameter-error'>
3200 Signalled if a function was called with incosistent or illegal parameters. A subclass of <clix:ref>HUNCHENTOOT-ERROR</clix:ref>.
3204 <clix:condition name='hunchentoot-warning'>
3206 Superclass for all warnings related to Hunchentoot and a subclass of <clix:ref>HUNCHENTOOT-CONDITION</clix:ref>.
3212 <clix:subchapter name="misc" title="Miscellaneous">
3214 Various functions and variables which didn't fit into one of the
3217 <clix:function name='abort-request-handler'>
3222 <clix:returns>result
3225 This function can be called by a request handler
3226 at any time to immediately abort handling the request. This works as
3227 if the handler had returned <clix:arg>result</clix:arg>. See the
3228 source code of <clix:ref>REDIRECT</clix:ref> for an example.
3232 <clix:function name="handle-if-modified-since">
3233 <clix:lambda-list>time <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
3234 <clix:returns>|</clix:returns>
3236 This function is designed to be used inside
3237 a <a href="#request-dispatch">handler</a>. If the client has sent an
3238 'If-Modified-Since' header
3239 (see <a href="http://www.faqs.org/rfcs/rfc2616.html">RFC 2616</a>,
3240 section 14.25) and the time specified matches the universal
3242 <clix:arg>time</clix:arg> then the
3243 header <clix:ref>+HTTP-NOT-MODIFIED+</clix:ref> with no content
3244 is immediately returned to the client.
3246 Note that for this function to be useful you should usually
3247 send 'Last-Modified' headers back to the client. See the
3249 of <clix:ref>CREATE-STATIC-FILE-DISPATCHER-AND-HANDLER</clix:ref>
3255 <clix:function name="handle-static-file">
3256 <clix:lambda-list>path <clix:lkw>optional</clix:lkw> content-type</clix:lambda-list>
3257 <clix:returns>nil</clix:returns>
3259 Sends the file denoted by the pathname designator
3260 <clix:arg>path</clix:arg> with content type
3261 <clix:arg>content-type</clix:arg> to the client. Sets the
3262 necessary handlers. In particular the function employs
3263 <clix:ref>HANDLE-IF-MODIFIED-SINCE</clix:ref>.
3265 If <clix:arg>content-type</clix:arg> is <code>NIL</code> the
3266 function tries to determine the correct content type from
3267 the file's suffix or falls back
3268 to <code>"application/octet-stream"</code> as a last resort.
3271 Note that this function
3272 calls <clix:ref>SEND-HEADERS</clix:ref> internally, so after
3273 you've called it, the headers are sent and the return value
3274 of your handler is ignored.
3279 <clix:function name="redirect">
3280 <clix:lambda-list>target <clix:lkw>key</clix:lkw> host port protocol add-session-id code</clix:lambda-list>
3281 <clix:returns>|</clix:returns>
3283 Sends back appropriate headers to redirect the client
3284 to <clix:arg>target</clix:arg> (a string).
3286 If <clix:arg>target</clix:arg> is a full URL starting with a
3287 scheme, <clix:arg>host</clix:arg>, <clix:arg>port</clix:arg>,
3288 and <clix:arg>protocol</clix:arg> are ignored.
3289 Otherwise, <clix:arg>target</clix:arg> should denote the path
3290 part of a URL, <clix:arg>protocol</clix:arg> must be one of
3291 the keywords <code>:HTTP</code> or <code>:HTTPS</code>, and
3292 the URL to redirect to will be constructed
3293 from <clix:arg>host</clix:arg>, <clix:arg>port</clix:arg>, <clix:arg>protocol</clix:arg>,
3294 and <clix:arg>target</clix:arg>.
3297 <clix:arg>code</clix:arg> must be a 3xx HTTP redirection
3298 status code to send to the client. It defaults to 302
3299 ("Found"). If <clix:arg>host</clix:arg> is not provided,
3300 the current host (see <clix:ref>HOST</clix:ref>) will be
3301 used. If <clix:arg>protocol</clix:arg> is the keyword
3302 <code>:HTTPS</code>, the client will be redirected to a
3303 https URL, if it's <code>:HTTP</code> it'll be sent to a
3304 http URL. If both <clix:arg>host</clix:arg> and
3305 <clix:arg>protocol</clix:arg> aren't provided, then the
3306 value of <clix:arg>protocol</clix:arg> will match the
3312 <clix:function name="require-authorization">
3313 <clix:lambda-list><clix:lkw>optional</clix:lkw> realm</clix:lambda-list>
3314 <clix:returns>|</clix:returns>
3316 Sends back appropriate headers to require basic HTTP
3318 (see <a href="http://www.faqs.org/rfcs/rfc2617.html">RFC 2617</a>)
3319 for the realm <clix:arg>realm</clix:arg>. The default value
3320 for <clix:arg>realm</clix:arg> is <code>"Hunchentoot"</code>.
3324 <clix:function name='no-cache'>
3330 Adds appropriate headers to completely prevent caching on most browsers.
3334 <clix:function name='ssl-p'>
3337 </clix:lkw> acceptor
3339 <clix:returns>generalized-boolean
3342 Whether the current connection to the client is secure. See <clix:ref>ACCEPTOR-SSL-P</clix:ref>.
3346 <clix:function name='reason-phrase'>
3347 <clix:lambda-list>return-code
3349 <clix:returns>string
3352 Returns a reason phrase for the HTTP return code <clix:arg>return-code</clix:arg>
3353 (which should be an integer) or <code>NIL</code> for return codes Hunchentoot
3358 <clix:function name='rfc-1123-date'>
3363 <clix:returns>string
3366 Generates a time string according to <a href="http://www.faqs.org/rfcs/rfc1123.html">RFC 1123</a>. Default is current time.
3367 This can be used to send a 'Last-Modified' header - see <clix:ref>HANDLE-IF-MODIFIED-SINCE</clix:ref>.
3371 <clix:function name='url-encode'>
3372 <clix:lambda-list>string
3374 </clix:lkw> external-format
3376 <clix:returns>string
3379 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>.
3383 <clix:function name='url-decode'>
3384 <clix:lambda-list>string
3386 </clix:lkw> external-format
3388 <clix:returns>string
3391 Decodes a URL-encoded string which is assumed to
3392 be encoded using the external
3393 format <clix:arg>external-format</clix:arg>, i.e. this is the inverse
3394 of <clix:ref>URL-ENCODE</clix:ref>. It is assumed that you'll rarely
3395 need this function, if ever. But just in case - here it is. The
3396 default for <clix:arg>external-format</clix:arg> is the value
3397 of <clix:ref>*HUNCHENTOOT-DEFAULT-EXTERNAL-FORMAT*</clix:ref>.
3401 <clix:function name='escape-for-html'>
3402 <clix:lambda-list>string
3404 <clix:returns>result
3407 Escapes the characters #\<, #\>, #\', #\", and #\& for HTML output.
3411 <clix:function name="http-token-p">
3412 <clix:lambda-list>object</clix:lambda-list>
3413 <clix:returns>generalized-boolean</clix:returns>
3415 This function tests whether <clix:arg>object</clix:arg> is a
3416 non-empty string which is a <em>token</em> according
3417 to <a href="http://www.faqs.org/rfcs/rfc2068.html">RFC
3418 2068</a> (i.e. whether it may be used for, say, cookie names).
3422 <clix:function name='mime-type'>
3423 <clix:lambda-list>pathspec
3425 <clix:returns>result
3428 Given a pathname designator <clix:arg>pathspec</clix:arg> returns the <a href="http://en.wikipedia.org/wiki/Internet_media_type">MIME type</a>
3429 (as a string) corresponding to the suffix of the file denoted by
3430 <clix:arg>pathspec</clix:arg> (or <code>NIL</code>).
3434 <clix:function name='within-request-p'>
3437 <clix:returns>generalized-boolean
3440 Returns true if in the context of a request. Otherwise, <code>NIL</code>.
3444 <clix:special-variable name="*tmp-directory*">
3446 This should be a pathname denoting a directory where temporary
3447 files can be stored. It is used for <a href="#upload">file
3450 </clix:special-variable>
3452 <clix:special-variable name='*header-stream*'>
3454 If this variable is not <code>NIL</code>, it should be bound to a stream to
3455 which incoming and outgoing headers will be written for debugging
3458 </clix:special-variable>
3461 <clix:special-variable name='*cleanup-function*'>
3463 A designator for a function without arguments which is called on a
3464 regular basis if <clix:ref>*CLEANUP-INTERVAL*</clix:ref> is not <code>NIL</code>. The initial value is
3465 the name of a function which invokes a garbage collection on 32-bit
3466 versions of LispWorks.
3468 This variable is only available on LispWorks.
3471 </clix:special-variable>
3473 <clix:special-variable name='*cleanup-interval*'>
3475 Should be <code>NIL</code> or a positive integer. The system calls
3476 <clix:ref>*CLEANUP-FUNCTION*</clix:ref>
3477 whenever <clix:ref>*CLEANUP-INTERVAL*</clix:ref> new worker threads
3478 (counted globally across all acceptors) have been created unless the
3479 value is <code>NIL</code>. The initial value is 100.
3481 This variable is only available on LispWorks.
3484 </clix:special-variable>
3488 <clix:chapter name="testing" title="Testing">
3489 Hunchentoot comes with a test script which verifies that the
3490 example web server responds as expected. This test script uses the
3491 <a href="http://weitz.de/drakma/">Drakma</a> HTTP client library
3492 and thus shares a significant amount of its base code with
3493 Hunchentoot itself. Still, running the test script is a useful
3494 confidence test, and it is also possible to run the script across
3495 machines in order to verify a new Hunchentoot (or, for that matter
3498 To run the confidence test, <a href="#start">start
3499 the example web server</a>. Then, in your Lisp
3501 <pre>(<a class="noborder" href="hunchentoot-test:test-hunchentoot">hunchentoot-test:test-hunchentoot</a> "http://localhost:4242")</pre>
3502 You will see some diagnostic output and a summary line that
3503 reports whether any tests have failed. (You can also use the
3504 example certificate and key files in the test directory and
3505 start and test an https server instead.)
3508 <clix:function name="hunchentoot-test:test-hunchentoot">
3509 <clix:lambda-list>base-url <clix:lkw>key</clix:lkw></clix:lambda-list>
3510 <clix:returns>|</clix:returns>
3512 Runs the built-in confidence
3513 test. <clix:arg>base-url</clix:arg> is the base URL to use
3514 for testing, it should not have a trailing slash. The keyword
3515 arguments accepted are for future extension and should not
3518 The script expects the Hunchentoot example test server to be
3519 running at the given <clix:arg>base-url</clix:arg> and
3520 retrieves various pages from that server, expecting certain
3527 <clix:chapter name="debugging" title="Debugging">
3528 By default, Hunchentoot intercepts all errors that occur while
3529 executing request handlers, logs them to the log file and displays
3530 a static error page to the user. While developing applications,
3531 you may want to change that behavior so that the debugger is
3532 invoked when an error occurs. You can set
3533 the <clix:ref>*CATCH-ERRORS-P*</clix:ref> to <code>NIL</code> to
3534 make that happen. Alternatively, you may want to have Hunchentoot
3535 display detailed error information in the error response page.
3536 You can set the <clix:ref>*SHOW-LISP-ERRORS-P*</clix:ref> to a
3537 true value to make that happen. If you don't want to see Lisp
3538 backtraces in these error pages, you can
3539 set <clix:ref>*SHOW-LISP-BACKTRACES-P*</clix:ref>
3540 to <code>NIL</code>.
3543 <clix:chapter name="history" title="History">
3545 Hunchentoot's predecessor <a href="http://weitz.de/tbnl/">TBNL</a>
3546 (which is short for "To Be Named Later") grew over the years as a
3547 toolkit that I used for various commercial and private
3548 projects. In August 2003, Daniel Barlow started
3549 a <a href="http://article.gmane.org/gmane.lisp.web/148">review of
3551 the <a href="http://www.red-bean.com/lispweb/">lispweb</a> mailing
3553 I <a href="http://article.gmane.org/gmane.lisp.web/153">described</a>
3554 the API of my hitherto-unreleased bunch of code (and christened it
3558 <a href="http://www.jeffcaldwell.com/">Jeff Caldwell</a> had
3559 worked on something similar so he emailed me and proposed to
3560 join our efforts. As I had no immediate plans to release my code
3561 (which was poorly organized, undocumented, and mostly
3562 CMUCL-specific), I gave it to Jeff and he worked towards a
3563 release. He added docstrings, refactored, added some stuff, and
3564 based it on KMRCL to make it portable across several Lisp
3568 Unfortunately, Jeff is at least as busy as I am so he didn't
3569 find the time to finish a full release. But in spring 2004 I
3570 needed a documented version of the code for a client of mine who
3571 thought it would be good if the toolkit were publicly available
3572 under an open source license. So I took Jeff's code, refactored
3573 again (to sync with the changes I had done in the meantime), and
3574 added documentation. This resulted in TBNL 0.1.0 (which
3575 initially required mod_lisp as its front-end).
3578 In March 2005, Bob Hutchinson sent patches which enabled TBNL to
3579 use other front-ends than mod_lisp. This made me aware that
3580 TBNL was already <em>almost</em> a full web server, so
3581 eventually I wrote Hunchentoot which <em>was</em> a full web
3582 server, implemented as a wrapper around TBNL. Hunchentoot 0.1.0
3583 was released at the end of 2005 and was originally
3587 Hunchentoot 0.4.0, released in October 2006, was the first
3588 release which also worked with other Common Lisp
3589 implementations. It is a major rewrite and also incorporates
3590 most of TBNL and replaces it completely.
3593 Hunchentoot 1.0.0, released in February 2009, is again a major
3594 rewrite and should be considered work in progress. It moved to
3596 the <a href="http://common-lisp.net/project/usocket/">usocket</a>
3597 and <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux
3598 Threads</a> libraries for non-LispWorks Lisps, thereby removing most of
3599 the platform dependent code. Threading behaviour was made
3600 controllable through the introduction of
3601 taskmasters. <a href="http://www.cliki.net/mod_lisp">mod_lisp</a>
3602 support and several other things were removed in this release to
3603 simplify the code base (and partly due to the lack of interest).
3604 Several architectural changes (lots of them not
3605 backwards-compatible) were made to ease customization of
3606 Hunchentoot's behaviour. A significant part of the 1.0.0
3608 by <a href="http://netzhansa.blogspot.com/">Hans Hübner</a>.
3612 <clix:chapter name="index" title="Symbol index">
3614 Here are all exported symbols of the <code>HUNCHENTOOT</code>
3615 package in alphabetical order linked to their corresponding
3616 documentation entries:
3622 <clix:chapter name="ack" title="Acknowledgements">
3624 Thanks to Jeff Caldwell - TBNL would not have been released
3625 without his efforts. Thanks
3626 to <a href="http://www.cliki.net/Stefan%20Scholl">Stefan
3627 Scholl</a> and Travis Cross for various additions and fixes to
3628 TBNL, to <a href="http://www.foldr.org/~michaelw/">Michael
3629 Weber</a> for initial file upload code, and
3630 to <a href="http://www.ltn.lv/~jonis/">Janis Dzerins</a> for
3631 his <a href="http://common-lisp.net/project/rfc2388/">RFC 2388
3632 code</a>. Thanks to Bob Hutchison for his code for multiple
3633 front-ends (which made me realize that TBNL was already pretty
3634 close to a "real" web server) and the initial UTF-8 example.
3635 Thanks to <a href="http://netzhansa.blogspot.com/">Hans Hübner</a>
3636 for a lot of architectural and implementation enhancements for the
3637 1.0.0 release and also for transferring the documentation to sane
3638 XHTML. Thanks to John
3639 Foderaro's <a href="http://opensource.franz.com/aserve/index.html">AllegroServe</a>
3640 for inspiration. Thanks to <a href="http://www.htg1.de/">Uwe von
3642 the <a href="http://www.htg1.de/hunchentoot/hunchentoot.html">Hunchentoot
3646 Hunchentoot originally used code
3647 from <a href="http://www.cliki.net/ACL-COMPAT">ACL-COMPAT</a>,
3648 specifically the chunking code from Jochen Schmidt. (This has been
3649 replaced by <a href="http://weitz.de/chunga/">Chunga</a>.) When I ported
3650 Hunchentoot to other Lisps than LispWorks, I stole code from
3651 ACL-COMPAT, <a href="http://www.cliki.net/kmrcl">KMRCL</a>,
3652 and <a href="http://www.cliki.net/trivial-sockets">trivial-sockets</a> for
3653 implementation-dependent stuff like sockets and MP. (This has been replaced by
3654 <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux
3656 and <a href="http://common-lisp.net/project/usocket/">usocket</a>.)
3659 Parts of this documentation were prepared
3660 with <a href="http://weitz.de/documentation-template/">DOCUMENTATION-TEMPLATE</a>,
3661 no animals were harmed.
3665 <a href='http://weitz.de/index.html'>BACK TO MY HOMEPAGE
3668 </clix:documentation>