Subject: [quicwg/base-drafts] RPC text changes up to Section 10 (#4877)

From: Martin Thomson <[email-masked]>
Date: Thu, 29 Apr 2021 00:43:46 -0700

This contains the first tranche of text changes from the RPC.  Because some of the changes that were made are not reproducible in kramdown, I&#39;ve some open pull requests on kramdown-rfc2629 to support this.  These are minor, and I hope that they can be resolved soon, but until then this will not compile properly.

https://github.com/cabo/kramdown-rfc2629/pull/113 adds support for the strings &quot;Appendix&quot; and &quot;Appendices&quot; in the expanded section reference format so that we can cite multiple appendices properly.

https://github.com/cabo/kramdown-rfc2629/pull/112 adds support for local section references that don&#39;t start with &quot;Section&quot; or &quot;Appendix&quot; so that we can build references to multiple sections in the form &quot;Sections X and Y&quot; (which is what the above already does for external references).

Changes might be needed in response to changes in how these two things work, so this won&#39;t be good for landing for some time.

Also, this doesn&#39;t include any XML-level changes or stuff where the RPC had questions.  Not sure how to manage that stuff yet.

You can view, comment on, or merge this pull request online at:

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

-- Commit Summary --

  * First few sections of RPC changes
  * Ten sections of RPC edits
  * Tweaks to reference format

-- File Changes --

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

-- Patch Links --

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

---

From: cabo <[email-masked]>
Date: Thu, 29 Apr 2021 05:17:11 -0700

@cabo commented on this pull request.

> @@ -513,12 +513,12 @@ implementations. An implementation can define a different state machine as long
 as its behavior is consistent with an implementation that implements these
 states.
 
-Note:
-
-: In some cases, a single event or action can cause a transition through
-  multiple states.  For instance, sending STREAM with a FIN bit set can cause
-  two state transitions for a sending stream: from the Ready state to the Send
-  state, and from the Send state to the Data Sent state.
+<aside><t>

Try `<aside markdown="1">`, then you can use normal markdown inside the aside.

-- 
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/4877#pullrequestreview-648131654

---

From: Martin Thomson <[email-masked]>
Date: Thu, 29 Apr 2021 16:44:50 -0700

@martinthomson commented on this pull request.

-Note:
-

Yeah, I've started doing that on other changes, but I need to review all the open PRs for it now.

-- 
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/4877#discussion_r623495463

---

From: Martin Thomson <[email-masked]>
Date: Thu, 29 Apr 2021 17:53:05 -0700

@martinthomson pushed 1 commit.

47235b55ef4245eacb962f9c4a7274c53575812f  Revert dependency on unmerged kramdown-rfc2629 change

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4877/files/aff23a516650ae6bd89eae2321777f47c11eb83c..47235b55ef4245eacb962f9c4a7274c53575812f

---

From: Martin Thomson <[email-masked]>
Date: Thu, 29 Apr 2021 17:54:06 -0700

392a1ae4b07ad3bc9ff8ac3f539b61b5de370070  Add attribute to aside block

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4877/files/47235b55ef4245eacb962f9c4a7274c53575812f..392a1ae4b07ad3bc9ff8ac3f539b61b5de370070

---

From: Martin Thomson <[email-masked]>
Date: Thu, 29 Apr 2021 17:55:17 -0700

b0999a244a850cb01dc36d21a5c63c32d1ea6a24  Add attribute to aside block

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4877/files/392a1ae4b07ad3bc9ff8ac3f539b61b5de370070..b0999a244a850cb01dc36d21a5c63c32d1ea6a24

---

From: Martin Thomson <[email-masked]>
Date: Thu, 29 Apr 2021 23:59:32 -0700

@martinthomson pushed 2 commits.

740f1da98cc8af3c5ea1f8612007d520feb5f718  Cite sections of recovery
acc33eb7c3dbef1f300c3afa61404af0b8d584a9  Asides

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

---

From: Martin Thomson <[email-masked]>
Date: Fri, 30 Apr 2021 00:02:49 -0700

1e61cbb5ba32bc82f1b0fd436d379dc868990597  Clearer forward references for error handling

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4877/files/acc33eb7c3dbef1f300c3afa61404af0b8d584a9..1e61cbb5ba32bc82f1b0fd436d379dc868990597

---

From: Martin Thomson <[email-masked]>
Date: Fri, 30 Apr 2021 00:05:30 -0700

6b3a0a64360af9995ba150ef1db0592f855cf049  Inline equation clarifications

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4877/files/1e61cbb5ba32bc82f1b0fd436d379dc868990597..6b3a0a64360af9995ba150ef1db0592f855cf049

---

From: Martin Thomson <[email-masked]>
Date: Fri, 30 Apr 2021 00:19:38 -0700

@martinthomson pushed 6 commits.

27aa5b198e73bb2f5ef78a550412d7cf73edf40f  It's the transport parameter value
84af6013e5a01d7915aefe731c3b3a5293fed51c  emdash for clarity
c7f3f369e2805aa41dec65a3326e8e4b94d642cd  S1 really is chosen by the client
0fa522f12284c9325fe7bd921ba000a8d26fcd91  This is a nasty sentence
6155320f94008613d22a006e24a7df47b801a5c4  default values, plural
9036660402a98810f9ea21839cc27f641a27a1b8  Update citation

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/4877/files/6b3a0a64360af9995ba150ef1db0592f855cf049..9036660402a98810f9ea21839cc27f641a27a1b8

---

From: Nick Banks <[email-masked]>
Date: Fri, 30 Apr 2021 07:57:36 -0700

@nibanks approved this pull request.

Looks good. Thanks for going through the considerable work to make all these edits!

>  servers.

-### Address Validation using Retry Packets {#validate-retry}
+### Address Validation Using Retry Packets {#validate-retry}

`Using` should be capitalized in a section title, but `during` (above) shouldn't? Just curious, are there "official" rules on which words to capitalize?

-- 
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/4877#pullrequestreview-649299139

---

From: Jana Iyengar <[email-masked]>
Date: Fri, 30 Apr 2021 18:40:45 -0700

@janaiyengar commented on this pull request.

A few suggestions and comments. Thanks for all the work, @martinthomson !

>  bidirectional streams, which allow both endpoints to send data; and
 unidirectional streams, which allow a single endpoint to send data. A
 credit-based scheme is used to limit stream creation and to bound the amount of
 data that can be sent.
 
 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 {{QUIC-RECOVERY}}. QUIC depends on congestion control
-to avoid network congestion. An exemplary congestion control algorithm is
-also described in {{QUIC-RECOVERY}}.
+congestion control. An algorithm for detecting and recovering from loss of data
+is described in {{Section 6 of QUIC-RECOVERY}}. QUIC depends on congestion
+control to avoid network congestion. An exemplary congestion control algorithm
+is also described in {{Section 7 of QUIC-RECOVERY}}.

```suggestion
is described in {{Section 7 of QUIC-RECOVERY}}.
```

-The receiver only sends MAX_STREAM_DATA in the "Recv" state.  A receiver MAY
-send STOP_SENDING in any state where it has not received a RESET_STREAM frame;
-that is states other than "Reset Recvd" or "Reset Read".  However there is
-little value in sending a STOP_SENDING frame in the "Data Recvd" state, since
-all stream data has been received.  A sender could receive either of these two
-frames in any state as a result of delayed delivery of packets.
+The receiver only sends MAX_STREAM_DATA frames in the "Recv" state.  A receiver
+MAY send STOP_SENDING frame in any state where it has not received a

```suggestion
MAY send STOP_SENDING frames in any state where it has not received a
```

-The receiver only sends MAX_STREAM_DATA in the "Recv" state.  A receiver MAY
-send STOP_SENDING in any state where it has not received a RESET_STREAM frame;
-that is states other than "Reset Recvd" or "Reset Read".  However there is
-little value in sending a STOP_SENDING frame in the "Data Recvd" state, since
-all stream data has been received.  A sender could receive either of these two
-frames in any state as a result of delayed delivery of packets.
+The receiver only sends MAX_STREAM_DATA frames in the "Recv" state.  A receiver
+MAY send STOP_SENDING frame in any state where it has not received a
+RESET_STREAM frame -- that is, states other than "Reset Recvd" or "Reset Read".
+However, there is little value in sending a STOP_SENDING frame in the "Data

```suggestion
However, there is little value in sending STOP_SENDING frames in the "Data
```

> +either of these two frames in any state as a result of delayed delivery of
+packets.

```suggestion
either of these two types of frames in any state as a result of delayed
delivery of packets.
```

> @@ -833,7 +834,7 @@ consuming a large amount of memory.  To enable a receiver to limit memory
 commitments for a connection, streams are flow controlled both individually and
 across a connection as a whole.  A QUIC receiver controls the maximum amount of
 data the sender can send on a stream as well as across all streams at any time,
-as described in {{data-flow-control}} and {{fc-credit}}.
+as described in Sections {{<data-flow-control}} and {{<fc-credit}}.

what does "<" do?

>  An endpoint SHOULD limit the number of connection IDs it has retired locally and
 have not yet been acknowledged. An endpoint SHOULD allow for sending and

```suggestion
An endpoint SHOULD limit the number of connection IDs it has retired through
RETIRE_CONNECTION_ID frames that remain unacknowledged. An endpoint SHOULD allow for sending and
```

> +tracking a number of RETIRE_CONNECTION_ID frames of at least twice the value of
+the active_connection_id_limit transport parameter. An endpoint MUST NOT forget

How about: "The number of RETIRE_CONNECTION_ID frames that an endpoint is allowed to send and track SHOULD be at least twice the value of the active_connection_id_limit transport parameter"

> @@ -1323,14 +1326,14 @@ Servers MUST drop incoming packets under all other circumstances.
 
 ### Considerations for Simple Load Balancers
 
-A server deployment could load balance among servers using only source and
+A server deployment could load-balance among servers using only source and

```suggestion
A server deployment could balance load among servers using only source and
```

> @@ -1828,11 +1832,11 @@ ack_delay_exponent, max_ack_delay, initial_source_connection_id,
 original_destination_connection_id, preferred_address,
 retry_source_connection_id, and stateless_reset_token. The client MUST use the
 server's new values in the handshake instead; if the server does not provide new
-values, the default value is used.
+values, the default values are used.

```suggestion
values, default values are used.
```

> -validation.  If the token is invalid then the server SHOULD proceed as if
-the client did not have a validated address, including potentially sending
-a Retry.  Tokens provided with NEW_TOKEN frames and Retry packets can be
-distinguished by servers (see {{token-differentiation}}), and the latter
-validated more strictly.  If the validation succeeds, the server SHOULD then
-allow the handshake to proceed.
-
-Note:
-
-: The rationale for treating the client as unvalidated rather than discarding
-  the packet is that the client might have received the token in a previous
-  connection using the NEW_TOKEN frame, and if the server has lost state, it
-  might be unable to validate the token at all, leading to connection failure if
-  the packet is discarded.
+validation.  If the token is invalid, then the server SHOULD proceed as if the
+client did not have a validated address, including potentially sending a Retry.

```suggestion
client did not have a validated address, including potentially sending a Retry packet.
```

>  ### Path Validation Responses
 
 On receiving a PATH_CHALLENGE frame, an endpoint MUST respond by echoing the
 data contained in the PATH_CHALLENGE frame in a PATH_RESPONSE frame.  An
 endpoint MUST NOT delay transmission of a packet containing a PATH_RESPONSE
 frame unless constrained by congestion control.
 
-A PATH_RESPONSE frame MUST be sent on the network path where the
-PATH_CHALLENGE was received.  This ensures that path validation by a peer only
-succeeds if the path is functional in both directions.  This requirement MUST
-NOT be enforced by the endpoint that initiates path validation as that would
-enable an attack on migration; see {{off-path-forward}}.
+A PATH_RESPONSE frame MUST be sent on the network path where the PATH_CHALLENGE

```suggestion
A PATH_RESPONSE frame MUST be sent on the network path where the PATH_CHALLENGE frame
```

> @@ -2338,8 +2343,8 @@ abandons its attempt to validate the path.
 Endpoints SHOULD abandon path validation based on a timer. When setting this
 timer, implementations are cautioned that the new path could have a longer
 round-trip time than the original.  A value of three times the larger of the
-current Probe Timeout (PTO) or the PTO for the new path (that is, using
-kInitialRtt as defined in {{QUIC-RECOVERY}}) is RECOMMENDED.
+current PTO or the PTO for the new path (that is, using kInitialRtt as defined

```suggestion
current PTO or the PTO for the new path (using kInitialRtt, as defined
```

> @@ -2573,13 +2578,13 @@ estimation for the new path.
 
 On confirming a peer's ownership of its new address, an endpoint MUST
 immediately reset the congestion controller and round-trip time estimator for
-the new path to initial values (see Appendices A.3 and B.3 in {{QUIC-RECOVERY}})
-unless the only change in the peer's address is its port number.  Because
-port-only changes are commonly the result of NAT rebinding or other middlebox
-activity, the endpoint MAY instead retain its congestion control state and
-round-trip estimate in those cases instead of reverting to initial values.
-In cases where congestion control state
-retained from an old path is used on a new path with substantially different
+the new path to initial values (see Appendices {{A.3<QUIC-RECOVERY}} and
+{{B.3<QUIC-RECOVERY}} of {{QUIC-RECOVERY}}) unless the only change in the peer's
+address is its port number.  Because port-only changes are commonly the result

```suggestion
address is its port number.  Since port-only changes are commonly the result
```

>  {{initiating-migration}} or when probing a new network path as described in
 {{probing}}.
 
 Similarly, an endpoint MUST NOT reuse a connection ID when sending to more than
 one destination address.  Due to network changes outside the control of its
 peer, an endpoint might receive packets from a new source address with the same
-destination connection ID, in which case it MAY continue to use the current
+Destination Connection ID, in which case it MAY continue to use the current

This is about the value of the field, and should not be capitalized, right?

> @@ -3257,9 +3264,10 @@ exhausted limits.
 Reducing the size of a Stateless Reset below 41 bytes means that the packet
 could reveal to an observer that it is a Stateless Reset, depending upon the
 length of the peer's connection IDs.  Conversely, refusing to send a Stateless
-Reset in response to a small packet might result in Stateless Reset not being
-useful in detecting cases of broken connections where only very small packets
-are sent; such failures might only be detected by other means, such as timers.
+Reset in response to a small packet might result in Stateless Reset packets not

```suggestion
Reset packet in response to a small packet might result in Stateless Reset packets not
```

>  Reducing the size of a Stateless Reset below 41 bytes means that the packet
 could reveal to an observer that it is a Stateless Reset, depending upon the

```suggestion
A Stateless Reset packet that is smaller than 41 bytes can be distinguishable
as a Stateless Reset packet to an observer, depending upon the
```

> @@ -3257,9 +3264,10 @@ exhausted limits.
 Reducing the size of a Stateless Reset below 41 bytes means that the packet
 could reveal to an observer that it is a Stateless Reset, depending upon the
 length of the peer's connection IDs.  Conversely, refusing to send a Stateless

```suggestion
length of the peer's connection IDs.  Conversely, not sending a Stateless
```

I'm surprised to see "during" not be capitalized.

>  An endpoint SHOULD limit the number of connection IDs it has retired locally and
 have not yet been acknowledged. An endpoint SHOULD allow for sending and

This is a semantic change, but it aligns the text with its spirit.

-- 
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/4877#pullrequestreview-649701285