- From: Willy Tarreau <w@1wt.eu>
- Date: Fri, 23 Jul 2021 08:52:24 +0200
- To: Mark Nottingham <mnot@mnot.net>
- Cc: HTTP Working Group <ietf-http-wg@w3.org>, Tommy Pauly <tpauly@apple.com>
Hi Mark, On Fri, Jul 23, 2021 at 10:05:40AM +1000, Mark Nottingham wrote: > Hello everyone, > > This is the start of Working Group Last Call announcement for this document: > https://www.ietf.org/archive/id/draft-ietf-httpbis-http2bis-03.html > > Please take time to review it carefully and raise any remaining issues you > see (keeping in mind the scope of work),[1] either on the issues list[2] or > on this mailing list. Also, we'd like to hear whether you think this document > is ready to progress (on this list, please). Overall it still looks good to me, however I've just noticed something that seriously bothers me about the new representation of the frames formats. I simply don't find them legible at all. Example: https://www.ietf.org/archive/id/draft-ietf-httpbis-http2bis-03.html#name-headers 6.2 Headers HEADERS Frame { Length (24), Type (8) = 1, Unused Flags (2), PRIORITY Flag (1), Unused Flag (1), PADDED Flag (1), END_HEADERS Flag (1), Unused Flag (1), END_STREAM Flag (1), Reserved (1), Stream Identifier (31), [Pad Length (8)], [Exclusive (1)], [Stream Dependency (31)], [Weight (8)], Field Block Fragment (..), Padding (..), } Most programming languages use byte boundaries, and I really dare anyone to visually spot the byte address of each field there. Worse, some implementors, in an attempt to avoid mistakes, could describe them using bit fields like this: struct headers { int length:24; int type:8; int unused1:2; int flag:1; int unused2:1; int padded:1; int end_headers:1; init unused3:1; int end_stream:1; int reserved:1; int stream_id:31; }; But this would in fact follow their machine's byte-ordering and invert all fields within words! Adding to that that the protocol itself is byte-oriented, I'd request two minor changes: - that a delimiter is placed at each byte boundary before or after a sub-byte field to help visually count without having to mentally maintain a modulo 8 when enumerating fields. Even just an empty line would be sufficient I guess. - that something helps figure that the high-order bits are enumerated first. And please don't start telling me "they're in network byte order" (as I'm already expecting to hear :-)), as except for those having been in low-level protocols for at least two decades, nobody knows how bits are serialized on the wire, and in practice due to modern encodings like 64/66, bits are not even serialized anymore and only bytes or words are relevant. And I'm not even counting crypto that is also byte- or block- oriented. Given that fields are of different sizes, it's not easy to place a bit number or a hex mask there, except for the flags, so probably it should be mentioned in 4.1 "Frame Format". Something like "All fields, including single bits, are represented and enumerated in network order, which means from MSB to LSB". This would certainly avoid some trivial traps. And I think that writing the flags' hex masks directly as a comment in front of the bits in the frame definition would provive a lot more legibility. Another point is that I haven't seen any mention of RFC8441 about the extended CONNECT scheme. Given that the rules imposed to CONNECT handling require to write an exception in the code, I think it would be worth mentioning in 8.5 after "A CONNECT request that does not conform to these restrictions is malformed", "Please note that negotiable extensions to this method exist" with a link to 8441. It doesn't imply users will implement it but it can hint them to help better design a parser to deal with this exception, because writing exceptions is annoying, but writing code later to work around purposely written exceptions is even more annoying. Otherwise I'm pretty happy with the quality and clarity of this document, which constitutes a nice improvement over 7540. Great work from our editors! Cheers, Willy
Received on Friday, 23 July 2021 06:52:49 UTC