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. 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.
9.4.1. Setup Options
9.4.1.2. PATH
The PATH option (Option Type 0x01) allows the client to specify the path
of the MoQ URI when using native QUIC ([QUIC]). It MUST NOT be used by
the server, or when WebTransport is used. When a PATH option is received
from a server, or when a PATH option is received while WebTransport is used,
or when a PATH option 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.
9.4.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.
9.4.1.4. AUTHORIZATION TOKEN
The AUTHORIZATION TOKEN Setup Option (Option Type 0x03) is functionally equivalent to the AUTHORIZATION TOKEN message parameter, see Section 9.3.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).
9.4.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.