From 91041eaf771e1dbfd27b38eeeeb3196b0ab974ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20B=C3=A9ky?= Date: Wed, 12 Dec 2018 15:32:44 -0500 Subject: [PATCH 1/4] Rearrange paragraphs. This commits only moves paragraphs around in whole. Paragraphs are not edited, redacted, broken up or joined. In addition, a new section "Eviction" is added. --- draft-ietf-quic-qpack.md | 78 +++++++++++++++++++++------------------- 1 file changed, 41 insertions(+), 37 deletions(-) diff --git a/draft-ietf-quic-qpack.md b/draft-ietf-quic-qpack.md index c1497f4c1b..5f743796c8 100644 --- a/draft-ietf-quic-qpack.md +++ b/draft-ietf-quic-qpack.md @@ -364,6 +364,32 @@ The dynamic table consists of a list of header fields maintained in first-in, first-out order. The dynamic table is initially empty. Entries are added by instructions on the encoder stream (see {{encoder-stream}}). +The dynamic table can contain duplicate entries (i.e., entries with the same +name and same value). Therefore, duplicate entries MUST NOT be treated as an +error by the decoder. + + +### Calculating Table Size + +The size of the dynamic table is the sum of the size of its entries. + +The size of an entry is the sum of its name's length in bytes (as defined in +{{string-literals}}), its value's length in bytes, and 32. + +The size of an entry is calculated using the length of its name and value +without any Huffman encoding applied. + + +### Maximum Table Size + +The encoder decides how to update the dynamic table and as such can control how +much memory is used by the dynamic table. To limit the memory requirements of +the decoder, the dynamic table size is strictly bounded. + +The decoder determines the maximum size that the encoder is permitted to use for +the dynamic table. In HTTP/3, this value is determined by the +SETTINGS_HEADER_TABLE_SIZE setting (see {{configuration}}). + The maximum size of the dynamic table can be modified by the encoder, subject to a decoder-controlled limit (see {{configuration}} and {{size-update}}). The initial maximum size is determined by the corresponding setting when HTTP @@ -374,6 +400,9 @@ 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. + +### Eviction + Before a new entry is added to the dynamic table, entries are evicted from the end of the dynamic table until the size of the dynamic table is less than or equal to (maximum size - new entry size) or until the table is empty. The @@ -390,21 +419,6 @@ when adding this new entry into the dynamic table. Implementations are cautioned to avoid deleting the referenced name if the referenced entry is evicted from the dynamic table prior to inserting the new entry. -The dynamic table can contain duplicate entries (i.e., entries with the same -name and same value). Therefore, duplicate entries MUST NOT be treated as an -error by the decoder. - - -### Maximum Table Size - -The encoder decides how to update the dynamic table and as such can control how -much memory is used by the dynamic table. To limit the memory requirements of -the decoder, the dynamic table size is strictly bounded. - -The decoder determines the maximum size that the encoder is permitted to use for -the dynamic table. In HTTP/3, this value is determined by the -SETTINGS_HEADER_TABLE_SIZE setting (see {{configuration}}). - An encoder can choose to use less capacity than this maximum size (see {{size-update}}), but the chosen size MUST stay lower than or equal to the maximum set by the decoder. Whenever the maximum size for the dynamic table is @@ -415,28 +429,6 @@ This mechanism can be used to completely clear entries from the dynamic table by setting a maximum size of 0, which can subsequently be restored. -### Calculating Table Size - -The size of the dynamic table is the sum of the size of its entries. - -The size of an entry is the sum of its name's length in bytes (as defined in -{{string-literals}}), its value's length in bytes, and 32. - -The size of an entry is calculated using the length of its name and value -without any Huffman encoding applied. - -`MaxEntries` is the maximum number of entries that the dynamic table can have. -The smallest entry has empty name and value strings and has the size of 32. -The MaxEntries is calculated as - -~~~ - MaxEntries = floor( MaxTableSize / 32 ) -~~~ - -MaxTableSize is the maximum size of the dynamic table as specified by the -decoder (see {{maximum-table-size}}). - - ### Absolute Indexing {#indexing} Each entry possesses both an absolute index which is fixed for the lifetime of @@ -821,6 +813,18 @@ zero, the encoder transforms it as follows before encoding: LargestReference = (LargestReference mod (2 * MaxEntries)) + 1 ~~~ +`MaxEntries` is the maximum number of entries that the dynamic table can have. +The smallest entry has empty name and value strings and has the size of 32. +The MaxEntries is calculated as + +~~~ + MaxEntries = floor( MaxTableSize / 32 ) +~~~ + +MaxTableSize is the maximum size of the dynamic table as specified by the +decoder (see {{maximum-table-size}}). + + The decoder reconstructs the Largest Reference using the following algorithm: ~~~ From 6dac31c71066a4d868fe516f902ea75c59cc014d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20B=C3=A9ky?= Date: Wed, 12 Dec 2018 15:52:49 -0500 Subject: [PATCH 2/4] Rearrange sentences. This commit breaks up and rejoints paragraphs and changes the order of sentences. No sentence is modified, redacted, omitted, or added. --- draft-ietf-quic-qpack.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/draft-ietf-quic-qpack.md b/draft-ietf-quic-qpack.md index 5f743796c8..2ee7743871 100644 --- a/draft-ietf-quic-qpack.md +++ b/draft-ietf-quic-qpack.md @@ -384,15 +384,14 @@ without any Huffman encoding applied. The encoder decides how to update the dynamic table and as such can control how much memory is used by the dynamic table. To limit the memory requirements of -the decoder, the dynamic table size is strictly bounded. - -The decoder determines the maximum size that the encoder is permitted to use for -the dynamic table. In HTTP/3, this value is determined by the -SETTINGS_HEADER_TABLE_SIZE setting (see {{configuration}}). - -The maximum size of the dynamic table can be modified by the encoder, subject to -a decoder-controlled limit (see {{configuration}} and {{size-update}}). The -initial maximum size is determined by the corresponding setting when HTTP +the decoder, the dynamic table size is strictly bounded. The decoder determines +the maximum size that the encoder is permitted to use for the dynamic table. In +HTTP/3, this value is determined by the SETTINGS_HEADER_TABLE_SIZE setting (see +{{configuration}}). The maximum size of the dynamic table can be modified by +the encoder, subject to a decoder-controlled limit (see {{configuration}} and +{{size-update}}). + +The initial maximum size is determined by the corresponding setting when HTTP 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 @@ -421,12 +420,13 @@ evicted from the dynamic table prior to inserting the new entry. An encoder can choose to use less capacity than this maximum size (see {{size-update}}), but the chosen size MUST stay lower than or equal to the -maximum set by the decoder. Whenever the maximum size for the dynamic table is -reduced, entries are evicted from the end of the dynamic table until the size of -the dynamic table is less than or equal to the maximum size. +maximum set by the decoder. -This mechanism can be used to completely clear entries from the dynamic table by -setting a maximum size of 0, which can subsequently be restored. +Whenever the maximum size for the dynamic table is reduced, entries are evicted +from the end of the dynamic table until the size of the dynamic table is less +than or equal to the maximum size. This mechanism can be used to completely +clear entries from the dynamic table by setting a maxiumum size of 0, which can +subsequently be restored. ### Absolute Indexing {#indexing} @@ -670,10 +670,10 @@ maximum table size is represented as an integer with a 5-bit prefix (see Section {:#fig-size-change title="Maximum Dynamic Table Size Change"} 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. +protocol using QPACK. In HTTP/3, this limit is the value of the +SETTINGS_HEADER_TABLE_SIZE parameter (see {{configuration}}) received from the +decoder. A value that exceeds this limit MUST be treated as a connection error +of type `HTTP_QPACK_ENCODER_STREAM_ERROR`. Reducing the maximum size of the dynamic table can cause entries to be evicted (see Section 4.3 of [RFC7541]). This MUST NOT cause the eviction of entries From c1e4f68e43ddc9e1ef55eee4975952cfcc450b39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20B=C3=A9ky?= Date: Wed, 12 Dec 2018 16:04:05 -0500 Subject: [PATCH 3/4] Editorial bikesheding. --- draft-ietf-quic-qpack.md | 52 +++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 28 deletions(-) diff --git a/draft-ietf-quic-qpack.md b/draft-ietf-quic-qpack.md index 2ee7743871..1ecd8e493f 100644 --- a/draft-ietf-quic-qpack.md +++ b/draft-ietf-quic-qpack.md @@ -382,14 +382,14 @@ without any Huffman encoding applied. ### Maximum Table Size -The encoder decides how to update the dynamic table and as such can control how -much memory is used by the dynamic table. To limit the memory requirements of -the decoder, the dynamic table size is strictly bounded. The decoder determines -the maximum size that the encoder is permitted to use for the dynamic table. In -HTTP/3, this value is determined by the SETTINGS_HEADER_TABLE_SIZE setting (see -{{configuration}}). The maximum size of the dynamic table can be modified by -the encoder, subject to a decoder-controlled limit (see {{configuration}} and -{{size-update}}). +The encoder decides how to update the dynamic table size and as such can control +how much memory is used by the dynamic table. To limit the memory requirements +of the decoder, the dynamic table size is strictly bounded. The decoder +determines the maximum size that the encoder is permitted to set for the dynamic +table. In HTTP/3, this value is determined by the SETTINGS_HEADER_TABLE_SIZE +setting (see {{configuration}}). The encoder MUST not set a dynamic table size +that exceeds this maximum, but it can choose to use a lower dynamic table size +(see {{size-update}}). The initial maximum size is determined by the corresponding setting when HTTP requests or responses are first permitted to be sent. For clients using 0-RTT @@ -418,15 +418,11 @@ when adding this new entry into the dynamic table. Implementations are cautioned to avoid deleting the referenced name if the referenced entry is evicted from the dynamic table prior to inserting the new entry. -An encoder can choose to use less capacity than this maximum size (see -{{size-update}}), but the chosen size MUST stay lower than or equal to the -maximum set by the decoder. - -Whenever the maximum size for the dynamic table is reduced, entries are evicted -from the end of the dynamic table until the size of the dynamic table is less -than or equal to the maximum size. This mechanism can be used to completely -clear entries from the dynamic table by setting a maxiumum size of 0, which can -subsequently be restored. +Whenever the maximum size for the dynamic table is reduced by the encoder, +entries are evicted from the end of the dynamic table until the size of the +dynamic table is less than or equal to the new maximum size. This mechanism can +be used to completely clear entries from the dynamic table by setting a maxiumum +size of 0, which can subsequently be restored. ### Absolute Indexing {#indexing} @@ -669,11 +665,11 @@ maximum table size is represented as an integer with a 5-bit prefix (see Section ~~~~~~~~~~ {:#fig-size-change title="Maximum Dynamic Table Size Change"} -The new maximum size MUST be lower than or equal to the limit determined by the -protocol using QPACK. In HTTP/3, this limit is the value of the +The new maximum size MUST be lower than or equal to the limit described in +{{maximum-table-size}}. In HTTP/3, this limit is the value of the SETTINGS_HEADER_TABLE_SIZE parameter (see {{configuration}}) received from the -decoder. A value that exceeds this limit MUST be treated as a connection error -of type `HTTP_QPACK_ENCODER_STREAM_ERROR`. +decoder. The decoder MUST treat a value that exceeds this limit as a connection +error of type `HTTP_QPACK_ENCODER_STREAM_ERROR`. Reducing the maximum size of the dynamic table can cause entries to be evicted (see Section 4.3 of [RFC7541]). This MUST NOT cause the eviction of entries @@ -772,9 +768,9 @@ 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. +outstanding. A decoder with a maximum dynamic table size equal to zero (see +{{maximum-table-size}}) MAY omit sending Stream Cancellations, because the +encoder cannot have any dynamic table references. An encoder cannot infer from this instruction that any updates to the dynamic table have been received. @@ -813,15 +809,15 @@ zero, the encoder transforms it as follows before encoding: LargestReference = (LargestReference mod (2 * MaxEntries)) + 1 ~~~ -`MaxEntries` is the maximum number of entries that the dynamic table can have. -The smallest entry has empty name and value strings and has the size of 32. -The MaxEntries is calculated as +Here `MaxEntries` is the maximum number of entries that the dynamic table can +have. The smallest entry has empty name and value strings and has the size of +32. Hence `MaxEntries` is calculated as ~~~ MaxEntries = floor( MaxTableSize / 32 ) ~~~ -MaxTableSize is the maximum size of the dynamic table as specified by the +`MaxTableSize` is the maximum size of the dynamic table as specified by the decoder (see {{maximum-table-size}}). From 3e6464fa57c0b993bb2f481a6e1b8a71df2c765f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20B=C3=A9ky?= Date: Tue, 18 Dec 2018 11:02:36 -0500 Subject: [PATCH 4/4] Swap eviction and max table size sections. --- draft-ietf-quic-qpack.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/draft-ietf-quic-qpack.md b/draft-ietf-quic-qpack.md index 1ecd8e493f..90c7e3946d 100644 --- a/draft-ietf-quic-qpack.md +++ b/draft-ietf-quic-qpack.md @@ -380,26 +380,6 @@ The size of an entry is calculated using the length of its name and value without any Huffman encoding applied. -### Maximum Table Size - -The encoder decides how to update the dynamic table size and as such can control -how much memory is used by the dynamic table. To limit the memory requirements -of the decoder, the dynamic table size is strictly bounded. The decoder -determines the maximum size that the encoder is permitted to set for the dynamic -table. In HTTP/3, this value is determined by the SETTINGS_HEADER_TABLE_SIZE -setting (see {{configuration}}). The encoder MUST not set a dynamic table size -that exceeds this maximum, but it can choose to use a lower dynamic table size -(see {{size-update}}). - -The initial maximum size is determined by the corresponding setting when HTTP -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. - - ### Eviction Before a new entry is added to the dynamic table, entries are evicted from the @@ -425,6 +405,26 @@ be used to completely clear entries from the dynamic table by setting a maxiumum size of 0, which can subsequently be restored. +### Maximum Table Size + +The encoder decides how to update the dynamic table size and as such can control +how much memory is used by the dynamic table. To limit the memory requirements +of the decoder, the dynamic table size is strictly bounded. The decoder +determines the maximum size that the encoder is permitted to set for the dynamic +table. In HTTP/3, this value is determined by the SETTINGS_HEADER_TABLE_SIZE +setting (see {{configuration}}). The encoder MUST not set a dynamic table size +that exceeds this maximum, but it can choose to use a lower dynamic table size +(see {{size-update}}). + +The initial maximum size is determined by the corresponding setting when HTTP +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. + + ### Absolute Indexing {#indexing} Each entry possesses both an absolute index which is fixed for the lifetime of