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). This allows, for example, moving the publishers and subscribers of a common set of tracks to a common relay without draining their entire session.

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),
}

• 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.