Re: Working Group Last Call: HTTP/2 revision

[Martin Thomson <[e-mail]>]

Hi Willy,

How does this look?  https://github.com/httpwg/http2-spec/pull/877

I agree that this was getting a bit unwieldy.  It's nice to have it all spelled out, but we ended up with a lot of independent fields.   A little vertical space does seem to help with readability.

On Fri, Jul 23, 2021, at 16:52, Willy Tarreau wrote:
> 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
> 
>