Draft: draft-ietf-quic-qpack

Commentary: A stylistic change primarily . We 've used the semi - colon form elsewhere .
Paragraph (version A):
Like HPACK, QPACK uses two tables for associating header fields to
indices.  The static table (see header-table-static) is predefined
and contains common header fields (some of them with an empty value).
The dynamic table (see header-table-dynamic) is built up over the
course of the connection and can be used by the encoder to index
header fields in the encoded header lists.
Paragraph (version B):
Like HPACK, QPACK uses two tables for associating header fields to
indices.  The static table (header-table-static) is predefined and
contains common header fields (some of them with an empty value).
The dynamic table (header-table-dynamic) is built up over the course
of the connection and can be used by the encoder to index header
fields in the encoded header lists.
Paragraph (version A):
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.
Paragraph (version B):
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.
Paragraph (version A):
An encoder MUST ensure that a header block which references a dynamic
table entry is not processed by the decoder after the referenced
entry has been evicted.  Hence the encoder needs to retain
information about each compressed header block that references the
dynamic table until that header block is acknowledged by the decoder
(see header-acknowledgement).
Paragraph (version B):
An encoder MUST ensure that a header block which references a dynamic
table entry is not processed by the decoder after the referenced
entry has been evicted.  Hence the encoder needs to retain
information about each compressed header block that references the
dynamic table until that header block is acknowledged by the decoder;
see header-acknowledgement.
Paragraph (version A):
To ensure that the encoder is not prevented from adding new entries,
the encoder can avoid referencing entries that are close to eviction.
Rather than reference such an entry, the encoder can emit a Duplicate
instruction (see duplicate), and reference the duplicate instead.
Paragraph (version A):
Determining which entries are too close to eviction to reference is
an encoder preference.  One heuristic is to target a fixed amount of
available space in the dynamic table: either unused space or space
that can be reclaimed by evicting non-blocking entries.  To achieve
this, the encoder can maintain a draining index, which is the
smallest absolute index (see indexing) in the dynamic table that it
will emit a reference for.  As new entries are inserted, the encoder
increases the draining index to maintain the section of the table
that it will not reference.  If the encoder does not create new
references to entries with an absolute index lower than the draining
index, the number of unacknowledged references to those entries will
eventually become zero, allowing them to be evicted.
Paragraph (version B):
To ensure that the encoder is not prevented from adding new entries,
the encoder can avoid referencing entries that are close to eviction.
Rather than reference such an entry, the encoder can emit a Duplicate
instruction (duplicate), and reference the duplicate instead.
Paragraph (version B):
Determining which entries are too close to eviction to reference is
an encoder preference.  One heuristic is to target a fixed amount of
available space in the dynamic table: either unused space or space
that can be reclaimed by evicting non-blocking entries.  To achieve
this, the encoder can maintain a draining index, which is the
smallest absolute index (indexing) in the dynamic table that it will
emit a reference for.  As new entries are inserted, the encoder
increases the draining index to maintain the section of the table
that it will not reference.  If the encoder does not create new
references to entries with an absolute index lower than the draining
index, the number of unacknowledged references to those entries will
eventually become zero, allowing them to be evicted.
Paragraph (version A):
Each header block contains a Required Insert Count (see header-
prefix), the lowest possible value for the Insert Count with which
the header block can be decoded.  For a header block with references
to the dynamic table, the Required Insert Count is one larger than
the largest absolute index of all referenced dynamic table entries.
For a header block with no references to the dynamic table, the
Required Insert Count is zero.
Paragraph (version A):
When the decoder receives a header block with a Required Insert Count
greater than its own Insert Count, the stream cannot be processed
immediately, and is considered "blocked" (see blocked-decoding).
Paragraph (version A):
The decoder specifies an upper bound on the number of streams which
can be blocked using the SETTINGS_QPACK_BLOCKED_STREAMS setting (see
configuration).  An encoder MUST limit the number of streams which
could become blocked to the value of SETTINGS_QPACK_BLOCKED_STREAMS
at all times.  If a decoder encounters more blocked streams than it
promised to support, it MUST treat this as a connection error of type
HTTP_QPACK_DECOMPRESSION_FAILED.
Paragraph (version B):
Each header block contains a Required Insert Count (header-prefix),
the lowest possible value for the Insert Count with which the header
block can be decoded.  For a header block with references to the
dynamic table, the Required Insert Count is one larger than the
largest absolute index of all referenced dynamic table entries.  For
a header block with no references to the dynamic table, the Required
Insert Count is zero.
Paragraph (version B):
When the decoder receives a header block with a Required Insert Count
greater than its own Insert Count, the stream cannot be processed
immediately, and is considered "blocked"; see blocked-decoding.
Paragraph (version B):
The decoder specifies an upper bound on the number of streams which
can be blocked using the SETTINGS_QPACK_BLOCKED_STREAMS setting; see
configuration.  An encoder MUST limit the number of streams which
could become blocked to the value of SETTINGS_QPACK_BLOCKED_STREAMS
at all times.  If a decoder encounters more blocked streams than it
promised to support, it MUST treat this as a connection error of type
HTTP_QPACK_DECOMPRESSION_FAILED.
Paragraph (version A):
When processing header blocks, the decoder expects the Required
Insert Count to exactly match the value defined in blocked-streams.
If it encounters a smaller value than expected, it MUST treat this as
a connection error of type HTTP_QPACK_DECOMPRESSION_FAILED (see
invalid-references).  If it encounters a larger value than expected,
it MAY treat this as a connection error of type
HTTP_QPACK_DECOMPRESSION_FAILED.
Paragraph (version B):
When processing header blocks, the decoder expects the Required
Insert Count to exactly match the value defined in blocked-streams.
If it encounters a smaller value than expected, it MUST treat this as
a connection error of type HTTP_QPACK_DECOMPRESSION_FAILED; see
invalid-references.  If it encounters a larger value than expected,
it MAY treat this as a connection error of type
HTTP_QPACK_DECOMPRESSION_FAILED.
Paragraph (version A):
When an endpoint receives a stream reset before the end of a stream
or before all header blocks are processed on that stream, or when it
abandons reading of a stream, it generates a Stream Cancellation
instruction (see stream-cancellation).  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 capacity equal
to zero (see maximum-dynamic-table-capacity) 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.
Paragraph (version A):
The Header Acknowledgement and Stream Cancellation instructions
permit the encoder to remove references to entries in the dynamic
table.  When an entry with absolute index lower than the Known
Received Count has zero references, then it is considered evictable
(see blocked-insertion).
Paragraph (version A):
After receiving new table entries on the encoder stream, the decoder
chooses when to emit Insert Count Increment instructions (see insert-
count-increment).  Emitting this instruction after adding each new
dynamic table entry will provide the timeliest feedback to the
encoder, but could be redundant with other decoder feedback.  By
delaying an Insert Count Increment instruction, the decoder might be
able to coalesce multiple Insert Count Increment instructions, or
replace them entirely with Header Acknowledgements (see header-
acknowledgement).  However, delaying too long may lead to compression
inefficiencies if the encoder waits for an entry to be acknowledged
before using it.
Paragraph (version B):
When an endpoint receives a stream reset before the end of a stream
or before all header blocks are processed on that stream, or when it
abandons reading of a stream, it generates a Stream Cancellation
instruction; see stream-cancellation.  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 capacity
(maximum-dynamic-table-capacity) equal to zero 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.
Paragraph (version B):
The Header Acknowledgement and Stream Cancellation instructions
permit the encoder to remove references to entries in the dynamic
table.  When an entry with absolute index lower than the Known
Received Count has zero references, then it is considered evictable;
see blocked-insertion.
Paragraph (version B):
After receiving new table entries on the encoder stream, the decoder
chooses when to emit Insert Count Increment instructions; see insert-
count-increment.  Emitting this instruction after adding each new
dynamic table entry will provide the timeliest feedback to the
encoder, but could be redundant with other decoder feedback.  By
delaying an Insert Count Increment instruction, the decoder might be
able to coalesce multiple Insert Count Increment instructions, or
replace them entirely with Header Acknowledgements; see header-
acknowledgement.  However, delaying too long may lead to compression
inefficiencies if the encoder waits for an entry to be acknowledged
before using it.
Paragraph (version A):
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".
Paragraph (version B):
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 (header-prefix), it MUST treat this as
a connection error of type "HTTP_QPACK_DECOMPRESSION_FAILED".
Paragraph (version A):
The dynamic table consists of a list of header fields maintained in
first-in, first-out order.  Each HTTP/3 endpoint holds a dynamic
table that is initially empty.  Entries are added by encoder
instructions received on the encoder stream (see encoder-
instructions).
Paragraph (version B):
The dynamic table consists of a list of header fields maintained in
first-in, first-out order.  Each HTTP/3 endpoint holds a dynamic
table that is initially empty.  Entries are added by encoder
instructions received on the encoder stream; see encoder-
instructions.
Paragraph (version A):
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 (table capacity - size of new entry).  The
encoder MUST NOT cause a dynamic table entry to be evicted unless
that entry is evictable (see blocked-insertion).  The new entry is
then added to the table.  It is an error if the encoder attempts to
add an entry that is larger than the dynamic table capacity; the
decoder MUST treat this as a connection error of type
"HTTP_QPACK_ENCODER_STREAM_ERROR".
Paragraph (version B):
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 (table capacity - size of new entry).  The
encoder MUST NOT cause a dynamic table entry to be evicted unless
that entry is evictable; see blocked-insertion.  The new entry is
then added to the table.  It is an error if the encoder attempts to
add an entry that is larger than the dynamic table capacity; the
decoder MUST treat this as a connection error of type
"HTTP_QPACK_ENCODER_STREAM_ERROR".
Paragraph (version A):
Whenever the dynamic table capacity is reduced by the encoder (see
set-dynamic-capacity), 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 table capacity.  This mechanism can be used to
completely clear entries from the dynamic table by setting a capacity
of 0, which can subsequently be restored.
Paragraph (version A):
To bound the memory requirements of the decoder, the decoder limits
the maximum value the encoder is permitted to set for the dynamic
table capacity.  In HTTP/3, this limit is determined by the value of
SETTINGS_QPACK_MAX_TABLE_CAPACITY sent by the decoder (see
configuration).  The encoder MUST not set a dynamic table capacity
that exceeds this maximum, but it can choose to use a lower dynamic
table capacity (see set-dynamic-capacity).
Paragraph (version B):
Whenever the dynamic table capacity is reduced by the encoder (set-
dynamic-capacity), 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 table capacity.  This mechanism can be used to completely
clear entries from the dynamic table by setting a capacity of 0,
which can subsequently be restored.
Paragraph (version B):
To bound the memory requirements of the decoder, the decoder limits
the maximum value the encoder is permitted to set for the dynamic
table capacity.  In HTTP/3, this limit is determined by the value of
SETTINGS_QPACK_MAX_TABLE_CAPACITY sent by the decoder; see
configuration.  The encoder MUST not set a dynamic table capacity
that exceeds this maximum, but it can choose to use a lower dynamic
table capacity; see set-dynamic-capacity.
Paragraph (version A):
In encoder instructions (see encoder-instructions), a relative index
of "0" refers to the most recently inserted value in the dynamic
table.  Note that this means the entry referenced by a given relative
index will change while interpreting instructions on the encoder
stream.
Paragraph (version A):
Unlike in encoder instructions, relative indices in header block
representations 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.
Paragraph (version B):
In encoder instructions (encoder-instructions), a relative index of
"0" refers to the most recently inserted value in the dynamic table.
Note that this means the entry referenced by a given relative index
will change while interpreting instructions on the encoder stream.
Paragraph (version B):
Unlike in encoder instructions, relative indices in header block
representations 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.
Paragraph (version A):
An encoder informs the decoder of a change to the dynamic table
capacity using 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).
Paragraph (version A):
The new capacity MUST be lower than or equal to the limit described
in maximum-dynamic-table-capacity.  In HTTP/3, this limit is the
value of the SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter (see
configuration) received from the decoder.  The decoder MUST treat a
new dynamic table capacity value that exceeds this limit as a
connection error of type "HTTP_QPACK_ENCODER_STREAM_ERROR".
Paragraph (version A):
Reducing the dynamic table capacity can cause entries to be evicted
(see eviction).  This MUST NOT cause the eviction of entries which
are not evictable (see blocked-insertion).  Changing the capacity of
the dynamic table is not acknowledged as this instruction does not
insert an entry.
Paragraph (version B):
An encoder informs the decoder of a change to the dynamic table
capacity using 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.
Paragraph (version B):
The new capacity MUST be lower than or equal to the limit described
in maximum-dynamic-table-capacity.  In HTTP/3, this limit is the
value of the SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter
(configuration) received from the decoder.  The decoder MUST treat a
new dynamic table capacity value that exceeds this limit as a
connection error of type "HTTP_QPACK_ENCODER_STREAM_ERROR".
Paragraph (version B):
Reducing the dynamic table capacity can cause entries to be evicted;
see eviction.  This MUST NOT cause the eviction of entries which are
not evictable; see blocked-insertion.  Changing the capacity of the
dynamic table is not acknowledged as this instruction does not insert
an entry.
Paragraph (version A):
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 ('T') bit indicates whether the
reference is to the static or dynamic table.  The 6-bit prefix
integer (see prefixed-integers) that follows is used to locate the
table entry for the header name.  When T=1, the number represents the
static table index; when T=0, the number is the relative index of the
entry in the dynamic table.
Paragraph (version A):
The header name reference is followed by the header field value
represented as a string literal (see string-literals).
Paragraph (version B):
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 ('T') bit indicates whether the
reference is to the static or dynamic table.  The 6-bit prefix
integer (prefixed-integers) that follows is used to locate the table
entry for the header name.  When T=1, the number represents the
static table index; when T=0, the number is the relative index of the
entry in the dynamic table.
Paragraph (version B):
The header name reference is followed by the header field value
represented as a string literal; see string-literals.
Paragraph (version A):
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).
Paragraph (version A):
An encoder duplicates an existing entry in the dynamic table using an
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.
Paragraph (version B):
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.
Paragraph (version B):
An encoder duplicates an existing entry in the dynamic table using an
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.
Paragraph (version A):
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 which is followed
by the header block's associated stream ID encoded as a 7-bit prefix
integer (see prefixed-integers).
Paragraph (version B):
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 which is followed
by the header block's associated stream ID encoded as a 7-bit prefix
integer; see prefixed-integers.
Paragraph (version A):
The Insert Count Increment instruction begins with the '00' two-bit
pattern, followed by the Increment encoded as a 6-bit prefix integer.
This instruction increases the Known Received Count (see known-
received-count) by the value of the Increment parameter.  The decoder
should send an Increment value that increases the Known Received
Count to the total number of dynamic table insertions and
duplications processed so far.
Paragraph (version B):
The Insert Count Increment instruction begins with the '00' two-bit
pattern, followed by the Increment encoded as a 6-bit prefix integer.
This instruction increases the Known Received Count (known-received-
count) by the value of the Increment parameter.  The decoder should
send an Increment value that increases the Known Received Count to
the total number of dynamic table insertions and duplications
processed so far.
Paragraph (version A):
Each header block is prefixed with two integers.  The Required Insert
Count is encoded as an integer with an 8-bit prefix after the
encoding described in ric).  The Base is encoded as a sign bit ('S')
and a Delta Base value with a 7-bit prefix (see base).
Paragraph (version B):
Each header block is prefixed with two integers.  The Required Insert
Count is encoded as an integer with an 8-bit prefix after the
encoding described in ric).  The Base is encoded as a sign bit ('S')
and a Delta Base value with a 7-bit prefix; see base.
Paragraph (version A):
"MaxTableCapacity" is the maximum capacity of the dynamic table as
specified by the decoder (see maximum-dynamic-table-capacity).
Paragraph (version B):
"MaxTableCapacity" is the maximum capacity of the dynamic table as
specified by the decoder; see maximum-dynamic-table-capacity.
Paragraph (version A):
This representation starts with the '1' 1-bit pattern, followed by
the 'T' bit indicating whether the reference is into the static or
dynamic table.  The 6-bit prefix integer (see prefixed-integers) that
follows is used to locate the table entry for the header field.  When
T=1, the number represents the static table index; when T=0, the
number is the relative index of the entry in the dynamic table.
Paragraph (version B):
This representation starts with the '1' 1-bit pattern, followed by
the 'T' bit indicating whether the reference is into the static or
dynamic table.  The 6-bit prefix integer (prefixed-integers) that
follows is used to locate the table entry for the header field.  When
T=1, the number represents the static table index; when T=0, the
number is the relative index of the entry in the dynamic table.
Paragraph (version A):
This representation starts with the '0001' 4-bit pattern.  This is
followed by the post-base index (see post-base) of the matching
header field, represented as an integer with a 4-bit prefix (see
prefixed-integers).
Paragraph (version B):
This representation starts with the '0001' 4-bit pattern.  This is
followed by the post-base index (post-base) of the matching header
field, represented as an integer with a 4-bit prefix; see prefixed-
integers.
Paragraph (version A):
This representation starts with the '01' two-bit pattern.  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
security-considerations for more details).
Paragraph (version A):
The fourth ('T') bit indicates whether the reference is to the static
or dynamic table.  The 4-bit prefix integer (see prefixed-integers)
that follows is used to locate the table entry for the header name.
When T=1, the number represents the static table index; when T=0, the
number is the relative index of the entry in the dynamic table.
Paragraph (version B):
This representation starts with the '01' two-bit pattern.  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
security-considerations for more details.
Paragraph (version B):
The fourth ('T') bit indicates whether the reference is to the static
or dynamic table.  The 4-bit prefix integer (prefixed-integers) that
follows is used to locate the table entry for the header name.  When
T=1, the number represents the static table index; when T=0, the
number is the relative index of the entry in the dynamic table.
Paragraph (version A):
This representation starts with the '0000' four-bit pattern.  The
fifth bit is the 'N' bit as described in literal-name-reference.
This is followed by a post-base index of the dynamic table entry (see
post-base) encoded as an integer with a 3-bit prefix (see prefixed-
integers).
Paragraph (version B):
This representation starts with the '0000' four-bit pattern.  The
fifth bit is the 'N' bit as described in literal-name-reference.
This is followed by a post-base index of the dynamic table entry
(post-base) encoded as an integer with a 3-bit prefix; see prefixed-
integers.
Paragraph (version A):
This representation 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).
Paragraph (version B):
This representation 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.