The SETUP message is the first message each endpoint sends on its control
stream (see Section 3.3); it allows the endpoints to agree on the initial
configuration before any other control messages are exchanged. An endpoint that
is not offering extensions which modify control message semantics MAY pipeline
other control messages after SETUP without waiting for the peer's SETUP.
The messages contain a sequence of key-value pairs called Setup Options; the semantics and format of which can vary based on whether the client or server is sending. To ensure future extensibility of MOQT, endpoints MUST ignore unknown Setup Options.
The wire format of the Setup message is as follows:
SETUP Message {
Type (vi64) = 0x2F00,
Length (16),
Setup Options (..) ...,
}
Setup Options are serialized as Key-Value-Pairs Figure 2, spanning the entire message payload, bounded by the message Length field. Setup Options use a namespace that is constant across all MOQT versions, separate from Message Parameters. Receivers MUST ignore unrecognized Setup Options. Senders MUST NOT repeat the same Option Type in a message unless the option definition explicitly allows multiple instances. Receivers MUST allow duplicates of unknown Setup Options.
The available Setup Options are detailed in the next sections.
10.3.1. Setup Options
10.3.1.2. PATH
The PATH option (Option Type 0x01) allows the client to specify the path
of the MoQ URI when using native QUIC (Section 3.1.5). It MUST NOT be used by
the server, or when WebTransport is used. When a PATH parameter is received
from a server, or when a PATH parameter is received while WebTransport is used,
or when a PATH parameter is received by a server but the server does not
support the specified path, the session MUST be closed with INVALID_PATH.
The PATH option follows the URI formatting rules [RFC3986].
When connecting to a server using a URI with the "moqt" scheme, the
client MUST set the PATH option to the path-abempty portion of the
URI; if query is present, the client MUST concatenate ?, followed by
the query portion of the URI to the option. If a PATH does not conform to
these rules, the session MUST be closed with MALFORMED_PATH.
10.3.1.3. MAX_AUTH_TOKEN_CACHE_SIZE
The MAX_AUTH_TOKEN_CACHE_SIZE option (Option Type 0x04) communicates the maximum size in bytes of all actively registered Authorization tokens that the endpoint is willing to store per Session. This option is optional. The default value is 0 which prohibits the use of token Aliases.
The token size is calculated as 16 bytes + the size of the Token Value field (see Figure 5). The total size as restricted by the MAX_AUTH_TOKEN_CACHE_SIZE option is calculated as the sum of the token sizes for all registered tokens (Alias Type value of 0x01) minus the sum of the token sizes for all deregistered tokens (Alias Type value of 0x00), since Session initiation.
10.3.1.4. AUTHORIZATION TOKEN
The AUTHORIZATION TOKEN Setup Option (Option Type 0x03) is functionally equivalent to the AUTHORIZATION TOKEN message parameter, see Section 10.2.2. The endpoint can specify one or more tokens in SETUP that the peer can use to authorize MOQT session establishment.
If an endpoint receives an AUTHORIZATION TOKEN option in SETUP with Alias
Type REGISTER that exceeds its MAX_AUTH_TOKEN_CACHE_SIZE, it MUST NOT fail
the session with AUTH_TOKEN_CACHE_OVERFLOW. Instead, it MUST treat the
option as Alias Type USE_VALUE. Since each endpoint's SETUP may be sent before
the peer's SETUP is received, the sender MUST handle registration failures
of this kind by purging any Token Aliases that failed to register based on the
peer's MAX_AUTH_TOKEN_CACHE_SIZE option in SETUP (or the default value of 0).
10.3.1.5. MOQT IMPLEMENTATION
The MOQT_IMPLEMENTATION option (Option Type 0x07) identifies the name and version of the sender's MOQT implementation. This SHOULD be a UTF-8 encoded string [RFC3629], though the message does not carry information, such as language tags, that would aid comprehension by any entity other than the one that created the text.
An endpoint SHOULD send a MOQT_IMPLEMENTATION option unless specifically configured not to do so. This option helps identify the scope of interoperability problems and work around implementation-specific limitations.
Senders SHOULD limit the value to the implementation name and version, avoiding advertising or other nonessential information. Implementations SHOULD NOT use the identifiers of other implementations to declare compatibility, as this undermines the usefulness of implementation identification for debugging.
10.3.1.6. MAX FILTER RANGES
The MAX_FILTER_RANGES option (Type 0x06) limits the peer's total number of Ranges (Start/End pairs) allowed concurrently in all Range filter Section 5.1.3 parameters for a given subscription or fetch. The default value is 0, so if not specified, the peer MUST NOT send any such filter parameters. If this limit is exceeded, an endpoint MUST reject this with REQUEST_ERROR with error code INVALID_FILTER.
10.3.1.7. MAX_REQUEST_UPDATES
The MAX_REQUEST_UPDATES option (Option Type 0x08) communicates the maximum number of unacknowledged REQUEST_UPDATE messages per request stream that the endpoint is willing to receive.
A REQUEST_UPDATE is considered outstanding from when it is sent until the sender receives the corresponding REQUEST_OK or REQUEST_ERROR response. The sender MUST NOT have more than MAX_REQUEST_UPDATES outstanding REQUEST_UPDATEs on any single request stream at a time. Each REQUEST_OK or REQUEST_ERROR response restores one credit on that stream. An implementation that processes and responds to a REQUEST_UPDATE immediately might not detect when a peer has pipelined messages exceeding its limit; coalescing REQUEST_UPDATE processing (see Section 10.9) can be more effective at enforcing MAX_REQUEST_UPDATES.
The value is encoded as a variable-length integer. A value of 0 means the endpoint does not limit REQUEST_UPDATE concurrency. If not present, the default value is 0.
If an endpoint receives a REQUEST_UPDATE on a stream that already has
MAX_REQUEST_UPDATES outstanding REQUEST_UPDATEs, it MUST close the session
with TOO_MANY_REQUEST_UPDATES.