Move day-in-the-life to intro #3858

martinthomson · 2020-07-08T04:50:24Z

This does a little shuffling to move some of the context-setting up. It
then adds some more meat to the introductory section.

Closes #3763.

This does a little shuffling to move some of the context-setting up. It then adds some more meat to the introductory section. Closes #3763.

MikeBishop · 2020-07-09T18:07:33Z

draft-ietf-quic-transport.md

+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) as possible, which might require prior communication to


Suggested change

immediately (0-RTT) as possible, which might require prior communication to

immediately (0-RTT), which might require prior communication to

MikeBishop · 2020-07-09T18:08:30Z

draft-ietf-quic-transport.md

+
+Frames are used in QUIC to communicate between endpoints.  Multiple frames are
+assembled into packets.  QUIC authenticates all packets and encrypts as much as
+is practical to avoid incurring a dependency on middleboxes.  QUIC packets are


Isn't the dependency the other way around; we're trying to avoid middleboxes becoming dependent on any visible features of QUIC.

ianswett

Some suggestions, but LG.

ianswett · 2020-07-13T15:40:47Z

draft-ietf-quic-transport.md

+and server. The primary purpose of a connection is to support the exchange of
+data by an application protocol.
+
+Streams ({{streams}}) are the primary means by which an application protocol


Saying 'primary' seems odd given there's no other option in v1.

You could say "Streams are the only means by which an application protocol exchange information in this version of QUIC."

ianswett · 2020-07-13T15:43:10Z

draft-ietf-quic-transport.md

+unidirectional streams allow a single endpoint to send.  Endpoints can create
+streams without prior negotiation.  A credit-based scheme is used to limit


I'd drop this sentence, since one could consider the stream limit TPs 'negotiation'.

Suggested change

unidirectional streams allow a single endpoint to send. Endpoints can create

streams without prior negotiation. A credit-based scheme is used to limit

unidirectional streams allow a single endpoint to send. A credit-based scheme is used to limit

ianswett · 2020-07-13T15:45:05Z

draft-ietf-quic-transport.md

+Frames are used in QUIC to communicate between endpoints.  Multiple frames are
+assembled into packets.  QUIC authenticates all packets and encrypts as much as


Suggested change

Frames are used in QUIC to communicate between endpoints. Multiple frames are

assembled into packets. QUIC authenticates all packets and encrypts as much as

Frames are used in QUIC to communicate between endpoints. One or more frames can

be sent in a single QUIC packet. QUIC authenticates all packets and encrypts as much as

ianswett · 2020-07-13T15:48:55Z

draft-ietf-quic-transport.md

+and server. The primary purpose of a connection is to support the exchange of
+data by an application protocol.
+
+Streams ({{streams}}) are the primary means by which an application protocol


Streams is the only reference in this section, so I'd be inclined to drop it given it's referenced in "Life of a QUIC connection"?

janaiyengar

A high-order idea: Merge the Overview and Structure sections. Basically, I think we could use your descriptions of the three major pieces (Streams, Connections, Packets/Frames) at the right points in the text under Document Structure, and just move all of it into Overview. WDYT?

janaiyengar · 2020-07-15T23:21:59Z

draft-ietf-quic-transport.md

@@ -979,6 +1022,34 @@ described in {{migration}}.  Finally, a connection may be terminated by either
 endpoint, as described in {{termination}}.


+## Life of a QUIC Connection {#connection-lifecycle}
+
+Each connection starts with a handshake phase, during which client and server


Suggested change

Each connection starts with a handshake phase, during which client and server

Each connection starts with a handshake phase, during which the two endpoints

janaiyengar · 2020-07-15T23:36:04Z

draft-ietf-quic-transport.md

+## Life of a QUIC Connection {#connection-lifecycle}
+


I think the text in this subsection can replace the text above in the Connections section header. The first sentence above is broken (there's no version negotiation), and the rest of them are covered below. So basically, delete all text from lines 1016 - 1026.

janaiyengar · 2020-07-15T23:39:35Z

draft-ietf-quic-transport.md

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


Suggested change

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.

An application protocol can use the connection during the handshake

phase, albeit to a limited extent. 0-RTT allows application data to be

sent by a client before receiving a response from the server. However,

there is no protection against replay attacks in 0-RTT; see {{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.

janaiyengar · 2020-07-15T23:46:38Z

draft-ietf-quic-transport.md

+and server. The primary purpose of a connection is to support the exchange of
+data by an application protocol.


Suggested change

and server. The primary purpose of a connection is to support the exchange of

data by an application protocol.

and server. The primary purpose of a connection is to support the structured

exchange of data by an application protocol.

I'm not so sure about this myself, but suggesting... the idea is to surface the use of QUIC streams.

janaiyengar · 2020-07-15T23:49:41Z

draft-ietf-quic-transport.md

+bidirectional streams allow both endpoints to send data; unidirectional streams
+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.


Suggested change

bidirectional streams allow both endpoints to send data; unidirectional streams

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.

bidirectional streams, that allow both endpoints to send data; and

unidirectional streams, that 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.

janaiyengar · 2020-07-15T23:56:55Z

draft-ietf-quic-transport.md

+QUIC establishes a connection, which is a stateful interaction between a client
+and server. The primary purpose of a connection is to support the exchange of
+data by an application protocol.


I would propose this be moved to after the para on streams

janaiyengar · 2020-07-15T23:58:34Z

draft-ietf-quic-transport.md

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


With the leading para on QUIC connections from lines 127-129 moved here, maybe combine this with that para and start with "QUIC connections are established using a handshake that combines..."

janaiyengar · 2020-07-16T00:10:15Z

draft-ietf-quic-transport.md

+{{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 '*'.


This seems a bit out of place. It would be more useful if it included data exchange and connection termination. Otherwise, I would suggest removing it entirely (this para and the text below as well).

martinthomson · 2020-07-16T00:50:28Z

Thanks for the review Jana. I've taken most of this, with small tweaks only.

Two things I didn't take:

Interleaving 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).
I didn'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 #handshake section, which didn't have that simple diagram (just some more complex ones), and I think benefits from it.

janaiyengar

Thanks for working through this!

Move day-in-the-life to intro

e7bee89

This does a little shuffling to move some of the context-setting up. It then adds some more meat to the introductory section. Closes #3763.

martinthomson added editorial An issue that does not affect the design of the protocol; does not require consensus. -transport labels Jul 8, 2020

martinthomson requested a review from janaiyengar July 8, 2020 04:50

MikeBishop approved these changes Jul 9, 2020

View reviewed changes

Rewird

cbe6f14

ianswett approved these changes Jul 13, 2020

View reviewed changes

Ian's review

86b1a78

ianswett approved these changes Jul 15, 2020

View reviewed changes

janaiyengar reviewed Jul 16, 2020

View reviewed changes

Some changes, not all

b0fb113

Merge branch 'master' into move-life-of

fbac101

janaiyengar approved these changes Jul 16, 2020

View reviewed changes

janaiyengar merged commit 8a9ebea into master Jul 16, 2020

janaiyengar deleted the move-life-of branch July 16, 2020 04:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Move day-in-the-life to intro #3858

Move day-in-the-life to intro #3858

martinthomson commented Jul 8, 2020

MikeBishop Jul 9, 2020

MikeBishop Jul 9, 2020

ianswett left a comment

ianswett Jul 13, 2020

ianswett Jul 13, 2020

ianswett Jul 13, 2020

ianswett Jul 13, 2020

janaiyengar left a comment

janaiyengar Jul 15, 2020

janaiyengar Jul 15, 2020

janaiyengar Jul 15, 2020

janaiyengar Jul 15, 2020

janaiyengar Jul 15, 2020

janaiyengar Jul 15, 2020

janaiyengar Jul 15, 2020

janaiyengar Jul 15, 2020

janaiyengar Jul 16, 2020

martinthomson commented Jul 16, 2020

janaiyengar left a comment

	immediately (0-RTT) as possible, which might require prior communication to
	immediately (0-RTT), which might require prior communication to

		unidirectional streams allow a single endpoint to send. Endpoints can create
		streams without prior negotiation. A credit-based scheme is used to limit

		Frames are used in QUIC to communicate between endpoints. Multiple frames are
		assembled into packets. QUIC authenticates all packets and encrypts as much as

	Each connection starts with a handshake phase, during which client and server
	Each connection starts with a handshake phase, during which the two endpoints

		and server. The primary purpose of a connection is to support the exchange of
		data by an application protocol.

Move day-in-the-life to intro #3858

Move day-in-the-life to intro #3858

Conversation

martinthomson commented Jul 8, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ianswett left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

janaiyengar left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

martinthomson commented Jul 16, 2020

janaiyengar left a comment

Choose a reason for hiding this comment