Draft: draft-ietf-quic-transport

Commentary: This does a little shuffling to move some of the context - setting up . It then adds some more meat to the introductory section . 
 Thanks for the review  . I 've taken most of this , with small tweaks only . Two things I did n't take : explanation with references to sections sounded appealing , but it turns out to be both harder to read as the links break up the flow , and harder to scan for links ( the structure section serves as an abbreviated and accessible ToC ) . did n't move the connection piece below streams as I think that - at this level - talking about the connection is important context . I 've moved the picture to the section , which did n't have that simple diagram ( just some more complex ones ) , and I think benefits from it . 
 When I was reading quic - transport I found it very difficult to deal with the forward references . Streams are presented before connections , the overall state machine is n't introduced up front , packets come long after frames , and both are long before the wire formats are described . It might worth revisiting the section ordering . 
 At some point , transport was hugely restructured , and I believe many of those changes were good , but some did n't work out that well . I find streams coming before connections particularly odd . 
 The larger idea is " high - level concepts , then wire encoding " which I think makes sense . It puts the things that someone needs for a conceptual understanding of the protocol in one place , and the things that someone needs to implement the protocol elsewhere . Within the high - level concepts , I also find it strange that connections do n't come before streams . However , the " connections " group also includes things that really do n't deserve pride - of - place as the first couple things to be discussed , either . 
 I think that the main concept you need is that QUIC has a connection that is shared state between two endpoints . The later sections about connections go into more detail than you need to understand the stream sections . But I note that we do n't properly provide that basic knowledge in our introductory parts , which are quite lean . Leanness is good , but we might have overdone it slightly in this regard . 
 Having worked my way through the spec , my suggested resolution to this is that Section 5.3 needs to be earlier , perhaps much earlier . At the least , it should open Section 5 ; some or all of it might belong in Section 1 . 
 Thanks for working through this !
Paragraph (version A):
QUIC uses UDP as a substrate to avoid requiring changes to legacy
client operating systems and middleboxes.  QUIC authenticates all of
its headers and encrypts most of the data it exchanges, including its
signaling, to avoid incurring a dependency on middleboxes.
Paragraph (version B):
QUIC establishes a connection, which is a stateful interaction
between a client and server.  The primary purpose of a connection is
to support the structured exchange of data by an application
protocol.
Paragraph (version B):
Streams are means by which an application protocol exchanges
information.  Streams are ordered sequences of bytes.  Two types of
stream can be created: bidirectional streams, which allow both
endpoints to send data; and unidirectional streams, which allow a
single endpoint to send.  A credit-based scheme is used to limit
stream creation and to bound the amount of data that can be sent.
Paragraph (version B):
The QUIC handshake combines negotiation of cryptographic and
transport parameters.  The handshake is structured to permit the
exchange of application data as soon as possible.  This includes an
option for clients to send data immediately (0-RTT), which might
require prior communication to enable.
Paragraph (version B):
QUIC connections are not strictly bound to a single network path.
Connection migration uses connection identifiers to allow connections
to transfer to a new network path.
Paragraph (version B):
Frames are used in QUIC to communicate between endpoints.  One or
more frames are assembled into packets.  QUIC authenticates all
packets and encrypts as much as is practical.  QUIC packets are
carried in UDP datagrams to better facilitate deployment in existing
systems and networks.
Paragraph (version B):
Once established, multiple options are provided for connection
termination.  Applications can manage a graceful shutdown, endpoints
can negotiate a timeout period, errors can cause immediate connection
teardown, and a stateless mechanism provides for termination of
connections after one endpoint has lost state.
Paragraph (version A):
QUIC's connection establishment combines version negotiation with the
cryptographic and transport handshakes to reduce connection
establishment latency, as described in handshake.  During connection
establishment, each side validates the peer's address, as described
in address-validation.  Once established, a connection may migrate to
a different IP or port at either endpoint as described in migration.
Finally, a connection may be terminated by either endpoint, as
described in termination.
Paragraph (version B):
A QUIC connection is shared state between a client and a server.
Paragraph (version B):
Each connection starts with a handshake phase, during which the two
endpoints establish a shared secret using the cryptographic handshake
protocol QUIC-TLS and negotiate the application protocol.  The
handshake (handshake) confirms that both endpoints are willing to
communicate (validate-handshake) and establishes parameters for the
connection (transport-parameters).
Paragraph (version B):
An application protocol can use the connection during the handshake
phase with some limitations.  0-RTT allows application data to be
sent by a client before receiving a response from the server.
However, 0-RTT provides no protection against replay attacks; see
Section 9.2 of QUIC-TLS.  A server can also send application data to
a client before it receives the final cryptographic handshake
messages that allow it to confirm the identity and liveness of the
client.  These capabilities allow an application protocol to offer
the option of trading some security guarantees for reduced latency.
Paragraph (version A):
A QUIC connection is a stateful interaction between a client and
server, the primary purpose of which is to support the exchange of
data by an application protocol.  Streams (streams) are the primary
means by which an application protocol exchanges information.
Paragraph (version A):
Each connection starts with a handshake phase, during which client
and server establish a shared secret using the cryptographic
handshake protocol QUIC-TLS and negotiate the application protocol.
The handshake (handshake) confirms that both endpoints are willing to
communicate (validate-handshake) and establishes parameters for the
connection (transport-parameters).
Paragraph (version A):
An application protocol can also operate in a limited fashion during
the handshake phase.  0-RTT allows application data to be sent by a
client before receiving any response from the server.  However, 0-RTT
lacks certain key security guarantees.  In particular, there is no
protection against replay attacks in 0-RTT; see QUIC-TLS.
Separately, a server can also send application data to a client
before it receives the final cryptographic handshake messages that
allow it to confirm the identity and liveness of the client.  These
capabilities allow an application protocol to offer the option to
trade some security guarantees for reduced latency.
Paragraph (version B):
fig-hs shows a simplied handshake and the exchange of packets and
frames that are used to advance the handshake.  Exchange of
application data during the handshake is enabled where possible,
shown with a '*'.  Once completed, endpoints are able to exchange
application data.