Subject: [quicwg/base-drafts] Move day-in-the-life to intro (#3858)

From: Martin Thomson <[email-masked]>
Date: Tue, 07 Jul 2020 21:50:47 -0700

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.
You can view, comment on, or merge this pull request online at:

  https://github.com/quicwg/base-drafts/pull/3858

-- Commit Summary --

  * Move day-in-the-life to intro

-- File Changes --

    M draft-ietf-quic-transport.md (116)

-- Patch Links --

https://github.com/quicwg/base-drafts/pull/3858.patch
https://github.com/quicwg/base-drafts/pull/3858.diff

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/3858

---

From: Mike Bishop <[email-masked]>
Date: Thu, 09 Jul 2020 11:13:18 -0700

@MikeBishop approved this pull request.

> -incurring a dependency on middleboxes.
+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.
+
+Streams ({{streams}}) are the primary means by which an application protocol
+exchanges information.  Streams are ordered sequences of bytes.  Two types of
+stream can be created: bidirectional streams allow both endpoints to send data;
+unidirectional streams allow a single endpoint to send.  Endpoints can create
+streams without prior negotiation.  A credit-based scheme is used to limit
+stream creation and to bound the amount of data that can be sent.
+
+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

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

> +streams without prior negotiation.  A credit-based scheme is used to limit
+stream creation and to bound the amount of data that can be sent.
+
+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
+enable.
+
+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.
+
+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.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/3858#pullrequestreview-445852015

---

From: Martin Thomson <[email-masked]>
Date: Sun, 12 Jul 2020 20:54:08 -0700

@martinthomson pushed 1 commit.

cbe6f146502d1c32bfcf421f87b7abe3018be669  Rewird

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/3858/files/e7bee89e737585b40d7959c7d115fdd8429f1c69..cbe6f146502d1c32bfcf421f87b7abe3018be669

---

From: ianswett <[email-masked]>
Date: Mon, 13 Jul 2020 08:49:36 -0700

@ianswett approved this pull request.

Some suggestions, but LG.

> @@ -124,10 +124,54 @@ provides:
 
 * Authenticated and encrypted header and payload
 
-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.
+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.
+
+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."

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

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

```suggestion
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
```

> @@ -124,10 +124,54 @@ provides:
 
 * Authenticated and encrypted header and payload
 
-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.
+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.
+
+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"?

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/3858#pullrequestreview-447370880

---

From: Martin Thomson <[email-masked]>
Date: Mon, 13 Jul 2020 18:34:46 -0700

86b1a78c9434d49e397970d1b200e260a59c4341  Ian's review

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/3858/files/cbe6f146502d1c32bfcf421f87b7abe3018be669..86b1a78c9434d49e397970d1b200e260a59c4341

---

From: ianswett <[email-masked]>
Date: Wed, 15 Jul 2020 14:52:05 -0700

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/3858#pullrequestreview-449369845

---

From: Jana Iyengar <[email-masked]>
Date: Wed, 15 Jul 2020 17:12:39 -0700

@janaiyengar commented on this pull request.

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?

> @@ -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

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

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

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

```suggestion
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.
```

```suggestion
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.

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

```suggestion
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.
```

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

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

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

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/3858#pullrequestreview-449407636

---

From: Martin Thomson <[email-masked]>
Date: Wed, 15 Jul 2020 17:44:13 -0700

b0fb113d7b472c499e78f43d877f67d6749317df  Some changes, not all

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/3858/files/86b1a78c9434d49e397970d1b200e260a59c4341..b0fb113d7b472c499e78f43d877f67d6749317df

---

From: Martin Thomson <[email-masked]>
Date: Wed, 15 Jul 2020 17:50:51 -0700

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

Two things I didn't take:

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

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

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/3858#issuecomment-659090049

---

From: Jana Iyengar <[email-masked]>
Date: Wed, 15 Jul 2020 21:27:13 -0700

@janaiyengar approved this pull request.

Thanks for working through this!

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/3858#pullrequestreview-449498058

---

From: Jana Iyengar <[email-masked]>
Date: Wed, 15 Jul 2020 21:27:21 -0700

Merged #3858 into master.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/pull/3858#event-3551299253