Subject: Working Group Last Call: HTTP/2 revision

From: Mark Nottingham <[email-masked]>
Date: Fri, 23 Jul 2021 10:05:40 +1000

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).

Working Group Last Call will end on 13 August 2021.

Cheers,

1. https://www.w3.org/mid/[email-masked]
2. https://github.com/httpwg/http2-spec/issues/

--
Mark Nottingham   https://www.mnot.net/

---

From: Willy Tarreau <[email-masked]>
Date: Fri, 23 Jul 2021 08:52:24 +0200

Hi Mark,

On Fri, Jul 23, 2021 at 10:05:40AM +1000, Mark Nottingham wrote:
> 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

---

From: "Martin Thomson" <[email-masked]>
Date: Fri, 23 Jul 2021 17:13:28 +1000

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.

---

From: Willy Tarreau <[email-masked]>
Date: Fri, 23 Jul 2021 09:23:15 +0200

On Fri, Jul 23, 2021 at 05:13:28PM +1000, Martin Thomson wrote:
> 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.

Yep, our messages have crossed, but as I responded there I agree it's already
significantly better. I think for the flags, which are fixed in a single byte
and already specified with their hex value, we could write the value in front
of the bit(s), like this:

  DATA Frame {
    Length (24),
    Type (8) = 0,

    Unused Flags (4),    // 0xF0
    PADDED Flag (1),     // 0x08
    Unused Flags (2),    // 0x06
    END_STREAM Flag (1), // 0x01

    Reserved (1),
    Stream Identifier (31),
    [Pad Length (8)],
    Data (..),
    Padding (..),
  }

I've found myself many times having to scan the text of 7540 to figure a
bit value, and having them there would definitely help IMHO.

Thank you!
Willy