Merge branch 'master' into abandon-initial

draft-ietf-quic-qpack.md

@@ -32,8 +32,8 @@ author:
 
 normative:
 
-  QUIC-HTTP:
-    title: "Hypertext Transfer Protocol (HTTP) over QUIC"
+  HTTP3:
+    title: "Hypertext Transfer Protocol Version 3 (HTTP/3)"
     date: {DATE}
     seriesinfo:
       Internet-Draft: draft-ietf-quic-http-latest
@@ -65,7 +65,7 @@ normative:
 --- abstract
 
 This specification defines QPACK, a compression format for efficiently
-representing HTTP header fields, to be used in HTTP/QUIC. This is a variation of
+representing HTTP header fields, to be used in HTTP/3. This is a variation of
 HPACK header compression that seeks to reduce head-of-line blocking.
 
 --- note_Note_to_Readers
@@ -87,12 +87,12 @@ semantics, and its design subsumes many of the features of HTTP/2.  HTTP/2 uses
 HPACK ({{!RFC7541}}) for header compression, but QUIC's stream multiplexing
 comes into some conflict with HPACK.  A key goal of the design of QUIC is to
 improve stream multiplexing relative to HTTP/2 by reducing head-of-line
-blocking.  If HPACK were used for HTTP/QUIC, it would induce head-of-line
+blocking.  If HPACK were used for HTTP/3, it would induce head-of-line
 blocking due to built-in assumptions of a total ordering across frames on all
 streams.
 
-QUIC is described in {{QUIC-TRANSPORT}}.  The HTTP/QUIC mapping is described in
-{{QUIC-HTTP}}. For a full description of HTTP/2, see {{?RFC7540}}. The
+QUIC is described in {{QUIC-TRANSPORT}}.  The HTTP/3 mapping is described in
+{{HTTP3}}. For a full description of HTTP/2, see {{?RFC7540}}. The
 description of HPACK is {{!RFC7541}}.
 
 QPACK reuses core concepts from HPACK, but is redesigned to allow correctness in
@@ -364,15 +364,23 @@ 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 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/QUIC, 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/QUIC servers and HTTP/QUIC 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 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.
+
+
+### 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
@@ -390,51 +398,31 @@ 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.
+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.
 
 
 ### 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/QUIC, this value is determined by the
-SETTINGS_HEADER_TABLE_SIZE setting (see {{configuration}}).
+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}}).
 
-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 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}}).
+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}
@@ -677,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.  A value that exceeds this limit MUST be treated as a
-connection error of type `HTTP_QPACK_ENCODER_STREAM_ERROR`.  In HTTP/QUIC, this
-limit is the value of the SETTINGS_HEADER_TABLE_SIZE parameter (see
-{{configuration}}) received from the decoder.
+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.  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
@@ -775,14 +763,14 @@ the stream ID of the affected stream - a request or push stream - encoded as a
 {:#fig-stream-cancel title="Stream Cancellation"}
 
 A stream that is reset might have multiple outstanding header blocks with
-dynamic table references.  When the decoder receives a stream reset before the
+dynamic table references.  When an endpoint receives a stream reset before the
 end of a stream, it generates a Stream Cancellation instruction on the decoder
-stream.  Similarly, when the decoder abandons reading of a stream it needs to
+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.
@@ -821,6 +809,18 @@ zero, the encoder transforms it as follows before encoding:
    LargestReference = (LargestReference mod (2 * MaxEntries)) + 1
 ~~~
 
+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
+decoder (see {{maximum-table-size}}).
+
+
 The decoder reconstructs the Largest Reference using the following algorithm:
 
 ~~~
@@ -858,7 +858,7 @@ indicates that the Base Index is less than the Largest Reference.  That is:
    if sign == 0:
       baseIndex = largestReference + deltaBaseIndex
    else:
-      baseIndex = largestReference - deltaBaseIndex
+      baseIndex = largestReference - deltaBaseIndex - 1
 ~~~
 
 A single-pass encoder determines the absolute value of Base Index before
@@ -870,10 +870,8 @@ not insert any new entries, Base Index will be greater than the Largest
 Reference, so the delta will be positive and the sign bit is set to 0.
 
 An encoder that produces table updates before encoding a header block might set
-Largest Reference and Base Index to the same value.  When Largest Reference and
-Base Index are equal, the Delta Base Index is encoded with a zero sign bit.  A
-sign bit set to 1 when the Delta Base Index is 0 MUST be treated as a decoder
-error.
+Largest Reference and Base Index to the same value.  In such case, both the sign
+bit and the Delta Base Index will be set to zero.
 
 A header block that does not reference the dynamic table can use any value for
 Base Index; setting both Largest Reference and Base Index to zero is the most
@@ -1011,27 +1009,29 @@ represented as an 8-bit prefix string literal.
 
 #  Configuration
 
-QPACK defines two settings which are included in the HTTP/QUIC SETTINGS frame.
+QPACK defines two settings which are included in the HTTP/3 SETTINGS frame.
 
   SETTINGS_HEADER_TABLE_SIZE (0x1):
-  : An integer with a maximum value of 2^30 - 1.  The default value is 4,096
+  : An integer with a maximum value of 2^30 - 1.  The default value is zero
     bytes.  See {{table-dynamic}} for usage.
 
   SETTINGS_QPACK_BLOCKED_STREAMS (0x7):
-  : An integer with a maximum value of 2^16 - 1.  The default value is 100.  See
-    {{overview-hol-avoidance}}.
+  : An integer with a maximum value of 2^16 - 1.  The default value is zero.
+    See {{overview-hol-avoidance}}.
 
 
 # Error Handling {#error-handling}
 
-The following error codes are defined for HTTP/QUIC to indicate failures of
+The following error codes are defined for HTTP/3 to indicate failures of
 QPACK which prevent the stream or connection from continuing:
 
 HTTP_QPACK_DECOMPRESSION_FAILED (TBD):
 : The decoder failed to interpret an instruction on a request or push stream and
   is not able to continue decoding that header block.
+
 HTTP_QPACK_ENCODER_STREAM_ERROR (TBD):
 : The decoder failed to interpret an instruction on the encoder stream.
+
 HTTP_QPACK_DECODER_STREAM_ERROR (TBD):
 : The encoder failed to interpret an instruction on the decoder stream.
 
@@ -1048,8 +1048,8 @@ TBD.
 
 ## Settings Registration
 
-This document creates two new settings in the "HTTP/QUIC Settings" registry
-established in {{QUIC-HTTP}}.
+This document creates two new settings in the "HTTP/3 Settings" registry
+established in {{HTTP3}}.
 
 The entries in the following table are registered by this document.
 
@@ -1062,8 +1062,8 @@ The entries in the following table are registered by this document.
 
 ## Stream Type Registration
 
-This document creates two new settings in the "HTTP/QUIC Stream Type" registry
-established in {{QUIC-HTTP}}.
+This document creates two new settings in the "HTTP/3 Stream Type" registry
+established in {{HTTP3}}.
 
 The entries in the following table are registered by this document.
 
@@ -1076,8 +1076,8 @@ The entries in the following table are registered by this document.
 
 ## Error Code Registration
 
-This document establishes the following new error codes in the "HTTP/QUIC Error
-Code" registry established in {{QUIC-HTTP}}.
+This document establishes the following new error codes in the "HTTP/3 Error
+Code" registry established in {{HTTP3}}.
 
 | --------------------------------- | ----- | ---------------------------------------- | ---------------------- |
 | Name                              | Code  | Description                              | Specification          |
@@ -1252,9 +1252,15 @@ return controlBuffer, prefixBuffer + streamBuffer
 > **RFC Editor's Note:** Please remove this section prior to publication of a
 > final version of this document.
 
+## Since draft-ietf-quic-qpack-04
+
+- Changed calculation of Delta Base Index to avoid an illegal value (#2002,
+  #2005)
+
 ## Since draft-ietf-quic-qpack-03
 
-Substantial editorial reorganization; no technical changes.
+- Change HTTP settings defaults (#2038)
+- Substantial editorial reorganization
 
 ## Since draft-ietf-quic-qpack-02