diff --git a/rfc9114.md b/rfc9114.md index 0079b4607c..2b56d3e579 100644 --- a/rfc9114.md +++ b/rfc9114.md @@ -895,33 +895,33 @@ indicated request. This trades off network usage against a potential latency gain. HTTP/3 server push is similar to what is described in {{Section 8.2 of HTTP2}}, but it uses different mechanisms. -Each server push is assigned a unique Push ID by the server. The Push ID is +Each server push is assigned a unique push ID by the server. The push ID is used to refer to the push in various contexts throughout the lifetime of the HTTP/3 connection. -The Push ID space begins at zero and ends at a maximum value set by the +The push ID space begins at zero and ends at a maximum value set by the MAX_PUSH_ID frame; see {{frame-max-push-id}}. In particular, a server is not able to push until after the client sends a MAX_PUSH_ID frame. A client sends MAX_PUSH_ID frames to control the number of pushes that a server can promise. A -server SHOULD use Push IDs sequentially, beginning from zero. A client MUST +server SHOULD use push IDs sequentially, beginning from zero. A client MUST treat receipt of a push stream as a connection error of type H3_ID_ERROR ({{errors}}) when no MAX_PUSH_ID frame has been sent or when the stream -references a Push ID that is greater than the maximum Push ID. +references a push ID that is greater than the maximum push ID. -The Push ID is used in one or more PUSH_PROMISE frames ({{frame-push-promise}}) +The push ID is used in one or more PUSH_PROMISE frames ({{frame-push-promise}}) that carry the control data and header fields of the request message. These frames are sent on the request stream that generated the push. This allows the -server push to be associated with a client request. When the same Push ID is +server push to be associated with a client request. When the same push ID is promised on multiple request streams, the decompressed request field sections MUST contain the same fields in the same order, and both the name and the value in each field MUST be identical. -The Push ID is then included with the push stream that ultimately fulfills -those promises; see {{push-streams}}. The push stream identifies the Push ID of +The push ID is then included with the push stream that ultimately fulfills +those promises; see {{push-streams}}. The push stream identifies the push ID of the promise that it fulfills, then contains a response to the promised request as described in {{request-response}}. -Finally, the Push ID can be used in CANCEL_PUSH frames; see +Finally, the push ID can be used in CANCEL_PUSH frames; see {{frame-cancel-push}}. Clients use this frame to indicate they do not wish to receive a promised resource. Servers use this frame to indicate they will not be fulfilling a previous promise. @@ -948,7 +948,7 @@ server authoritative. Any corresponding responses MUST NOT be used or cached. Each pushed response is associated with one or more client requests. The push is associated with the request stream on which the PUSH_PROMISE frame was received. The same server push can be associated with additional client -requests using a PUSH_PROMISE frame with the same Push ID on multiple request +requests using a PUSH_PROMISE frame with the same push ID on multiple request streams. These associations do not affect the operation of the protocol, but they MAY be considered by user agents when deciding how to use pushed resources. @@ -959,7 +959,7 @@ that a client requests a resource that will be pushed by the server. Due to reordering, push stream data can arrive before the corresponding PUSH_PROMISE frame. When a client receives a new push stream with an -as-yet-unknown Push ID, both the associated client request and the pushed +as-yet-unknown push ID, both the associated client request and the pushed request header fields are unknown. The client can buffer the stream data in expectation of the matching PUSH_PROMISE. The client can use stream flow control ({{Section 4.1 of QUIC-TRANSPORT}}) to limit the amount of data a server may @@ -1013,8 +1013,8 @@ connection and initiate a graceful connection close. Endpoints initiate the graceful shutdown of an HTTP/3 connection by sending a GOAWAY frame ({{frame-goaway}}). The GOAWAY frame contains an identifier that indicates to the receiver the range of requests or pushes that were or might be processed in -this connection. The server sends a client-initiated bidirectional Stream ID; -the client sends a Push ID ({{server-push}}). Requests or pushes with the +this connection. The server sends a client-initiated bidirectional stream ID; +the client sends a push ID ({{server-push}}). Requests or pushes with the indicated identifier or greater are rejected ({{request-cancellation}}) by the sender of the GOAWAY. This identifier MAY be zero if no requests or pushes were processed. @@ -1034,22 +1034,22 @@ connection to send additional requests. Some requests or pushes might already be in transit: - Upon receipt of a GOAWAY frame, if the client has already sent requests with - a Stream ID greater than or equal to the identifier contained in the GOAWAY + a stream ID greater than or equal to the identifier contained in the GOAWAY frame, those requests will not be processed. Clients can safely retry unprocessed requests on a different HTTP connection. A client that is unable to retry requests loses all requests that are in flight when the server closes the connection. - Requests on Stream IDs less than the Stream ID in a GOAWAY frame from the + Requests on stream IDs less than the stream ID in a GOAWAY frame from the server might have been processed; their status cannot be known until a response is received, the stream is reset individually, another GOAWAY is - received with a lower Stream ID than that of the request in question, + received with a lower stream ID than that of the request in question, or the connection terminates. Servers MAY reject individual requests on streams below the indicated ID if these requests were not processed. - - If a server receives a GOAWAY frame after having promised pushes with a Push + - If a server receives a GOAWAY frame after having promised pushes with a push ID greater than or equal to the identifier contained in the GOAWAY frame, those pushes will not be accepted. @@ -1076,12 +1076,12 @@ or pushes to arrive, the endpoint can send another GOAWAY frame indicating which requests or pushes it might accept before the end of the connection. This ensures that a connection can be cleanly shut down without losing requests. -A client has more flexibility in the value it chooses for the Push ID in a +A client has more flexibility in the value it chooses for the Push ID field in a GOAWAY that it sends. A value of 262-1 indicates that the server can continue fulfilling pushes that have already been promised. A smaller value -indicates the client will reject pushes with Push IDs greater than or equal to +indicates the client will reject pushes with push IDs greater than or equal to this value. Like the server, the client MAY send subsequent GOAWAY frames so -long as the specified Push ID is no greater than any previously sent value. +long as the specified push ID is no greater than any previously sent value. Even when a GOAWAY indicates that a given request or push will not be processed or accepted upon receipt, the underlying transport resources still exist. The @@ -1261,12 +1261,12 @@ Server push is an optional feature introduced in HTTP/2 that allows a server to initiate a response before a request has been made. See {{server-push}} for more details. -A push stream is indicated by a stream type of 0x01, followed by the Push ID +A push stream is indicated by a stream type of 0x01, followed by the push ID of the promise that it fulfills, encoded as a variable-length integer. The remaining data on this stream consists of HTTP/3 frames, as defined in {{frames}}, and fulfills a promised server push by zero or more interim HTTP responses followed by a single final HTTP response, as defined in -{{request-response}}. Server push and Push IDs are described in +{{request-response}}. Server push and push IDs are described in {{server-push}}. Only servers can push; if a server receives a client-initiated push stream, this @@ -1281,12 +1281,12 @@ Push Stream Header { ~~~~~~~~~~ {: title="Push Stream Header"} -A client SHOULD NOT abort reading on a push stream prior to reading the Push ID, -as this could lead to disagreement between client and server on which Push IDs -have already been consumed. +A client SHOULD NOT abort reading on a push stream prior to reading the push +stream header, as this could lead to disagreement between client and server on +which push IDs have already been consumed. -Each Push ID MUST only be used once in a push stream header. If a client detects -that a push stream header includes a Push ID that was used in another push +Each push ID MUST only be used once in a push stream header. If a client detects +that a push stream header includes a push ID that was used in another push stream header, the client MUST treat this as a connection error of type H3_ID_ERROR; see {{errors}}. @@ -1411,7 +1411,7 @@ error of type H3_FRAME_UNEXPECTED; see {{errors}}. The CANCEL_PUSH frame (type=0x03) is used to request cancellation of a server push prior to the push stream being received. The CANCEL_PUSH frame identifies -a server push by Push ID (see {{server-push}}), encoded as a variable-length +a server push by push ID (see {{server-push}}), encoded as a variable-length integer. When a client sends a CANCEL_PUSH frame, it is indicating that it does not wish @@ -1450,15 +1450,15 @@ CANCEL_PUSH Frame { ~~~~~~~~~~ {: title="CANCEL_PUSH Frame"} -The CANCEL_PUSH frame carries a Push ID encoded as a variable-length integer. -The Push ID identifies the server push that is being cancelled; see -{{server-push}}. If a CANCEL_PUSH frame is received that references a Push ID +The CANCEL_PUSH frame carries a push ID encoded as a variable-length integer. +The Push ID field identifies the server push that is being cancelled; see +{{server-push}}. If a CANCEL_PUSH frame is received that references a push ID greater than currently allowed on the connection, this MUST be treated as a connection error of type H3_ID_ERROR. -If the client receives a CANCEL_PUSH frame, that frame might identify a Push ID +If the client receives a CANCEL_PUSH frame, that frame might identify a push ID that has not yet been mentioned by a PUSH_PROMISE frame due to reordering. If a -server receives a CANCEL_PUSH frame for a Push ID that has not yet been +server receives a CANCEL_PUSH frame for a push ID that has not yet been mentioned by a PUSH_PROMISE frame, this MUST be treated as a connection error of type H3_ID_ERROR. @@ -1615,7 +1615,7 @@ PUSH_PROMISE Frame { The payload consists of: Push ID: -: A variable-length integer that identifies the server push operation. A Push +: A variable-length integer that identifies the server push operation. A push ID is used in push stream headers ({{server-push}}) and CANCEL_PUSH frames ({{frame-cancel-push}}). @@ -1623,26 +1623,26 @@ Encoded Field Section: : QPACK-encoded request header fields for the promised response. See {{QPACK}} for more details. -A server MUST NOT use a Push ID that is larger than the client has provided in a +A server MUST NOT use a push ID that is larger than the client has provided in a MAX_PUSH_ID frame ({{frame-max-push-id}}). A client MUST treat receipt of a -PUSH_PROMISE frame that contains a larger Push ID than the client has advertised +PUSH_PROMISE frame that contains a larger push ID than the client has advertised as a connection error of H3_ID_ERROR. -A server MAY use the same Push ID in multiple PUSH_PROMISE frames. If so, the +A server MAY use the same push ID in multiple PUSH_PROMISE frames. If so, the decompressed request header sets MUST contain the same fields in the same order, and both the name and the value in each field MUST be exact matches. Clients SHOULD compare the request header sections for resources promised multiple -times. If a client receives a Push ID that has already been promised and detects +times. If a client receives a push ID that has already been promised and detects a mismatch, it MUST respond with a connection error of type H3_GENERAL_PROTOCOL_ERROR. If the decompressed field sections match exactly, the client SHOULD associate the pushed content with each stream on which a PUSH_PROMISE frame was received. -Allowing duplicate references to the same Push ID is primarily to reduce -duplication caused by concurrent requests. A server SHOULD avoid reusing a Push +Allowing duplicate references to the same push ID is primarily to reduce +duplication caused by concurrent requests. A server SHOULD avoid reusing a push ID over a long period. Clients are likely to consume server push responses and not retain them for reuse over time. Clients that see a PUSH_PROMISE frame that -uses a Push ID that they have already consumed and discarded are forced to +uses a push ID that they have already consumed and discarded are forced to ignore the promise. If a PUSH_PROMISE frame is received on the control stream, the client MUST @@ -1672,12 +1672,12 @@ GOAWAY Frame { {: title="GOAWAY Frame"} The GOAWAY frame is always sent on the control stream. In the server-to-client -direction, it carries a QUIC Stream ID for a client-initiated bidirectional +direction, it carries a QUIC stream ID for a client-initiated bidirectional stream encoded as a variable-length integer. A client MUST treat receipt of a -GOAWAY frame containing a Stream ID of any other type as a connection error of +GOAWAY frame containing a stream ID of any other type as a connection error of type H3_ID_ERROR. -In the client-to-server direction, the GOAWAY frame carries a Push ID encoded as +In the client-to-server direction, the GOAWAY frame carries a push ID encoded as a variable-length integer. The GOAWAY frame applies to the entire connection, not a specific stream. A @@ -1690,7 +1690,7 @@ See {{connection-shutdown}} for more information on the use of the GOAWAY frame. The MAX_PUSH_ID frame (type=0x0d) is used by clients to control the number of server pushes that the server can initiate. This sets the maximum value for a -Push ID that the server can use in PUSH_PROMISE and CANCEL_PUSH frames. +push ID that the server can use in PUSH_PROMISE and CANCEL_PUSH frames. Consequently, this also limits the number of push streams that the server can initiate in addition to the limit maintained by the QUIC transport. @@ -1701,10 +1701,10 @@ type H3_FRAME_UNEXPECTED. A server MUST NOT send a MAX_PUSH_ID frame. A client MUST treat the receipt of a MAX_PUSH_ID frame as a connection error of type H3_FRAME_UNEXPECTED. -The maximum Push ID is unset when an HTTP/3 connection is created, meaning that +The maximum push ID is unset when an HTTP/3 connection is created, meaning that a server cannot push until it receives a MAX_PUSH_ID frame. A client that wishes to manage the number of promised server pushes can increase the maximum -Push ID by sending MAX_PUSH_ID frames as the server fulfills or cancels server +push ID by sending MAX_PUSH_ID frames as the server fulfills or cancels server pushes. ~~~~~~~~~~ ascii-art @@ -1717,8 +1717,8 @@ MAX_PUSH_ID Frame { {: title="MAX_PUSH_ID Frame"} The MAX_PUSH_ID frame carries a single variable-length integer that identifies -the maximum value for a Push ID that the server can use; see {{server-push}}. A -MAX_PUSH_ID frame cannot reduce the maximum Push ID; receipt of a MAX_PUSH_ID +the maximum value for a push ID that the server can use; see {{server-push}}. A +MAX_PUSH_ID frame cannot reduce the maximum push ID; receipt of a MAX_PUSH_ID frame that contains a smaller value than previously received MUST be treated as a connection error of type H3_ID_ERROR. @@ -1809,7 +1809,7 @@ H3_EXCESSIVE_LOAD (0x0107): generating excessive load. H3_ID_ERROR (0x0108): -: A Stream ID or Push ID was used incorrectly, such as exceeding a limit, +: A stream ID or push ID was used incorrectly, such as exceeding a limit, reducing a limit, or being reused. H3_SETTINGS_ERROR (0x0109): @@ -1952,7 +1952,7 @@ state. Settings for these features ensure that memory commitments for these features are strictly bounded. The number of PUSH_PROMISE frames is constrained in a similar fashion. A client -that accepts server push SHOULD limit the number of Push IDs it issues at a +that accepts server push SHOULD limit the number of push IDs it issues at a time. Processing capacity cannot be guarded as effectively as state capacity. @@ -2449,18 +2449,18 @@ subject to flow control. ### Guidance for New Frame Type Definitions Frame type definitions in HTTP/3 often use the QUIC variable-length integer -encoding. In particular, Stream IDs use this encoding, which allows for a +encoding. In particular, stream IDs use this encoding, which allows for a larger range of possible values than the encoding used in HTTP/2. Some frames -in HTTP/3 use an identifier other than a Stream ID (e.g., Push -IDs). Redefinition of the encoding of extension frame types might be necessary -if the encoding includes a Stream ID. +in HTTP/3 use an identifier other than a stream ID (e.g., push IDs). +Redefinition of the encoding of extension frame types might be necessary if the +encoding includes a stream ID. Because the Flags field is not present in generic HTTP/3 frames, those frames that depend on the presence of flags need to allocate space for flags as part of their frame payload. Other than these issues, frame type HTTP/2 extensions are typically portable to -QUIC simply by replacing Stream 0 in HTTP/2 with a control stream in HTTP/3. +QUIC simply by replacing stream 0 in HTTP/2 with a control stream in HTTP/3. HTTP/3 extensions will not assume ordering, but would not be harmed by ordering, and are expected to be portable to HTTP/2. @@ -2488,7 +2488,7 @@ SETTINGS (0x04): PUSH_PROMISE (0x05): : The PUSH_PROMISE frame does not reference a stream; instead, the push stream - references the PUSH_PROMISE frame using a Push ID. See + references the PUSH_PROMISE frame using a push ID. See {{frame-push-promise}}. PING (0x06): @@ -2497,7 +2497,7 @@ PING (0x06): GOAWAY (0x07): : GOAWAY does not contain an error code. In the client-to-server direction, - it carries a Push ID instead of a server-initiated stream ID. + it carries a push ID instead of a server-initiated stream ID. See {{frame-goaway}}. WINDOW_UPDATE (0x08): @@ -2537,7 +2537,7 @@ SETTINGS_ENABLE_PUSH (0x02): SETTINGS frame is an error. SETTINGS_MAX_CONCURRENT_STREAMS (0x03): -: QUIC controls the largest open Stream ID as part of its flow-control logic. +: QUIC controls the largest open stream ID as part of its flow-control logic. Specifying a setting with the identifier 0x03 (corresponding to the SETTINGS_MAX_CONCURRENT_STREAMS parameter) in the HTTP/3 SETTINGS frame is an error.