Subject: Re: [quicwg/base-drafts] Reorganize ACK section (#2197)

From: janaiyengar <[email-masked]>
Date: Fri, 04 Jan 2019 17:21:41 -0800

janaiyengar commented on this pull request.

Looks good, a few comments, mostly minor. One note: ACK Ranges and ECN Counters are not fields, they are composed of fields. I would refrain from calling them fields.

> @@ -2841,23 +2841,24 @@ needing acknowledgement are received.  The sender can use the receiver's
 Strategies and implications of the frequency of generating acknowledgments are
 discussed in more detail in {{QUIC-RECOVERY}}.
 
-To limit ACK Blocks to those that have not yet been received by the sender, the
-receiver SHOULD track which ACK frames have been acknowledged by its peer.  Once
-an ACK frame has been acknowledged, the packets it acknowledges SHOULD NOT be
-acknowledged again.
+To limit the ranges of acknowledged packet numbers to those that have not yet
+been received by the sender, the receiver SHOULD track which ACK frames have
+been acknowledged by its peer.  Once an ACK frame has been acknowledged, the
+packets it acknowledges SHOULD NOT be acknowledged again.

This is now fixed in #2245.

 Because ACK frames are not sent in response to ACK-only packets, a receiver that
 is only sending ACK frames will only receive acknowledgements for its packets
 if the sender includes them in packets with non-ACK frames.  A sender SHOULD
 bundle ACK frames with other frames when possible.
 
 To limit receiver state or the size of ACK frames, a receiver MAY limit the
-number of ACK Blocks it sends.  A receiver can do this even without receiving
-acknowledgment of its ACK frames, with the knowledge this could cause the sender
-to unnecessarily retransmit some data.  Standard QUIC {{QUIC-RECOVERY}}
-algorithms declare packets lost after sufficiently newer packets are
-acknowledged.  Therefore, the receiver SHOULD repeatedly acknowledge newly
-received packets in preference to packets received in the past.
+number of ACK Range fields it sends.  A receiver can do this even without

```suggestion
number of ACK Ranges it sends.  A receiver can do this even without
```

-The ACK frame uses the least significant bit (that is, type 0x03) to indicate
-ECN feedback and report receipt of QUIC packets with associated ECN codepoints
-of ECT(0), ECT(1), or CE in the packet's IP header.
+
+### ACK Ranges Section {#ack-ranges-section}

```suggestion
### ACK Ranges {#ack-ranges-section}
```

-The ACK frame uses the least significant bit (that is, type 0x03) to indicate
-ECN feedback and report receipt of QUIC packets with associated ECN codepoints
-of ECT(0), ECT(1), or CE in the packet's IP header.
+
+### ACK Ranges Section {#ack-ranges-section}
+
+The ACK Range Section consists of alternating Gap and ACK Range fields in

```suggestion
The ACK Ranges consists of alternating Gap and ACK Range fields in
```

-The ACK frame uses the least significant bit (that is, type 0x03) to indicate
-ECN feedback and report receipt of QUIC packets with associated ECN codepoints
-of ECT(0), ECT(1), or CE in the packet's IP header.
+
+### ACK Ranges Section {#ack-ranges-section}
+
+The ACK Range Section consists of alternating Gap and ACK Range fields in
+descending packet number order.  The First Ack Range field is followed by a
+variable number of alternating Gap and ACK Range fields.  The number of Gap and

This sentence ("The First Ack Range ...") can probably go.

-The ACK frame uses the least significant bit (that is, type 0x03) to indicate
-ECN feedback and report receipt of QUIC packets with associated ECN codepoints
-of ECT(0), ECT(1), or CE in the packet's IP header.
+
+### ACK Ranges Section {#ack-ranges-section}
+
+The ACK Range Section consists of alternating Gap and ACK Range fields in
+descending packet number order.  The First Ack Range field is followed by a
+variable number of alternating Gap and ACK Range fields.  The number of Gap and
+ACK Range fields is determined by the ACK Range Count field; one of each field
+is present for each value in the ACK Range Count field.
+
+The ACK Ranges field is structured as follows:

```suggestion
ACK Ranges are structured as follows:
```

>  number of acknowledged packets that precede the largest packet number in that
-block.  A value of zero indicates that only the largest packet number is
-acknowledged.  Larger ACK Block values indicate a larger range, with
+range.  A value of zero indicates that only the largest packet number is
+acknowledged.  Larger ACK range values indicate a larger range, with

```suggestion
acknowledged.  Larger ACK Range values indicate a larger range, with
```

>  ~~~
 
-The range of packets that are acknowledged by the ACK Block include the range
-from the smallest packet number to the largest, inclusive.
+The packets that are acknowledged by the ACK Range include the range from the
+smallest packet number to the largest, inclusive.

Suggestion: "An ACK Range acknowledges all packet numbers between the smallest packet number and the largest, inclusive."

-: Contains one or more blocks of packet numbers which have been successfully
-  received, see {{ack-block-section}}.
+: A variable-length integer indicating the number of contiguous packets
+  preceding the Largest Acknowledged that are being acknowledged.

I think some more text about parsing this needs to be moved up. How about adding something like: 

"The smallest value in this range is determined by the formula:
~~~
   smallest = Largest Acknowledged - First ACK Range
~~~

The First ACK range acknowledges all packet numbers between the smallest and the Largest Acknowledged, inclusive."

-The largest value for the First ACK Block is determined by the Largest
-Acknowledged field; the largest for Additional ACK Blocks is determined by
-cumulatively subtracting the size of all preceding ACK Blocks and Gaps.
+The largest packet number value for the First ACK Range is determined by the
+Largest Acknowledged field; the largest value for subsequent ACK Range fields is

Remove this first part about First ACK Range. Start the sentence with: "The largest value for an ACK Range is determined by ..."

 The value of the Gap field establishes the largest packet number value for the
-ACK Block that follows the gap using the following formula:
+ACK Range that follows the gap using the following formula:

```suggestion
subsequent ACK Range, using the following formula:
```

 ~~~
   largest = previous_smallest - gap - 2
 ~~~
 
-If the calculated value for largest or smallest packet number for any ACK Block
+If the calculated value for largest or smallest packet number for any ACK Range

```suggestion
If any of these computed packet numbers
```

>  is negative, an endpoint MUST generate a connection error of type
 FRAME_ENCODING_ERROR indicating an error in an ACK frame.
 
-The fields in the ACK Block Section are:
-
-First ACK Block:
-
-: A variable-length integer indicating the number of contiguous packets
-  preceding the Largest Acknowledged that are being acknowledged.
+The fields that form the ACK Ranges field are:

```suggestion
The fields that form the ACK Ranges are:
```

>  is negative, an endpoint MUST generate a connection error of type
 FRAME_ENCODING_ERROR indicating an error in an ACK frame.
 
-The fields in the ACK Block Section are:
-
-First ACK Block:
-
-: A variable-length integer indicating the number of contiguous packets
-  preceding the Largest Acknowledged that are being acknowledged.
+The fields that form the ACK Ranges field are:

This should be moved above, to before the entire description of how ACK ranges are to be parsed. Probably to the top of {{ack-range-section}}.

> @@ -4310,6 +4317,8 @@ section consists of 3 ECN counters as shown below.
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 ~~~
 
+The fields that form the ECN Counters field are:

```suggestion
The fields that form the ECN Counters are:
```

-- 
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/2197#pullrequestreview-189574193

---

From: Martin Thomson <[email-masked]>
Date: Sun, 06 Jan 2019 14:56:17 -0800

@martinthomson pushed 3 commits.

808ed5dcb45158ad388f1c598e9da775a40acae6  Port #2245
6807d155a6bbcc9415081aa9ad7896a7de64e80c  Stop using 'fields' for ACK Range and Gap, tweak structure a little
bdd84ea0aeb25afdf51d14f1d89cf2e4794e9df7  Merge branch 'master' into shuffle-ack

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2197/files/92d35a8267f496e29466d220e29fc8aff8d68176..bdd84ea0aeb25afdf51d14f1d89cf2e4794e9df7

---

From: janaiyengar <[email-masked]>
Date: Mon, 07 Jan 2019 17:19:21 -0800

-
-### ECN section
+The ACK frame uses the least significant bit (that is, type 0x03) to indicate
+ECN feedback and report receipt of QUIC packets with associated ECN codepoints
+of ECT(0), ECT(1), or CE in the packet's IP header.  The ECN section is only
+present when the ACK frame type is 0x03.
 
 The ECN section should only be parsed when the ACK frame type is 0x03.  The ECN

```suggestion
ECN Counts should only be parsed when the ACK frame type is 0x03.  The ECN
```

-- 
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/2197#pullrequestreview-190060974

---

From: janaiyengar <[email-masked]>
Date: Mon, 07 Jan 2019 17:19:48 -0800

-
-### ECN section

```suggestion
of ECT(0), ECT(1), or CE in the packet's IP header.  ECN Counts are only
```

-- 
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/2197#pullrequestreview-190061054

---

From: janaiyengar <[email-masked]>
Date: Mon, 07 Jan 2019 17:21:51 -0800

The ECN section should only be parsed when the ACK frame type is 0x03.  The ECN
-section consists of 3 ECN counts as shown below.
+section consists of 3 ECN counts as follows:

three ECN counts, as follows:

-- 
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/2197#pullrequestreview-190061379

---

From: janaiyengar <[email-masked]>
Date: Mon, 07 Jan 2019 17:22:34 -0800

> @@ -4349,6 +4362,8 @@ section consists of 3 ECN counts as shown below.
 
+The fields that form the ECN Counts are:

```suggestion
The three ECN Counts are:
```

-- 
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/2197#pullrequestreview-190061518

---

From: janaiyengar <[email-masked]>
Date: Mon, 07 Jan 2019 17:23:30 -0800

janaiyengar approved this pull request.

Just a few more nits, but looks good. Commit once you've addressed those.

-- 
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/2197#pullrequestreview-190061705

---

From: Martin Thomson <[email-masked]>
Date: Mon, 07 Jan 2019 20:33:32 -0800

Merged #2197 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/2197#event-2059240012