RFC: Support connection-linked helper notes

[yadij]

Allow admin to configure which helper kv-pair notes
to share across transactions sharing a client TCP
connection.

Previously, this functionality was limited to notes named clt_conn_tag.

[rousskov]

I support adding this feature, in principle.

Are all annotations not named by the new configuration option guaranteed to not be treated like clt_conn_tag? Or will we make that decision later, possibly on a helper-by-helper basis? In other words, are we drawing a hard line here or just adding one more way to say "clt_conn_tag", with the rest of it still being undecided/uncertain at this point? For example, are these changes compatible, in principle, with helper-driven decision where helpers send clt_conn_*=value annotations and expect those annotations to annotate the client connection without any squid.conf changes?

Will the new configuration option apply to all key=value fields returned by the helper or only to the custom fields that Squid does not already handle specially (e.g., will some of the annotations listed in Notes::ReservedKeys() be banned from being listed as connection-annotating)?

It would also be nice to document which same-connection transactions are going to get the annotations set by another transaction. I might say something about getting request headers (or equivalent) parsed being the moment when the previously stored connection annotations would be copied to the "new" transaction, but I have not checked those details.

We should also document that once associated with a client connection, connection annotations survive Squid reconfiguration, even if the new configuration no longer names them.

Finally, we should mention that annotation names are case sensitive.

All those documentation request should ultimately be addressed by cf.data.pre changes, of course, but we can abuse PR description to finalize those decisions first and then move that text to cf.data.pre, with proper formatting.

PR description: Previously this was limited to exactly one note called clt_conn_tag which was erased and replaced each time a new value was received from any helper.

I have rephrased that paragraph to avoid an implication that the new functionality does not "erase and replace" like clt_conn_tag did. This PR preserves that old functionality. New option documentation should be explicit about that functionality, of course.

P.S. This RFC has a lot of code noise that makes it difficult for me to see the key changes we are supposed to review at this stage. AFAICT, most of those non-key changes can and should be avoided (in this PR). I tried to filter out that noise during this initial review, but I could easily miss something important.

[rousskov]

clt_conn_tag should always annotate TCP connection because that is what happens today, and it would be very easy for an admin to forget to list that annotation name explicitly when customizing their configuration. It is not just the default (to be used when no annotation names were configured); it has to be added to the container even if some other annotation names were configured.

[rousskov]

Please use (less problematic) STL descriptions and avoid an otherwise unused type alias:

Suggested change

	/// points to the first argument
	const_iterator begin() const { return entries.cbegin(); }
	/// points to the end of list
	const_iterator end() const { return entries.cend(); }
	/// an iterator to the first note
	auto begin() const { return entries.cbegin(); }
	/// an iterator past the last note
	auto end() const { return entries.cend(); }

[rousskov]

The need to apply annotations to client-to-Squid connections goes beyond helpers. For example, ICAP/eCAP adapters and "note" ACL also set transaction annotations and would benefit from a very similar feature. Please do not place that feature code inside ChildConfig. Let ChildConfig use code defined elsewhere (e.g., AnnotationNames or even Configuration::AnnotationNames).

[rousskov]

SBufList optimizes insertions and deletions while preserving order and supporting duplicates. For AnnotationNames, we need to optimize search time and ban duplicates. Please use an std::unordered_set container instead of SBufList.

[rousskov]

Please refuse configurations with duplicate names because they may be dangerous typos.