From 187114796561016e40a562a3bcdd9b2f664c63aa Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 24 Oct 2017 12:19:10 +1100 Subject: [PATCH] Improve GOAWAY description As noted by @hardie in #604, the description of GOAWAY hasn't tracked the changes in the transport. This updates it. Most importantly, it says what to do to finish a graceful shutdown, including the sending of APPLICATION_CLOSE frames. I added a new error code for when the server receives a GOAWAY. I also changed the description to be less generic and use client and server as appropriate. --- draft-ietf-quic-http.md | 41 ++++++++++++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/draft-ietf-quic-http.md b/draft-ietf-quic-http.md index 074a2b8672..92e62ba507 100644 --- a/draft-ietf-quic-http.md +++ b/draft-ietf-quic-http.md @@ -740,14 +740,17 @@ The GOAWAY frame (type=0x7) is used to initiate graceful shutdown of a connection by a server. GOAWAY allows a server to stop accepting new requests while still finishing processing of previously received requests. This enables administrative actions, like server maintenance. GOAWAY by itself does not -close a connection. (Note that clients do not need to send GOAWAY to gracefully -close a connection; they simply stop making new requests.) +close a connection. The GOAWAY frame does not define any flags, and the payload is a QUIC stream identifier. The GOAWAY frame applies to the connection, not a specific stream. -An endpoint MUST treat a GOAWAY frame on a stream other than the control stream +A client MUST treat a GOAWAY frame on a stream other than the control stream as a connection error ({{errors}}) of type HTTP_WRONG_STREAM. +Clients do not need to send GOAWAY to initiate a graceful shutdown; they simply +stop making new requests. A server MUST treat receipt of a GOAWAY frame as a +connection error ({{errors}}) of type HTTP_UNEXPECTED_GOAWAY. + New client requests might already have been sent before the client receives the server's GOAWAY frame. The GOAWAY frame contains the stream identifier of the last client-initiated request that was or might be processed in this connection, @@ -781,7 +784,7 @@ If a stream is cancelled after receiving a complete response, the client MAY ignore the cancellation and use the response. However, if a stream is cancelled after receiving a partial response, the response SHOULD NOT be used. Automatically retrying such requests is not possible, unless this is otherwise -permitted (e.g. idempotent actions like GET, PUT, or DELETE). Requests on +permitted (e.g., idempotent actions like GET, PUT, or DELETE). Requests on stream IDs less than or equal to the stream ID in the GOAWAY frame might have been processed; their status cannot be known until they are completed successfully, reset individually, or the connection terminates. @@ -794,18 +797,23 @@ connection, the client cannot know if the server started to process that POST request if the server does not send a GOAWAY frame to indicate what streams it might have acted on. -For unexpected closures caused by error conditions, a QUIC CONNECTION_CLOSE -frame MUST be used. However, a GOAWAY MAY be sent first to provide additional -detail to clients. If a connection terminates without a GOAWAY frame, the last -stream identifier is effectively the highest possible stream identifier (as -determined by QUIC's MAX_STREAM_ID). +For unexpected closures caused by error conditions, a QUIC CONNECTION_CLOSE or +APPLICATION_CLOSE frame MUST be used. However, a GOAWAY MAY be sent first to +provide additional detail to clients and to allow the client to retry requests. +Including the GOAWAY frame in the same packet as the QUIC CONNECTION_CLOSE or +APPLICATION_CLOSE frame improves the chances of the frame being received by +clients. + +If a connection terminates without a GOAWAY frame, the last stream identifier is +effectively the highest possible stream identifier (as determined by QUIC's +MAX_STREAM_ID). An endpoint MAY send multiple GOAWAY frames if circumstances change. For instance, an endpoint that sends GOAWAY without an error code during graceful shutdown could subsequently encounter an error condition. The last stream identifier from the last GOAWAY frame received indicates which streams could -have been acted upon. Endpoints MUST NOT increase the value they send in the -last stream identifier, since the peers might already have retried unprocessed +have been acted upon. A server MUST NOT increase the value they send in the +last stream identifier, since clients might already have retried unprocessed requests on another connection. A client that is unable to retry requests loses all requests that are in flight @@ -818,6 +826,13 @@ After allowing time for any in-flight requests (at least one round-trip time), the server MAY send another GOAWAY frame with an updated last stream identifier. This ensures that a connection can be cleanly shut down without losing requests. +Once all requests on streams at or below the identified stream number have been +completed or cancelled, and all promised server push responses associated with +those requests have been completed or cancelled, the connection can be closed +using an Immediate Close (see {{QUIC-TRANSPORT}}). An endpoint that completes a +graceful shutdown SHOULD use the QUIC APPLICATION_CLOSE frame with the +HTTP_NO_ERROR code. + ### MAX_PUSH_ID {#frame-max-push-id} @@ -949,6 +964,9 @@ HTTP_MALFORMED_PUSH (0x12): HTTP_MALFORMED_MAX_PUSH_ID (0x13): : A MAX_PUSH_ID frame has been received with an invalid format. +HTTP_UNEXPECTED_GOAWAY (0x14): +: A GOAWAY frame has been received by a server. + # Considerations for Transitioning from HTTP/2 @@ -1326,6 +1344,7 @@ The entries in the following table are registered by this document. | HTTP_MULTIPLE_SETTINGS | 0x11 | Multiple SETTINGS frames | {{http-error-codes}} | | HTTP_MALFORMED_PUSH | 0x12 | Invalid push stream header | {{http-error-codes}} | | HTTP_MALFORMED_MAX_PUSH_ID | 0x13 | Invalid MAX_PUSH_ID frame | {{http-error-codes}} | +| HTTP_UNEXPECTED_GOAWAY | 0x14 | A server received GOAWAY | {{http-error-codes}} | |-----------------------------------|--------|----------------------------------------|----------------------|