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