drafts, hunchentoot-vi: Update

diff --git a/drafts/000-hunchentoot-vi.markdown b/drafts/000-hunchentoot-vi.markdown
index c5da5f8..cf59587 100644 (file)
--- a/drafts/000-hunchentoot-vi.markdown
+++ b/drafts/000-hunchentoot-vi.markdown
@@ -10,11 +10,11 @@ This post is part of a series on [Common Lisp WWWism][cl-www], more
 specifically dissecting the Common Lisp web server known as
 Hunchentoot. Other posts in the series include:
 
-* a walk through the project's [history][ht-i];
-* a set of [architectural notes][ht-ii] and [follow-up][ht-iii] on the
-  same;
-* a review of [acceptors][ht-iv]; and
-* a review of [taskmasters][ht-v].
+* a walk through the project's [history][hunchentoot-i];
+* a set of [architectural notes][hunchentoot-ii] and
+  [follow-up][hunchentoot-iii] on the same;
+* a review of [acceptors][hunchentoot-iv]; and
+* a review of [taskmasters][hunchentoot-v].
 
 This post will discuss the objects known as "requests" and "replies",
 as they are part of the very same fundamental mechanism.
@@ -54,6 +54,112 @@ this; the actual policy (i.e. whether a resource is to be associated
 with a file on the disk, or a set of database entries or whatever) is
 implemented by the user.
 
+In what is becoming a traditional tarpitian style of documenting code,
+we will move directly to:
+
+**[[]]** [**request**][ht-c-req]: Object holding everything pertaining
+to a HTTP request: headers, a method, local/remote address/ports, the
+protocol version, a socket stream, GET/POST parameters, the resource
+being requested; additionally: the raw POST data, a reference to the
+acceptor on which the request was made, "auxiliary data" to be
+employed by the user however he or she wishes.
+
+Note that (somewhat counter-intuitively) request parsing and object
+creation doesn't occur in request.lisp, but upstream in
+[process-connection][ht-pc], and more specifically headers are parsed
+in headers.lisp, in [get-request-data][ht-iv-grd][^3]. So then what
+does request.lisp do? Well, it: defines the data structure; implements
+a lot of scaffolding for GET and POST parameter parsing; implements a
+user interface for request handlers; and finally, it creates a context
+in which request handlers can be safely executed, i.e. if something
+fails, execution can be unwound to the place where
+[handle-request][ht-hr] was called and an error response can be logged
+and returned. Let's look at each of these pieces.
+
+<a name="ch" href="#ch">[ch]</a> [**convert-hack**][ht-ch]:
+
+<a name="prfd" href="#prfd">[prfd]</a>
+[**parse-rfc2388-form-data**][ht-prfd]:
+
+<a name="gpd" href="#gpd">[prfd]</a> [**get-post-data**][ht-gpd]:
+
+<a name="ii2" href="#ii2">[ii2]</a> [**initialize-instance**][ht-ii2]:
+
+<a name="pr" href="#pr">[pr]</a> [**process-request**][ht-pr]:
+
+<a name="wrp" href="#wrp">[wrp]</a> [**within-request-p**][ht-wrp]:
+
+<a name="mrpp" href="#mrpp">[mrpp]</a>
+[**maybe-read-post-parameters**][ht-mrpp]:
+
+<a name="rrp" href="#rrp">[rrp]</a>
+[**recompute-request-parameters**][ht-rrp]:
+
+<a name="sns" href="#sns">[sns]</a> [**script-name\***][ht-sns]:
+
+<a name="qss" href="#sns">[qss]</a> [**query-string\***][ht-qss]:
+
+<a name="gps" href="#gps">[gps]</a> [**get-parameters\***][ht-gps]:
+
+<a name="pp" href="#pp">[pp]</a> [**post-parameters**][ht-pp]:
+
+<a name="pps" href="#pps">[pps]</a> [**post-parameters\***][ht-pps]:
+
+<a name="his" href="#his">[his]</a> [**headers-in\***][ht-his]:
+
+<a name="cis" href="#cis">[cis]</a> [**cookies-in\***][ht-cis]:
+
+<a name="hi" href="#hi">[hi]</a> [**header-in**][ht-hi]:
+
+<a name="his2" href="#his2">[his2]</a> [**header-in\***][ht-his2]:
+
+<a name="a" href="#a">[a]</a> [**authorization**][ht-a]:
+
+<a name="ras" href="#ras">[ras]</a> [**remote-addr\***][ht-ras]:
+
+<a name="rps" href="#rps">[rps]</a> [**remote-port\***][ht-rps]:
+
+<a name="las" href="#las">[las]</a> [**local-addr\***][ht-las]:
+
+<a name="lps" href="#lps">[lps]</a> [**local-port\***][ht-lps]:
+
+<a name="rra" href="#rra">[rra]</a> [**real-remote-addr**][ht-rra]:
+
+<a name="h" href="#h">[h]</a> [**host**][ht-h]:
+
+<a name="rus" href="#rus">[rus]</a> [**request-uri\***][ht-rus]:
+
+<a name="rms" href="#rms">[rms]</a> [**request-method\***][ht-rms]:
+
+<a name="sps" href="#sps">[sps]</a> [**server-protocol\***][ht-sps]:
+
+<a name="ua" href="#ua">[ua]</a> [**user-agent**][ht-ua]:
+
+<a name="ci" href="#ci">[ci]</a> [**cookie-in**][ht-ci]:
+
+<a name="r" href="#r">[r]</a> [**referer**][ht-r]:
+
+<a name="gp" href="#gp">[gp]</a> [**get-parameter**][ht-gp]:
+
+<a name="pp" href="#pp">[pp]</a> [**post-parameter**][ht-pp]:
+
+<a name="p" href="#p">[p]</a> [**parameter**][ht-p]:
+
+<a name="hims" href="#hims">[hims]</a> [**handle-if-modified-since**][ht-hims]:
+
+<a name="effct" href="#effct">[effct]</a>
+[**external-format-from-content-type**][ht-effct]:
+
+<a name="rpd" href="#rpd">[rpd]</a> [**raw-post-data**][ht-rpd]:
+
+<a name="arv" href="#arv">[arv]</a> [**aux-request-value**][ht-arv]:
+
+<a name="darv" href="#darv">[darv]</a> [**delete-aux-request-value**][ht-darv]:
+
+<a name="pp2" href="#pp2">[pp2]</a> [**parse-path**][ht-pp2]:
+
+<a name="rp" href="#rp">[rp]</a> [**request-pathname**][ht-rp]:
+
 [^1]: In practice some c in C can also be a s in S and vice-versa, why
     not? In a sane world C and S would be the same set, and thus our
     client-server-herpderp model would become that of a peer-to-peer
@@ -78,6 +184,14 @@ implemented by the user.
        In other words, fuck these sons of bitches and all their cancerous
     "improvements".
 
+[^3]: And here's where I find out I've actually been reading all this
+    in the correct order, given that *I know* where this particular
+    bit occurs and I don't need to spend hours digging into finding
+    out. Pretty neat, huh?
+
+       Now how 'bout *you* get a blog and start doing this for the coad
+    that you're using? Wouldn't that be neat?
+
 [chunking]: /posts/y06/098-hunchentoot-iv.html#fn2
 [tcp]: /posts/y05/096-hunchentoot-ii.html#fn1
 [alf-cl-on-pc]: http://trilema.com/2019/trilema-goes-dark/#comment-130686
@@ -89,3 +203,49 @@ implemented by the user.
 [rfc-8615]: https://tools.ietf.org/html/rfc8615
 [rfc-1945-5]: https://tools.ietf.org/html/rfc1945#section-5
 [rfc-1945-6]: https://tools.ietf.org/html/rfc1945#section-6
+[ht-c-req]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L31
+[ht-ch]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L118
+[ht-prfd]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L127
+[ht-gpd]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L150
+[ht-ii2]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L185
+[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-pmfd]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L266
+[ht-mrpp]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L282
+[ht-rrp]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L334
+[ht-sns]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L344
+[ht-qss]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L349
+[ht-gps]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L354
+[ht-pp]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L359
+[ht-pps]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L368
+[ht-his]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L373
+[ht-cis]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L378
+[ht-hi]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L383
+[ht-his2]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L389
+[ht-a]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L394
+[ht-ras]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L407
+[ht-rps]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L411
+[ht-las]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L415
+[ht-lps]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L419
+[ht-rra]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L423
+[ht-h]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L433
+[ht-rus]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L437
+[ht-rms]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L441
+[ht-sps]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L445
+[ht-ua]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L449
+[ht-ci]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L453
+[ht-r]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L458
+[ht-gp]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L462
+[ht-pp]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L467
+[ht-p]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L472
+[ht-hims]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L480
+[ht-effct]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L495
+[ht-rpd]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L508
+[ht-arv]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L551
+[ht-arv2]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L559
+[ht-darv]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L576
+[ht-pp2]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L585
+[ht-rp]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L613
+[ht-pc]: /posts/y06/098-hunchentoot-iv.html#pc
+[ht-iv-grd]: /posts/y06/098-hunchentoot-iv.html#fn3
+[ht-hr]: /posts/y06/098-hunchentoot-iv.html#hr