[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/
BKNR Commits
bknr at bknr.net
Thu Feb 19 01:11:43 UTC 2009
Revision: 4289
Author: edi
URL: http://bknr.net/trac/changeset/4289
Done (?)
U trunk/thirdparty/hunchentoot/CHANGELOG
U trunk/thirdparty/hunchentoot/doc/index.xml
Modified: trunk/thirdparty/hunchentoot/CHANGELOG
===================================================================
--- trunk/thirdparty/hunchentoot/CHANGELOG 2009-02-19 00:36:53 UTC (rev 4288)
+++ trunk/thirdparty/hunchentoot/CHANGELOG 2009-02-19 01:11:43 UTC (rev 4289)
@@ -1,5 +1,5 @@
Version 1.0.0
-2009-02-10
+2009-02-19
Architectural redesign (thanks to Hans Hübner)
Lots of small fixes and improvement, too many to enumerate here
Modified: trunk/thirdparty/hunchentoot/doc/index.xml
===================================================================
--- trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-19 00:36:53 UTC (rev 4288)
+++ trunk/thirdparty/hunchentoot/doc/index.xml 2009-02-19 01:11:43 UTC (rev 4289)
@@ -443,7 +443,8 @@
These are readers for various slots of <clix:ref>ACCEPTOR</clix:ref>
objects (and some of them obviously only make sense
for <clix:ref>SSL-ACCEPTOR</clix:ref> objects). See the docstrings of
-these slots for more information.
+these slots for more information and note that there are corresponding
+initargs for all of them.
</clix:description>
</clix:readers>
@@ -513,16 +514,11 @@
<clix:description>
These are accessors for various slots of <clix:ref>ACCEPTOR</clix:ref>
-objects. See the docstrings of these slots for more information.
+objects. See the docstrings of these slots for more information and
+note that there are corresponding initargs for all of them.
</clix:description>
</clix:accessors>
- <clix:special-variable name='*acceptor*'>
- <clix:description>The current ACCEPTOR object while in the context of a request.
- </clix:description>
- </clix:special-variable>
-
-
<clix:function generic='true' name='acceptor-ssl-p'>
<clix:lambda-list>acceptor
</clix:lambda-list>
@@ -765,66 +761,117 @@
</clix:subchapter>
- <clix:subchapter name="request-dispatch" title="Request dispatch">
+ <clix:subchapter name="request-dispatch" title="Request dispatch and handling">
+The main job of <clix:ref>PROCESS-REQUEST</clix:ref> is to select and
+call a function which handles the request, i.e. which looks at the
+data the client has sent and prepares an appropriate reply to send
+back. This is implemented as follows:
+<p>
+Each acceptor has a <a href="#acceptor-request-dispatcher"><em>request
+dispatcher</em></a> which is a unary function that accepts
+a <clix:ref>REQUEST</clix:ref> object. This function is called by
+<clix:ref>PROCESS-REQUEST</clix:ref>. The idea is that this function
+looks at the request object and depending on its contents decides to
+call another function which "does the work". This "other" function is
+by convention called a <a class="none" name="handlers"><em>request
+handler</em></a>. (Obviously, this is really only a convention as
+process-request doesn't "know" what the request dispatcher does. You
+could as well say that the request dispatcher and the request handler
+have the same job.)
+</p>
+<p>
+The default behaviour, unless you implement your own request
+dispatcher, is that Hunchentoot walks through the list
+*dispatch-table* which consists of <em>dispatch functions</em>. Each
+of these functions accepts the request object as its only argument and
+either returns a request handler to handle the request
+or <code>NIL</code> which means that the next dispatcher in the list
+will be tried. If all dispatch functions return <code>NIL</code>, the
+return code
+<clix:ref>+HTTP-NOT-FOUND+</clix:ref> will be sent to the client.
+</p>
+<p>
+All functions and variables in this section are related to the
+standard request dispatch mechanism described above and are
+meaningless if you're using your own request dispatcher.
+</p>
+<p>
+Request handlers do their work by modifying
+the <a href="#replies">reply object</a> if necessary and by eventually
+returning the response body in the form of a string or a binary
+sequence. As an alternative, they can also
+call <clix:ref>SEND-HEADERS</clix:ref> and write directly to a stream.
+</p>
- <clix:function name='create-folder-dispatcher-and-handler'>
- <clix:lambda-list>uri-prefix base-path
- <clix:lkw>optional
- </clix:lkw> content-type
- </clix:lambda-list>
- <clix:returns>result
- </clix:returns>
- <clix:description>Creates and returns a dispatch function which will dispatch to a
-handler function which emits the file relative to BASE-PATH that is
-denoted by the URI of the request relative to URI-PREFIX. URI-PREFIX
-must be a string ending with a slash, BASE-PATH must be a pathname
-designator for an existing directory. If CONTENT-TYPE is not NIL,
-it'll be the content type used for all files in the folder.
+ <clix:special-variable name='*dispatch-table*'>
+ <clix:description>A global list of dispatch functions. The
+ initial value is a list consisting of the two
+ symbols <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>
+ and <clix:ref>DEFAULT-DISPATCHER</clix:ref>.
</clix:description>
- </clix:function>
- <clix:function name='create-prefix-dispatcher'>
- <clix:lambda-list>prefix handler
+ </clix:special-variable>
+
+ <clix:function name='default-dispatcher'>
+ <clix:lambda-list>request
</clix:lambda-list>
<clix:returns>result
</clix:returns>
- <clix:description>Creates a request dispatch function which will dispatch to the
-function denoted by HANDLER if the file name of the current request
-starts with the string PREFIX.
+ <clix:description>Default dispatch function which handles every request with the
+function stored in <clix:ref>*DEFAULT-HANDLER*</clix:ref>.
</clix:description>
</clix:function>
- <clix:function name='create-regex-dispatcher'>
- <clix:lambda-list>regex handler
- </clix:lambda-list>
- <clix:returns>result
- </clix:returns>
- <clix:description>Creates a request dispatch function which will dispatch to the
-function denoted by HANDLER if the file name of the current request
-matches the CL-PPCRE regular expression REGEX.
+
+ <clix:special-variable name='*default-handler*'>
+ <clix:description>The name of the function which is always returned by
+<clix:ref>DEFAULT-DISPATCHER</clix:ref>.
</clix:description>
- </clix:function>
+ </clix:special-variable>
- <clix:function name="handle-static-file">
- <clix:lambda-list>path <clix:lkw>optional</clix:lkw> content-type</clix:lambda-list>
- <clix:returns>nil</clix:returns>
+ <clix:function name="create-prefix-dispatcher">
+ <clix:lambda-list>prefix handler</clix:lambda-list>
+ <clix:returns>dispatch-fn</clix:returns>
<clix:description>
- Sends the file denoted by the pathname designator
- <clix:arg>path</clix:arg> with content type
- <clix:arg>content-type</clix:arg> to the client. Sets the
- necessary handlers. In particular the function employs
- <clix:ref>HANDLE-IF-MODIFIED-SINCE</clix:ref>.
+ A convenience function which will return a dispatcher that
+ returns <clix:arg>handler</clix:arg> whenever the path part of
+ the request URI starts with the
+ string <clix:arg>prefix</clix:arg>.
+ </clix:description>
+ </clix:function>
+
+ <clix:function name="create-regex-dispatcher">
+ <clix:lambda-list>regex handler</clix:lambda-list>
+ <clix:returns>dispatch-fn</clix:returns>
+ <clix:description>
+ A convenience function which will return a dispatcher that
+ returns <clix:arg>handler</clix:arg> whenever the path part of
+ the request URI matches
+ the <a href="http://weitz.de/cl-ppcre/">CL-PPCRE</a> regular
+ expression <clix:arg>regex</clix:arg> (which can be a string, an
+ s-expression, or a scanner).
+ </clix:description>
+ </clix:function>
+
+ <clix:function name="create-folder-dispatcher-and-handler">
+ <clix:lambda-list>uri-prefix base-path <clix:lkw>optional</clix:lkw> content-type</clix:lambda-list>
+ <clix:returns>dispatch-fn</clix:returns>
+ <clix:description>
+ Creates and returns a dispatch function which will dispatch to
+ a handler function which emits the file relative
+ to <clix:arg>base-path</clix:arg> that is denoted by the URI of
+ the request relative
+ to <clix:arg>uri-prefix</clix:arg>. <clix:arg>uri-prefix</clix:arg>
+ must be a string ending with a
+ slash, <clix:arg>base-path</clix:arg> must be a pathname
+ designator for an existing directory.
+ Uses <clix:ref>HANDLE-STATIC-FILE</clix:ref> internally.
<p>
- If <clix:arg>content-type</clix:arg> is <code>NIL</code> the
- function tries to determine the correct content type from
- the file's suffix or falls back
- to <code>"application/octet-stream"</code> as a last resort.
+ If <clix:arg>content-type</clix:arg> is <em>not</em>
+ <code>NIL</code>, it will be used as a the content type for
+ all files in the folder. Otherwise (which is the default)
+ the content type of each file will be
+ determined <a href="#handle-static-file">as usual</a>.
</p>
- <p>
- Note that this function
- calls <clix:ref>SEND-HEADERS</clix:ref> internally, so after
- you've called it, the headers are sent and the return value
- of your handler is ignored.
- </p>
</clix:description>
</clix:function>
@@ -843,15 +890,6 @@
</clix:description>
</clix:function>
- <clix:function name='default-dispatcher'>
- <clix:lambda-list>request
- </clix:lambda-list>
- <clix:returns>result
- </clix:returns>
- <clix:description>Default dispatch function which handles every request with the
-function stored in *DEFAULT-HANDLER*.
- </clix:description>
- </clix:function>
<clix:function macro="true" name="define-easy-handler">
<clix:lambda-list>description lambda-list [[declaration* | documentation]] form*</clix:lambda-list>
@@ -1050,65 +1088,14 @@
<clix:returns>result
</clix:returns>
<clix:description>This is a dispatcher which returns the appropriate handler
-defined with DEFINE-EASY-HANDLER, if there is one.
+defined with <clix:ref>DEFINE-EASY-HANDLER</clix:ref>, if there is one.
</clix:description>
</clix:function>
- <clix:special-variable name='*default-handler*'>
- <clix:description>The name of the function which is always returned by
-DEFAULT-DISPATCHER.
- </clix:description>
- </clix:special-variable>
- <clix:special-variable name='*dispatch-table*'>
- <clix:description>A global list of dispatch functions.
- </clix:description>
- </clix:special-variable>
-
</clix:subchapter>
- <clix:subchapter name="handlers" title="Handlers">
-
- <clix:function name='abort-request-handler'>
- <clix:lambda-list>
- <clix:lkw>optional
- </clix:lkw> result
- </clix:lambda-list>
- <clix:returns>result
- </clix:returns>
- <clix:description>This function can be called by a request handler
-at any time to immediately abort handling the request. This works as
-if the handler had returned <clix:arg>result</clix:arg>. See the
-source code of <clix:ref>REDIRECT</clix:ref> for an example.
- </clix:description>
- </clix:function>
-
- <clix:function name="handle-if-modified-since">
- <clix:lambda-list>time <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
- <clix:returns>|</clix:returns>
- <clix:description>
- This function is designed to be used inside
- a <a href="#handlers">handler</a>. If the client has sent an
- 'If-Modified-Since' header
- (see <a href="http://www.faqs.org/rfcs/rfc2616.html">RFC 2616</a>,
- section 14.25) and the time specified matches the universal
- time
- <clix:arg>time</clix:arg> then the
- header <clix:ref>+HTTP-NOT-MODIFIED+</clix:ref> with no content
- is immediately returned to the client.
- <p>
- Note that for this function to be useful you should usually
- send 'Last-Modified' headers back to the client. See the
- code
- of <clix:ref>CREATE-STATIC-FILE-DISPATCHER-AND-HANDLER</clix:ref>
- for an example.
- </p>
- </clix:description>
- </clix:function>
-
- </clix:subchapter>
-
<clix:subchapter name="requests" title="Request objects">
For each incoming request, the <a href="#acceptors">acceptor</a>
@@ -2434,7 +2421,7 @@
<clix:subchapter name="cookies" title="Cookies">
- Outgoing cookies are stored in the request's <code>REPLY</code>
+ Outgoing cookies are stored in the request's <clix:ref>REPLY</clix:ref>
object (see <clix:ref>COOKIE-OUT</clix:ref>
and <clix:ref>COOKIES-OUT*</clix:ref>). They are CLOS objects
defined like this:
@@ -2599,26 +2586,9 @@
<clix:subchapter name="conditions" title="Conditions and error handling">
- <clix:condition name='hunchentoot-condition'>
- <clix:description>Superclass for all conditions related to Hunchentoot.
- </clix:description>
- </clix:condition>
+This section describes how Hunchentoot deals with exceptional
+situations. See also the secion about <a href="#logging">logging</a>.
- <clix:condition name='hunchentoot-error'>
- <clix:description>Superclass for all errors related to Hunchentoot and a subclass of <clix:ref>HUNCHENTOOT-CONDITION</clix:ref>.
- </clix:description>
- </clix:condition>
-
- <clix:condition name='parameter-error'>
- <clix:description>Signalled if a function was called with incosistent or illegal parameters. A subclass of <clix:ref>HUNCHENTOOT-ERROR</clix:ref>.
- </clix:description>
- </clix:condition>
-
- <clix:condition name='hunchentoot-warning'>
- <clix:description>Superclass for all warnings related to Hunchentoot and a subclass of <clix:ref>HUNCHENTOOT-CONDITION</clix:ref>.
- </clix:description>
- </clix:condition>
-
<clix:special-variable name='*show-lisp-errors-p*'>
<clix:description>Whether Lisp errors should be shown in HTML output.
</clix:description>
@@ -2648,10 +2618,94 @@
</clix:description>
</clix:special-variable>
+ <clix:condition name='hunchentoot-condition'>
+ <clix:description>Superclass for all conditions related to Hunchentoot.
+ </clix:description>
+ </clix:condition>
+
+ <clix:condition name='hunchentoot-error'>
+ <clix:description>Superclass for all errors related to Hunchentoot and a subclass of <clix:ref>HUNCHENTOOT-CONDITION</clix:ref>.
+ </clix:description>
+ </clix:condition>
+
+ <clix:condition name='parameter-error'>
+ <clix:description>Signalled if a function was called with incosistent or illegal parameters. A subclass of <clix:ref>HUNCHENTOOT-ERROR</clix:ref>.
+ </clix:description>
+ </clix:condition>
+
+ <clix:condition name='hunchentoot-warning'>
+ <clix:description>Superclass for all warnings related to Hunchentoot and a subclass of <clix:ref>HUNCHENTOOT-CONDITION</clix:ref>.
+ </clix:description>
+ </clix:condition>
+
</clix:subchapter>
<clix:subchapter name="misc" title="Miscellaneous">
+ Various functions and variables which didn't fit into one of the
+ other categories.
+
+ <clix:function name='abort-request-handler'>
+ <clix:lambda-list>
+ <clix:lkw>optional
+ </clix:lkw> result
+ </clix:lambda-list>
+ <clix:returns>result
+ </clix:returns>
+ <clix:description>This function can be called by a request handler
+at any time to immediately abort handling the request. This works as
+if the handler had returned <clix:arg>result</clix:arg>. See the
+source code of <clix:ref>REDIRECT</clix:ref> for an example.
+ </clix:description>
+ </clix:function>
+
+ <clix:function name="handle-if-modified-since">
+ <clix:lambda-list>time <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
+ <clix:returns>|</clix:returns>
+ <clix:description>
+ This function is designed to be used inside
+ a <a href="#handlers">handler</a>. If the client has sent an
+ 'If-Modified-Since' header
+ (see <a href="http://www.faqs.org/rfcs/rfc2616.html">RFC 2616</a>,
+ section 14.25) and the time specified matches the universal
+ time
+ <clix:arg>time</clix:arg> then the
+ header <clix:ref>+HTTP-NOT-MODIFIED+</clix:ref> with no content
+ is immediately returned to the client.
+ <p>
+ Note that for this function to be useful you should usually
+ send 'Last-Modified' headers back to the client. See the
+ code
+ of <clix:ref>CREATE-STATIC-FILE-DISPATCHER-AND-HANDLER</clix:ref>
+ for an example.
+ </p>
+ </clix:description>
+ </clix:function>
+
+ <clix:function name="handle-static-file">
+ <clix:lambda-list>path <clix:lkw>optional</clix:lkw> content-type</clix:lambda-list>
+ <clix:returns>nil</clix:returns>
+ <clix:description>
+ Sends the file denoted by the pathname designator
+ <clix:arg>path</clix:arg> with content type
+ <clix:arg>content-type</clix:arg> to the client. Sets the
+ necessary handlers. In particular the function employs
+ <clix:ref>HANDLE-IF-MODIFIED-SINCE</clix:ref>.
+ <p>
+ If <clix:arg>content-type</clix:arg> is <code>NIL</code> the
+ function tries to determine the correct content type from
+ the file's suffix or falls back
+ to <code>"application/octet-stream"</code> as a last resort.
+ </p>
+ <p>
+ Note that this function
+ calls <clix:ref>SEND-HEADERS</clix:ref> internally, so after
+ you've called it, the headers are sent and the return value
+ of your handler is ignored.
+ </p>
+ </clix:description>
+ </clix:function>
+
<clix:function name="redirect">
<clix:lambda-list>target <clix:lkw>key</clix:lkw> host port protocol add-session-id code</clix:lambda-list>
<clix:returns>|</clix:returns>
More information about the Bknr-cvs
mailing list