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. _______________________________________________ squid-dev mailing list squid-dev@lists.squid-cache.org http://lists.squid-cache.org/listinfo/squid-dev