From 1e054caf6952464bba2518d93b568b8d7c02fe5a Mon Sep 17 00:00:00 2001 From: Lucian Mogosanu Date: Wed, 24 Jul 2019 15:47:13 +0300 Subject: [PATCH] Add hunchentoot notes draft For now, an architectural diagram. --- drafts/000-hunchentoot-iii.markdown | 137 +++++++++++++++++++++++++++++ uploads/2019/07/hunchentootarch.dot | 63 ++++++++++++++ uploads/2019/07/hunchentootarch.svg | 163 +++++++++++++++++++++++++++++++++++ 3 files changed, 363 insertions(+) create mode 100644 drafts/000-hunchentoot-iii.markdown create mode 100644 uploads/2019/07/hunchentootarch.dot create mode 100644 uploads/2019/07/hunchentootarch.svg diff --git a/drafts/000-hunchentoot-iii.markdown b/drafts/000-hunchentoot-iii.markdown new file mode 100644 index 0000000..f7e80a8 --- /dev/null +++ b/drafts/000-hunchentoot-iii.markdown @@ -0,0 +1,137 @@ +--- +postid: 000 +title: Hunchentoot: further architectural notes; and usage examples +date: July 25, 2019 +author: Lucian Mogoșanu +tags: tech, tmsr +--- + +This post is part of a series on [Common Lisp WWWism][cl-www], more +specifically a continuation of [ongoing work][hunchentoot-i] to +[understand][hunchentoot-ii] the web server known as Hunchentoot and, +as a result, produce a signed genesis to be used by members of the +TMSR [WoT][wot]. + +In this episode we'll do another illustration of the Hunchentoot +architecture; and we'll have fun documenting a running web server +instance, thusly exploring for now a few of things that it can do[^1]. + +First, the architectural diagram, with bells, whistles and clickable +stuff: + + +
+ + + +
+ +No, really, I'm not kidding: if you have a browser that implements +SVG, clicking on the text should direct you to defgeneric pieces of +code[^2]. Anyway, the big squares are Hunchentoot components and, more +specifically, the name of their CL classes, while the small squares +found inside the big ones represent methods specializing on a given +class. The green boxes are user actionable or defineable methods, so +this is where you should start looking; while the arrows denote the "X +calls Y" relation, with the exception of the dashed green arrow, that +denotes that header-out is in fact a setf-able object used from +somewhere within the context of acceptor-dispatch-request, e.g. a +dispatcher function. + +Now from this airplane view, Hunchentoot's organization looks quite +digestible, which should give us a very good idea of how to start +using it. + +[^1]: Contrary to popular belief and expectations, the things that + some particular X can do that are known to (some particular) me + are not to be confused with the total set of things that said X + can possibly do, nor with the set of things that it *can't* + do. Take for example X = your average pointeristic slash + buffer-overflowistic C barfola: you can identify some particular + uses for it, sure, but meanwhile the average douchebag will + exercise code paths that may make it usable for things you've + never imagined, such as stealing your keys, wiping your disk and + murdering your dog... and many other things, short of making you + some french fries, which is something that e.g. a web server can't + do. + + In other words, nobody gives a fuck about popular beliefs and + expectations; and by the time I publish a [signed][io] genesis for + this Hunchentoot thing -- good, bad, with or without warts or + however we have it -- I will be entirely able to say what it does + and doesn't do, which is exactly what I'm doing here right now. + + And now to be an asshole and leave this otherwise properly rounded + footnote hanging: what about, say, [usocket][usocket]? and then + what about SBCL or some other working CLtron? and what about + [Linux][btcbase-1923536] and [its userland][cuntoo]? This + unfortunately is the curse of our postmodern times: our ability to + run computing machines rests, for the time being, upon the promise + of some [shitheads][btcbase-1918973]. + +[^2]: I don't write HTML and CSS for a living, so I might as well use + this footnote to document the pain required to generate this, for + later reference. + + Specifying the diagram in GraphViz is fairly straightforward: one + simply has to list the clusters, the nodes and the edges within + them in a text file -- see for example the final [.dot + file][hunchentootarch-dot] used for generating the illustration + above. Adding links and colours and all that is also easy, as + previously shown. The problem, however, with this GraphViz thing + is that graph generation involves an automated step, i.e. node + layout generation and edge routing, that can easily prove to be a + pain in the ass for the user: not only do I want this diagram + generated, but I also want the diagram generated like *so*, and + not like *that*, because I want the viewer to be able to look at + the components of the graph in some particular order. + + To add insult to injury, this automated step is almost entirely + opaque to the user: in order to have that square near that one, I + need to frantically shuffle nodes and edges about until I find the + magic ordering that generates something close to what I want -- + that is, the relationship between said ordering and the output is + purely coincidental, and I'm stuck guessing based on the vague + hints found in the spec. Anyway, this is the best diagram layout + we've got here at The Tar Pit, sorry... do make sure to write in + if I'm in the wrong. + + Now that I have a representation, I need to embed it in the blog + post. One would expect that's also straightforward, wouldn't they? + Well, no! You see, I got the idea that putting clickable links in + the generated SVG files is cool, only this doesn't work in the + slightest when inserting the .svg using img tags, because + completely counter-intuitively, the browser displays *an image*, + not a DOM sub-tree. So then I look at how Phf did it with his + [patch viewe][btcbase-patches], and it looks like he's inserting a + HTML image-map in the HTML document, which kinda beats the purpose + of having links in the SVG in the first place. I really, *really* + don't want to copy-paste the whole SVG file into the post, so what + the fuck am I gonna do, use <object> tags?! + + So if by now you were curious enough to look at the page source, + you'll notice that what I did was to insert an inline svg that + then imports the content of my .svg file using the + [<use>][svg-use] tag, which works exactly the way I want + it. And no, you won't find this anywhere on Google either, because + Google [doesn't fucking work][btcbase-1922361]. + + To sum this up: IMHO the result looks pretty cool, with the + mention that I'm most likely going to draw the SVG "by hand" next + time I'm doing anything non-trivial. At least then no magic tool + will lie to me that it saves hours of my work, when it instead + adds to it. + +[cl-www]: /posts/y05/090-tmsr-work-ii.html#selection-108.0-108.17 +[hunchentoot-i]: /posts/y05/093-hunchentoot-i.html +[hunchentoot-ii]: /posts/y05/096-hunchentoot-ii.html +[wot]: http://wot.deedbot.org/ +[io]: /posts/y04/069-on-intellectual-ownership.html +[usocket]: http://archive.is/3UKXf +[btcbase-1923536]: http://btcbase.org/log/2019-07-19#1923536 +[cuntoo]: http://btcbase.org/log-search?q=cuntoo +[btcbase-1918973]: http://btcbase.org/log/2019-06-20#1918973 +[hunchentootarch-dot]: /uploads/2019/07/hunchentootarch.dot +[btcbase-patches]: http://btcbase.org/patches +[svg-use]: http://archive.is/JfGyb +[btcbase-1922361]: http://btcbase.org/log/2019-07-12#1922361 diff --git a/uploads/2019/07/hunchentootarch.dot b/uploads/2019/07/hunchentootarch.dot new file mode 100644 index 0000000..0a8130f --- /dev/null +++ b/uploads/2019/07/hunchentootarch.dot @@ -0,0 +1,63 @@ +// Hunchentoot architectural diagram +// +// A synthesis of +// http://thetarpit.org/posts/y05/096-hunchentoot-ii.html + +digraph hunchentoot_arch { + rankdir=LR // really? + newrank=true + ranksep=0.4 + nodesep=0.2 + node [shape=box] + + subgraph cluster_acceptor { + label="acceptor" + start [label="start",color=darkgreen, + href="http://coad.thetarpit.org/hunchentoot/c-acceptor.lisp.html#L221"] + start_listening [label="start-listening", + href="http://coad.thetarpit.org/hunchentoot/c-acceptor.lisp.html#L244"] + accept_connections [label="accept-connections", + href="http://coad.thetarpit.org/hunchentoot/c-acceptor.lisp.html#L251"] + process_connection [label="process-connection", + href="http://coad.thetarpit.org/hunchentoot/c-acceptor.lisp.html#L272"] + handle_request [label="handle-request", + href="http://coad.thetarpit.org/hunchentoot/c-acceptor.lisp.html#L284"] + acceptor_dispatch_request [label="acceptor-dispatch-request", + color=darkgreen, + href="http://coad.thetarpit.org/hunchentoot/c-acceptor.lisp.html#L293"] + stop [label="stop",color=darkgreen, + href="http://coad.thetarpit.org/hunchentoot/c-acceptor.lisp.html#L225"] + } + + subgraph cluster_taskmaster { + label="taskmaster" + execute_acceptor [label="execute-acceptor", + href="http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L40"] + handle_incoming_connection [label="handle-incoming-connection", + href="http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L47"] + shutdown [label="shutdown", + href="http://coad.thetarpit.org/hunchentoot/c-taskmaster.lisp.html#L56"] + } + + subgraph cluster_request { + label="request" + process_request [label="process-request", + href="http://coad.thetarpit.org/hunchentoot/c-request.lisp.html#L105"] + } + + subgraph cluster_reply { + label="reply" + header_out [label="header-out", + href="http://coad.thetarpit.org/hunchentoot/c-reply.lisp.html#L135"] + } + + start -> start_listening + start_listening -> execute_acceptor [constraint=false] + execute_acceptor -> accept_connections + accept_connections -> handle_incoming_connection [constraint=false] + handle_incoming_connection -> process_connection + process_connection -> process_request -> handle_request [constraint=false] + handle_request -> acceptor_dispatch_request + acceptor_dispatch_request -> header_out [style=dashed,color=darkgreen] + stop -> shutdown +} diff --git a/uploads/2019/07/hunchentootarch.svg b/uploads/2019/07/hunchentootarch.svg new file mode 100644 index 0000000..6acab3a --- /dev/null +++ b/uploads/2019/07/hunchentootarch.svg @@ -0,0 +1,163 @@ + + + + + + +hunchentoot_arch + +cluster_acceptor + +acceptor + +cluster_taskmaster + +taskmaster + +cluster_request + +request + +cluster_reply + +reply + + +start + + +start + + + +start_listening + + +start-listening + + + +start->start_listening + + + + +execute_acceptor + + +execute-acceptor + + + +start_listening->execute_acceptor + + + + +accept_connections + + +accept-connections + + + +handle_incoming_connection + + +handle-incoming-connection + + + +accept_connections->handle_incoming_connection + + + + +process_connection + + +process-connection + + + +process_request + + +process-request + + + +process_connection->process_request + + + + +handle_request + + +handle-request + + + +acceptor_dispatch_request + + +acceptor-dispatch-request + + + +handle_request->acceptor_dispatch_request + + + + +header_out + + +header-out + + + +acceptor_dispatch_request->header_out + + + + +stop + + +stop + + + +shutdown + + +shutdown + + + +stop->shutdown + + + + +execute_acceptor->accept_connections + + + + +handle_incoming_connection->process_connection + + + + +process_request->handle_request + + + + + -- 1.7.10.4