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 fully-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://postabon.com/">Postabon</a>,
62 <a href="http://www.city-farming.de/">City Farming</a>,
63 <a href="http://www.thoughtcrime.us/tp/">Trip Planner</a>,
64 <a href="http://clutu.com/">clutu</a>,
65 <a href="http://twitterbuzz.com/">TwitterBuzz</a>,
66 <a href="http://www.jalat.com/">Jalat</a>,
67 <a href="http://heikestephan.de/">Heike Stephan</a>,
68 <a href="http://www.memetrics.com/">xOs</a>, and
69 <a href="http://syseng.nist.gov/moss">the</a>
70 <a href="http://syseng.nist.gov/se-interop">NIST</a>.
73 <font color="red">Download shortcut:</font>
74 <a href="http://weitz.de/files/hunchentoot.tar.gz">http://weitz.de/files/hunchentoot.tar.gz</a>.
79 <clix:chapter name='contents' title='Contents'></clix:chapter>
80 <clix:contents></clix:contents>
82 <clix:chapter name="install" title="Download and installation">
83 Hunchentoot depends on a couple of other Lisp libraries which you'll need
86 <li>Pierre R. Mai's <a href="http://www.cliki.net/md5">MD5</a>,</li>
87 <li>Kevin Rosenberg's <a href="http://www.cliki.net/cl-base64">CL-BASE64</a>,</li>
88 <li>Janis Dzerins' <a href="http://common-lisp.net/project/rfc2388/">RFC2388</a>,</li>
89 <li>Peter Seibel's <a href="http://weitz.de/cl-fad/">CL-FAD</a>,</li>
90 <li>Gary King's <a href="http://common-lisp.net/project/trivial-backtrace/">trivial-backtrace</a>,</li>
91 <li>Erik Huelsmann's <a href="http://common-lisp.net/project/usocket">usocket</a> (unless you're using LispWorks),</li>
92 <li>Greg Pfeil's <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux Threads</a> (unless you're using LispWorks),
95 David Lichteblau's <a href="http://common-lisp.net/project/cl-plus-ssl/">CL+SSL</a>
96 (unless you're using LispWorks),
99 and my own <a href="http://weitz.de/flexi-streams/">FLEXI-STREAMS</a> (0.12.0 or higher),
100 <a href="http://weitz.de/chunga/">Chunga</a> (1.0.0 or
101 higher), and <a href="http://weitz.de/cl-ppcre/">
103 <a href="http://weitz.de/cl-who/">CL-WHO</a> for the <a href="#start">example code</a>
104 and <a href="http://weitz.de/drakma/">Drakma</a> for the <a href="#testing">tests</a>).
108 Make sure to use the <em>newest</em> versions of all of these
109 libraries (which might themselves depend on other libraries) - try
110 the repository versions if you're in doubt. Note: You can compile
111 Hunchentoot without SSL support - and thus without the need to
112 have CL+SSL - if you add <code>:HUNCHENTOOT-NO-SSL</code> to
113 <a href="http://www.lispworks.com/documentation/HyperSpec/Body/v_featur.htm">
114 <code>*FEATURES*</code></a> <em>before</em> you compile it.
116 Hunchentoot will only work with Lisps where
117 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#character_code">character
119 all <a href="http://en.wikipedia.org/wiki/ISO_8859-1">Latin-1</a>
120 characters coincide with their
121 Unicode <a href="http://en.wikipedia.org/wiki/Code_point">code
122 points</a> (which is the case for all current implementations I
126 Hunchentoot itself together with this documentation can be
128 <a href="http://weitz.de/files/hunchentoot.tar.gz">http://weitz.de/files/hunchentoot.tar.gz</a>.
129 The current version is 1.1.1.
132 The preferred method to compile and load Hunchentoot is via
133 <a href="http://www.cliki.net/asdf">ASDF</a>. If you think that
134 it's too much work to find and download all the libraries
135 mentioned above, try something like
136 <a href="http://common-lisp.net/project/asdf-install/">ASDF-INSTALL</a>,
137 <a href="http://common-lisp.net/project/clbuild/">clbuild</a>,
138 or my own <a href="http://weitz.de/starter-pack/">Starter
139 Pack</a>. There's also a port for
140 <a href="http://www.gentoo.org/proj/en/common-lisp/index.xml">Gentoo
141 Linux</a> thanks to Matthew Kennedy.
144 The current development version of Hunchentoot can be found
145 at <a href="http://bknr.net/trac/browser/trunk/thirdparty">http://bknr.net/trac/browser/trunk/thirdparty</a>.
146 This is the one to send <a href="#mail">patches</a> against.
147 Use at your own risk.
151 unofficial <a href="http://www.selenic.com/mercurial/wiki/">Mercurial</a>
152 repository of older versions is available at
153 <a href="http://arcanes.fr.eu.org/~pierre/2007/02/weitz/">http://arcanes.fr.eu.org/~pierre/2007/02/weitz/</a>
154 thanks to Pierre Thierry.
157 Luís Oliveira maintains an
158 unofficial <a href="http://darcs.net/">darcs</a> repository of
160 <a href="http://common-lisp.net/~loliveira/ediware/">http://common-lisp.net/~loliveira/ediware/</a>.
163 Andrey Moskvitin maintains an
164 unofficial <a href="http://git-scm.com/">git</a> repository of
166 <a href="http://github.com/archimag/hunchentoot">http://github.com/archimag/hunchentoot</a>.
169 <clix:subchapter name="proxy" title="Hunchentoot behind a proxy">
171 If you're feeling unsecure about exposing Hunchentoot to the wild,
172 wild Internet or if your Lisp web application is part of a larger
173 website, you can hide it behind a
174 <a href="http://en.wikipedia.org/wiki/Proxy_server">proxy server</a>.
175 One approach that I have used several times is to employ Apache's
176 <a href="http://httpd.apache.org/docs/2.0/mod/mod_proxy.html">mod_proxy</a>
177 module with a configuration that looks like this:
179 <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
180 <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>
182 This will tunnel all requests where the URI path begins with
183 <code>"/hunchentoot"</code> to a (Hunchentoot) server listening on
184 port 3000 on the same machine.
188 <a href="http://www.red-bean.com/pipermail/lispweb/2006-October/001342.html">several
189 other</a> (more lightweight) web proxies that you could use
195 <clix:chapter name="mail" title="Support and mailing lists">
197 For questions, bug reports, feature requests, improvements, or
198 patches please use the
199 <a href="http://common-lisp.net/mailman/listinfo/tbnl-devel">tbnl-devel
200 mailing list</a>. If you want to be notified about future
201 releases subscribe to the
202 <a href="http://common-lisp.net/mailman/listinfo/tbnl-announce">tbnl-announce
203 mailing list</a>. These mailing lists were made available thanks
205 <a href="http://common-lisp.net/">common-lisp.net</a>. You can
206 <b>search</b> the devel mailing list
207 <a href="http://google.com/coop/cse?cx=002927904911724867201%3A0l5rif_cxj0">here</a>
208 (thanks to Tiarnán Ó Corráin).
210 If you want to send patches, please
211 <a href="http://weitz.de/patches.html">read this first</a>.
215 <clix:chapter name="start" title="Your own webserver (the easy teen-age New York version)">
216 Starting your own web server is pretty easy. Do something like this:
217 <pre>(hunchentoot:<a class="noborder" href="#start">start</a> (make-instance 'hunchentoot:<a class="noborder" href="#acceptor">easy-acceptor</a> :port 4242))</pre>
218 That's it. Now you should be able to enter the address
219 "<a href='http://127.0.0.1:4242/'><code>http://127.0.0.1:4242/</code></a>" in
220 your browser and see something, albeit nothing very interesting
224 Now be a bit more adventurous, try this
225 <pre>(hunchentoot:<a class="noborder" href="#define-easy-handler">define-easy-handler</a> (say-yo :uri "/yo") (name)
226 (setf (hunchentoot:<a class="noborder" href="#content-type*">content-type*</a>) "text/plain")
227 (format nil "Hey~@[ ~A~]!" name))</pre>
228 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
229 "<a href='http://127.0.0.1:4242/yo?name=Dude'><code>http://127.0.0.1:4242/yo?name=Dude</code></a>" .
233 Hunchentoot comes with a little example website which you can use
234 to see if it works and which should also demonstrate a couple of
235 the things you can do with Hunchentoot. To start the example
236 website, enter the following code into your listener:
238 <pre>(<a class="noborder" href="http://common-lisp.net/~mmommer/asdf-howto.shtml#sec11">asdf:oos</a> 'asdf:load-op :hunchentoot-test)</pre>
240 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.
244 <clix:chapter name="tutorials" title="Tutorials and add-ons">
246 Here are some Hunchentoot tutorials done by others:
250 <a href="http://www.adampetersen.se/articles/lispweb.htm">"Lisp for the Web"</a> by Adam Petersen.
253 Two <a href="http://myblog.rsynnott.com/2007/09/getting-started-with-hunchento.html">getting</a>
254 <a href="http://myblog.rsynnott.com/2007/10/doing-more-with-hunchentoot-cl-server.html">started</a>
255 articles by Robert Synnott.
258 <a href="http://www.newartisans.com/blog_files/common.lisp.with.apache.php">Running Common Lisp
259 behind Apache</a> by John Wiegley. (And there's a
260 <a href="http://www.newartisans.com/blog_files/hunchentoot.primer.php">second part</a>.)
263 A <a href="http://www.lispcast.com/index.php/2007/10/lispcast-writing-a-simple-reddit-clone-in-common-lisp/">"LispCast"</a>
264 by Eric Normand about writing a <a href="http://reddit.com/">Reddit</a> clone using
265 Hunchentoot. Apparently the first part of a
266 <a href="http://bc.tech.coop/blog/071028.html">series</a>.
269 A <a href="http://roeim.net/vetle/docs/cl-webapp-intro/">tutorial</a> about
270 implementing a blog in Common Lisp by Vetle Roeim.
273 A <a href="http://www.jalat.com/blogs/lisp?id=3">tutorial</a> for (an older version of)
274 Hunchentoot by Asbjørn Bjørnstad.
277 A <a href="http://www.frank-buss.de/lisp/tbnl.html">TBNL tutorial</a> from Frank Buss.
278 (Hunchentoot is not <a href="http://weitz.de/tbnl/">TBNL</a>, but the two are similar enough
279 to make the tutorial worthwhile.)
283 Clementson <a href="http://bc.tech.coop/blog/041105.html">explains</a>
284 how to set up Hunchentoot's
285 predecessor <a href="http://weitz.de/tbnl/">TBNL</a> with
287 also <a href="http://bc.tech.coop/blog/061013.html">http://bc.tech.coop/blog/061013.html</a>.
291 Check the dates of these tutorials! Many of them might not be a
292 perfect fit with the latest release of Hunchentoot as there have
293 been several changes to its API recently, especially in 2009.
294 Also, the fact that these tutorials are listed here doesn't
295 necessarily mean that I endorse them or think that they show
296 idiomatic Lisp code. You'll have to decide yourself if they're
297 helpful to you or not.
300 Here is some software which extends Hunchentoot or is based on it:
303 <li>Tomo Matsumoto's web application
304 framework <a href="http://web4r.org/en/">web4r</a>.
307 <a href="http://common-lisp.net/project/cl-weblocks/">Weblocks</a>
308 by Slava Akhmechet is a "continuations-based web framework" which is
309 based on Hunchentoot.
312 <a href="http://pen.two-bytes.com/misc/ht-ajax.html">HT-AJAX</a> is
313 an <a href="http://en.wikipedia.org/wiki/Ajax_%28programming%29">Ajax</a>
314 framework for Hunchentoot by Ury Marshak.
318 <a href="http://common-lisp.net/pipermail/tbnl-devel/2007-May/001324.html">has
319 ported <a href="http://lemonodor.com/">John Wiseman</a>'s
320 <a href="http://www.lemonodor.com/archives/000128.html">Lisp
321 Server Pages</a> to Hunchentoot.</a>
324 <a href="http://site.znain.com/dl/lisp/hunchentoot-dir-lister/">hunchentoot-dir-lister</a>
325 is a directory listing addition for Hunchentoot by Dimitre Liotev.
329 <a href="http://cyrusharmon.org/blog/display?id=64">nuclblog</a> is a
330 <a href="http://en.wikipedia.org/wiki/Blog">blog</a> engine which uses Hunchentoot.
333 <a href="http://cyrusharmon.org/projects?project=hunchentoot-cgi">hunchentoot-cgi</a>
334 (also by Cyrus Harmon) provides
335 <a href="http://en.wikipedia.org/wiki/Common_Gateway_Interface">CGI</a>
336 handlers for Hunchentoot.
339 <a href="http://weitz.de/cl-webdav/">CL-WEBDAV</a> is a <a href="http://webdav.org/">WebDAV</a>
340 server based on Hunchentoot.
343 <a href="http://restas.lisper.ru/">RESTAS</a> is a web
344 framework based on Hunchentoot.
349 <clix:chapter name="reference" title="Function and variable reference">
351 <clix:subchapter name="acceptors" title="Acceptors">
353 If you want Hunchentoot to actually do something, you have to create and
354 <a href="#start">start</a> an <a href="#acceptor">acceptor</a>.
355 You can also run several acceptors in one image, each one
356 listening on a different different port.
358 <clix:class name='acceptor'>
360 To create a Hunchentoot webserver, you make an instance of
361 this class and use the generic function
362 <clix:ref>START</clix:ref> to start it (and
363 <clix:ref>STOP</clix:ref> to stop it). Use the
364 <code>:port</code> initarg if you don't want to listen
365 on the default http port 80. There are other initargs most
366 of which you probably won't need very often. They are
367 explained in detail in the docstrings of the slot
368 definitions for this class.
370 Unless you are in a Lisp without MP capabilities, you can
371 have several active instances of
372 <clix:ref>ACCEPTOR</clix:ref> (listening on different
373 ports) at the same time.
378 <clix:class name='ssl-acceptor'>
379 <clix:description>Create and <clix:ref>START</clix:ref> an instance of this class
380 (instead of <clix:ref>ACCEPTOR</clix:ref>) if you want an https server. There are two
381 required initargs, <code>:SSL-CERTIFICATE-FILE</code> and <code>:SSL-PRIVATEKEY-FILE</code>, for
382 pathname designators denoting the certificate file and the key file in
383 PEM format. On LispWorks, you can have both in one file in which case
384 the second initarg is optional. You can also use the
385 <code>:SSL-PRIVATEKEY-PASSWORD</code> initarg to provide a password
386 (as a string) for the key file (or <code>NIL</code>, the default, for
389 The default port for <clix:ref>SSL-ACCEPTOR</clix:ref> instances is 443 instead of 80
394 <clix:function generic='true' name='start'>
395 <clix:lambda-list>acceptor
397 <clix:returns>acceptor
399 <clix:description>Starts <clix:arg>acceptor</clix:arg> so that it begins accepting
400 connections. Returns the acceptor.
404 <clix:function generic='true' name='stop'>
405 <clix:lambda-list>acceptor
407 <clix:returns>acceptor
409 <clix:description>Stops <clix:arg>acceptor</clix:arg> so that it
410 no longer accepts requests.
414 <clix:special-variable name='*acceptor*'>
415 <clix:description>The current ACCEPTOR object in the context of a request.
417 </clix:special-variable>
419 <clix:readers generic='true'>
420 <clix:listed-reader generic='true' name='acceptor-address'>
421 <clix:lambda-list>acceptor
423 <clix:returns>address
425 </clix:listed-reader>
427 <clix:listed-reader generic='true' name='acceptor-port'>
428 <clix:lambda-list>acceptor
432 </clix:listed-reader>
434 <clix:listed-reader generic='true' name='acceptor-read-timeout'>
435 <clix:lambda-list>acceptor
437 <clix:returns>read-timeout
439 </clix:listed-reader>
441 <clix:listed-reader generic='true' name='acceptor-ssl-certificate-file'>
442 <clix:lambda-list>ssl-acceptor
444 <clix:returns>ssl-certificate-file
446 </clix:listed-reader>
448 <clix:listed-reader generic='true' name='acceptor-ssl-privatekey-file'>
449 <clix:lambda-list>ssl-acceptor
451 <clix:returns>ssl-privatekey-file
453 </clix:listed-reader>
455 <clix:listed-reader generic='true' name='acceptor-ssl-privatekey-password'>
456 <clix:lambda-list>ssl-acceptor
458 <clix:returns>ssl-privatekey-password
460 </clix:listed-reader>
462 <clix:listed-reader generic='true' name='acceptor-ssl-certificate-file'>
463 <clix:lambda-list>listen-backlog
465 <clix:returns>number-of-pending-connections
467 </clix:listed-reader>
470 Number of pending connections allowed in the listen socket
471 before the kernel rejects further incoming connections.
475 <clix:listed-reader generic='true' name='acceptor-write-timeout'>
476 <clix:lambda-list>acceptor
478 <clix:returns>write-timeout
480 </clix:listed-reader>
483 These are readers for various slots of <clix:ref>ACCEPTOR</clix:ref>
484 objects (and some of them obviously only make sense
485 for <clix:ref>SSL-ACCEPTOR</clix:ref> objects). See the docstrings of
486 these slots for more information and note that there are corresponding
487 initargs for all of them.
491 <clix:accessors generic='true'>
492 <clix:listed-accessor generic='true' name='acceptor-access-log-destination'>
493 <clix:lambda-list>acceptor
495 <clix:returns>(or pathname null)
497 </clix:listed-accessor>
499 <clix:listed-accessor generic='true' name='acceptor-error-template-directory'>
500 <clix:lambda-list>acceptor
502 <clix:returns>(or pathname null)
504 </clix:listed-accessor>
506 <clix:listed-accessor generic='true' name='acceptor-input-chunking-p'>
507 <clix:lambda-list>acceptor
509 <clix:returns>input-chunking-p
511 </clix:listed-accessor>
513 <clix:listed-accessor generic='true' name='acceptor-message-log-destination'>
514 <clix:lambda-list>acceptor
516 <clix:returns>(or pathname null)
518 </clix:listed-accessor>
520 <clix:listed-accessor generic='true' name='acceptor-name'>
521 <clix:lambda-list>acceptor
525 </clix:listed-accessor>
527 <clix:listed-accessor generic='true' name='acceptor-output-chunking-p'>
528 <clix:lambda-list>acceptor
530 <clix:returns>output-chunking-p
532 </clix:listed-accessor>
534 <clix:listed-accessor generic='true' name='acceptor-persistent-connections-p'>
535 <clix:lambda-list>acceptor
537 <clix:returns>persistent-connections-p
539 </clix:listed-accessor>
541 <clix:listed-accessor generic='true' name='acceptor-reply-class'>
542 <clix:lambda-list>acceptor
544 <clix:returns>reply-class
546 </clix:listed-accessor>
548 <clix:listed-accessor generic='true' name='acceptor-request-class'>
549 <clix:lambda-list>acceptor
551 <clix:returns>request-class
553 </clix:listed-accessor>
555 <clix:listed-accessor generic='true' name='acceptor-request-dispatcher'>
556 <clix:lambda-list>acceptor
558 <clix:returns>request-dispatcher
560 </clix:listed-accessor>
563 These are accessors for various slots of <clix:ref>ACCEPTOR</clix:ref>
564 objects. See the docstrings of these slots for more information and
565 note that there are corresponding initargs for all of them.
569 <clix:function generic='true' name='acceptor-ssl-p'>
570 <clix:lambda-list>acceptor
572 <clix:returns>generalized-boolean
574 <clix:description>Returns a true value if <clix:arg>acceptor</clix:arg> uses SSL
575 connections. The default is to unconditionally return <code>NIL</code> and
576 subclasses of <clix:ref>ACCEPTOR</clix:ref> must specialize this method to signal that
577 they're using secure connections - see the <clix:ref>SSL-ACCEPTOR</clix:ref> class.
581 <clix:special-variable name='*default-connection-timeout*'>
582 <clix:description>The default connection timeout used when an
583 acceptor is reading from and writing to a socket stream. Note that
584 some Lisps allow you to set different timeouts for reading and writing
585 and you can specify both values via initargs when you create
586 an <a href="#acceptors">acceptor</a>.
588 </clix:special-variable>
592 <clix:subchapter name="acceptor-behaviour" title="Customizing acceptor behaviour">
594 If you want to modify what acceptors do, you should subclass
595 <clix:ref>ACCEPTOR</clix:ref> (or
596 <clix:ref>SSL-ACCEPTOR</clix:ref>) and specialize the generic
597 functions that constitute their behaviour. The life of an
598 acceptor looks like this: It is started with the function
599 <clix:ref>START</clix:ref> which immediately calls
600 <clix:ref>START-LISTENING</clix:ref> and then applies the
601 function <clix:ref>EXECUTE-ACCEPTOR</clix:ref> to its <a
602 href="#taskmasters">taskmaster</a>. This function will
603 eventually call <clix:ref>ACCEPT-CONNECTIONS</clix:ref> which is
604 responsible for settings things up to wait for clients to
605 connect. For each connection which comes in,
606 <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref> is applied to
607 the taskmaster which will either call
608 <clix:ref>PROCESS-CONNECTION</clix:ref> directly,
609 or will create a thread to call it.
610 <clix:ref>PROCESS-CONNECTION</clix:ref> calls
611 <clix:ref>INITIALIZE-CONNECTION-STREAM</clix:ref> before it does
612 anything else, then it selects and calls a function which
613 handles the <a href="#requests">request</a>, and finally it
614 sends the <a href="#replies">reply</a> to the client before it
615 calls <clix:ref>RESET-CONNECTION-STREAM</clix:ref>. If the
616 connection is persistent, this procedure is repeated (except for
617 the intialization step) in a loop until the connection is
618 closed. The acceptor is stopped with <clix:ref>STOP</clix:ref>.
621 If you just want to use the standard acceptors that come with
622 Hunchentoot, you don't need to know anything about the functions
623 listed in this section.
626 <clix:function generic='true' name='start-listening'>
627 <clix:lambda-list>acceptor
631 <clix:description>Sets up a listen socket for the given acceptor and
632 enables it to listen to incoming connections. This function is called
633 from the thread that starts the acceptor initially and may return
634 errors resulting from the listening operation (like 'address in use'
639 <clix:function generic='true' name='accept-connections'>
640 <clix:lambda-list>acceptor
644 <clix:description>In a loop, accepts a connection and hands it over
645 to the acceptor's taskmaster for processing using
646 <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref>. On LispWorks, this
647 function returns immediately, on other Lisps it returns only once the
648 acceptor has been stopped.
652 <clix:function generic='true' name='process-connection'>
653 <clix:lambda-list>acceptor socket
658 This function is called by the taskmaster when a new client
659 connection has been established. Its arguments are the
660 <clix:ref>ACCEPTOR</clix:ref> object and a LispWorks socket
661 handle or a usocket socket stream object in
662 <clix:arg>socket</clix:arg>. It reads the request headers,
663 sets up the <a href="#requests">request</a> and <a
664 href="#replies">reply</a> objects, and hands over to
665 <clix:ref>PROCESS-REQUEST</clix:ref> which calls
666 <clix:ref>HANDLE-REQUEST</clix:ref> to select and call a
667 handler for the request and sends its reply to the client.
668 This is done in a loop until the stream has to be closed or
669 until a connection timeout occurs. It is probably not a
670 good idea to re-implement this method until you really,
671 really know what you're doing.
675 <clix:function generic='true' name='initialize-connection-stream'>
676 <clix:lambda-list>acceptor stream
681 Can be used to modify the stream which is used to
682 communicate between client and server before the request is
683 read. The default method of <clix:ref>ACCEPTOR</clix:ref>
684 does nothing, but see for example the method defined for
685 <clix:ref>SSL-ACCEPTOR</clix:ref>. All methods of this
686 generic function <em>must</em> return the stream to use.
690 <clix:function generic='true' name='reset-connection-stream'>
691 <clix:lambda-list>acceptor stream
696 Resets the stream which is used to communicate
697 between client and server after one request has been served so that it
698 can be used to process the next request. This generic function is
699 called after a request has been processed and <em>must</em> return the
704 <clix:function name="acceptor-log-access" generic="true">
705 <clix:lambda-list>acceptor &key return-code content content-length</clix:lambda-list>
707 Function to call to log access to the acceptor. The <clix:arg>return-code</clix:arg>,
708 <clix:arg>content</clix:arg> and <clix:arg>content-length</clix:arg> keyword arguments contain additional
709 information about the request to log. In addition, it can use the
710 standard request accessor functions that are available to handler
711 functions to find out more information about the request.
715 <clix:function name="acceptor-log-message" generic="true">
716 <clix:lambda-list>acceptor log-level format-string &rest format-arguments</clix:lambda-list>
718 Function to call to log messages by the <clix:arg>acceptor</clix:arg>. It must accept
719 a severity level for the message, which will be one of :ERROR, :INFO,
720 or :WARNING, a format string and an arbitary number of formatting
725 <clix:function name="acceptor-status-message" generic="true">
726 <clix:lambda-list>acceptor http-return-code content</clix:lambda-list>
728 This function is called after the request's handler has been
729 invoked to convert the <clix:arg>HTTP-STATUS-CODE</clix:arg>
730 to a HTML message to be displayed to the user. If this
731 function returns a string, that string is sent to the client
732 instead of the content produced by the handler, if any.
734 If an ERROR-TEMPLATE-DIRECTORY is set in the current
735 acceptor and the directory contains a file corresponding to
736 HTTP-STATUS-CODE named <code>.html, that file is sent
737 to the client after variable substitution. Variables are
738 referenced by ${<variable-name>}.
740 Additional keyword arguments may be provided which are made
741 available to the templating logic as substitution variables.
742 These variables can be interpolated into error message
743 templates in, which contains the current URL relative to the
744 server and without GET parameters.
746 In addition to the variables corresponding to keyword
747 arguments, the script-name, lisp-implementation-type,
748 lisp-implementation-version and hunchentoot-version
749 variables are available.
755 <clix:subchapter name="taskmasters" title="Taskmasters">
756 As a "normal" Hunchentoot user, you can completely ignore
757 taskmasters and skip this section. But if you're still reading,
758 here are the dirty details: Each <a
759 href="#acceptors">acceptor</a> has a taskmaster associated with
760 it at creation time. It is the taskmaster's job to distribute
761 the work of accepting and handling incoming connections. The
762 acceptor calls the taskmaster if appropriate and the taskmaster
763 calls back into the acceptor. This is done using the generic
764 functions described in this and the <a
765 href="#acceptor-behaviour">previous</a> section. Hunchentoot
766 comes with two standard taskmaster implementations - one (which
767 is the default used on multi-threaded Lisps) which starts a new
768 thread for each incoming connection and one which handles all
769 requests sequentially. It should for example be relatively
770 straightforward to create a taskmaster which allocates threads
771 from a fixed pool instead of creating a new one for each
775 You can control the resources consumed by a threaded taskmaster via
776 two initargs. <code>:max-thread-count</code> lets you set the maximum
777 number of request threads that can be processes simultaneously. If
778 this is <code>nil</code>, the is no thread limit imposed.
780 <code>:max-accept-count</code> lets you set the maximum number of requests
781 that can be outstanding (i.e. being processed or queued for processing).
783 If <code>:max-thread-count</code> is supplied and <code>:max-accept-count</code>
784 is <code>NIL</code>, then a <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>
785 error will be generated if there are more than the max-thread-count
786 threads processing requests. If both <code>:max-thread-count</code>
787 and <code>:max-accept-count</code> are supplied, then max-thread-count
788 must be less than max-accept-count; if more than max-thread-count
789 requests are being processed, then requests up to max-accept-count
790 will be queued until a thread becomes available. If more than
791 max-accept-count requests are outstanding, then a <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>
792 error will be generated.
794 In a load-balanced environment with multiple Hunchentoot servers, it's
795 reasonable to provide <code>:max-thread-count</code> but leave
796 <code>:max-accept-count</code> null. This will immediately result
797 in <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref> when one server is
798 out of resources, so the load balancer can try to find another server.
800 In an environment with a single Hunchentoot server, it's reasonable
801 to provide both <code>:max-thread-count</code> and a somewhat larger value
802 for <code>:max-accept-count</code>. This will cause a server that's almost
803 out of resources to wait a bit; if the server is completely out of resources,
804 then the reply will be <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>.
805 The default for these values is 100 and 120, respectively.
809 If you want to implement your own taskmasters, you should subclass
810 <clix:ref>TASKMASTER</clix:ref> or one of its subclasses,
811 <clix:ref>SINGLE-THREADED-TASKMASTER</clix:ref> or
812 <clix:ref>ONE-THREAD-PER-CONNECTION-TASKMASTER</clix:ref>, and
813 specialize the generic functions in this section.
816 <clix:class name='taskmaster'>
818 An instance of this class is responsible for distributing
819 the work of handling requests for its acceptor. This is an
820 "abstract" class in the sense that usually only instances of
821 subclasses of <clix:ref>TASKMASTER</clix:ref> will be used.
825 <clix:class name='one-thread-per-connection-taskmaster'>
827 A taskmaster that starts one thread for listening to
828 incoming requests and one thread for each incoming
831 This is the default taskmaster implementation for multi-threaded Lisp
837 <clix:class name='single-threaded-taskmaster'>
839 A taskmaster that runs synchronously in the
840 thread where the <clix:ref>START</clix:ref> function was invoked (or
841 in the case of LispWorks in the thread started
842 by <a href="http://www.lispworks.com/documentation/lw51/LWRM/html/lwref-61.htm#marker-910861"><code>COMM:START-UP-SERVER</code></a>).
843 This is the simplest possible taskmaster implementation in that its
844 methods do nothing but calling their acceptor "sister"
845 methods - <clix:ref>EXECUTE-ACCEPTOR</clix:ref> calls <clix:ref>ACCEPT-CONNECTIONS</clix:ref>,
846 <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref> calls <clix:ref>PROCESS-CONNECTION</clix:ref>.
850 <clix:function generic='true' name='execute-acceptor'>
851 <clix:lambda-list>taskmaster
855 <clix:description>This is a callback called by the acceptor once it
856 has performed all initial processing to start listening for incoming
857 connections (see <clix:ref>START-LISTENING</clix:ref>). It usually calls the
858 <clix:ref>ACCEPT-CONNECTIONS</clix:ref> method of the acceptor, but depending on the
859 taskmaster instance the method might be called from a new thread.
863 <clix:function generic='true' name='handle-incoming-connection'>
864 <clix:lambda-list>taskmaster socket
869 This function is called by the acceptor to start
870 processing of requests on a new incoming connection. <clix:arg>socket</clix:arg> is the
871 usocket instance that represents the new connection (or a socket
872 handle on LispWorks). The taskmaster starts processing requests on
873 the incoming connection by calling the <clix:ref>PROCESS-CONNECTION</clix:ref>
874 method of the acceptor instance. The <clix:arg>socket</clix:arg> argument is passed to
875 <clix:ref>PROCESS-CONNECTION</clix:ref> as an argument.
877 If the taskmaster is a multi-threaded taskmaster, <clix:ref>HANDLE-INCOMING-THREAD</clix:ref>
878 will call <clix:ref>CREATE-TASKMASTER-THREAD</clix:ref>, which will call
879 <clix:ref>PROCESS-CONNECTION</clix:ref> in a new thread.
880 <clix:ref>HANDLE-INCOMING-THREAD</clix:ref> might issue a
881 <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref> error
882 if there are too many request threads or it might block waiting for a
883 request thread to finish.
887 <clix:function generic='true' name='create-taskmaster-thread'>
888 <clix:lambda-list>taskmaster socket
892 <clix:description>This function is called by <clix:ref>HANDLE-INCOMING-THREAD</clix:ref>
893 to create a new thread which calls <clix:ref>PROCESS-CONNECTION</clix:ref>.
894 If you specialize this function, you must be careful to have the thread
895 call <clix:ref>DECREMENT-TASKMASTER-REQUEST-COUNT</clix:ref> before
896 it exits. A typical method will look like this:
898 <pre>(defmethod create-taskmaster-thread ((taskmaster monitor-taskmaster) socket)
901 (with-monitor-error-handlers
903 (with-monitor-variable-bindings
904 (process-connection (taskmaster-acceptor taskmaster) socket))
905 (decrement-taskmaster-request-count taskmaster))))))</pre>
916 <clix:function generic='true' name='shutdown'>
917 <clix:lambda-list>taskmaster
919 <clix:returns>taskmaster
921 <clix:description>Shuts down the taskmaster, i.e. frees all resources
922 that were set up by it. For example, a multi-threaded taskmaster
923 might terminate all threads that are currently associated with it.
924 This function is called by the acceptor's <clix:ref>STOP</clix:ref> method.
928 <clix:accessor generic='true' name='taskmaster-acceptor'>
929 <clix:lambda-list>taskmaster
931 <clix:returns>acceptor
934 This is an accessor for the slot of a <clix:ref>TASKMASTER</clix:ref>
935 object that links back to the <a href="#acceptors">acceptor</a> it is
942 <clix:subchapter name="request-dispatch" title="Request dispatch and handling">
944 The main job of <clix:ref>HANDLE-REQUEST</clix:ref> is to select
945 and call a function which handles the request, i.e. which looks
946 at the data the client has sent and prepares an appropriate
947 reply to send back. This is by default implemented as follows:
949 Each acceptor has a <a href="#acceptor-request-dispatcher"><em>request
950 dispatcher</em></a> which is a unary function that accepts
951 a <clix:ref>REQUEST</clix:ref> object. This function is called by the
952 default method of <clix:ref>HANDLE-REQUEST</clix:ref>. The idea is
953 that this function looks at the request object and depending on its
954 contents decides to call another function which "does the work". This
955 "other" function is by convention called a <a class="none"
956 name="handlers"><em>request handler</em></a>. (Obviously, this is
957 really only a convention as <clix:ref>HANDLE-REQUEST</clix:ref>
958 doesn't "know" what the request dispatcher does. You could as well
959 say that the request dispatcher and the request handler have the same
963 The default behaviour, unless your acceptor has its own request
964 dispatcher, is that Hunchentoot walks through the list
965 <clix:ref>*DISPATCH-TABLE*</clix:ref> which consists of <em>dispatch
966 functions</em>. Each of these functions accepts the request object as
967 its only argument and either returns a request handler to handle the
968 request or <code>NIL</code> which means that the next dispatcher in
969 the list will be tried. If all dispatch functions
970 return <code>NIL</code>, the return code
971 <clix:ref>+HTTP-NOT-FOUND+</clix:ref> will be sent to the client.
974 The default method of <clix:ref>HANDLE-REQUEST</clix:ref> also sets up
975 <a href="#logging">standard error handling</a> before it calls the acceptor's request
979 All functions and variables in this section are related to the
980 standard request dispatch mechanism described above and are
981 meaningless if you're using your own request dispatcher.
984 Request handlers do their work by modifying
985 the <a href="#replies">reply object</a> if necessary and by eventually
986 returning the response body in the form of a string or a binary
987 sequence. As an alternative, they can also
988 call <clix:ref>SEND-HEADERS</clix:ref> and write directly to a stream.
991 <clix:special-variable name='*dispatch-table*'>
993 A global list of dispatch functions. The initial value is a
994 list consisting of the two symbols
995 <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref> and
996 <clix:ref>DEFAULT-DISPATCHER</clix:ref>.
998 </clix:special-variable>
1000 <clix:function name='default-dispatcher'>
1001 <clix:lambda-list>request
1003 <clix:returns>result
1006 Default dispatch function which handles every request with
1007 the function stored in
1008 <clix:ref>*DEFAULT-HANDLER*</clix:ref>.
1012 <clix:special-variable name='*default-handler*'>
1013 <clix:description>The name of the function which is always returned by
1014 <clix:ref>DEFAULT-DISPATCHER</clix:ref>.
1016 </clix:special-variable>
1018 <clix:function name="create-prefix-dispatcher">
1019 <clix:lambda-list>prefix handler</clix:lambda-list>
1020 <clix:returns>dispatch-fn</clix:returns>
1022 A convenience function which will return a dispatcher that
1023 returns <clix:arg>handler</clix:arg> whenever the path part of
1024 the request URI starts with the
1025 string <clix:arg>prefix</clix:arg>.
1029 <clix:function name="create-regex-dispatcher">
1030 <clix:lambda-list>regex handler</clix:lambda-list>
1031 <clix:returns>dispatch-fn</clix:returns>
1033 A convenience function which will return a dispatcher that
1034 returns <clix:arg>handler</clix:arg> whenever the path part of
1035 the request URI matches
1036 the <a href="http://weitz.de/cl-ppcre/">CL-PPCRE</a> regular
1037 expression <clix:arg>regex</clix:arg> (which can be a string, an
1038 s-expression, or a scanner).
1042 <clix:function name="create-folder-dispatcher-and-handler">
1043 <clix:lambda-list>uri-prefix base-path <clix:lkw>optional</clix:lkw> content-type</clix:lambda-list>
1044 <clix:returns>dispatch-fn</clix:returns>
1046 Creates and returns a dispatch function which will dispatch to
1047 a handler function which emits the file relative
1048 to <clix:arg>base-path</clix:arg> that is denoted by the URI of
1049 the request relative
1050 to <clix:arg>uri-prefix</clix:arg>. <clix:arg>uri-prefix</clix:arg>
1051 must be a string ending with a
1052 slash, <clix:arg>base-path</clix:arg> must be a pathname
1053 designator for an existing directory.
1054 Uses <clix:ref>HANDLE-STATIC-FILE</clix:ref> internally.
1056 If <clix:arg>content-type</clix:arg> is <em>not</em>
1057 <code>NIL</code>, it will be used as a the content type for
1058 all files in the folder. Otherwise (which is the default)
1059 the content type of each file will be
1060 determined <a href="#handle-static-file">as usual</a>.
1065 <clix:function name='create-static-file-dispatcher-and-handler'>
1066 <clix:lambda-list>uri path
1068 </clix:lkw> content-type
1070 <clix:returns>result
1073 Creates and returns a request dispatch function which will
1074 dispatch to a handler function which emits the file denoted
1075 by the pathname designator PATH with content type
1076 CONTENT-TYPE if the SCRIPT-NAME of the request matches the
1077 string URI. If CONTENT-TYPE is NIL, tries to determine the
1078 content type via the file's suffix.
1082 <clix:function macro="true" name="define-easy-handler">
1083 <clix:lambda-list>description lambda-list [[declaration* | documentation]] form*</clix:lambda-list>
1085 Defines a handler as if
1086 by <a href="http://www.lispworks.com/documentation/HyperSpec/Body/m_defun.htm">
1087 <code>DEFUN</code></a> and optionally registers it with a
1088 URI so that it will be found
1089 by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>.
1091 <clix:arg>description</clix:arg> is either a
1092 symbol <clix:arg>name</clix:arg> or a list matching the
1093 <a href="http://www.lispworks.com/documentation/HyperSpec/Body/03_de.htm">destructuring
1096 <pre>(name &key uri acceptor-names default-parameter-type default-request-type).</pre>
1097 <clix:arg>lambda-list</clix:arg> is a list the elements of which
1098 are either a symbol <clix:arg>var</clix:arg> or a list matching
1099 the destructuring lambda list
1100 <pre>(var &key real-name parameter-type init-form request-type).</pre>
1101 The resulting handler will be a Lisp function with the
1102 name <clix:arg>name</clix:arg> and keyword parameters named by
1103 the <clix:arg>var</clix:arg> symbols.
1104 Each <clix:arg>var</clix:arg> will be bound to the value of the
1105 GET or POST parameter called <clix:arg>real-name</clix:arg> (a
1106 string) before the body of the function is executed.
1107 If <clix:arg>real-name</clix:arg> is not provided, it will be
1109 by <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_stg_up.htm#string-downcase">downcasing</a>
1110 the symbol name of <clix:arg>var</clix:arg>.
1112 If <clix:arg>uri</clix:arg> (which is evaluated) is provided,
1113 then it must be a string or
1114 a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_f.htm#function_designator">function
1115 designator</a> for a unary function. In this case, the
1116 handler will be returned
1117 by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>,
1118 if <clix:arg>uri</clix:arg> is a string and
1119 the <a href="#script-name">script name</a> of the current
1120 request is <clix:arg>uri</clix:arg>, or
1121 if <clix:arg>uri</clix:arg> designates a function and applying
1123 the <a href="#*request*">current <code>REQUEST</code>
1124 object</a> returns a true value.
1127 <clix:arg>acceptor-names</clix:arg> (which is evaluated) can be a
1128 list of symbols which means that the handler will only be
1129 returned by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref> in
1130 acceptors which have one of these names
1131 (see <clix:ref>ACCEPTOR-NAME</clix:ref>). <clix:arg>acceptor-names</clix:arg> can also be the
1132 symbol <code>T</code> which means that the handler will be
1133 returned by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>
1134 in <em>every</em> acceptor.
1137 Whether the GET or POST parameter (or both) will be taken into
1138 consideration, depends on <clix:arg>request-type</clix:arg>
1140 be <code>:GET</code>, <code>:POST</code>, <code>:BOTH</code>,
1141 or <code>NIL</code>. In the last case, the value of
1142 <clix:arg>default-request-type</clix:arg> (the default of which
1143 is <code>:BOTH</code>) will be used.
1146 The value of <clix:arg>var</clix:arg> will usually be a string
1147 (unless it resulted from a <a href="#upload">file upload</a>
1148 in which case it won't be converted at all), but
1149 if <clix:arg>parameter-type</clix:arg> (which is evaluated) is
1150 provided, the string will be converted to another Lisp type by
1151 the following rules:
1154 If the corresponding GET or POST parameter wasn't provided by
1155 the client, <clix:arg>var</clix:arg>'s value will
1156 be <code>NIL</code>. If <clix:arg>parameter-type</clix:arg>
1157 is <code>'STRING</code>,
1158 <clix:arg>var</clix:arg>'s value remains as is.
1159 If <clix:arg>parameter-type</clix:arg> is <code>'INTEGER</code>
1160 and the parameter string consists solely of decimal
1161 digits, <clix:arg>var</clix:arg>'s value will be the
1162 corresponding integer, otherwise <code>NIL</code>.
1163 If <clix:arg>parameter-type</clix:arg> is
1164 <code>'KEYWORD</code>, <clix:arg>var</clix:arg>'s value will be
1165 the keyword obtained
1166 by <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_intern.htm">interning</a>
1167 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_stg_up.htm#string-upcase">upcased</a>
1168 parameter string into
1169 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/11_abc.htm">keyword
1170 package</a>. If <clix:arg>parameter-type</clix:arg>
1171 is <code>'CHARACTER</code> and the parameter string is of
1172 length one, <clix:arg>var</clix:arg>'s value will be the single
1173 character of this string, otherwise <code>NIL</code>.
1174 If <clix:arg>parameter-type</clix:arg>
1175 is <code>'BOOLEAN</code>, <clix:arg>var</clix:arg>'s value will
1176 always be <code>T</code> (unless it is <code>NIL</code> by the
1177 first rule above, of course).
1178 If <clix:arg>parameter-type</clix:arg> is any other atom, it is
1180 a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_f.htm#function_designator">function
1181 designator</a> for a unary function which will be called to
1182 convert the string to something else.
1185 Those were the rules for <em>simple</em> parameter types, but
1186 <clix:arg>parameter-type</clix:arg> can also be a list starting
1187 with one of the symbols
1188 <code>LIST</code>, <code>ARRAY</code>,
1189 or <code>HASH-TABLE</code>. The second value of the list must
1190 always be a simple parameter type as in the last paragraph -
1191 we'll call it the <em>inner type</em> below.
1194 In the case of <code>'LIST</code>, all GET/POST parameters
1195 called <clix:arg>real-name</clix:arg> will be collected,
1196 converted to the inner type as by the rules above, and
1197 assembled into a list which will be the value of
1198 <clix:arg>var</clix:arg>.
1201 In the case of <code>'ARRAY</code>, all GET/POST parameters
1202 which have a name like the result of
1204 <pre>(format nil "~A[~A]" real-name n)</pre>
1205 where <clix:arg>n</clix:arg> is a non-negative integer, will be
1206 assembled into an array where the <clix:arg>n</clix:arg>th element
1207 will be set accordingly, after conversion to the inner type.
1208 The array, which will become the value
1209 of <clix:arg>var</clix:arg>, will be big enough to hold all
1210 matching parameters, but not bigger. Array elements not set as
1211 described above will be <code>NIL</code>. Note
1212 that <code>VAR</code> will always be bound to an array, which
1213 may be empty, so it will never be <code>NIL</code>, even if no
1214 appropriate GET/POST parameters are found.
1216 The full form of a <code>'HASH-TABLE</code> parameter type is
1218 <pre>(hash-table inner-type key-type test-function)</pre>
1219 but <clix:arg>key-type</clix:arg>
1220 and <clix:arg>test-function</clix:arg> can be left out in which
1221 case they default to <code>'STRING</code>
1222 and <code>'EQUAL</code>, respectively. For this parameter type,
1223 all GET/POST parameters which have a name like the result of
1224 <pre>(format nil "~A{~A}" real-name key)</pre>
1225 (where <clix:arg>key</clix:arg> is a string that doesn't contain
1226 curly brackets) will become the values (after conversion
1227 to <clix:arg>inner-type</clix:arg>) of a hash table with test
1228 function <clix:arg>test-function</clix:arg>
1229 where <clix:arg>key</clix:arg> (after conversion
1230 to <clix:arg>key-type</clix:arg>) will be the corresponding key.
1231 Note that <clix:arg>var</clix:arg> will always be bound to a hash
1232 table, which may be empty, so it will never be <code>NIL</code>,
1233 even if no appropriate GET/POST parameters are found.
1235 To make matters even more complicated, the three compound
1236 parameter types also have an abbreviated form - just one of
1237 the symbols <code>LIST</code>, <code>ARRAY</code>,
1238 or <code>HASH-TABLE</code>. In this case, the inner type will
1239 default to <code>'STRING</code>.
1242 If <clix:arg>parameter-type</clix:arg> is not provided
1243 or <code>NIL</code>, <clix:arg>default-parameter-type</clix:arg>
1244 (the default of which is <code>'STRING</code>) will be used
1248 If the result of the computations above would be
1249 that <clix:arg>var</clix:arg> would be bound
1250 to <code>NIL</code>, then <clix:arg>init-form</clix:arg> (if
1251 provided) will be evaluated instead,
1252 and <clix:arg>var</clix:arg> will be bound to the result of this
1256 Handlers built with this macro are constructed in such a way
1257 that the resulting Lisp function is useful even outside of
1258 Hunchentoot. Specifically, all the parameter computations
1259 above will only happen if <clix:ref>*REQUEST*</clix:ref> is
1260 bound, i.e. if we're within a Hunchentoot request.
1261 Otherwise, <clix:arg>var</clix:arg> will always be bound to the
1262 result of evaluating <clix:arg>init-form</clix:arg> unless a
1263 corresponding keyword argument is provided.
1266 The <a href="#example">example code</a> that comes with
1267 Hunchentoot contains an example which demonstrates some of the
1268 features of <clix:ref>DEFINE-EASY-HANDLER</clix:ref>.
1273 <clix:function name='dispatch-easy-handlers'>
1274 <clix:lambda-list>request
1276 <clix:returns>result
1278 <clix:description>This is a dispatcher which returns the appropriate handler
1279 defined with <clix:ref>DEFINE-EASY-HANDLER</clix:ref>, if there is one.
1285 <clix:subchapter name="requests" title="Request objects">
1287 For each incoming request, the <a href="#acceptors">acceptor</a> (in
1288 <clix:ref>PROCESS-CONNECTION</clix:ref>) creates a
1289 <clix:ref>REQUEST</clix:ref> object and makes it available to <a
1290 href="#handlers">handlers</a> via the special variable
1291 <clix:ref>*REQUEST*</clix:ref>. This object contains all relevant
1292 information about the request and this section collects the functions
1293 which can be used to query such an object. In all function where
1294 <clix:arg>request</clix:arg> is an optional or keyword parameter, the
1295 default is <clix:ref>*REQUEST*</clix:ref>.
1298 If you need more fine-grained control over the behaviour of request
1299 objects, you can subclass <clix:ref>REQUEST</clix:ref> and initialize
1300 the <a href="#acceptor-request-class"><code>REQUEST-CLASS</code></a>
1301 slot of the <clix:ref>ACCEPTOR</clix:ref> class accordingly. The
1302 acceptor will generate request objects of the class named by this
1306 <clix:class name='request'>
1308 Objects of this class hold all the information
1309 about an incoming request. They are created automatically by
1310 acceptors and can be accessed by the
1311 corresponding <a href="#handlers">handler</a>.
1313 You should not mess with the slots of these objects directly, but you
1314 can subclass <clix:ref>REQUEST</clix:ref> in order to implement your
1316 the <a href="#acceptor-request-class"><code>REQUEST-CLASS</code></a>
1317 slot of the <clix:ref>ACCEPTOR</clix:ref> class.
1321 <clix:special-variable name='*request*'>
1322 <clix:description>The current REQUEST object while in the context of a request.
1324 </clix:special-variable>
1326 <clix:function name='real-remote-addr'>
1331 <clix:returns>string{, list}
1334 Returns the '<code>X-Forwarded-For</code>' incoming http header as the
1335 second value in the form of a list of IP addresses and the first
1336 element of this list as the first value if this header exists.
1337 Otherwise returns the value of <clix:ref>REMOTE-ADDR</clix:ref> as the only value.
1341 <clix:function name='parameter'>
1342 <clix:lambda-list>name
1346 <clix:returns>string
1349 Returns the GET or the POST parameter with name
1350 <clix:arg>name</clix:arg> (a string) - or <code>NIL</code>
1351 if there is none. If both a GET and a POST parameter with
1352 the same name exist the GET parameter is returned. Search
1353 is case-sensitive. See also
1354 <clix:ref>GET-PARAMETER</clix:ref> and
1355 <clix:ref>POST-PARAMETER</clix:ref>.
1359 <clix:function name="get-parameter">
1360 <clix:lambda-list>name <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1361 <clix:returns>string</clix:returns>
1363 Returns the value of the GET parameter (as provided via the
1364 request URI) named by the string <clix:arg>name</clix:arg> as a
1365 string (or <code>NIL</code> if there ain't no GET parameter
1366 with this name). Note that only the first value will be
1367 returned if the client provided more than one GET parameter
1368 with the name <clix:arg>name</clix:arg>. See
1369 also <clix:ref>GET-PARAMETERS*</clix:ref>.
1373 <clix:function name="post-parameter">
1374 <clix:lambda-list>name <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1375 <clix:returns>string</clix:returns>
1377 Returns the value of the POST parameter (as provided in the
1378 request's body) named by the
1379 string <clix:arg>name</clix:arg>. Note that only the first value
1380 will be returned if the client provided more than one POST
1381 parameter with the name <clix:arg>name</clix:arg>. This value
1382 will usually be a string (or <code>NIL</code> if there ain't
1383 no POST parameter with this name). If, however, the browser
1384 sent a <a class="none" name="upload">file</a> through
1385 a <a href="http://www.faqs.org/rfcs/rfc2388.html">
1386 <code>multipart/form-data</code>
1387 </a> form, the value of this function is a three-element list
1388 <pre>(path file-name content-type)</pre>
1389 where <clix:arg>path</clix:arg> is a pathname denoting the place
1390 were the uploaded file was
1391 stored, <clix:arg>file-name</clix:arg> (a string) is the file
1392 name sent by the browser, and <clix:arg>content-type</clix:arg>
1393 (also a string) is the content type sent by the browser. The
1394 file denoted by <clix:arg>path</clix:arg> will be deleted after
1395 the request has been handled - you have to move or copy it
1396 somewhere else if you want to keep it.
1398 POST parameters will only be computed if the content type of
1399 the request body was <code>multipart/form-data</code>
1400 or <code>application/x-www-form-urlencoded</code>. Although
1401 this function is called <code>POST-PARAMETER</code>, you can
1402 instruct Hunchentoot to compute these parameters for other
1404 setting <clix:ref>*METHODS-FOR-POST-PARAMETERS*</clix:ref>.
1407 See also <clix:ref>POST-PARAMETERS</clix:ref>
1408 and <clix:ref>*TMP-DIRECTORY*</clix:ref>.
1413 <clix:function name="get-parameters*">
1414 <clix:lambda-list><clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1415 <clix:returns>alist</clix:returns>
1418 an <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_a.htm#alist">alist</a>
1419 of all GET parameters (as provided via the request
1420 URI). The <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#car">car</a>
1421 of each element of this list is the parameter's name while
1422 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#cdr">cdr</a>
1423 is its value (as a string). The elements of this list are in
1424 the same order as they were within the request URI. See
1425 also <clix:ref>GET-PARAMETER</clix:ref>.
1429 <clix:function name="post-parameters*">
1430 <clix:lambda-list><clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1431 <clix:returns>alist</clix:returns>
1434 an <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_a.htm#alist">alist</a>
1435 of all POST parameters (as provided via the request's
1436 body). The <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#car">car</a>
1437 of each element of this list is the parameter's name while
1438 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#cdr">cdr</a>
1439 is its value. The elements of this list are in the same order
1440 as they were within the request's body.
1442 See also <clix:ref>POST-PARAMETER</clix:ref>.
1447 <clix:special-variable name='*methods-for-post-parameters*'>
1448 <clix:description>A list of the request method types (as keywords) for which
1449 Hunchentoot will try to compute <clix:arg>post-parameters</clix:arg>.
1451 </clix:special-variable>
1453 <clix:function name='cookie-in'>
1454 <clix:lambda-list>name
1458 <clix:returns>cookie
1461 Returns the cookie with the name <clix:arg>name</clix:arg> (a string) as sent by the
1462 browser - or <code>NIL</code> if there is none.
1466 <clix:function name='cookies-in*'>
1473 <clix:description>Returns an alist of all cookies associated with the <clix:ref>REQUEST</clix:ref> object
1474 <clix:arg>request</clix:arg>.
1478 <clix:function name='host'>
1485 <clix:description>Returns the 'Host' incoming http header value.
1489 <clix:function name='query-string*'>
1494 <clix:returns>string
1497 Returns the query string of the <clix:ref>REQUEST</clix:ref> object <clix:arg>request</clix:arg>. That's
1498 the part behind the question mark (i.e. the GET parameters).
1502 <clix:function name='referer'>
1507 <clix:returns>result
1510 Returns the 'Referer' (sic!) http header.
1514 <clix:function name='request-method*'>
1519 <clix:returns>keyword
1522 Returns the request method as a Lisp keyword.
1526 <clix:function name='request-uri*'>
1534 Returns the request URI.
1538 <clix:function name='server-protocol*'>
1543 <clix:returns>keyword
1546 Returns the request protocol as a Lisp keyword.
1550 <clix:function name='user-agent'>
1555 <clix:returns>result
1558 Returns the 'User-Agent' http header.
1562 <clix:function name='header-in*'>
1563 <clix:lambda-list>name
1567 <clix:returns>header
1570 Returns the incoming header with name
1571 <clix:arg>name</clix:arg>. <clix:arg>name</clix:arg> can be
1572 a keyword (recommended) or a string.
1576 <clix:function name='headers-in*'>
1584 Returns an alist of the incoming headers associated with the
1585 <clix:ref>REQUEST</clix:ref> object
1586 <clix:arg>request</clix:arg>.
1590 <clix:function name='remote-addr*'>
1595 <clix:returns>address
1598 Returns the address the current request originated from.
1602 <clix:function name='remote-port*'>
1610 Returns the port the current request originated from.
1614 <clix:function name='script-name*'>
1619 <clix:returns>script-name
1622 Returns the file name of the <clix:ref>REQUEST</clix:ref>
1623 object <clix:arg>request</clix:arg>. That's the
1624 requested URI without the query string (i.e the GET
1629 <clix:accessor name='aux-request-value'>
1630 <clix:lambda-list>symbol
1634 <clix:returns>value, present-p
1637 This accessor can be used to associate arbitrary
1638 data with the the symbol <clix:arg>symbol</clix:arg> in the <clix:ref>REQUEST</clix:ref> object
1639 <clix:arg>request</clix:arg>. <clix:arg>present-p</clix:arg> is true if such data was found, otherwise <code>NIL</code>.
1643 <clix:function name='delete-aux-request-value'>
1644 <clix:lambda-list>symbol
1651 Removes the value associated with <clix:arg>symbol</clix:arg> from the <clix:ref>REQUEST</clix:ref> object
1652 <clix:arg>request</clix:arg>.
1656 <clix:function name='authorization'>
1661 <clix:returns>result
1664 Returns as two values the user and password (if any) as
1665 encoded in the 'AUTHORIZATION' header. Returns
1666 <code>NIL</code> if there is no such header.
1670 <clix:special-variable name='*hunchentoot-default-external-format*'>
1672 The external format used to compute the <clix:ref>REQUEST</clix:ref> object.
1674 </clix:special-variable>
1676 <clix:special-variable name='*file-upload-hook*'>
1678 If this is not <code>NIL</code>, it should be a unary
1679 function which will be called with a pathname for each file
1680 which is <a href="#upload">uploaded</a> to Hunchentoot. The
1681 pathname denotes the temporary file to which the uploaded
1682 file is written. The hook is called directly before the
1683 file is created. At this point,
1684 <clix:ref>*REQUEST*</clix:ref> is already bound to the
1685 current <clix:ref>REQUEST</clix:ref> object, but obviously
1686 you can't access the post parameters yet.
1688 </clix:special-variable>
1690 <clix:function name="raw-post-data">
1692 <clix:lkw>key</clix:lkw>
1693 request external-format force-text force-binary want-stream
1695 <clix:returns>raw-body-or-stream</clix:returns>
1697 Returns the content sent by the client in the request body if
1698 there was any (unless the content type
1699 was <code>multipart/form-data</code> in which
1700 case <code>NIL</code> is returned). By default, the result is
1701 a string if the type of the <code>Content-Type</code>
1702 <a href="http://www.faqs.org/rfcs/rfc1590.html">media type</a>
1703 is <code>"text"</code>, and a vector of octets otherwise. In
1704 the case of a string, the external format to be used to decode
1705 the content will be determined from the <code>charset</code>
1706 parameter sent by the client (or
1707 otherwise <clix:ref>*HUNCHENTOOT-DEFAULT-EXTERNAL-FORMAT*</clix:ref>
1710 You can also provide an external format explicitly (through
1711 <clix:arg>external-format</clix:arg>) in which case the result
1712 will unconditionally be a string. Likewise, you can provide
1713 a true value for <clix:arg>force-text</clix:arg> which will
1714 force Hunchentoot to act as if the type of the media type
1715 had been <code>"text"</code>
1716 (with <clix:arg>external-format</clix:arg> taking precedence
1717 if provided). Or you can provide a true value
1718 for <clix:arg>force-binary</clix:arg> which means that you
1719 want a vector of octets at any rate. (If both
1720 <clix:arg>force-text</clix:arg>
1721 and <clix:arg>force-binary</clix:arg> are true, an error will
1725 If, however, you provide a true value
1726 for <clix:arg>want-stream</clix:arg>, the other parameters are
1727 ignored and you'll get the content (flexi) stream to read
1728 from it yourself. It is then your responsibility to read
1729 the correct amount of data, because otherwise you won't be
1730 able to return a response to the client. The stream will
1732 its <a href="http://weitz.de/flexi-streams/#flexi-streams">octet
1733 position</a> set to <code>0</code>. If the client provided
1734 a <code>Content-Length</code> header, the stream will also
1736 corresponding <a href="http://weitz.de/flexi-streams/#flexi-streams">bound</a>,
1737 so no matter whether the client used chunked encoding or
1738 not, you can always read until EOF.
1741 If the content type of the request
1742 was <code>multipart/form-data</code>
1743 or <code>application/x-www-form-urlencoded</code>, the
1744 content has been read by Hunchentoot already and you can't
1745 read from the stream anymore.
1748 You can call <clix:ref>RAW-POST-DATA</clix:ref> more than once
1749 per request, but you can't mix calls which have different
1750 values for <clix:arg>want-stream</clix:arg>.
1753 Note that this function is slightly misnamed because a
1754 client can send content even if the request method is not
1761 <clix:function name='recompute-request-parameters'>
1764 </clix:lkw> request external-format
1769 Recomputes the GET and POST parameters for the <clix:ref>REQUEST</clix:ref> object
1770 <clix:arg>request</clix:arg>. This only makes sense if you're switching external formats
1775 <clix:function generic='true' name='process-request'>
1776 <clix:lambda-list>request
1781 This function is called by <clix:ref>PROCESS-CONNECTION</clix:ref>
1782 after the incoming headers have been read. It
1783 calls <clix:ref>HANDLE-REQUEST</clix:ref> (and is more or less just a
1784 thin wrapper around it) to select and call a
1785 <a href="#handlers">handler</a> and send the output of this handler to
1786 the client. Note that <clix:ref>PROCESS-CONNECTION</clix:ref> is
1787 called once per connection and loops in case of a persistent
1788 connection while <clix:ref>PROCESS-REQUEST</clix:ref> is called anew
1791 The return value of this function is ignored.
1794 Like <clix:ref>PROCESS-CONNECTION</clix:ref>, this is another function
1795 the behaviour of which you should only modify if you really, really
1796 know what you're doing.
1801 <clix:function generic='true' name='handle-request'>
1802 <clix:lambda-list>acceptor request
1804 <clix:returns>content
1807 This function is called by <clix:ref>PROCESS-REQUEST</clix:ref> once
1808 the request has been read and a <clix:ref>REQUEST</clix:ref> object
1809 has been created. Its job is to actually handle the request, i.e. to
1810 return something to the client.
1812 The default method calls the
1813 acceptor's <a href="#request-dispatch">request dispatcher</a>, but you
1814 can of course implement a different behaviour. The default method
1815 also sets up <a href="#logging">standard error handling</a> for
1816 the <a href="#handlers">handler</a>.
1819 Might be a good place to bind or rebind special variables which can
1820 then be accessed by your <a href="#handlers">handlers</a>.
1826 <clix:readers generic='true'>
1827 <clix:listed-reader generic='true' name='cookies-in'>
1828 <clix:lambda-list>request
1830 <clix:returns>cookies
1832 </clix:listed-reader>
1834 <clix:listed-reader generic='true' name='get-parameters'>
1835 <clix:lambda-list>request
1837 <clix:returns>get-parameters
1839 </clix:listed-reader>
1841 <clix:listed-reader generic='true' name='header-in'>
1842 <clix:lambda-list>name request
1844 <clix:returns>result
1848 </clix:listed-reader>
1850 <clix:listed-reader generic='true' name='headers-in'>
1851 <clix:lambda-list>request
1853 <clix:returns>headers
1855 </clix:listed-reader>
1857 <clix:listed-reader generic='true' name='post-parameters'>
1858 <clix:lambda-list>request
1860 <clix:returns>post-parameters
1862 </clix:listed-reader>
1864 <clix:listed-reader generic='true' name='query-string'>
1865 <clix:lambda-list>request
1867 <clix:returns>query-string
1869 </clix:listed-reader>
1871 <clix:listed-reader generic='true' name='remote-addr'>
1872 <clix:lambda-list>request
1874 <clix:returns>address
1876 </clix:listed-reader>
1878 <clix:listed-reader generic='true' name='remote-port'>
1879 <clix:lambda-list>request
1883 </clix:listed-reader>
1885 <clix:listed-reader generic='true' name='request-acceptor'>
1886 <clix:lambda-list>request
1888 <clix:returns>acceptor
1890 </clix:listed-reader>
1892 <clix:listed-reader generic='true' name='request-method'>
1893 <clix:lambda-list>request
1895 <clix:returns>method
1897 </clix:listed-reader>
1899 <clix:listed-reader generic='true' name='request-uri'>
1900 <clix:lambda-list>request
1904 </clix:listed-reader>
1906 <clix:listed-reader generic='true' name='server-protocol'>
1907 <clix:lambda-list>request
1909 <clix:returns>protocol
1911 </clix:listed-reader>
1913 <clix:listed-reader generic='true' name='script-name'>
1914 <clix:lambda-list>request
1916 <clix:returns>result
1918 </clix:listed-reader>
1921 These are various generic readers which are used
1922 to read information about a <clix:ref>REQUEST</clix:ref> object. If you are writing a
1923 <a href="#handlers">handler</a>, you should <em>not</em> use these readers but instead utilize the
1924 corresponding functions with an asterisk at the end of their name,
1925 also listed in this section. These generic readers are only
1926 exported for users who want to create their own subclasses of
1927 <clix:ref>REQUEST</clix:ref>.
1934 <clix:subchapter name="replies" title="Reply objects">
1936 For each incoming request, the <a href="#acceptors">acceptor</a>
1937 (in <clix:ref>PROCESS-CONNECTION</clix:ref>) creates
1938 a <clix:ref>REPLY</clix:ref> object and makes it available
1939 to <a href="#handlers">handlers</a> via the special variable
1940 <clix:ref>*REPLY*</clix:ref>. This object contains all relevant
1941 information (except for the content body) about the reply that will be
1942 sent to the client and this section collects the functions which can
1943 be used to query and modify such an object. In all function
1944 where <clix:arg>reply</clix:arg> is an optional or keyword parameter,
1945 the default is <clix:ref>*REPLY*</clix:ref>.
1948 If you need more fine-grained control over the behaviour of reply
1949 objects, you can subclass <clix:ref>REPLY</clix:ref> and initialize
1950 the <a href="#acceptor-reply-class"><code>REPLY-CLASS</code></a>
1951 slot of the <clix:ref>ACCEPTOR</clix:ref> class accordingly. The
1952 acceptor will generate reply objects of the class named by this
1956 <clix:class name='reply'>
1958 Objects of this class hold all the information about an
1959 outgoing reply. They are created automatically by
1960 Hunchentoot and can be accessed and modified by the
1961 corresponding <a href="#handlers">handler</a>.
1963 You should not mess with the slots of these objects directly, but you
1964 can subclass <clix:ref>REPLY</clix:ref> in order to implement your own behaviour. See the
1965 <a href="#acceptor-reply-class"><code>:reply-class</code></a> initarg
1966 of the <clix:ref>ACCEPTOR</clix:ref> class.
1971 <clix:special-variable name='*reply*'>
1973 The current <clix:ref>REPLY</clix:ref> object in the context of a request.
1975 </clix:special-variable>
1977 <clix:accessor name='header-out'>
1978 <clix:lambda-list>name
1982 <clix:returns>string
1985 <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.
1987 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>.
1988 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>.
1993 <clix:function name='headers-out*'>
2000 <clix:description>Returns an alist of the outgoing headers associated with the
2001 <clix:ref>REPLY</clix:ref> object <clix:arg>reply</clix:arg>. See also <clix:ref>HEADER-OUT</clix:ref>.
2005 <clix:accessor name='content-length*'>
2010 <clix:returns>content-length
2013 The outgoing 'Content-Length' http header of <clix:arg>reply</clix:arg>.
2017 <clix:accessor name='content-type*'>
2022 <clix:returns>content-type
2025 The outgoing 'Content-Type' http header of <clix:arg>reply</clix:arg>.
2029 <clix:function name='cookie-out'>
2030 <clix:lambda-list>name
2034 <clix:returns>result
2037 Returns the current value of the outgoing <a
2038 href="#cookies">cookie</a> named
2039 <clix:arg>name</clix:arg>. Search is case-sensitive.
2043 <clix:accessor name='cookies-out*'>
2051 Returns or sets an alist of the outgoing <a
2052 href="#cookies">cookies</a> associated with the
2053 <clix:ref>REPLY</clix:ref> object
2054 <clix:arg>reply</clix:arg>.
2058 <clix:accessor name='return-code*'>
2063 <clix:returns>return-code
2066 Gets or sets the http return code of
2067 <clix:arg>reply</clix:arg>. The return code of each
2068 <clix:ref>REPLY</clix:ref> object is initially set to
2069 <clix:ref>+HTTP-OK+</clix:ref>.
2073 <clix:function name="send-headers">
2074 <clix:returns>stream</clix:returns>
2076 Sends the initial status line and all headers as determined
2077 by the <clix:ref>REPLY</clix:ref>
2078 object <clix:ref>*REPLY*</clix:ref>. Returns
2079 a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_b.htm#binary">binary</a>
2080 stream to which the body of the reply can be written. Once
2081 this function has been called, further changes
2082 to <clix:ref>*REPLY*</clix:ref> don't have any effect.
2083 Also, automatic handling of errors (i.e. sending the
2084 corresponding status code to the browser, etc.) is turned
2085 off for this request and functions
2086 like <clix:ref>REDIRECT</clix:ref> or
2087 to <clix:ref>ABORT-REQUEST-HANDLER</clix:ref> won't have the
2088 desired effect once the headers are sent.
2090 If your handlers return the full body as a string or as an
2091 array of octets, you should <em>not</em> call this function.
2092 If a handler calls <clix:ref>SEND-HEADERS</clix:ref> , its
2093 return value is ignored.
2098 <clix:accessor name='reply-external-format*'>
2103 <clix:returns>external-format
2106 Gets or sets the external format of <clix:arg>reply</clix:arg> which is used for character output.
2110 <clix:special-variable name='*default-content-type*'>
2112 The default content-type header which is returned to the client.
2114 </clix:special-variable>
2117 <clix:listed-constant name="+http-continue+"/>
2118 <clix:listed-constant name="+http-switching-protocols+"/>
2119 <clix:listed-constant name="+http-ok+"/>
2120 <clix:listed-constant name="+http-created+"/>
2121 <clix:listed-constant name="+http-accepted+"/>
2122 <clix:listed-constant name="+http-non-authoritative-information+"/>
2123 <clix:listed-constant name="+http-no-content+"/>
2124 <clix:listed-constant name="+http-reset-content+"/>
2125 <clix:listed-constant name="+http-partial-content+"/>
2126 <clix:listed-constant name="+http-multi-status+"/>
2127 <clix:listed-constant name="+http-multiple-choices+"/>
2128 <clix:listed-constant name="+http-moved-permanently+"/>
2129 <clix:listed-constant name="+http-moved-temporarily+"/>
2130 <clix:listed-constant name="+http-see-other+"/>
2131 <clix:listed-constant name="+http-not-modified+"/>
2132 <clix:listed-constant name="+http-use-proxy+"/>
2133 <clix:listed-constant name="+http-temporary-redirect+"/>
2134 <clix:listed-constant name="+http-bad-request+"/>
2135 <clix:listed-constant name="+http-authorization-required+"/>
2136 <clix:listed-constant name="+http-payment-required+"/>
2137 <clix:listed-constant name="+http-forbidden+"/>
2138 <clix:listed-constant name="+http-not-found+"/>
2139 <clix:listed-constant name="+http-method-not-allowed+"/>
2140 <clix:listed-constant name="+http-not-acceptable+"/>
2141 <clix:listed-constant name="+http-proxy-authentication-required+"/>
2142 <clix:listed-constant name="+http-request-time-out+"/>
2143 <clix:listed-constant name="+http-conflict+"/>
2144 <clix:listed-constant name="+http-gone+"/>
2145 <clix:listed-constant name="+http-length-required+"/>
2146 <clix:listed-constant name="+http-precondition-failed+"/>
2147 <clix:listed-constant name="+http-request-entity-too-large+"/>
2148 <clix:listed-constant name="+http-request-uri-too-large+"/>
2149 <clix:listed-constant name="+http-unsupported-media-type+"/>
2150 <clix:listed-constant name="+http-requested-range-not-satisfiable+"/>
2151 <clix:listed-constant name="+http-expectation-failed+"/>
2152 <clix:listed-constant name="+http-failed-dependency+"/>
2153 <clix:listed-constant name="+http-internal-server-error+"/>
2154 <clix:listed-constant name="+http-not-implemented+"/>
2155 <clix:listed-constant name="+http-bad-gateway+"/>
2156 <clix:listed-constant name="+http-service-unavailable+"/>
2157 <clix:listed-constant name="+http-gateway-time-out+"/>
2158 <clix:listed-constant name="+http-version-not-supported+"/>
2160 The values of these constants are 100, 101, 200, 201, 202,
2161 203, 204, 205, 206, 207, 300, 301, 302, 303, 304, 305, 307,
2162 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411,
2163 412, 413, 414, 415, 416, 417, 424, 500, 501, 502, 503, 504,
2164 and 505. See <clix:ref>RETURN-CODE</clix:ref>.
2168 <clix:readers generic='true'>
2169 <clix:listed-reader generic='true' name='content-length'>
2170 <clix:lambda-list>reply
2172 <clix:returns>content-length
2174 </clix:listed-reader>
2176 <clix:listed-reader generic='true' name='content-type'>
2177 <clix:lambda-list>reply
2179 <clix:returns>content-type
2181 </clix:listed-reader>
2183 <clix:listed-reader generic='true' name='headers-out'>
2184 <clix:lambda-list>reply
2186 <clix:returns>headers-out
2188 </clix:listed-reader>
2191 These are various generic readers which are used
2192 to read information about a <clix:ref>REPLY</clix:ref> object. If you are writing a
2193 <a href="#handlers">handler</a>, you should <em>not</em> use these readers but instead utilize the
2194 corresponding functions with an asterisk at the end of their name,
2195 also listed in this section. These generic readers are only
2196 exported for users who want to create their own subclasses of
2197 <clix:ref>REPLY</clix:ref>.
2201 <clix:accessors generic='true'>
2202 <clix:listed-accessor generic='true' name='cookies-out'>
2203 <clix:lambda-list>reply
2205 <clix:returns>result
2207 </clix:listed-accessor>
2209 <clix:listed-accessor generic='true' name='return-code'>
2210 <clix:lambda-list>reply
2212 <clix:returns>result
2214 </clix:listed-accessor>
2216 <clix:listed-accessor generic='true' name='reply-external-format'>
2217 <clix:lambda-list>reply
2219 <clix:returns>result
2221 </clix:listed-accessor>
2224 These are various generic accessors which are
2225 used to query and modify a <clix:ref>REPLY</clix:ref> objects. If
2227 <a href="#handlers">handler</a>, you should <em>not</em> use these
2228 accessors but instead utilize the corresponding functions with an
2229 asterisk at the end of their name, also listed in this section.
2230 These generic accessors are only exported for users who want to
2231 create their own subclasses of
2232 <clix:ref>REPLY</clix:ref>.
2239 <clix:subchapter name="sessions" title="Sessions">
2240 Hunchentoot supports <em>sessions</em>: Once a <a href="#handlers">request
2241 handler</a> has called <clix:ref>START-SESSION</clix:ref>, Hunchentoot
2242 uses either cookies or (if the client doesn't send the cookies
2243 back) <a href="#*rewrite-for-session-urls*">rewrites URLs</a> to keep
2244 track of this client, i.e. to provide a kind of 'state' for the
2245 stateless http protocol. The session associated with the client is a
2246 <a href="#session">CLOS object</a> which can be used
2247 to <a href="#session-value">store arbitrary data</a> between requests.
2249 Hunchentoot makes some reasonable effort to prevent eavesdroppers from
2250 hijacking sessions (see below), but this should not be considered
2251 really secure. Don't store sensitive data in sessions and rely solely
2252 on the session mechanism as a safeguard against malicious users who
2253 want to get at this data!
2256 For each request there's one <clix:ref>SESSION</clix:ref> object which is accessible to the
2257 <a href="#handler">handler</a> via the special
2258 variable <clix:ref>*SESSION*</clix:ref>. This object holds all the
2259 information available about the session and can be accessed with the
2260 functions described in this chapter. Note that the internal structure
2261 of <clix:ref>SESSION</clix:ref> objects should be considered opaque
2262 and may change in future releases of Hunchentoot.
2265 Sessions are automatically <a href="#session-verify">verified</a> for
2266 validity and age when the <clix:ref>REQUEST</clix:ref> object is
2267 instantiated, i.e. if <clix:ref>*SESSION*</clix:ref> is not NIL then
2268 this session is valid (as far as Hunchentoot is concerned) and
2269 not <a href="#session-too-old-p">too old</a>. Old sessions
2270 are <a href="#session-gc">automatically removed</a>.
2273 <clix:class name='session'>
2275 <clix:ref>SESSION</clix:ref> objects are
2276 automatically maintained by Hunchentoot. They should not be created
2277 explicitly with <code>MAKE-INSTANCE</code> but implicitly
2278 with <clix:ref>START-SESSION</clix:ref> and they should be treated as
2281 You can ignore Hunchentoot's <clix:ref>SESSION</clix:ref> objects and
2282 <a href="#session-behaviour">implement your own sessions</a> if you provide corresponding methods for
2283 <clix:ref>SESSION-COOKIE-VALUE</clix:ref>
2284 and <clix:ref>SESSION-VERIFY</clix:ref>.
2289 <clix:function name='start-session'>
2292 <clix:returns>session
2295 Returns the current <clix:ref>SESSION</clix:ref>
2296 object. If there is no current session, creates one and updates the
2297 corresponding data structures. In this case the function will also
2298 send a session cookie to the browser.
2302 <clix:accessor name='session-value'>
2303 <clix:lambda-list>symbol
2307 <clix:returns>value, present-p
2310 This accessor can be used to associate arbitrary data with the the
2311 symbol <clix:arg>symbol</clix:arg> in the <clix:ref>SESSION</clix:ref>
2312 object <clix:arg>session</clix:arg>. <clix:arg>present-p</clix:arg> is
2313 true if such data was found, otherwise <code>NIL</code>. The default
2314 value for <clix:arg>session</clix:arg> is
2315 <clix:ref>*SESSION*</clix:ref>.
2317 If <code>SETF</code> of <clix:ref>SESSION-VALUE</clix:ref> is called
2318 with <clix:arg>session</clix:arg> being <code>NIL</code> then a
2319 session is automatically instantiated
2320 with <clix:ref>START-SESSION</clix:ref>.
2325 <clix:function name='delete-session-value'>
2326 <clix:lambda-list>symbol
2333 Removes the value associated with
2334 <clix:arg>symbol</clix:arg> from
2335 <clix:arg>session</clix:arg> if there is one.
2339 <clix:special-variable name='*session*'>
2341 The current session while in the context of a request, or
2344 </clix:special-variable>
2346 <clix:function name='remove-session'>
2347 <clix:lambda-list>session
2352 Completely removes the <clix:ref>SESSION</clix:ref> object
2353 <clix:arg>session</clix:arg> from Hunchentoot's
2354 internal <a href="#session-db">session database</a>.
2358 <clix:function name='reset-sessions'>
2361 </clix:lkw> acceptor
2366 Removes <em>all</em> stored sessions of
2367 <clix:arg>acceptor</clix:arg>. The default for
2368 <clix:arg>acceptor</clix:arg> is
2369 <clix:ref>*ACCEPTOR*</clix:ref>.
2373 <clix:special-variable name='*rewrite-for-session-urls*'>
2375 Whether HTML pages should possibly be rewritten for cookie-less
2378 </clix:special-variable>
2380 <clix:special-variable name='*content-types-for-url-rewrite*'>
2382 The content types for which url-rewriting is OK. See
2383 <clix:ref>*REWRITE-FOR-SESSION-URLS*</clix:ref>.
2385 </clix:special-variable>
2387 <clix:special-variable name='*use-remote-addr-for-sessions*'>
2389 Whether the client's remote IP (as returned by <clix:ref>REAL-REMOTE-ADDR</clix:ref>)
2390 should be encoded into the session string. If this value is true, a
2391 session will cease to be accessible if the client's remote IP changes.
2393 This might for example be an issue if the client uses a proxy server
2394 which doesn't send correct 'X_FORWARDED_FOR' headers.
2397 </clix:special-variable>
2399 <clix:function generic='true' name='session-remote-addr'>
2400 <clix:lambda-list>session
2402 <clix:returns>remote-addr
2405 The remote IP address of the client when this session was started (as
2406 returned by <clix:ref>REAL-REMOTE-ADDR</clix:ref>).
2410 <clix:special-variable name='*use-user-agent-for-sessions*'>
2411 <clix:description>Whether the 'User-Agent' header should
2412 be encoded into the session string. If this value is true, a session
2413 will cease to be accessible if the client sends a different
2414 'User-Agent' header.
2416 </clix:special-variable>
2418 <clix:function generic='true' name='session-user-agent'>
2419 <clix:lambda-list>session
2421 <clix:returns>user-agent
2424 The incoming 'User-Agent' header that
2425 was sent when this session was created.
2429 <clix:accessor generic='true' name='session-max-time'>
2430 <clix:lambda-list>session
2432 <clix:returns>max-time
2435 Gets or sets the time (in seconds) after
2436 which <clix:arg>session</clix:arg> expires if it's not used.
2441 <clix:special-variable name='*session-max-time*'>
2443 The default time (in seconds) after which a session times out.
2445 </clix:special-variable>
2447 <clix:special-variable name='*session-gc-frequency*'>
2449 A session GC (see function <clix:ref>SESSION-GC</clix:ref>) will happen every
2450 <clix:ref>*SESSION-GC-FREQUENCY*</clix:ref> requests (counting only
2451 requests which create a new session) if this variable is
2452 not <code>NIL</code>. See <clix:ref>SESSION-CREATED</clix:ref>.
2454 </clix:special-variable>
2456 <clix:function name='session-gc'>
2462 Removes sessions from the current session database which are
2463 too old - see <clix:ref>SESSION-TOO-OLD-P</clix:ref>.
2467 <clix:function name='session-too-old-p'>
2468 <clix:lambda-list>session
2470 <clix:returns>generalized-boolean
2473 Returns true if the <clix:ref>SESSION</clix:ref> object <clix:arg>session</clix:arg> has not been active in
2474 the last <code>(session-max-time session)</code> seconds.
2478 <clix:special-variable name='*session-removal-hook*'>
2480 A function of one argument
2481 (a <clix:ref>SESSION</clix:ref> object) which is called whenever a
2482 session is <a href="#session-gc">garbage-collected</a>.
2484 </clix:special-variable>
2486 <clix:function generic='true' name='session-id'>
2487 <clix:lambda-list>session
2489 <clix:returns>session-id
2492 The unique ID (an INTEGER) of the session.
2496 <clix:function generic='true' name='session-start'>
2497 <clix:lambda-list>session
2499 <clix:returns>universal-time
2502 The time this session was started.
2509 <clix:subchapter name="session-behaviour" title="Customizing session behaviour">
2511 For everyday session usage, you will probably just
2512 use <clix:ref>START-SESSION</clix:ref>,
2513 <clix:ref>SESSION-VALUE</clix:ref>,
2514 and maybe <clix:ref>DELETE-SESSION-VALUE</clix:ref>
2515 and <clix:ref>*SESSION*</clix:ref>. However, there are two ways to
2516 customize the way Hunchentoot maintains sessions.
2518 One way is to mostly leave the session mechanism intact but to tweak
2521 <li>The publicly visible part of a session is encoded using a
2522 <a href="#*session-secret*">secret</a> which you can set yourself.</li>
2523 <li>And it is stored using a cookie (or GET
2524 parameter) <a href="#session-cookie-name">name</a> that you can
2526 <li>Each session receives a <a href="#next-session-id">new ID</a> when
2527 it is created and you can implement a more robust way to do that.</li>
2528 <li>You can arrange to be called whenever a session
2529 is <a href="#session-created">created</a> to trigger some action. You
2530 might also do this to invent your own
2531 session <a href="#session-gc">garbage collection</a>.</li>
2532 <li>By default, all sessions are stored in a global alist in memory.
2533 You can't change the alist part, but you can distribute your sessions
2534 over different <a href="#session-db">"databases"</a>.</li>
2535 <li>By default, every operation which modifies sessions or one of the
2536 session databases is guarded by a global lock, but you can arrange to
2537 <a href="#session-db-lock">provide</a> different locks for this.</li>
2541 The other way to customize Hunchentoot's sessions is to completely
2542 replace them. This is actually pretty easy: Create your own class to
2543 store state (which doesn't have to and probably shouldn't inherit
2544 from <clix:ref>SESSION</clix:ref>) and implement methods for
2545 <clix:ref>SESSION-VERIFY</clix:ref>
2546 and <clix:ref>SESSION-COOKIE-VALUE</clix:ref> - that's it.
2547 Hunchentoot will continue to use cookies and/or to rewrite URLs to
2548 keep track of session state and it will store "the current session"
2549 (whatever that is in your implementation)
2550 in <clix:ref>*SESSION*</clix:ref>. Everything else (like persisting
2551 sessions, GC, getting and setting values) you'll have to take care of
2552 yourself and the other session functions
2553 (like <clix:ref>START-SESSION</clix:ref> or
2554 <clix:ref>SESSION-VALUE</clix:ref>) won't work anymore. (Almost)
2555 total freedom, but a lot of responsibility as well... :)
2558 <clix:special-variable name='*session-secret*'>
2560 A random ASCII string that's used to encode the public
2561 session data. This variable is initially unbound and will
2562 be set (using <clix:ref>RESET-SESSION-SECRET</clix:ref>) the
2563 first time a session is created, if necessary. You can
2564 prevent this from happening if you set the value yourself
2565 before starting <a href="#acceptors">acceptors</a>.
2567 </clix:special-variable>
2569 <clix:function name='reset-session-secret'>
2572 <clix:returns>secret
2575 Sets <clix:ref>*SESSION-SECRET*</clix:ref> to a
2576 new random value. All old sessions will cease to be valid.
2580 <clix:function generic='true' name='session-cookie-name'>
2581 <clix:lambda-list>acceptor
2586 Returns the name (a string) of the cookie (or
2587 the GET parameter) which is used to store a session on the client
2588 side. The default is to use the
2589 string <code>"hunchentoot-session"</code>, but you can
2590 specialize this function if you want another name.
2594 <clix:function generic='true' name='session-created'>
2595 <clix:lambda-list>acceptor new-session
2597 <clix:returns>result
2600 This function is called whenever a new session
2601 has been created. There's a default method which might trigger
2602 a <a href="#session-gc">session GC</a> based on the value of
2603 <clix:ref>*SESSION-GC-FREQUENCY*</clix:ref>.
2605 The return value is ignored.
2610 <clix:function generic='true' name='next-session-id'>
2611 <clix:lambda-list>acceptor
2616 Returns the next sequential session ID, an
2617 integer, which should be unique per session. The default method uses
2618 a simple global counter and isn't guarded by a lock. For a
2619 high-performance production environment you might consider using a
2620 more robust implementation.
2624 <clix:accessor generic='true' name='session-db'>
2625 <clix:lambda-list>acceptor
2627 <clix:returns>database
2630 Returns the current session database which is an
2631 alist where each car is a session's ID and the cdr is the
2632 corresponding <clix:ref>SESSION</clix:ref> object itself. The default
2633 is to use a global list for all acceptors.
2637 <clix:function generic='true' name='session-db-lock'>
2638 <clix:lambda-list>acceptor
2640 </clix:lkw> whole-db-p
2645 A function which returns a lock that will be
2646 used to prevent concurrent access to sessions. The first argument
2647 will be the <a href="#acceptors">acceptor</a> that handles the
2648 current <a href="#requests">request</a>, the second argument is true
2649 if the whole (current) session database is modified. If it
2650 is <code>NIL</code>, only one existing session in the database is
2653 This function can return <code>NIL</code> which means that sessions or
2654 session databases will be modified without a lock held (for example
2655 for single-threaded environments). The default is to always return a
2656 global lock (ignoring the <clix:arg>acceptor</clix:arg> argument) for
2657 Lisps that support threads and <code>NIL</code> otherwise.
2662 <clix:function generic='true' name='session-verify'>
2663 <clix:lambda-list>request
2665 <clix:returns>session-or-nil
2668 Tries to get a session identifier from the cookies
2669 (or alternatively from the GET parameters) sent by the client (see
2670 <clix:ref>SESSION-COOKIE-NAME</clix:ref>
2671 and <clix:ref>SESSION-COOKIE-VALUE</clix:ref>). This identifier is
2672 then checked for validity against the <clix:ref>REQUEST</clix:ref>
2674 <clix:arg>request</clix:arg>. On success the corresponding session object (if not too
2675 old) is returned (and updated). Otherwise <code>NIL</code> is returned.
2677 A default method is provided and you only need to write your own one
2678 if you want to maintain your own sessions.
2683 <clix:function generic='true' name='session-cookie-value'>
2684 <clix:lambda-list>session
2686 <clix:returns>string
2689 Returns a string which can be used to safely
2690 restore the session <clix:arg>session</clix:arg> if as session has
2691 already been established. This is used as the value stored in the
2692 session cookie or in the corresponding GET parameter and verified
2693 by <clix:ref>SESSION-VERIFY</clix:ref>.
2696 method is provided and there's no reason to change it unless you
2697 want to use your own session objects.
2704 <clix:subchapter name="cookies" title="Cookies">
2706 Outgoing cookies are stored in the request's <clix:ref>REPLY</clix:ref>
2707 object (see <clix:ref>COOKIE-OUT</clix:ref>
2708 and <clix:ref>COOKIES-OUT*</clix:ref>). They are CLOS objects
2711 <pre>(defclass cookie ()
2712 ((name :initarg :name
2713 :reader <a class="noborder" name="cookie-name">cookie-name</a>
2715 :documentation "The name of the cookie - a string.")
2716 (value :initarg :value
2717 :accessor <a class="noborder" name="cookie-value">cookie-value</a>
2719 :documentation "The value of the cookie. Will be URL-encoded when sent to the browser.")
2720 (expires :initarg :expires
2722 :accessor <a class="noborder" name="cookie-expires">cookie-expires</a>
2723 :documentation "The time (a universal time) when the cookie expires (or NIL).")
2724 (path :initarg :path
2726 :accessor <a class="noborder" name="cookie-path">cookie-path</a>
2727 :documentation "The path this cookie is valid for (or NIL).")
2728 (domain :initarg :domain
2730 :accessor <a class="noborder" name="cookie-domain">cookie-domain</a>
2731 :documentation "The domain this cookie is valid for (or NIL).")
2732 (secure :initarg :secure
2734 :accessor <a class="noborder" name="cookie-secure">cookie-secure</a>
2735 :documentation "A generalized boolean denoting whether this is a secure cookie.")
2736 (http-only :initarg :http-only
2738 :accessor <a class="noborder" name="cookie-http-only">cookie-http-only</a>
2739 :documentation "A generalized boolean denoting whether this is a <a href="http://msdn2.microsoft.com/en-us/library/ms533046.aspx">HttpOnly</a> cookie.")))
2742 The <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_r.htm#reader">reader</a>
2743 <clix:ref>COOKIE-NAME</clix:ref> and
2744 the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_a.htm#accessor">accessors</a>
2745 <clix:ref>COOKIE-VALUE</clix:ref>, <clix:ref>COOKIE-EXPIRES</clix:ref>,
2746 <clix:ref>COOKIE-PATH</clix:ref>, <clix:ref>COOKIE-DOMAIN</clix:ref>, <clix:ref>COOKIE-SECURE</clix:ref>,
2747 and <clix:ref>COOKIE-HTTP-ONLY</clix:ref> are all exported from
2748 the <code>HUNCHENTOOT</code> package. For now, the class name itself is <em>not</em> exported.
2750 <clix:function name="set-cookie">
2752 name <clix:lkw>key</clix:lkw> value expires path
2753 domain secure http-only reply
2755 <clix:returns>cookie</clix:returns>
2757 Creates a <code>COOKIE</code> object from the parameters
2758 provided to this function and adds it to the outgoing cookies
2759 of the <a href="#replies"><code>REPLY</code> object</a>
2760 <clix:arg>reply</clix:arg>. If a cookie with the same name
2761 (case-sensitive) already exists, it is replaced. The default
2762 for <clix:arg>reply</clix:arg>
2763 is <clix:ref>*REPLY*</clix:ref>. The default
2764 for <clix:arg>value</clix:arg> is the empty string.
2768 <clix:function name="set-cookie*">
2769 <clix:lambda-list>cookie <clix:lkw>optional</clix:lkw> reply</clix:lambda-list>
2770 <clix:returns>cookie</clix:returns>
2772 Adds the <code>COOKIE</code> object <clix:arg>cookie</clix:arg>
2773 to the outgoing cookies of
2774 the <a href="#replies"><code>REPLY</code> object</a>
2775 <clix:arg>reply</clix:arg>. If a cookie with the same name
2776 (case-sensitive) already exists, it is replaced. The default
2777 for <clix:arg>reply</clix:arg> is <clix:ref>*REPLY*</clix:ref>.
2782 <clix:subchapter name="logging" title="Logging">
2783 Hunchentoot can log accesses and diagnostic messages to two
2784 separate destinations, which can be either files in the file
2785 system or streams. Logging can also be disabled by setting the
2786 <clix:code>ACCESS-LOG-DESTINATION</clix:code> and
2787 <clix:code>MESSAGE-LOG-DESTINATION</clix:code> slots in the
2788 <clix:ref>ACCEPTOR</clix:ref> instance of the running server,
2789 either by providing the :ACCESS-LOG-DESTINATION and
2790 :MESSAGE-LOG-DESTINATION initialization arguments when creating the
2791 acceptor or by setting the slots through its
2792 <clix:ref>ACCEPTOR-MESSAGE-LOG-DESTINATION</clix:ref> and
2793 <clix:ref>ACCEPTOR-ACCESS-LOG-DESTINATION</clix:ref> accessors.
2795 When the path for the message or accept log is set to a
2796 variable holding an output stream, hunchentoots writes
2797 corresponding log entries to that stream. By default,
2798 Hunchentoot logs to *STANDARD-ERROR*.
2801 Access logging is done in a format similar to what
2802 the Apache web server can write so that logfile analysis using
2803 standard tools is possible. Errors during request processing are
2804 logged to a separate file.
2807 The standard logging mechanism is deliberately simple and slow. The
2808 log files are opened for each log entry and closed again after
2809 writing, and access to them is protected by a global lock. Derived
2810 acceptor classes can implement methods for the
2811 <clix:ref>ACCEPTOR-LOG-MESSAGE</clix:ref> and
2812 <clix:ref>ACCEPTOR-LOG-ACCESS</clix:ref> generic functions in order to
2813 log differently (e.g. to a central logging server or in a different
2817 Errors happening within a <a href="#handlers">handler</a>
2818 which are not caught by the handler itself are handled by
2819 Hunchentoot by logging them to the established
2820 <clix:ref>ACCEPTOR-MESSAGE-LOG-DESTINATION</clix:ref>.
2823 <clix:function name='log-message*'>
2824 <clix:lambda-list>log-level format-string
2826 </clix:lkw> format-arguments
2828 <clix:returns>result
2831 Convenience function which calls the message
2832 logger of the current acceptor (if there is one) with the same
2833 arguments it accepts. Returns <code>NIL</code> if there is no message
2834 logger or whatever the message logger returns.
2836 This is the function which Hunchentoot itself uses to log errors it
2837 catches during request processing.
2842 <clix:special-variable name='*log-lisp-errors-p*'>
2844 Whether Lisp errors in request handlers should be logged.
2846 </clix:special-variable>
2848 <clix:special-variable name='*log-lisp-backtraces-p*'>
2850 Whether Lisp backtraces should be logged. Only
2851 has an effect if <clix:ref>*LOG-LISP-ERRORS-P*</clix:ref> is true
2854 </clix:special-variable>
2856 <clix:special-variable name='*log-lisp-warnings-p*'>
2858 Whether Lisp warnings in request handlers should be logged.
2860 </clix:special-variable>
2862 <clix:special-variable name='*lisp-errors-log-level*'>
2864 Log level for Lisp errors. Should be one
2865 of <code>:ERROR</code> (the default), <code>:WARNING</code>,
2866 or <code>:INFO</code>.
2868 </clix:special-variable>
2870 <clix:special-variable name='*lisp-warnings-log-level*'>
2872 Log level for Lisp warnings.
2873 Should be one of <code>:ERROR</code>, <code>:WARNING</code>
2874 (the default), or <code>:INFO</code>.
2876 </clix:special-variable>
2879 <clix:subchapter name="conditions" title="Conditions and error handling">
2881 This section describes how Hunchentoot deals with exceptional
2882 situations. See also the secion about <a href="#logging">logging</a>.
2885 When an error occurs while processing a request, Hunchentoot's
2886 default behavior is to catch catch the error, log it and
2887 optionally display it to the client in the HTML response.
2888 This behavior can be customized through the values of a number
2889 of special variables, which are documented below.
2892 <clix:special-variable name='*catch-errors-p*'>
2894 If the value of this variable is <code>NIL</code>
2895 (the default is <code>T</code>), then errors which happen while a
2896 request is handled aren't <a href="#logging">caught as usual</a>, but
2899 href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_d.htm#debugger">debugger</a>
2901 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_invoke.htm">invoked</a>.
2902 This variable should obviously always be set to a <em>true</em> value
2903 in a production environment.
2904 See <clix:ref>MAYBE-INVOKE-DEBUGGER</clix:ref>
2905 if you want to fine-tune this behaviour.
2907 </clix:special-variable>
2909 <clix:special-variable name='*show-lisp-errors-p*'>
2911 Whether Lisp errors should be shown in HTML output. Note
2912 that this only affects canned responses generated by Lisp.
2913 If an error template is present for the "internal server
2914 error" status code, this special variable is not used (see
2915 <clix:ref>acceptor-status-message</clix:ref>).
2917 </clix:special-variable>
2919 <clix:special-variable name='*show-lisp-backtraces-p*'>
2921 Whether Lisp backtraces should be shown in HTML output if
2922 <clix:ref>*SHOW-LISP-ERRORS-P*</clix:ref> is true and an error occurs.
2924 </clix:special-variable>
2926 <clix:function generic='true' name='maybe-invoke-debugger'>
2927 <clix:lambda-list>condition
2932 This generic function is called whenever a
2934 href="http://www.lispworks.com/documentation/HyperSpec/Body/09_.htm">condition</a> <code><i>condition</i></code>
2935 is signaled in Hunchentoot. You might want to specialize it on
2936 specific condition classes for debugging purposes. The default
2938 href="http://www.lispworks.com/documentation/HyperSpec/Body/f_invoke.htm">invokes
2939 the debugger</a> with <clix:arg>condition</clix:arg> if
2940 <clix:ref>*CATCH-ERRORS-P*</clix:ref> is <code>NIL</code>.
2944 <clix:condition name='hunchentoot-condition'>
2946 Superclass for all conditions related to Hunchentoot.
2950 <clix:condition name='hunchentoot-error'>
2952 Superclass for all errors related to Hunchentoot and a subclass of <clix:ref>HUNCHENTOOT-CONDITION</clix:ref>.
2956 <clix:condition name='parameter-error'>
2958 Signalled if a function was called with incosistent or illegal parameters. A subclass of <clix:ref>HUNCHENTOOT-ERROR</clix:ref>.
2962 <clix:condition name='hunchentoot-warning'>
2964 Superclass for all warnings related to Hunchentoot and a subclass of <clix:ref>HUNCHENTOOT-CONDITION</clix:ref>.
2970 <clix:subchapter name="misc" title="Miscellaneous">
2972 Various functions and variables which didn't fit into one of the
2975 <clix:function name='abort-request-handler'>
2980 <clix:returns>result
2983 This function can be called by a request handler
2984 at any time to immediately abort handling the request. This works as
2985 if the handler had returned <clix:arg>result</clix:arg>. See the
2986 source code of <clix:ref>REDIRECT</clix:ref> for an example.
2990 <clix:function name="handle-if-modified-since">
2991 <clix:lambda-list>time <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
2992 <clix:returns>|</clix:returns>
2994 This function is designed to be used inside
2995 a <a href="#handlers">handler</a>. If the client has sent an
2996 'If-Modified-Since' header
2997 (see <a href="http://www.faqs.org/rfcs/rfc2616.html">RFC 2616</a>,
2998 section 14.25) and the time specified matches the universal
3000 <clix:arg>time</clix:arg> then the
3001 header <clix:ref>+HTTP-NOT-MODIFIED+</clix:ref> with no content
3002 is immediately returned to the client.
3004 Note that for this function to be useful you should usually
3005 send 'Last-Modified' headers back to the client. See the
3007 of <clix:ref>CREATE-STATIC-FILE-DISPATCHER-AND-HANDLER</clix:ref>
3013 <clix:function name="handle-static-file">
3014 <clix:lambda-list>path <clix:lkw>optional</clix:lkw> content-type</clix:lambda-list>
3015 <clix:returns>nil</clix:returns>
3017 Sends the file denoted by the pathname designator
3018 <clix:arg>path</clix:arg> with content type
3019 <clix:arg>content-type</clix:arg> to the client. Sets the
3020 necessary handlers. In particular the function employs
3021 <clix:ref>HANDLE-IF-MODIFIED-SINCE</clix:ref>.
3023 If <clix:arg>content-type</clix:arg> is <code>NIL</code> the
3024 function tries to determine the correct content type from
3025 the file's suffix or falls back
3026 to <code>"application/octet-stream"</code> as a last resort.
3029 Note that this function
3030 calls <clix:ref>SEND-HEADERS</clix:ref> internally, so after
3031 you've called it, the headers are sent and the return value
3032 of your handler is ignored.
3037 <clix:function name="redirect">
3038 <clix:lambda-list>target <clix:lkw>key</clix:lkw> host port protocol add-session-id code</clix:lambda-list>
3039 <clix:returns>|</clix:returns>
3041 Sends back appropriate headers to redirect the client
3042 to <clix:arg>target</clix:arg> (a string).
3044 If <clix:arg>target</clix:arg> is a full URL starting with a
3045 scheme, <clix:arg>host</clix:arg>, <clix:arg>port</clix:arg>,
3046 and <clix:arg>protocol</clix:arg> are ignored.
3047 Otherwise, <clix:arg>target</clix:arg> should denote the path
3048 part of a URL, <clix:arg>protocol</clix:arg> must be one of
3049 the keywords <code>:HTTP</code> or <code>:HTTPS</code>, and
3050 the URL to redirect to will be constructed
3051 from <clix:arg>host</clix:arg>, <clix:arg>port</clix:arg>, <clix:arg>protocol</clix:arg>,
3052 and <clix:arg>target</clix:arg>.
3055 If <clix:arg>code</clix:arg> is a 3xx redirection code, it
3056 will be sent as status code. In case of <code>NIL</code>, a
3057 302 status code will be sent to the client.
3058 If <clix:arg>host</clix:arg> is not provided, the current host
3059 (see <clix:ref>HOST</clix:ref>) will be
3060 used. If <clix:arg>protocol</clix:arg> is the
3061 keyword <code>:HTTPS</code>, the client will be redirected
3062 to a https URL, if it's <code>:HTTP</code> it'll be sent to
3063 a http URL. If both <clix:arg>host</clix:arg>
3064 and <clix:arg>protocol</clix:arg> aren't provided, then the
3065 value of <clix:arg>protocol</clix:arg> will match the current
3071 <clix:function name="require-authorization">
3072 <clix:lambda-list><clix:lkw>optional</clix:lkw> realm</clix:lambda-list>
3073 <clix:returns>|</clix:returns>
3075 Sends back appropriate headers to require basic HTTP
3077 (see <a href="http://www.faqs.org/rfcs/rfc2617.html">RFC 2617</a>)
3078 for the realm <clix:arg>realm</clix:arg>. The default value
3079 for <clix:arg>realm</clix:arg> is <code>"Hunchentoot"</code>.
3083 <clix:function name='no-cache'>
3089 Adds appropriate headers to completely prevent caching on most browsers.
3093 <clix:function name='ssl-p'>
3096 </clix:lkw> acceptor
3098 <clix:returns>generalized-boolean
3101 Whether the current connection to the client is secure. See <clix:ref>ACCEPTOR-SSL-P</clix:ref>.
3105 <clix:function name='reason-phrase'>
3106 <clix:lambda-list>return-code
3108 <clix:returns>string
3111 Returns a reason phrase for the HTTP return code <clix:arg>return-code</clix:arg>
3112 (which should be an integer) or <code>NIL</code> for return codes Hunchentoot
3117 <clix:function name='rfc-1123-date'>
3122 <clix:returns>string
3125 Generates a time string according to <a href="http://www.faqs.org/rfcs/rfc1123.html">RFC 1123</a>. Default is current time.
3126 This can be used to send a 'Last-Modified' header - see <clix:ref>HANDLE-IF-MODIFIED-SINCE</clix:ref>.
3130 <clix:function name='url-encode'>
3131 <clix:lambda-list>string
3133 </clix:lkw> external-format
3135 <clix:returns>string
3138 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>.
3142 <clix:function name='url-decode'>
3143 <clix:lambda-list>string
3145 </clix:lkw> external-format
3147 <clix:returns>string
3150 Decodes a URL-encoded string which is assumed to
3151 be encoded using the external
3152 format <clix:arg>external-format</clix:arg>, i.e. this is the inverse
3153 of <clix:ref>URL-ENCODE</clix:ref>. It is assumed that you'll rarely
3154 need this function, if ever. But just in case - here it is. The
3155 default for <clix:arg>external-format</clix:arg> is the value
3156 of <clix:ref>*HUNCHENTOOT-DEFAULT-EXTERNAL-FORMAT*</clix:ref>.
3160 <clix:function name='escape-for-html'>
3161 <clix:lambda-list>string
3163 <clix:returns>result
3166 Escapes the characters #\<, #\>, #\', #\", and #\& for HTML output.
3170 <clix:function name="http-token-p">
3171 <clix:lambda-list>object</clix:lambda-list>
3172 <clix:returns>generalized-boolean</clix:returns>
3174 This function tests whether <clix:arg>object</clix:arg> is a
3175 non-empty string which is a <em>token</em> according
3176 to <a href="http://www.faqs.org/rfcs/rfc2068.html">RFC
3177 2068</a> (i.e. whether it may be used for, say, cookie names).
3181 <clix:function name='mime-type'>
3182 <clix:lambda-list>pathspec
3184 <clix:returns>result
3187 Given a pathname designator <clix:arg>pathspec</clix:arg> returns the <a href="http://en.wikipedia.org/wiki/Internet_media_type">MIME type</a>
3188 (as a string) corresponding to the suffix of the file denoted by
3189 <clix:arg>pathspec</clix:arg> (or <code>NIL</code>).
3193 <clix:function name='within-request-p'>
3196 <clix:returns>generalized-boolean
3199 Returns true if in the context of a request. Otherwise, <code>NIL</code>.
3203 <clix:special-variable name="*tmp-directory*">
3205 This should be a pathname denoting a directory where temporary
3206 files can be stored. It is used for <a href="#upload">file
3209 </clix:special-variable>
3211 <clix:special-variable name='*header-stream*'>
3213 If this variable is not <code>NIL</code>, it should be bound to a stream to
3214 which incoming and outgoing headers will be written for debugging
3217 </clix:special-variable>
3220 <clix:special-variable name='*cleanup-function*'>
3222 A designator for a function without arguments which is called on a
3223 regular basis if <clix:ref>*CLEANUP-INTERVAL*</clix:ref> is not <code>NIL</code>. The initial value is
3224 the name of a function which invokes a garbage collection on 32-bit
3225 versions of LispWorks.
3227 This variable is only available on LispWorks.
3230 </clix:special-variable>
3232 <clix:special-variable name='*cleanup-interval*'>
3234 Should be <code>NIL</code> or a positive integer. The system calls
3235 <clix:ref>*CLEANUP-FUNCTION*</clix:ref>
3236 whenever <clix:ref>*CLEANUP-INTERVAL*</clix:ref> new worker threads
3237 (counted globally across all acceptors) have been created unless the
3238 value is <code>NIL</code>. The initial value is 100.
3240 This variable is only available on LispWorks.
3243 </clix:special-variable>
3247 <clix:chapter name="testing" title="Testing">
3248 Hunchentoot comes with a test script which verifies that the
3249 example web server responds as expected. This test script uses the
3250 <a href="http://weitz.de/drakma/">Drakma</a> HTTP client library
3251 and thus shares a significant amount of its base code with
3252 Hunchentoot itself. Still, running the test script is a useful
3253 confidence test, and it is also possible to run the script across
3254 machines in order to verify a new Hunchentoot (or, for that matter
3257 To run the confidence test, <a href="#start">start
3258 the example web server</a>. Then, in your Lisp
3260 <pre>(<a class="noborder" href="hunchentoot-test:test-hunchentoot">hunchentoot-test:test-hunchentoot</a> "http://localhost:4242")</pre>
3261 You will see some diagnostic output and a summary line that
3262 reports whether any tests have failed. (You can also use the
3263 example certificate and key files in the test directory and
3264 start and test an https server instead.)
3267 <clix:function name="hunchentoot-test:test-hunchentoot">
3268 <clix:lambda-list>base-url <clix:lkw>key</clix:lkw></clix:lambda-list>
3269 <clix:returns>|</clix:returns>
3271 Runs the built-in confidence
3272 test. <clix:arg>base-url</clix:arg> is the base URL to use
3273 for testing, it should not have a trailing slash. The keyword
3274 arguments accepted are for future extension and should not
3277 The script expects the Hunchentoot example test server to be
3278 running at the given <clix:arg>base-url</clix:arg> and
3279 retrieves various pages from that server, expecting certain
3286 <clix:chapter name="debugging" title="Debugging">
3287 By default, Hunchentoot intercepts all errors that occur while
3288 executing request handlers, logs them to the log file and displays
3289 a static error page to the user. While developing applications,
3290 you may want to change that behavior so that the debugger is
3291 invoked when an error occurs. You can set
3292 the <clix:ref>*CATCH-ERRORS-P*</clix:ref> to <code>NIL</code> to
3293 make that happen. Alternatively, you may want to have Hunchentoot
3294 display detailed error information in the error response page.
3295 You can set the <clix:ref>*SHOW-LISP-ERRORS-P*</clix:ref> to a
3296 true value to make that happen. If you don't want to see Lisp
3297 backtraces in these error pages, you can
3298 set <clix:ref>*SHOW-LISP-BACKTRACES-P*</clix:ref>
3299 to <code>NIL</code>.
3302 <clix:chapter name="history" title="History">
3304 Hunchentoot's predecessor <a href="http://weitz.de/tbnl/">TBNL</a>
3305 (which is short for "To Be Named Later") grew over the years as a
3306 toolkit that I used for various commercial and private
3307 projects. In August 2003, Daniel Barlow started
3308 a <a href="http://article.gmane.org/gmane.lisp.web/148">review of
3310 the <a href="http://www.red-bean.com/lispweb/">lispweb</a> mailing
3312 I <a href="http://article.gmane.org/gmane.lisp.web/153">described</a>
3313 the API of my hitherto-unreleased bunch of code (and christened it
3317 <a href="http://www.jeffcaldwell.com/">Jeff Caldwell</a> had
3318 worked on something similar so he emailed me and proposed to
3319 join our efforts. As I had no immediate plans to release my code
3320 (which was poorly organized, undocumented, and mostly
3321 CMUCL-specific), I gave it to Jeff and he worked towards a
3322 release. He added docstrings, refactored, added some stuff, and
3323 based it on KMRCL to make it portable across several Lisp
3327 Unfortunately, Jeff is at least as busy as I am so he didn't
3328 find the time to finish a full release. But in spring 2004 I
3329 needed a documented version of the code for a client of mine who
3330 thought it would be good if the toolkit were publicly available
3331 under an open source license. So I took Jeff's code, refactored
3332 again (to sync with the changes I had done in the meantime), and
3333 added documentation. This resulted in TBNL 0.1.0 (which
3334 initially required mod_lisp as its front-end).
3337 In March 2005, Bob Hutchinson sent patches which enabled TBNL to
3338 use other front-ends than mod_lisp. This made me aware that
3339 TBNL was already <em>almost</em> a full web server, so
3340 eventually I wrote Hunchentoot which <em>was</em> a full web
3341 server, implemented as a wrapper around TBNL. Hunchentoot 0.1.0
3342 was released at the end of 2005 and was originally
3346 Hunchentoot 0.4.0, released in October 2006, was the first
3347 release which also worked with other Common Lisp
3348 implementations. It is a major rewrite and also incorporates
3349 most of TBNL and replaces it completely.
3352 Hunchentoot 1.0.0, released in February 2009, is again a major
3353 rewrite and should be considered work in progress. It moved to
3355 the <a href="http://common-lisp.net/project/usocket/">usocket</a>
3356 and <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux
3357 Threads</a> libraries for non-LispWorks Lisps, thereby removing most of
3358 the platform dependent code. Threading behaviour was made
3359 controllable through the introduction of
3360 taskmasters. <a href="http://www.cliki.net/mod_lisp">mod_lisp</a>
3361 support and several other things were removed in this release to
3362 simplify the code base (and partly due to the lack of interest).
3363 Several architectural changes (lots of them not
3364 backwards-compatible) were made to ease customization of
3365 Hunchentoot's behaviour. A significant part of the 1.0.0
3367 by <a href="http://netzhansa.blogspot.com/">Hans Hübner</a>.
3371 <clix:chapter name="index" title="Symbol index">
3373 Here are all exported symbols of the <code>HUNCHENTOOT</code>
3374 package in alphabetical order linked to their corresponding
3375 documentation entries:
3381 <clix:chapter name="ack" title="Acknowledgements">
3383 Thanks to Jeff Caldwell - TBNL would not have been released
3384 without his efforts. Thanks
3385 to <a href="http://www.cliki.net/Stefan%20Scholl">Stefan
3386 Scholl</a> and Travis Cross for various additions and fixes to
3387 TBNL, to <a href="http://www.foldr.org/~michaelw/">Michael
3388 Weber</a> for initial file upload code, and
3389 to <a href="http://www.ltn.lv/~jonis/">Janis Dzerins</a> for
3390 his <a href="http://common-lisp.net/project/rfc2388/">RFC 2388
3391 code</a>. Thanks to Bob Hutchison for his code for multiple
3392 front-ends (which made me realize that TBNL was already pretty
3393 close to a "real" web server) and the initial UTF-8 example.
3394 Thanks to <a href="http://netzhansa.blogspot.com/">Hans Hübner</a>
3395 for a lot of architectural and implementation enhancements for the
3396 1.0.0 release and also for transferring the documentation to sane
3397 XHTML. Thanks to John
3398 Foderaro's <a href="http://opensource.franz.com/aserve/index.html">AllegroServe</a>
3399 for inspiration. Thanks to <a href="http://www.htg1.de/">Uwe von
3401 the <a href="http://www.htg1.de/hunchentoot/hunchentoot.html">Hunchentoot
3405 Hunchentoot originally used code
3406 from <a href="http://www.cliki.net/ACL-COMPAT">ACL-COMPAT</a>,
3407 specifically the chunking code from Jochen Schmidt. (This has been
3408 replaced by <a href="http://weitz.de/chunga/">Chunga</a>.) When I ported
3409 Hunchentoot to other Lisps than LispWorks, I stole code from
3410 ACL-COMPAT, <a href="http://www.cliki.net/kmrcl">KMRCL</a>,
3411 and <a href="http://www.cliki.net/trivial-sockets">trivial-sockets</a> for
3412 implementation-dependent stuff like sockets and MP. (This has been replaced by
3413 <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux
3415 and <a href="http://common-lisp.net/project/usocket/">usocket</a>.)
3418 Parts of this documentation were prepared
3419 with <a href="http://weitz.de/documentation-template/">DOCUMENTATION-TEMPLATE</a>,
3420 no animals were harmed.
3424 <a href='http://weitz.de/index.html'>BACK TO MY HOMEPAGE
3427 </clix:documentation>