Experience of a new implementor with the latest working drafts

[JP Sugarbroad <[e-mail]>]

So I decided to poke my head in and answer the question "what does a bare
minimum compliant HTTP/3 client look like?". The answer so far has been...
slow going.

I started with "how do I construct the first packet", but the information I
needed was scattered. I'm used to being able to pull partial information
from an RFC without reading the whole thing, so I skipped around a lot:

Do you send an Initial packet or a Handshake packet? Well, section 5 says
"Each connection starts with a handshake phase", so maybe Handshake packet.
But then 5.2.2 says "If the packet is an Initial packet fully conforming
with the specification, the server proceeds with the handshake", so Initial
is first? Ok.

What goes in the Initial packet?

Section 17.2.2 references "destination connection id", "source connection
id", "token", "packet number", and "payload". Token is covered right there,
and it seems to be optional except for something called a Retry packet.
There's also reference to NEW_TOKEN -- it's not clear if either of these
tokens is required to be used from here. The payload is also in the same
section with "The first packet sent by a client...", which is useful.

Connection IDs are a bit more mysterious. Section 5.1.1 is titled "Issuing
Connection IDs", but isn't very useful. Section 5.1 says "A zero-length
connection ID can be used when a connection ID is not needed to route to
the correct endpoint." so maybe they can both be empty? I'm skimming over
all the frame talk since obviously I can't exchange frames yet. Reading
through the rest of section 5, there's nothing in here. Turns out the
answer is buried in the middle of section 7.2: "When an Initial packet is
sent by a client that has not previously received an Initial or Retry
packet from the server...". This took me literally fifteen minutes of
searching to find. I was significantly impeded by the split between
sections 5 and 7.

Ok, what goes in Version? Can't be zero, that's version negotiation.
Finally found it in the preamble of section 7. That's *certainly* not where
I'd expected to find it at all.

Eventually I realized that several of the remaining fields are actually
defined in 17.2, and it is necessary to read QUIC-TLS to understand some
special mangling that happens to all packets, even the first ones. (Why do
Initial packets need header protection? Unclear.) Basically what I'm
realizing is that these documents cannot be treated as two standalone
layers of a protocol but are instead intertwined in a fairly complex way. :(

In the end, it took me hours just to learn how the first packet works. I'll
keep going, but I thought perhaps the feedback on my experience so far
might help inform future changes to the document.

(It would be nice to have more cross-references. An example packet flow
that covers all of the packet details with references to the sections that
constrain them would be *really* great. Figure 5 is good, but doesn't talk
about things like connection IDs.)

-- 
JP Sugarbroad <[e-mail]>
"Please let me know if there's any further trouble I can give you."
    -- Unknown