[squid-dev] RFC: protocols in Squid

[Alex Rousskov]

On 1/30/22 6:56 AM, Amos Jeffries wrote:
> Attached is first draft of a map for the transactions possible by
> protocols supported (and "should be") by Squid.
> 
> 
> In this diagram transactions are split into three types:
> 
>  1) switching - Protocol A ending initiates Protocol B.
> 
>  2) nested - Protocol B carries Protocol C in its message payload.
> 
>  3) fetch - Protocol B initiates Protocol D to fetch some data used by
> Protocol B.
> 
> Note: to simplify the number of arrows surrounding "HTTP" I have split
> out the CONNECT tunnel as a separate thing.
> 
> 
> Am posting this as RFC to see of anyone has additions of transactions I
> missed. Or suggestions on how better to document it.

Who is the target audience for this work? What are the primary goals of
this documentation effort? It is difficult to suggest improvements
without understanding who we are talking to and what we want them to
learn or do with that information...

FWIW, I personally do not find the chosen illustration approach useful
for documenting the relationship between various transactions or
protocols in Squid:

* At a high level, if the target audience are folks who do not know much
about Squid but are familiar with many network protocols, then the
picture can be morphed into a useful introductory illustration of the
protocols supported by Squid. However, most of the effort on
switch/nest/fetch documentation would be lost or misplaced in the
process -- there are much simpler/better ways to illustrate which
protocols are supported where, of course.

* At a high level, if the target audience are folks that want to do
serious Squid development, then the picture effectively obscures or
hides such critical architectural concepts as transaction layering and
grouping/cooperating. Illustrating those concepts needs a very different
approach IMO.

* At a low level, correctly interpreting or even tracing some of the
depicted individual relationships is already quite difficult for a human
like me, and when all the [should be] supported relationships are
included, the interesting parts may become an intractable spaghetti of
colored lines. I suspect it would be easier and a lot more useful to
just say (in text form!) what transport protocols are used by which
to-Squid and from-Squid higher-level transactions.


> Next step is to write up which object(s) or function implements each of
> these in Squid.

Developing a high-level documentation of primary transaction-related
class relationships may be very useful for establishing common
terminology and resolving refactoring conflicts. Such a document would
be based on about ~10 classes and rely heavily on the embedded class
documentation (instead of repeating or substituting it). I can draft
such a document if you think it may be useful.

At the level of "objects or functions", it would take a lot of time to
write and review such detailed function-level documentation. Maintaining
it would be costly as well, especially given the fact that a lot of that
code should be seriously refactored! This is your call, but I think your
personal energy and talents are better spent elsewhere, and the Project
as a whole should not undertake such a costly initiative with murky
outcomes.


Cheers,

Alex.
P.S. FWIW, I do not know what the various
circles/diamonds/hexagons/ovals mean on this particular diagram. Many
different standards and common notations are recycling those basic
shapes, of course.