From cf39769cbcd48c56bb19bcc24146918539370d5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20B=C3=A9ky?= Date: Wed, 31 Jul 2019 11:33:22 -0400 Subject: [PATCH] instructions --- draft-ietf-quic-qpack.md | 175 +++++++++++++++++++-------------------- 1 file changed, 84 insertions(+), 91 deletions(-) diff --git a/draft-ietf-quic-qpack.md b/draft-ietf-quic-qpack.md index daa77f930b..58ffe5c1c0 100644 --- a/draft-ietf-quic-qpack.md +++ b/draft-ietf-quic-qpack.md @@ -149,8 +149,8 @@ x (A) : Indicates that x is A bits long x (A+) -: Indicates that x uses the prefixed integer encoding defined in Section 5.1 of - [RFC7541], beginning with an A-bit prefix. +: Indicates that x uses the prefixed integer encoding defined in + {{prefixed-integers}}, beginning with an A-bit prefix. x ... : Indicates that x is variable-length and extends to the end of the region. @@ -170,13 +170,13 @@ decoder and vice versa. An encoder converts a header list into a header block by emitting either an indexed or a literal representation for each header field in the list (see -{{header-block-representations}}). Indexed representations achieve high -compression by replacing the literal name and possibly the value with an index -to either the static or dynamic table. References to the static table and -literal representations do not require any dynamic state and never risk -head-of-line blocking. References to the dynamic table risk head-of-line -blocking if the encoder has not received an acknowledgement indicating the entry -is available at the decoder. +{{header-blocks}}). Indexed representations achieve high compression by +replacing the literal name and possibly the value with an index to either the +static or dynamic table. References to the static table and literal +representations do not require any dynamic state and never risk head-of-line +blocking. References to the dynamic table risk head-of-line blocking if the +encoder has not received an acknowledgement indicating the entry is available at +the decoder. An encoder MAY insert any entry in the dynamic table it chooses; it is not limited to header fields it is compressing. @@ -378,11 +378,10 @@ acknowledged before using it. ### Invalid References -If the decoder encounters a reference in a header block representation to a -dynamic table entry which has already been evicted or which has an absolute -index greater than or equal to the declared Required Insert Count (see -{{header-prefix}}), it MUST treat this as a connection error of type -`HTTP_QPACK_DECOMPRESSION_FAILED`. +If the decoder encounters in a header block a reference to a dynamic table entry +which has already been evicted or which has an absolute index greater than or +equal to the declared Required Insert Count (see {{header-prefix}}), it MUST +treat this as a connection error of type `HTTP_QPACK_DECOMPRESSION_FAILED`. If the decoder encounters a reference in an encoder instruction to a dynamic table entry which has already been evicted, it MUST treat this as a connection @@ -407,11 +406,10 @@ index. Note the QPACK static table is indexed from 0, whereas the HPACK static table is indexed from 1. -When the decoder encounters an invalid static table index in a header block -representation it MUST treat this as a connection error of type -`HTTP_QPACK_DECOMPRESSION_FAILED`. If this index is received on the encoder -stream, this MUST be treated as a connection error of type -`HTTP_QPACK_ENCODER_STREAM_ERROR`. +When the decoder encounters an invalid static table index in a header block it +MUST treat this as a connection error of type `HTTP_QPACK_DECOMPRESSION_FAILED`. +If this index is received on the encoder stream, this MUST be treated as a +connection error of type `HTTP_QPACK_ENCODER_STREAM_ERROR`. ## Dynamic Table {#table-dynamic} @@ -527,7 +525,7 @@ d = count of entries dropped ~~~~~ {: title="Example Dynamic Table Indexing - Encoder Stream"} -Unlike encoder instructions, relative indices in header block representations +Unlike in encoder instructions, relative indices in header block instructions are relative to the Base at the beginning of the header block (see {{header-prefix}}). This ensures that references are stable even if header blocks and dynamic table updates are processed out of order. @@ -652,9 +650,9 @@ This section specifies the following encoder instructions. ### Set Dynamic Table Capacity {#set-dynamic-capacity} An encoder informs the decoder of a change to the dynamic table capacity using -an instruction which begins with the '001' three-bit pattern. The new dynamic -table capacity is represented as an integer with a 5-bit prefix (see Section 5.1 -of [RFC7541]). +an instruction which begins with the '001' three-bit pattern. This is followed +by the new dynamic table capacity represented as an integer with a 5-bit prefix +(see {{prefixed-integers}}). ~~~~~~~~~~ drawing 0 1 2 3 4 5 6 7 @@ -680,15 +678,15 @@ acknowledged as this instruction does not insert an entry. An encoder adds an entry to the dynamic table where the header field name matches the header field name of an entry stored in the static or the dynamic -table using an instruction that starts with the '1' one-bit pattern. The second +table using an instruction that begins with the '1' one-bit pattern. The second (`S`) bit indicates whether the reference is to the static or dynamic table. The -6-bit prefix integer (see Section 5.1 of [RFC7541]) that follows is used to -locate the table entry for the header name. When S=1, the number represents the -static table index; when S=0, the number is the relative index of the entry in -the dynamic table. +6-bit prefix integer (see {{prefixed-integers}}) that follows is used to locate +the table entry for the header name. When S=1, the number represents the static +table index; when S=0, the number is the relative index of the entry in the +dynamic table. The header name reference is followed by the header field value represented as a -string literal (see Section 5.2 of [RFC7541]). +string literal (see {{string-literals}}). ~~~~~~~~~~ drawing 0 1 2 3 4 5 6 7 @@ -706,11 +704,12 @@ string literal (see Section 5.2 of [RFC7541]). ### Insert Without Name Reference An encoder adds an entry to the dynamic table where both the header field name -and the header field value are represented as string literals (see -{{primitives}}) using an instruction that starts with the '01' two-bit pattern. +and the header field value are represented as string literals using an +instruction that begins with the '01' two-bit pattern. -The name is represented as a 6-bit prefix string literal, while the value is -represented as an 8-bit prefix string literal. +This is followed by the name represented as a 6-bit prefix string literal, and +the value represented as an 8-bit prefix string literal (see +{{string-literals}}). ~~~~~~~~~~ drawing 0 1 2 3 4 5 6 7 @@ -730,8 +729,9 @@ represented as an 8-bit prefix string literal. ### Duplicate {#duplicate} An encoder duplicates an existing entry in the dynamic table using an -instruction that starts with the '000' three-bit pattern. The relative index of -the existing entry is represented as an integer with a 5-bit prefix. +instruction that begins with the '000' three-bit pattern. This is followed by +the relative index of the existing entry represented as an integer with a 5-bit +prefix (see {{prefixed-integers}}. ~~~~~~~~~~ drawing 0 1 2 3 4 5 6 7 @@ -762,10 +762,12 @@ This section specifies the following decoder instructions. After processing a header block whose declared Required Insert Count is not zero, the decoder emits a Header Acknowledgement instruction. The instruction -begins with the '1' one-bit pattern and includes the header block's associated -stream ID, encoded as a 7-bit prefix integer. It is used by the peer's encoder -to know when it is safe to evict an entry ({{blocked-insertion}}), and possibly -update the Known Received Count ({{known-received-count}}). +begins with the '1' one-bit pattern which is followed by the header block's +associated stream ID encoded as a 7-bit prefix integer (see +{{prefixed-integers}}). + +This instruction is used as described in {{known-received-count}} and +in {{state-synchronization}}. ~~~~~~~~~~ drawing 0 1 2 3 4 5 6 7 @@ -785,8 +787,10 @@ already been acknowledged, that MUST be treated as a connection error of type When a stream is reset or reading is abandoned, the decoder emits a Stream Cancellation instruction. The instruction begins with the '01' two-bit -pattern. The instruction includes the stream ID of the affected stream encoded -as a 6-bit prefix integer. See {{state-synchronization}}. +pattern, which is followed by the stream ID of the affected stream encoded as a +6-bit prefix integer. + +This instruction is used as described in {{state-synchronization}}. ~~~~~~~~~~ drawing 0 1 2 3 4 5 6 7 @@ -798,13 +802,14 @@ as a 6-bit prefix integer. See {{state-synchronization}}. ### Insert Count Increment -The Insert Count Increment instruction begins with the '00' two-bit pattern. -The instruction specifies the total number of dynamic table inserts and -duplications since the last Insert Count Increment or Header Acknowledgement -that increased the Known Received Count for the dynamic table (see -{{known-received-count}}). The Increment field is encoded as a 6-bit prefix -integer. The encoder uses this value to determine which table entries might -cause a stream to become blocked, as described in {{state-synchronization}}. +The Insert Count Increment instruction begins with the '00' two-bit pattern, +followed by the Increment encoded as a 6-bit prefix integer. The value of the +Increment is the total number of dynamic table insertions and duplications +processed by the decoder since the last time it sent a Header Acknowledgement +instruction that increased the Known Received Count (see +{{known-received-count}}) or an Insert Count Increment instruction. The encoder +uses this value to update the Known Received Count, as described in +{{state-synchronization}}. ~~~~~~~~~~ drawing 0 1 2 3 4 5 6 7 @@ -819,12 +824,13 @@ the Known Received Count beyond what the encoder has sent MUST treat this as a connection error of type `HTTP_QPACK_DECODER_STREAM_ERROR`. -## Header Block Representations +## Header Block Instructions -Header blocks contain compressed representations of header lists and are carried -in frames on streams defined by the enclosing protocol. These representations -reference the static table, or dynamic table in a particular state without -modifying it. +A header block is a compressed representation of a header list and is carried +in frames on streams defined by the enclosing protocol. Each header block +consists of a prefix and a possibly empty sequence of instructions defined in +this section. These instructions can reference the static table, or the dynamic +table in a particular state without modifying it. ### Header Block Prefix {#header-prefix} @@ -966,10 +972,10 @@ decoded header list, as described in Section 3.2 of [RFC7541]. {: title="Indexed Header Field"} If the entry is in the static table, or in the dynamic table with an absolute -index less than the Base, this representation starts with the '1' 1-bit pattern, +index less than the Base, this instruction begins with the '1' 1-bit pattern, followed by the `S` bit indicating whether the reference is into the static or -dynamic table. The 6-bit prefix integer (see Section 5.1 of [RFC7541]) that -follows is used to locate the table entry for the header name. When S=1, the +dynamic table. The 6-bit prefix integer (see {{prefixed-integers}}) that +follows is used to locate the table entry for the header field. When S=1, the number represents the static table index; when S=0, the number is the relative index of the entry in the dynamic table. @@ -977,10 +983,9 @@ index of the entry in the dynamic table. ### Indexed Header Field With Post-Base Index If the entry is in the dynamic table with an absolute index greater than or -equal to the Base, the representation starts with the '0001' 4-bit pattern, +equal to the Base, the instruction begins with the '0001' 4-bit pattern, followed by the post-base index (see {{post-base}}) of the matching header -field, represented as an integer with a 4-bit prefix (see Section 5.1 of -[RFC7541]). +field, represented as an integer with a 4-bit prefix (see {{prefixed-integers}}). ~~~~~~~~~~ drawing 0 1 2 3 4 5 6 7 @@ -998,20 +1003,14 @@ header field name matches the header field name of an entry stored in the static table or the dynamic table. If the entry is in the static table, or in the dynamic table with an absolute -index less than the Base, this representation starts with the '01' two-bit +index less than the Base, this instruction begins with the '01' two-bit pattern. -Only the header field name stored in the static or dynamic table is used. Any -header field value MUST be ignored. - The following bit, 'N', indicates whether an intermediary is permitted to add this header to the dynamic header table on subsequent hops. When the 'N' bit is -set, the encoded header MUST always be encoded with a literal representation. In -particular, when a peer sends a header field that it received represented as a -literal header field with the 'N' bit set, it MUST use a literal representation -to forward this header field. This bit is intended for protecting header field -values that are not to be put at risk by compressing them (see Section 7.1 of -[RFC7541] for more details). +set, the encoded header MUST always be encoded with a literal representation. +This bit is intended for protecting header field values that are not to be put +at risk by compressing them (see {{security-considerations}} for more details). ~~~~~~~~~~ drawing 0 1 2 3 4 5 6 7 @@ -1026,20 +1025,21 @@ values that are not to be put at risk by compressing them (see Section 7.1 of {: title="Literal Header Field With Name Reference"} The fourth (`S`) bit indicates whether the reference is to the static or dynamic -table. The 4-bit prefix integer (see Section 5.1 of [RFC7541]) that follows is +table. The 4-bit prefix integer (see {{prefixed-integers}}) that follows is used to locate the table entry for the header name. When S=1, the number represents the static table index; when S=0, the number is the relative index of -the entry in the dynamic table. +the entry in the dynamic table. Only the header field name stored in the static +or dynamic table is used. Any header field value MUST be ignored. ### Literal Header Field With Post-Base Name Reference If the name entry is in the dynamic table with an absolute index greater than or -equal to the Base, the representation starts with the '0000' four-bit -pattern. The fifth bit is the 'N' bit as described in -{{literal-name-reference}}. Finally, the header field name is represented using -the post-base index of that entry (see {{post-base}}) encoded as an integer with -a 3-bit prefix. +equal to the Base, the instruction begins with the '0000' four-bit pattern. The +fifth bit is the 'N' bit as described in {{literal-name-reference}}. Finally, +the header field name is represented using the post-base index of that entry +(see {{post-base}}) encoded as an integer with a 3-bit prefix (see +{{prefixed-integers}}). ~~~~~~~~~~ drawing 0 1 2 3 4 5 6 7 @@ -1056,21 +1056,14 @@ a 3-bit prefix. ### Literal Header Field Without Name Reference -An addition to the header table where both the header field name and the header -field value are represented as string literals (see {{primitives}}) starts with -the '001' three-bit pattern. - -The fourth bit, 'N', indicates whether an intermediary is permitted to add this -header to the dynamic header table on subsequent hops. When the 'N' bit is set, -the encoded header MUST always be encoded with a literal representation. In -particular, when a peer sends a header field that it received represented as a -literal header field with the 'N' bit set, it MUST use a literal representation -to forward this header field. This bit is intended for protecting header field -values that are not to be put at risk by compressing them (see Section 7.1 of -[RFC7541] for more details). - -The name is represented as a 4-bit prefix string literal, while the value is -represented as an 8-bit prefix string literal. +The literal header field without name reference instruction represents a header +field where both the header field name and the header field value are +encoded as string literals (see {{primitives}}). + +This instruction begins with the '001' three-bit pattern. The fourth bit is the +'N' bit as described in {{literal-name-reference}}. The name follows, +represented as a 4-bit prefix string literal, then the value, represented as an +8-bit prefix string literal (see {{string-literals}}). ~~~~~~~~~~ drawing 0 1 2 3 4 5 6 7