Strongly disagree with all these changes to the macro casing. The system doesn't and shouldn't care about case for macros, and neither should we. I wouldn't reject on this, but not a fan.

I actually prefer all lower case, and plan on injecting it whenever I write a doc.

The system doesn't and shouldn't care about case for macros, and neither should we.

Yeah, I have no strong opinions on what convention we settle for this syntax as long as there's only one way to write it, so "all lower, no spaces" is fine with me. This is what we're currently looking at:

• 1x {{HttpHeader(…)}}
• 3x {{ HTTPHeader(…) }}
• 3x {{ httpheader(…) }}
• 3x {{HTTPheader(…)}}
• 422x {{httpheader(…)}}
• 1814x {{HTTPHeader(…)}}

FMI what is the point of Available-Dictionary, and does it always require Dictionary-ID too?

I ask because you get and return the server id. Why do you need a hash of the dictionary too when you already have an identity for it?

I can take this one. @pmeenan correct me if I'm wrong.

The point of Available-Dictionary is for the client to tell the server which Dictionary it has that can be used for compression. It is a crypto-graphic hash to ensure the correct dictionary is actually used.

No it does not require the optional Dictionary-ID too. This is an optional, extra field that, from my understanding, servers may use if they don't want to store dictionaries by the hash value but by some other identifier. In this case calculating the hash of all available dictionaries to find the match to the Available-Dictionary would be expensive. And storing a key-value store of these might be large. Once the dictionary is found, the hash must still be calculated and checked against the Available-Dictionary to ensure a match.

The identifier is provided in the Use-As-Dictionary header (when the dictionary is originally sent to the client) in the id field and and must be reflected in the Dictionary-ID header for any subsequent request wanting to use that dictionary.

See: httpwg/http-extensions#2687 (and the issue it closes).

Correct. The Dictionary-ID was an added helper to make it easier for origins and CDN's to find/fetch the dictionary using whatever key they want (for example, the URL of the original resource). It saves them from having to hash every response that includes a Use-As-Dictionary response header just in case it might eventually be used as a dictionary (and to avoid double-storing).

The client doesn't do anything with it except echo whatever value was used back. The hard-verification (and failure in case of a mismatch) is on the dictionary hash.

They still verify the hash against Available-Dictionary before using it but that's when they're already initializing the dictionary itself anyway.

OK updated the main docs in this PR with some information on this: #38974

Thank you both. I will look at that.