Restructure document

[martinthomson]

The current document structure has suffered a little from the large volume of changes that we've thrown at the spec. Here's a structure that I think will survive a little better:

Fluff

• Introduction (Why QUIC, really high level of what it does)
• Overview (see Rewrite overview #410)

High-Level Concepts

• Connections
  • lifecycle (include handshake overview here)
  • graceful shutdown
  • error handling
  • public reset (semantics, not bits)
  • source address validation and DoS
• Streams (lifecycle, purpose and function, priority, flow control)
• Packets and Frames
  • relationship between packets and frames
  • packetization
  • retransmission rules
  • pmtud
• Versions (version negotiation, version numbers)
• Connection IDs (why, migration, nat rebinding, changing ID, privacy)

Mechanics

• Packet Format
  • long and short headers
  • what is constant between versions
  • definition of each of the packet types
• Packet Protection (key phases, AEAD)
• Frames (definition of each frame type; include current Sections 6+8)
• Handshake (crypto, transport parameters)
• Error Codes

Boilerplate

• Security Considerations
• IANA
• etc...

[martinthomson]

Might look at #463 at the same time.

[mirjak]

I did a fully review of transport-14 and can confirm that the current organization is not super great as a lot of concepts you need to understand the details are explained too late in the doc. Also I noticed that the QUIC overview section was removed on -11. I agree that the text in that section was not great but I think it would help a reader, who is not familar with quic, a lot to have a (non-normative) section first explaining the main concepts (multiplexing/streams/frames, how encryption works/session resumption, reliability/packet numbers, maybe also flow control, migration, and versioning).

Here are a bunch of micro re-org suggestions based on -14 (however I agree with the general stuture @martinthomson prposes above which at minimim would mean to move section 8 much earlier in the doc):

• section 5 (Frames and Frame Type) should be merged with section 7 (Frame Types and Format): I guess the intention was to provide the reader a full list with all frame types early on. That was actually rather confusing than helpful. I think it is okay to just provide a reference to the respective section later in the doc whenever a frame type is mention that was not introduced yet.

• I would recommend to merge the text in section 6.6.3 (New Transports Paramters) just in the intro text of section 6.6. (Transport Paramter)

• Section 6.7 (Stateless Retry) needs to show up earlier in section 6 because it is mentioned in previous subsections.

• Most text in the intro part of section 6.9 (Proof of Source Address Validation) sounds like it should rather be in the security considerations section...

• Section 6.11.5 (Privacy Implications of Connection Migration) really seems to belong in the secuirty considerations instead.

• I would recommend to have section 6.12.4.2 (Calculating a Stateless Rest Token) before section 6.13.4.1 (Detecting a Stateless Reset).

• Depending on the final order I think there is some text in section 9 that belongs in section 7.20. I think in any case section 7.20 should also talk about the meaning of the last two bits. I would recommend to talk about the bit encoding only in section 7.20 and just introduce the concepts of bi/uni-direction and server/client-initiated in section 9.

• I would recommend to have the section on sending and receiving data (9.5) before the state diagrams are introduced.

• Order of section 10 (Flow Control) seemed completely random to me.

Also not quite an issue on document structure directly, but definitely related and should probably be cleaned up together, is that there are a couple of duplicted normative statements, e.g.

sec 7.8. (MAX_STREAM_ID Frame)
"Loss or reordering can mean that a MAX_STREAM_ID frame can be
received which states a lower stream limit than the client has
previously received. MAX_STREAM_ID frames which do not increase the
maximum stream ID MUST be ignored."
sec 9.4 (Stream Concurrency)
"A receiver cannot renege on an advertisement; that is, once a
receiver advertises a stream ID via a MAX_STREAM_ID frame,
advertising a smaller maximum ID has no effect. A sender MUST ignore
any MAX_STREAM_ID frame that does not increase the maximum stream ID."
sec 10 (Flow Control)
"A receiver MAY advertise a larger offset at any point by sending
MAX_DATA or MAX_STREAM_DATA frames. A receiver cannot renege on an
advertisement; that is, once a receiver advertises an offset,
advertising a smaller offset has no effect. A sender MUST therefore
ignore any MAX_DATA or MAX_STREAM_DATA frames that do not increase
flow control limits."

These normative statements do all say the same thing but are worded slightly different. To avoid any ambiguity, I would recommend to state these things normatively only once. There are a few more of these kind of cases...

[martinthomson]

Thanks @mirjak. @janaiyengar and I have some time set aside after the next interim meeting to look at this issue. We've been waiting until the velocity of changes slows a little before attempting this because more changes tend to undo any work you do on improving structure and removing redundant text. But it looks like things are stabilizing now.

[martinthomson]

Discussed on 2018-09-24:

Proposed structure w/ notes:

1. Introduction
2. Overview
3. Streams (might be multiple top-level sections)
   a. concepts
   b. lifecycle
   c. flow control
4. Connection Handshake
   a. Example Handshake (high level)
   b. Packet Handling
   c. Version Negotiation
   d. Retry (tokens, etc....)
   e. Handshake Packets (cite TLS drafts)
   f. Amplification attack defense (Handshake loss recovery interacts poorly with amplification attack defense #1764)
   g. Transport parameters (what they are for, not the format)
5. Connection Migration
6. Connection Shutdown
7. Packets and Frames (format, layout, coalescing)
8. Sending and Resending Packets
9. Acknowledging Packets
10. Packet Size (Initial size, PMTUD etc...)
11. Version Numbers
12. Long and Short Headers
13. Packet Formats
14. Transport Parmeters
15. Frame Formats
16. Error Codes
17. Security Considerations
18. IANA
19. Other stuff...

From Section 11 onwards, try to keep to pure format and only have minimal description of semantics. Most of the semantic stuff should already be covered.

[ianswett]

It seems odd to put connection migration so early when things like Sending and Acknowledging packets is much later(though having those adjacent I think makes sense). Is there a reason connection migration needs to be that early, such as it's introducing text used later?

Re 8: QUIC doesn't resent packets

[mirjak]

I guess you will also need to have the "Packets and Frame" section much earlier in the doc and I would think that the "Short and Long Headers" might be a subsection of that...? Also "Packet Size" might also be rather a subsection somewhere.

However, I also have to say that the split in the current doc between section 5 "Frames and Frame Types" and 7 "Frame Types and Formats" is rather awkward, so I not sure I would recommend to keep it that way but maybe that's currently rather an editorial issue.

[britram]

wrt §7, it's probably useful to split this into sections for the non-encrypted part of the wire image (basically the packet headers) and everything inside. Otherwise it seems easy to get confused about what's encrypted and what's in the clear.

[martinthomson]

Whoa, we did this already!