Subject: [quicwg/base-drafts] Restructure the abstract and overview (#4329)

From: Martin Thomson <[email-masked]>
Date: Tue, 03 Nov 2020 19:53:18 -0800

This takes some of the concepts that @MikeBishop added in #4326 and
massages those into the introduction.  The net effect is two-fold: a
little more substance in this section and the addition of prominent,
early references to the key supporting documents.

It removes the bullet feature list and puts that into the abstract as a
single sentence.

I have also reordered this slightly.  There is no perfect ordering here,
but this no longer slavishly adheres to the document structure.

Closes #4326.
You can view, comment on, or merge this pull request online at:

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

-- Commit Summary --

  * Restructure the abstract and overview

-- File Changes --

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

-- Patch Links --

https://github.com/quicwg/base-drafts/pull/4329.patch
https://github.com/quicwg/base-drafts/pull/4329.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/4329

---

From: Mike Bishop <[email-masked]>
Date: Wed, 04 Nov 2020 06:46:13 -0800

@MikeBishop approved this pull request.

Yes, I think this is a good direction.

> +Application data can be reliably delivered by QUIC. An acknowledgment-based
+algorithm for detecting and recovering from loss of data is described in
+{{QUIC-RECOVERY}}. QUIC depends on congestion control to avoid network
+congestion. An exemplary congestion control algorithm is also described in
+{{QUIC-RECOVERY}}.

I feel like it's worth mentioning that QUIC provides the feedback necessary to implement such algorithms, but doesn't mandate a particular one.

> @@ -92,7 +92,10 @@ informative:
 
 --- abstract
 
-This document defines the core of the QUIC transport protocol.  Accompanying
+This document defines the core of the QUIC transport protocol. QUIC provides
+multiplexed streams for delivering ordered application data, flow control,
+low-latency connection establishment, migration, resilience to path changes,

For the abstract, I feel like it's sufficient to let migration and path changes be the same thing.

-- 
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/4329#pullrequestreview-523428254

---

From: Nick Banks <[email-masked]>
Date: Wed, 04 Nov 2020 07:50:13 -0800

@nibanks approved this pull request.

-- 
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/4329#pullrequestreview-523492572

---

From: Martin Thomson <[email-masked]>
Date: Wed, 04 Nov 2020 18:43:23 -0800

@martinthomson pushed 1 commit.

d32ab43269065b06d8b81c414d022798efef5f79  Tweak abstract again

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

---

From: Martin Thomson <[email-masked]>
Date: Wed, 04 Nov 2020 18:43:58 -0800

@martinthomson commented on this pull request.

 --- abstract

Agreed.  I've tweaked this.  And the next sentence too, mainly to avoid a possessive.

-- 
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/4329#discussion_r517760035

---

From: Martin Thomson <[email-masked]>
Date: Wed, 04 Nov 2020 18:44:53 -0800

I tried, but couldn't find anything satisfactory.  I don't think that ECN needs top-billing any more than the spin bit or any of the other minor protocol features we have.

-- 
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/4329#discussion_r517760320

---

From: Mike Bishop <[email-masked]>
Date: Thu, 05 Nov 2020 07:19:19 -0800

@MikeBishop commented on this pull request.

I'm not suggesting calling out ECN specifically, but making sure the general focus of -transport versus -recovery is clear.  Transport defines feedback mechanisms, but no algorithm.  Recovery provides *an* algorithm, but not *the* algorithm.

Perhaps as simple as:

> QUIC provides the necessary feedback to implement reliable delivery and congestion control. An algorithm for detecting and recovering from loss of data is described in....

-- 
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/4329#discussion_r518130688

---

From: Mike Bishop <[email-masked]>
Date: Thu, 05 Nov 2020 07:20:44 -0800

> @@ -94,10 +94,10 @@ informative:
 
 This document defines the core of the QUIC transport protocol. QUIC provides
 multiplexed streams for delivering ordered application data, flow control,
-low-latency connection establishment, migration, resilience to path changes,
-and uses authenticated encryption for most protocol data. Accompanying
-documents describe QUIC's loss detection and congestion control and the use of
-TLS for key negotiation.
+low-latency connection establishment, network path migration, and uses
+authenticated encryption for most protocol data. Accompanying documents describe
+the integration of TLS for key negotiation, loss detection and an exemplary

```suggestion
the integration of TLS for key negotiation, loss detection, and an exemplary
```
Oxford comma purist, checking in.  😁

-- 
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/4329#pullrequestreview-524369134

---

From: Martin Thomson <[email-masked]>
Date: Thu, 05 Nov 2020 14:36:36 -0800

28df8f075d784a7a1008c944090229b80e869c77  A delivery from Oxford

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4329/files/d32ab43269065b06d8b81c414d022798efef5f79..28df8f075d784a7a1008c944090229b80e869c77

---

From: Martin Thomson <[email-masked]>
Date: Thu, 05 Nov 2020 14:37:05 -0800

9944eba16c8a9d4e708d937f5b61e36d9384d9c6  Feedback

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4329/files/28df8f075d784a7a1008c944090229b80e869c77..9944eba16c8a9d4e708d937f5b61e36d9384d9c6

---

From: Martin Thomson <[email-masked]>
Date: Thu, 05 Nov 2020 14:37:29 -0800

OK, now I think that I get it.  And I like it.  Thanks.

-- 
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/4329#discussion_r518412408

---

From: Jana Iyengar <[email-masked]>
Date: Fri, 06 Nov 2020 16:20:20 -0800

@janaiyengar commented on this pull request.

A few suggestions, but this is great!

> @@ -92,9 +92,12 @@ informative:
 
 --- abstract

maybe?
```suggestion
streams for structuring application data, flow control,
```

> @@ -111,22 +114,26 @@ code and issues list for this draft can be found at
 
 # Overview
 
-QUIC is a multiplexed and secure general-purpose transport protocol that
-provides:
+QUIC is a multiplexed and secure general-purpose transport protocol. This

```suggestion
QUIC is a secure general-purpose transport protocol. This
```

-* Stream- and connection-level flow control
-
-* Low-latency connection establishment
-
-* Connection migration and resilience to NAT rebinding
-
-* Authenticated and encrypted header and payload
-
-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.
+The QUIC handshake combines negotiation of cryptographic and transport
+parameters. QUIC integrates the TLS {{?TLS13}} handshake, though provides a

```suggestion
parameters. QUIC integrates the TLS ({{?TLS13}}) handshake, although using a
```

-* Stream- and connection-level flow control
-
-* Low-latency connection establishment
-
-* Connection migration and resilience to NAT rebinding
-
-* Authenticated and encrypted header and payload
-
-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.
+The QUIC handshake combines negotiation of cryptographic and transport
+parameters. QUIC integrates the TLS {{?TLS13}} handshake, though provides a
+customized scheme for protecting packets. The integration of TLS and QUIC is

Something better than "scheme"? Maybe "framing"?
```suggestion
customized framing for protecting packets. The integration of TLS and QUIC is
```

> -
-* Authenticated and encrypted header and payload
-
-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.
+The QUIC handshake combines negotiation of cryptographic and transport
+parameters. QUIC integrates the TLS {{?TLS13}} handshake, though provides a
+customized scheme for protecting packets. The integration of TLS and QUIC is
+described in more detail in {{QUIC-TLS}}. 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.
+
+Endpoints communicate in QUIC by exchanging QUIC packets. Most packets contain
+frames, which carry both control information and application data between

```suggestion
frames, which carry both control information and application data between the
```

> @@ -92,9 +92,12 @@ informative:
 
 --- abstract

I don't think "delivering ordered data" is quite right... at best this should be "ordered delivery of application data". But that is a tricky one, since there's no ordering across streams. Hence my suggestion of streams as something that an application uses for structuring data.

Also, I think "multiplexed" is an unnecessary detail for an overview.

> @@ -111,22 +114,26 @@ code and issues list for this draft can be found at
 
 # Overview
 
-QUIC is a multiplexed and secure general-purpose transport protocol that
-provides:
+QUIC is a multiplexed and secure general-purpose transport protocol. This

"multiplexed" is an odd qualifier here.

-- 
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/4329#pullrequestreview-525563336

---

From: Martin Thomson <[email-masked]>
Date: Sun, 08 Nov 2020 22:07:33 -0800

94aeddcf5fb8efa5f8a163faadcea246fa57179a  Jana's suggestions

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4329/files/9944eba16c8a9d4e708d937f5b61e36d9384d9c6..94aeddcf5fb8efa5f8a163faadcea246fa57179a

---

From: ianswett <[email-masked]>
Date: Mon, 09 Nov 2020 06:46:58 -0800

@ianswett approved this pull request.

 --- abstract
 
+streams for structuring application data, flow control,

structuring application data is not clear to me.

```suggestion
flow-controlled streams for transmitting application data,
```

+parameters. QUIC integrates the TLS ({{?TLS13}}) handshake, although using a
+customized framing for protecting packets. The integration of TLS and QUIC is

To me, "both" makes implies that one frame carries both control and application data.

```suggestion
frames, which carry control information and application data between
```

-- 
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/4329#pullrequestreview-526324058

---

From: Jana Iyengar <[email-masked]>
Date: Mon, 09 Nov 2020 16:34:41 -0800

--- abstract

I don't think you want to remove flow control from the connection-level descriptors of QUIC.

On "structuring data", the idea is that streams are a way to retain and structure application data. How about "QUIC provides streams for retaining structure in application data, flow control" ?

-- 
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/4329#discussion_r520209551

---

From: ianswett <[email-masked]>
Date: Mon, 09 Nov 2020 16:53:19 -0800

@ianswett commented on this pull request.

 --- abstract

Streams are flow controlled, but other frames are not, so I was attempting to connect the two.  Saying you have flow control and not indicating what you're controlling seems potentially confusing to me.

-- 
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/4329#discussion_r520215684

---

From: Martin Thomson <[email-masked]>
Date: Mon, 09 Nov 2020 19:26:32 -0800

b880714d5a10934076ec421d4da40a7bb71207d0  -both

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4329/files/94aeddcf5fb8efa5f8a163faadcea246fa57179a..b880714d5a10934076ec421d4da40a7bb71207d0

---

From: Martin Thomson <[email-masked]>
Date: Mon, 09 Nov 2020 19:32:06 -0800

--- abstract

I think that I prefer Ian's suggestion here.  Breaking these apart doesn't make sense any more.

This could be two sentences instead: one for streams, one for the prime characteristics.  But then Ian's suggestion is shorter than my original proposal.

-- 
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/4329#discussion_r520264113

---

From: Martin Thomson <[email-masked]>
Date: Mon, 09 Nov 2020 19:44:12 -0800

--- abstract

> QUIC provides applications with flow-controlled streams for structured communication, low-latency connection establishment, and network path migration.  QUIC includes security measures that ensure confidentiality, integrity, and availability in a range of deployment circumstances.

^^ ?

-- 
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/4329#discussion_r520267266

---

From: Jana Iyengar <[email-masked]>
Date: Mon, 09 Nov 2020 20:38:18 -0800

--- abstract

I like your proposed text @martinthomson 

-- 
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/4329#discussion_r520281328

---

From: Martin Thomson <[email-masked]>
Date: Mon, 09 Nov 2020 21:06:40 -0800

4b60b93cbd69d05780c2bdc1bbeca75fd81a06c0  Damn, I was worried someone might like this

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4329/files/b880714d5a10934076ec421d4da40a7bb71207d0..4b60b93cbd69d05780c2bdc1bbeca75fd81a06c0

---

From: Jana Iyengar <[email-masked]>
Date: Mon, 09 Nov 2020 21:10:02 -0800

Merged #4329 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/4329#event-3977002733