Subject: [quicwg/base-drafts] Clean up text on Maximum Table Size. (#2115)

From: Bence Béky <[email-masked]>
Date: Tue, 11 Dec 2018 11:01:51 -0800

Consistently refer to the maximum size of the dynamic table (set by the
encoder) as Maximum Table Size, and the limit on this maximum (usually
set by the decoder) as limit on the Maximum Table Size.  Remove
references to the decoder setting this limit in the general case, as
QPACK deployments might have preset values for this limit that are not
communicated using the protocol using QPACK.  Rearrange sections on
table size, Maximum Table Size, and eviction.  Move MaxEntries
definition to where it's used.
You can view, comment on, or merge this pull request online at:

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

-- Commit Summary --

  * Clean up text on Maximum Table Size.

-- File Changes --

    M draft-ietf-quic-qpack.md (148)

-- Patch Links --

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

---

From: Martin Thomson <[email-masked]>
Date: Wed, 12 Dec 2018 00:39:21 +0000 (UTC)

martinthomson requested changes on this pull request.

I think that we should instead refer to the current limit as the "Table Size" or "Dynamic Table Size" and reserve "Maximum Table Size" to refer to the maximum value that can take.  In other words, Maximum refers to the setting.

Not sure how to review the moved text.  How much changed?

-~~~
-   MaxEntries = floor( MaxTableSize / 32 )
-~~~
+### Maximum Table Size

I think that we need to use "Table Size" for this concept and reserve the maximum table size for the setting.

That invalidates much of 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/2115#pullrequestreview-183947287

---

From: Bence Béky <[email-masked]>
Date: Wed, 12 Dec 2018 11:52:36 -0800

Hi Martin, I think that's a great option.  Please help me with the nomenclature here.  There are three distinct quantities at play:

A: The sum of the size of the entries in the dynamic table.

B: The amount of memory the decoder is required for dynamic table entries.  Oldest entries that do not fit in B will be evicted.  This quantity can be changed unilaterally by the encoder as long as it does not exceed C.

C: Hard limit on B.  In HTTP/3, this is set by the decoder via SETTINGS_HEADER_TABLE_SIZE.

All three quantities have to be discussed in the spec, and a compliant optimal decoder needs to keep track of all three of them.  Therefore I feel strongly that they need consistent and distinct names (or phrases) for them.

Currently the spec consistently uses "(dynamic) table size" for A (for example, first sentence of 3.2.2) and "maximum (dynamic) table size" or "maximum size of the dynamic table" for C (for example, when calculating MaxEntries or in 4.4.3 when talking about omitting stream cancellations).  For B, the spec sometimes uses "table size", sometimes "maximum table size", sometimes within the same section, like 4.3.4.

What I drafted up was A: "table size", B: "Maximum Table Size", C: "limit on Maximum Table Size".  Another option you are proposing, if I understand you correctly, is B: "table size", C: "maximum table size".  Then we need to find something for A, like "table load" or "table utilization" or "table memory footprint", or just write out "sum of size of entries" every time.  I'm fine with that.

A third option could be A: "table size" (which I think is the conventional meaning of "size"); C: "maximum table size", and find something for B, like "table capacity".

I do not have a strong opinion on any of these names, as long as the text is clean and unambiguous.  Please tell me what your preference is.  Thanks.

As for the reordering of large chunks of text, sorry for mixing that in with this PR.  I'll draft a separate PR for that and rebase this one on that.

-- 
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/2115#issuecomment-446721184

---

From: Martin Thomson <[email-masked]>
Date: Wed, 12 Dec 2018 16:28:27 -0800

So I don't think that the amount of *used* space (your A) is that important in the text.  What is most relevant is the amount of space the decoder allows (the setting, your C) and the amount of space the encoder is using (your B).

If we can avoid talking too much about the occupied space, then we might be in a better position.  If we have to, we can talk about "used" or "occupied" space.

I'd like to suggest "maximum table capacity" (C), "table capacity" (B), and "table size" (A).  Would that be better?  I think that avoids the problems you are talking about by using the word "capacity".

-- 
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/2115#issuecomment-446796679

---

From: Bence Béky <[email-masked]>
Date: Thu, 13 Dec 2018 07:32:55 -0800

Sure that sounds good.  Your first two paragraphs kinda imply "table size" for B and just avoiding talking about A (or I guess writing it "sum of size of entries"), but you are proposing something different in the last paragraph.  I'm totally fine with either.  I'll write up something as soon as https://github.com/quicwg/base-drafts/pull/2115 is merged.

By the way can you please add "-qpack" label to this PR and to https://github.com/quicwg/base-drafts/pull/2115?  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/2115#issuecomment-447010651

---

From: Bence Béky <[email-masked]>
Date: Thu, 13 Dec 2018 07:33:23 -0800

And by #2115 I of course meant https://github.com/quicwg/base-drafts/pull/2134.

-- 
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/2115#issuecomment-447010838

---

From: Bence Béky <[email-masked]>
Date: Tue, 18 Dec 2018 08:04:28 -0800

@bencebeky pushed 8 commits.

06b688bddb3ef56bb1513cd267b7dc016b1fff89  undo some of the reshuffling
c51d86659368c9b71b50972cf77782295845673c  Revert "undo some of the reshuffling"
ca090ded7f0dac1cb53f1929ddf48eb9fb8428b6  Revert "Clean up text on Maximum Table Size."
585d8e134c4e21169df9f43eefd3c45abb9b50a8  Rearrange paragraphs.
01e02216c5b176209cdd7692231add66b486841d  Rearrange sentences.
4ffef16f839a3157aeccc86bbeca749bb8430eea  Editorial bikesheding.
a172b353d39143f7908f9e6cd0dec1679c806f97  Swap eviction and max table size sections.
dc49d225f219995498eace6440ec660494b4903a  Use and clarify dynamic table capacity.

-- 
You are receiving this because you are subscribed to this thread.
View it on GitHub:
https://github.com/quicwg/base-drafts/pull/2115/files/5c076b4222d611c4cdd0b10db1b2fefc33b31a4d..dc49d225f219995498eace6440ec660494b4903a

---

From: Bence Béky <[email-masked]>
Date: Tue, 18 Dec 2018 16:11:23 +0000 (UTC)

I added a bunch of commits to this PR: I revert the original change, then cherry-pick all four commits from https://github.com/quicwg/base-drafts/pull/2134, and add a final commit, titled "Use and clarify dynamic table capacity.", that implements the terminology proposed at https://github.com/quicwg/base-drafts/pull/2115#issuecomment-446796679.

Sorry, I do not know how to make dependent PRs, but all but the last commit will disappear once https://github.com/quicwg/base-drafts/pull/2134 lands and I rebase this PR.

-- 
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/2115#issuecomment-448275419

---

From: Bence Béky <[email-masked]>
Date: Tue, 18 Dec 2018 08:16:27 -0800

bencebeky commented on this pull request.

> -requests or responses are first permitted to be sent. For clients using 0-RTT
-data in HTTP/3, the table size is the remembered value of the setting, even if
-the server later specifies a larger maximum in its SETTINGS frame.  For HTTP/3
-servers and HTTP/3 clients when 0-RTT is not attempted or is rejected, the
-initial maximum table size is the value of the setting in the peer's SETTINGS
-frame.
+The initial dynamic table capacity is the value of the maximum dynamic table
+capacity when HTTP requests or responses are first permitted to be sent.  For
+HTTP/3 servers and HTTP/3 clients when 0-RTT is not attempted or is rejected,
+the initial maximum table capacity is zero.  For clients using 0-RTT data in
+HTTP/3, the initial table capacity is the remembered value of the setting, even
+if the server later specifies a different maximum dynamic table capacity in its
+SETTINGS frame.  It is not an error for the SETTINGS frame to contain a
+SETTINGS_MAXIMUM_DYNAMIC_TABLE_CAPACITY value lower than the initial table
+capacity on a 0-RTT connection; the maximum dynamic table capacity only limits
+subsequent table capacity changes.  However, if an endpoint receives a

This is so that a decoder can request reduction of maximum dynamic table capacity on a new connection.

There are other, much simpler options:
1. Ban an endpoint from sending a SETTINGS_MAXIMUM_DYNAMIC_TABLE_CAPACITY value on a 0-RTT connection that is smaller than the remembered value.
2. Have the maximum table capacity always default to 0, even on a 0-RTT connection, until the SETTINGS frame is received.

-- 
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/2115#pullrequestreview-186153636

---

From: Bence Béky <[email-masked]>
Date: Tue, 18 Dec 2018 08:19:47 -0800

-The initial maximum size is determined by the corresponding setting when HTTP

I have changed the initial maximum table capacity to zero in the spirit of https://github.com/quicwg/base-drafts/pull/2038, because that is what's consistent with the first sentence.  And endpoint is allowed to send HTTP requests and responses before receiving the peer's SETTINGS frame.

Another option is to scratch the first sentence, and describe that an endpoint cannot use the dynamic table until the SETTINGS frame is received, however, at that point the dynamic table capacity is changed to the value of SETTINGS_MAXIMUM_DYNAMIC_TABLE_CAPACITY.

-- 
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/2115#pullrequestreview-186155542

---

From: Bence Béky <[email-masked]>
Date: Tue, 18 Dec 2018 08:28:01 -0800

> @@ -768,9 +781,7 @@ end of a stream, it generates a Stream Cancellation instruction on the decoder
 stream.  Similarly, when an endpoint abandons reading of a stream it needs to
 signal this using the Stream Cancellation instruction.  This signals to the
 encoder that all references to the dynamic table on that stream are no longer
-outstanding.  A decoder with a maximum dynamic table size equal to zero (see

I think there is a race here for 0-RTT connections.  Assume the remembered value for SETTINGS_MAXIMUM_DYNAMIC_TABLE_CAPACITY is non-zero.  An endpoint can send a SETTINGS frame with zero SETTINGS_MAXIMUM_DYNAMIC_TABLE_CAPACITY, then send a request and cancel it.  Since the decoder's maximum dynamic table capacity is zero, it does not have to send a Stream Cancellation.  However, the peer might receive the request and send a response using the remembered value of SETTINGS_MAXIMUM_DYNAMIC_TABLE_CAPACITY, inserting entries to the dynamic table.  Those references will never be cleared.

This isssue is intertwined with the one above on the initial value of maximum table capacity on 0-RTT connections.

-- 
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/2115#pullrequestreview-186160080

---

From: Bence Béky <[email-masked]>
Date: Tue, 18 Dec 2018 08:28:23 -0800

This also affects whether stream cancellations can be optional, see below.

-- 
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/2115#discussion_r242608360

---

From: afrind <[email-masked]>
Date: Tue, 18 Dec 2018 14:43:49 -0800

afrind commented on this pull request.

Can you file a separate issue for 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/2115#discussion_r242733875

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 14:50:04 -0800

MikeBishop requested changes on this pull request.

I think this is a good improvement, but a few things need fixing before it merges.  Also, if you want GitHub to give you credit for the commits, the `user.email` needs to be an e-mail that GitHub has associated with your user account (verified or not).

Good catch!  I like your proposed text, and this reflects the agreement we reached on #1530.

HTTP/3 in general bars reducing the value of a setting while accepting 0-RTT, so (1) would be more consistent.  From 4.2.5.2 in H3:

> If 0-RTT data is accepted by the server, its SETTINGS frame MUST NOT reduce any limits or alter any values that might be violated by the client with its 0-RTT data.

-The new maximum size MUST be lower than or equal to the limit determined by the
-protocol using QPACK.  A value that exceeds this limit MUST be treated as a
-connection error of type `HTTP_QPACK_ENCODER_STREAM_ERROR`.  In HTTP/3, this
-limit is the value of the SETTINGS_HEADER_TABLE_SIZE parameter (see
-{{configuration}}) received from the decoder.
+The new capacity MUST be lower than or equal to the limit described in
+{{maximum-dynamic-table-capacity}}.  On 1-RTT HTTP/3 connections, this limit is

True for all connections -- the setting has an initial value of (0 , previous) and then gets updated when the SETTINGS frame is received.

> @@ -780,9 +781,7 @@ end of a stream, it generates a Stream Cancellation instruction on the decoder
 stream.  Similarly, when an endpoint abandons reading of a stream it needs to
 signal this using the Stream Cancellation instruction.  This signals to the
 encoder that all references to the dynamic table on that stream are no longer
-outstanding.  A decoder with a maximum dynamic table size equal to zero MAY omit
-sending Stream Cancellations, because the encoder cannot have any dynamic table
-references.

...and therefore, we still want this text.

> @@ -1261,7 +1272,8 @@ Substantial editorial reorganization; no technical changes.
 - Largest Reference encoded modulo MaxEntries (#1763)
 - New Static Table (#1355)
 - Table Size Update with Insert Count=0 is a connection error (#1762)
-- Stream Cancellations are optional when SETTINGS_HEADER_TABLE_SIZE=0 (#1761)
+- Stream Cancellations are optional when
+  SETTINGS_MAXIMUM_DYNAMIC_TABLE_CAPACITY=0 (#1761)

Rather than retconning the changelog, it's probably more appropriate to add a current changelog entry that SETTINGS_HEADER_TABLE_SIZE was renamed.

-- 
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/2115#pullrequestreview-186314467

---

From: Mike Bishop <[email-masked]>
Date: Tue, 18 Dec 2018 22:52:14 +0000 (UTC)

BTW, for a dependent PR, you set the parent branch of the PR to something other than `master`.  It's also common practice to also add a very prominent **DO NOT MERGE** note indicating that it shouldn't actually get merged to that branch, but retargeted to master once that PR merges.

-- 
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/2115#issuecomment-448401874

---

From: Martin Thomson <[email-masked]>
Date: Tue, 18 Dec 2018 17:45:16 -0800

martinthomson commented on this pull request.

Yes, just forbid reductions.  It's simpler.

I don't like this because I think that it means that I have to send a capacity update instruction, which I don't currently, but that's my problem.

-- 
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/2115#discussion_r242767981