doc/index.xml

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