GOAWAY

An endpoint sends a GOAWAY message on its control stream to inform the peer it intends to close the session soon. When sent by a server, it can initiate session migration (Section 3.6) with an optional URI. A client MUST send a zero-length New Session URI in any GOAWAY, as clients cannot instruct servers to initiate connections.

A GOAWAY MAY also be sent on a request stream to initiate migration of that individual request. Upon receiving a GOAWAY on a request stream, the endpoint SHOULD re-issue that specific request on a session at the specified URI (or the current session if no URI is provided), and close the old request stream using the appropriate mechanism (e.g. FIN, stream reset, or PUBLISH_DONE).

The GOAWAY message does not impact subscription state. A subscriber SHOULD individually UNSUBSCRIBE for each existing subscription, while a publisher MAY reject new requests after sending a GOAWAY.

Upon receiving a GOAWAY on the control stream, an endpoint SHOULD NOT initiate new requests to the peer including SUBSCRIBE, PUBLISH, FETCH, PUBLISH_NAMESPACE, SUBSCRIBE_NAMESPACE, SUBSCRIBE_TRACKS and TRACK_STATUS.

Sending a GOAWAY does not prevent the sender from initiating new requests, though the sender SHOULD avoid initiating requests unless required by migration (see (Section 9.4.1 and Section 9.5.1). An endpoint that receives a GOAWAY MAY reject new requests with an appropriate error code (e.g., REQUEST_ERROR with error code GOING_AWAY).

The endpoint MUST close the session with a PROTOCOL_VIOLATION (Section 3.5) if it receives more than one GOAWAY on the control stream or on a single request stream.

GOAWAY Message {
  Type (vi64) = 0x10,
  Length (16),
  New Session URI Length (vi64),
  New Session URI (..),
  Timeout (vi64),
  [Request ID (vi64)],
}

• New Session URI: When received by a client, indicates where the client can connect to continue this session or re-issue this request. The client MUST use this URI for the new session if provided. If the URI is zero bytes long, the current URI is reused instead. The new session URI SHOULD use the same scheme as the current URI to ensure compatibility. The maximum length of the New Session URI is 8,192 bytes. If an endpoint receives a length exceeding the maximum, it MUST close the session with a PROTOCOL_VIOLATION.

  If a server receives a GOAWAY with a non-zero New Session URI Length it MUST close the session with a PROTOCOL_VIOLATION.

• Timeout: The time in milliseconds the sender will wait for graceful closure. When sent on the control stream, the sender closes the session with GOAWAY_TIMEOUT after the indicated timeout if there are still open requests. When sent on a request stream, the sender SHOULD reset the stream with GOING_AWAY after the indicated timeout. A value of 0 indicates the sender has no specific timeout, but the recipient SHOULD migrate as quickly as possible. This is a hint; the sender of the GOAWAY MAY close the session or reset the request stream before the indicated timeout has elapsed.

• Request ID: Present only when sent on the control stream. The smallest peer Request ID that was not or might not have been processed prior to sending the GOAWAY. If no requests have been processed, this is 0 (at a server) or 1 (at a client). If the parity of the Request ID does not match the receiver's parity, the endpoint MUST close the session with INVALID_REQUEST_ID. Requests with a Request ID equal to or greater than the indicated value, as well as any requests that arrive after the GOAWAY, MUST be rejected with REQUEST_ERROR using error code GOING_AWAY. Requests with a Request ID less than the indicated value were or might have been processed; their status can be determined from the response on each request stream.