drafts, hunchentoot-vib: Document process-request

diff --git a/drafts/000-hunchentoot-vib.markdown b/drafts/000-hunchentoot-vib.markdown
index 17dad70..f7a390a 100644 (file)
--- a/drafts/000-hunchentoot-vib.markdown
+++ b/drafts/000-hunchentoot-vib.markdown
@@ -6,7 +6,45 @@ author: Lucian Mogoșanu
 tags: tech, tmsr
 ---
 
-<a name="pr" href="#pr">[pr]</a> [**process-request**][ht-pr]:
+<a name="pr" href="#pr">[pr]</a> [**process-request**][ht-pr]: This
+function is on the main request processing/handling path, and is
+called by [process-connection][ht-pc] whenever a new HTTP request is
+available. It does a bunch of more or less related things, let's take
+'em one by one.
+
+a\. the first part of the function a1. defines and binds some special
+variables, e.g. the current \*request\* being processed, and a2. wraps
+everything into some condition handling code, namely: a2i. it "maps"
+all [conditions][ht-wmc][^1]; a2ii. wraps this in an
+[unwind-protect][clhs-unwind-protect][^2]; a2iii. all this wrapped in
+a [catch][clhs-catch][^3].
+
+b\. the code at (a) wraps a b1. local procedure definition,
+report-error-to-client, which [logs][ht-lms] an error and returns a
+http-internal-error, i.e. [start-output][ht-so] on the result of an
+[acceptor-status-message][ht-asm]; and b2. a call to
+[handle-request][ht-hr] wrapped in a catch for "handler-done"[^4],
+with the return values for handle-request bound to "contents", "error"
+and "backtrace"; b3. if "error", then report-error-to-client; b4. if
+headers are not yet sent, [start-output][ht-so] with the return code
+of \*reply\* and whatever contents we have; b4. if no contents are
+set, then get a default page from [acceptor-status-message][ht-asm];
+b5. if an error occurs during (b4), then call report-error-to-client.
+
+c\. this occurs on the "cleanup-form" part of the unwind-protect at
+(a2ii): if there are any temporary files that were set up during the
+function, delete them.
+
+This function is all over the fucking place, owing mainly to the
+pretense of "modularity" and separation between requests and replies
+-- I did say they're part of the same logical unit, didn't I? Just
+look at it: "request processing" calls "start output" -- which by the
+way, is part of "headers", right? but this same "start output" is the
+one which actually delivers a response to the client, which response
+delivery oughta be part of "reply"!! So to conclude: this whole shit
+is in dire need of refactoring and ultimately a complete
+rewrite. No-no, this time I'm pretty damn sure it's not the protocol's
+fault for this abomination.
 
 <a name="wrp" href="#wrp">[wrp]</a> [**within-request-p**][ht-wrp]:
 
@@ -75,6 +113,27 @@ tags: tech, tmsr
 
 <a name="rp" href="#rp">[rp]</a> [**request-pathname**][ht-rp]:
 
+[^1]: with-mapped-conditions is actually a [usocket][usocket-wmc]
+    macro which, annoyingly enough, is not documented. Long story
+    short, it can be used to define a context in which all usocket
+    conditions are safely handled. (TODO: add reference to usocket
+    coad?)
+
+[^2]: Which ensures that the code at the end of the function (TODO add
+    reference) gets executed no matter what conditions occur during
+    execution.
+
+[^3]: More precisely, the "request-processed" throw is caught here,
+    which, as the comment describes, is thrown by
+    [start-output][ht-so] after responding to a HEAD
+    request. Basically, what this does is exit process-request once
+    the headers are sent, bypassing all the other request handling
+    code.
+
+       More details about this later.
+
+[^4]: We get there via [abort-request-handler][ht-arh], basically.
+
 [ht-pr]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L219
 [ht-wrp]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L262
 [ht-rrp]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L334
@@ -110,3 +169,13 @@ tags: tech, tmsr
 [ht-darv]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L576
 [ht-pp3]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L585
 [ht-rp]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L613
+[ht-pc]: http://thetarpit.org/posts/y06/098-hunchentoot-iv.html#pc
+[ht-wmc]: http://coad.thetarpit.org/hunchentoot/c-util.lisp.html#L353
+[ht-so]: http://coad.thetarpit.org/hunchentoot/c-headers.lisp.html#L67
+[ht-lms]: http://thetarpit.org/posts/y06/098-hunchentoot-iv.html#lms
+[ht-asm]: http://thetarpit.org/posts/y06/098-hunchentoot-iv.html#asm
+[ht-hr]: http://thetarpit.org/posts/y06/098-hunchentoot-iv.html#hr
+[ht-arh]: /posts/y06/098-hunchentoot-iv.html#selection-762.0-762.5
+[usocket-wmc]: https://quickref.common-lisp.net/usocket.html#go-to-the-USOCKET_003ccolon_003e_003ccolon_003eWITH_002dMAPPED_002dCONDITIONS-macro
+[clhs-catch]: http://www.lispworks.com/documentation/HyperSpec/Body/s_catch.htm
+[clhs-unwind-protect]: http://www.lispworks.com/documentation/HyperSpec/Body/s_unwind.htm