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