Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

QPACK [editorial] Update text on wire instructions. #2938

Closed
wants to merge 1 commit into from
Closed

QPACK [editorial] Update text on wire instructions. #2938

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
175 changes: 84 additions & 91 deletions draft-ietf-quic-qpack.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

header-blocks is a dangling reference , causing the build failure

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.
Expand Down Expand Up @@ -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
Expand All @@ -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}

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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}

Expand Down Expand Up @@ -966,21 +972,20 @@ 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.


### 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
Expand All @@ -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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sentence starting with "In particular" does not seem to add any value, therefore I propose removing it.

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
Expand All @@ -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
Expand All @@ -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
Expand Down