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:refACCEPTOR</clix:ref> objects (and some of them obviously only make sense for clix:refSSL-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:refACCEPTOR</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:descriptionThe 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-listacceptor </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:refPROCESS-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:refREQUEST</clix:ref> object. This function is called by +clix:refPROCESS-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:refSEND-HEADERS</clix:ref> and write directly to a stream. +</p>

- <clix:function name='create-folder-dispatcher-and-handler'> - clix:lambda-listuri-prefix base-path - clix:lkwoptional - </clix:lkw> content-type - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:descriptionCreates 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&#039;ll be the content type used for all files in the folder. + <clix:special-variable name='*dispatch-table*'> + clix:descriptionA global list of dispatch functions. The + initial value is a list consisting of the two + symbols clix:refDISPATCH-EASY-HANDLERS</clix:ref> + and clix:refDEFAULT-DISPATCHER</clix:ref>. </clix:description> - </clix:function> - <clix:function name='create-prefix-dispatcher'> - clix:lambda-listprefix handler + </clix:special-variable> + + <clix:function name='default-dispatcher'> + clix:lambda-listrequest </clix:lambda-list> clix:returnsresult </clix:returns> - clix:descriptionCreates 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:descriptionDefault 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-listregex handler - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:descriptionCreates 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:descriptionThe name of the function which is always returned by +clix:refDEFAULT-DISPATCHER</clix:ref>. </clix:description> - </clix:function> + </clix:special-variable>

- <clix:function name="handle-static-file"> - clix:lambda-listpath clix:lkwoptional</clix:lkw> content-type</clix:lambda-list> - clix:returnsnil</clix:returns> + <clix:function name="create-prefix-dispatcher"> + clix:lambda-listprefix handler</clix:lambda-list> + clix:returnsdispatch-fn</clix:returns> clix:description - Sends the file denoted by the pathname designator - clix:argpath</clix:arg> with content type - clix:argcontent-type</clix:arg> to the client. Sets the - necessary handlers. In particular the function employs - clix:refHANDLE-IF-MODIFIED-SINCE</clix:ref>. + A convenience function which will return a dispatcher that + returns clix:arghandler</clix:arg> whenever the path part of + the request URI starts with the + string clix:argprefix</clix:arg>. + </clix:description> + </clix:function> + + <clix:function name="create-regex-dispatcher"> + clix:lambda-listregex handler</clix:lambda-list> + clix:returnsdispatch-fn</clix:returns> + clix:description + A convenience function which will return a dispatcher that + returns clix:arghandler</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:argregex</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-listuri-prefix base-path clix:lkwoptional</clix:lkw> content-type</clix:lambda-list> + clix:returnsdispatch-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:argbase-path</clix:arg> that is denoted by the URI of + the request relative + to clix:arguri-prefix</clix:arg>. clix:arguri-prefix</clix:arg> + must be a string ending with a + slash, clix:argbase-path</clix:arg> must be a pathname + designator for an existing directory. + Uses clix:refHANDLE-STATIC-FILE</clix:ref> internally. <p> - If clix:argcontent-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:argcontent-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:refSEND-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-listrequest - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:descriptionDefault 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-listdescription lambda-list [[declaration* | documentation]] form*</clix:lambda-list> @@ -1050,65 +1088,14 @@ clix:returnsresult </clix:returns> clix:descriptionThis is a dispatcher which returns the appropriate handler -defined with DEFINE-EASY-HANDLER, if there is one. +defined with clix:refDEFINE-EASY-HANDLER</clix:ref>, if there is one. </clix:description> </clix:function>

- <clix:special-variable name='*default-handler*'> - clix:descriptionThe name of the function which is always returned by -DEFAULT-DISPATCHER. - </clix:description> - </clix:special-variable>

- <clix:special-variable name='*dispatch-table*'> - clix:descriptionA 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:lkwoptional - </clix:lkw> result - </clix:lambda-list> - clix:returnsresult - </clix:returns> - clix:descriptionThis 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:argresult</clix:arg>. See the -source code of clix:refREDIRECT</clix:ref> for an example. - </clix:description> - </clix:function> - - <clix:function name="handle-if-modified-since"> - clix:lambda-listtime clix:lkwoptional</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:argtime</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:refCREATE-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:refREPLY</clix:ref> object (see clix:refCOOKIE-OUT</clix:ref> and clix:refCOOKIES-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:descriptionSuperclass 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:descriptionSuperclass for all errors related to Hunchentoot and a subclass of clix:refHUNCHENTOOT-CONDITION</clix:ref>. - </clix:description> - </clix:condition> - - <clix:condition name='parameter-error'> - clix:descriptionSignalled if a function was called with incosistent or illegal parameters. A subclass of clix:refHUNCHENTOOT-ERROR</clix:ref>. - </clix:description> - </clix:condition> - - <clix:condition name='hunchentoot-warning'> - clix:descriptionSuperclass for all warnings related to Hunchentoot and a subclass of clix:refHUNCHENTOOT-CONDITION</clix:ref>. - </clix:description> - </clix:condition> - <clix:special-variable name='*show-lisp-errors-p*'> clix:descriptionWhether 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:descriptionSuperclass for all conditions related to Hunchentoot. + </clix:description> + </clix:condition> + + <clix:condition name='hunchentoot-error'> + clix:descriptionSuperclass for all errors related to Hunchentoot and a subclass of clix:refHUNCHENTOOT-CONDITION</clix:ref>. + </clix:description> + </clix:condition> + + <clix:condition name='parameter-error'> + clix:descriptionSignalled if a function was called with incosistent or illegal parameters. A subclass of clix:refHUNCHENTOOT-ERROR</clix:ref>. + </clix:description> + </clix:condition> + + <clix:condition name='hunchentoot-warning'> + clix:descriptionSuperclass for all warnings related to Hunchentoot and a subclass of clix:refHUNCHENTOOT-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:lkwoptional + </clix:lkw> result + </clix:lambda-list> + clix:returnsresult + </clix:returns> + clix:descriptionThis 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:argresult</clix:arg>. See the +source code of clix:refREDIRECT</clix:ref> for an example. + </clix:description> + </clix:function> + + <clix:function name="handle-if-modified-since"> + clix:lambda-listtime clix:lkwoptional</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:argtime</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:refCREATE-STATIC-FILE-DISPATCHER-AND-HANDLER</clix:ref> + for an example. + </p> + </clix:description> + </clix:function> + + <clix:function name="handle-static-file"> + clix:lambda-listpath clix:lkwoptional</clix:lkw> content-type</clix:lambda-list> + clix:returnsnil</clix:returns> + clix:description + Sends the file denoted by the pathname designator + clix:argpath</clix:arg> with content type + clix:argcontent-type</clix:arg> to the client. Sets the + necessary handlers. In particular the function employs + clix:refHANDLE-IF-MODIFIED-SINCE</clix:ref>. + <p> + If clix:argcontent-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:refSEND-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-listtarget clix:lkwkey</clix:lkw> host port protocol add-session-id code</clix:lambda-list> clix:returns|</clix:returns>