From 31363f498e867bdc2f14571f850aeaa6560805cc Mon Sep 17 00:00:00 2001
From: Lucian Mogosanu <lucian@mogosanu.ro>
Date: Wed, 28 Aug 2019 11:41:05 +0300
Subject: [PATCH] drafts, hunchentoot-vib: Document start-output

---
 drafts/000-hunchentoot-vib.markdown |   54 ++++++++++++++++++++++++++++++-----
 1 file changed, 47 insertions(+), 7 deletions(-)

diff --git a/drafts/000-hunchentoot-vib.markdown b/drafts/000-hunchentoot-vib.markdown
index ee2ca67..4f20374 100644
--- a/drafts/000-hunchentoot-vib.markdown
+++ b/drafts/000-hunchentoot-vib.markdown
@@ -328,14 +328,52 @@ running.
     reference) gets executed no matter what conditions occur during
     execution.
 
-[^5]: More precisely, the "request-processed" throw is caught here,
-    which, as the comment describes, is thrown by
+[^5]: More precisely, "request-processed" [throw][clhs-throw]s are
+    caught here, which, as the comment describes, are 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.
+    request. The idea is, when the request method is HEAD, exit
+    process-request once the headers are sent, bypassing all the other
+    request handling code.
+
+	Since we're here, let's examine [start-output][ht-so]: this is the
+    function that pushes the actual response headers and content to
+    the socket. a\. determine whether the keep-alive should be set: if
+    either: a1. we used chunked transmission; or a2. the request
+    method is HEAD; or a3. the return code is http-not-modified; or
+    a4. the content-length or the content are set; then set
+    keep-alive-p to true. b\. when the acceptor requests output
+    chunking, set the Transfer-Encoding header to chunked; c\. if
+    c1. keep-alive-p is set to true, then set
+    \*finish-processing-socket\* to nil; if a keep-alive was
+    requested, then set the Connection header to Keep-Alive, and set
+    the keep-alive timeout; otherwise, if c2. the Connection header is
+    not set, set it to Close. d\. set the Server header, if the
+    acceptor contains one and it wasn't already set. e\. set the Date
+    header; f\. do some weird-ass URL rewriting for
+    sessions\*. g\. convert the content to the encoding given by
+    [reply-external-format\*](#refs). h\. set the
+    content-length. i\. if \*headers-sent\* was set, then return;
+    otherwise j\. set \*headers-sent\* to true and call
+    [send-response][ht-sr], then k\. throw a request-processed to end
+    processing. Otherwise, l\. make our stream into a "chunked
+    stream".
+
+	From the sausage above, [send-response][ht-sr] is what does the
+    actual pushing of the first response line, headers, content and so
+    on.
+
+	The only thing this whole load of crap gives is the ability for
+    the user to do his own processing, by writing a custom
+    start-output which throws its own request-processed and bypasses
+    the entire process-request control flow. This is, as far as I can
+    tell, evidence of serious brain rot on the part of whoever wrote
+    this, since the user can write his own thing by simply modifying
+    the existing code, otherwise there being really no need for all
+    this imagined flexibility.
+
+	\-\-\-  
+	\*: I don't know what the fuck this is, make sure to keep note of
+    it if you ever plan to use the "sessions" thing.
 
 [^6]: We get there via [abort-request-handler][ht-arh], basically.
 
@@ -393,6 +431,7 @@ running.
 [ht-effct]: /posts/y06/09c-hunchentoot-via.html#effct
 [ht-ad-slot]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L90
 [ht-sn-slot]: http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L79
+[ht-sr]: http://coad.thetarpit.org/hunchentoot/c-headers.lisp.html#L160
 [ht-c-rep]: http://coad.thetarpit.org/hunchentoot/c-reply.lisp.html#L31
 [ht-ct-slot]: http://coad.thetarpit.org/hunchentoot/c-reply.lisp.html#L32
 [ht-cl-slot]: http://coad.thetarpit.org/hunchentoot/c-reply.lisp.html#L35
@@ -423,6 +462,7 @@ running.
 [rfc-7239]: https://tools.ietf.org/html/rfc7239#section-4
 [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-throw]: http://clhs.lisp.se/Body/s_throw.htm
 [clhs-unwind-protect]: http://www.lispworks.com/documentation/HyperSpec/Body/s_unwind.htm
 [hunchentoot-iii]: /posts/y06/097-hunchentoot-iii.html
 [logs-mp-on-lisp-www]: http://logs.nosuchlabs.com/log/trilema/2019-08-01#1926066
-- 
1.7.10.4