Re: Working Group Last Call: HTTP/2 revision

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