Message Parameters — MoQT draft-20 §10.2.

Some control messages include a field that encodes optional Message Parameters. Message Parameters are serialized as follows:

Message Parameter {
  Type Delta (vi64),
  Value (..)
}

Figure 4: Message Parameter

Type Delta: The difference between this Parameter Type and the previous Parameter Type in the message, or the Parameter Type itself for the first parameter. Parameters MUST be serialized in ascending order by Type. If the resulting Type would be greater than 2^64 - 1, the endpoint MUST close the session with a PROTOCOL_VIOLATION.

Value: The encoding is specified by each parameter definition. The encodings defined in this draft are:
- uint8: A single-byte unsigned integer (0-255)
- varint: A variable-length integer
- Location: Two consecutive varints (Group, Object)
- Length-prefixed: A varint length followed by that many bytes

Message Parameters are intended for the peer only and are not forwarded by Relays, though relays can consider received parameter values when making a request.

All Message Parameters MUST be defined in the negotiated version of MOQT or negotiated via Setup Options. An endpoint that receives an unknown Message Parameter MUST close the session with PROTOCOL_VIOLATION. Because the receiver has to understand every Message Parameter, there is no need for a mechanism to skip unknown parameters. Because unknown parameters cannot be skipped, the block is bounded by a parameter count rather than a length.

The Message Parameter types defined in this version of MOQT are defined in the following subsections.

Senders MUST NOT repeat the same Parameter Type in a message unless the parameter definition explicitly allows multiple instances of that type to be sent in a single message. Receivers SHOULD check that there are no unexpected duplicate parameters and close the session with PROTOCOL_VIOLATION if found.

The number of Message Parameters is not specifically limited, but the total length of a control message is limited to 2^16-1 bytes.

Message Parameters in SUBSCRIBE and FETCH MUST NOT cause the publisher to alter the payload of the objects it sends, as that would violate the track uniqueness guarantee described in Section 2.4.3.

10.2.1. Parameter Scope

Message Parameters are always intended for the peer endpoint only and are not forwarded by Relays, though relays can consider received parameter values when making a request. Track information not specific to the Message or Session is encoded in Track Properties. See Section 2.5.

Each Message Parameter definition indicates the message types in which it can appear. If it appears in some other type of message, the receiving endpoint MUST close the connection with a PROTOCOL_VIOLATION. Note that since Setup Options use a separate namespace, it is impossible for Message Parameters to appear in Setup messages.

10.2.2. AUTHORIZATION TOKEN Parameter

The AUTHORIZATION TOKEN parameter (Parameter Type 0x03) uses Length-prefixed encoding. It MAY appear in a PUBLISH, SUBSCRIBE, REQUEST_UPDATE, SUBSCRIBE_NAMESPACE, SUBSCRIBE_TRACKS, PUBLISH_NAMESPACE, TRACK_STATUS or FETCH message. This parameter conveys information to authorize the sender to perform the operation carrying the parameter. This Parameter MUST NOT be copied from a SUBSCRIBE_TRACKS to the resulting PUBLISH message Parameters.

The parameter value is a Token structure containing an optional Session-specific Alias. The Alias allows the sender to reference a previously transmitted Token Type and Token Value in future messages. The Token structure is serialized as follows:

Token {
  Alias Type (vi64),
  [Token Alias (vi64),]
  [Token Type (vi64),]
  [Token Value (..)]
}

Figure 5: Token structure

Alias Type - an integer defining both the serialization and the processing behavior of the receiver. This Alias type has the following code points:

DELETE (0x0):: There is an Alias but no Type or Value. This Alias and the Token Value it was previously associated with MUST be retired. Retiring removes them from the pool of actively registered tokens.
REGISTER (0x1):: There is an Alias, a Type and a Value. This Alias MUST be associated with the Token Value for the duration of the Session or it is deleted. This action is termed "registering" the Token.
USE_ALIAS (0x2):: There is an Alias but no Type or Value. Use the Token Type and Value previously registered with this Alias.
USE_VALUE (0x3):: There is no Alias and there is a Type and Value. Use the Token Value as provided. The Token Value MAY be discarded after processing.

If a server receives Alias Type DELETE (0x0) or USE_ALIAS (0x2) in a SETUP message, it MUST close the session with a PROTOCOL_VIOLATION.

Token Alias - a Session-specific integer identifier that references a Token Type and Token Value. There are separate Alias spaces for the client and server (e.g.: they can each register Alias=1). Once a Token Alias has been registered, it cannot be re-registered by the same endpoint in the Session without first being deleted. Use of the Token Alias is optional.
Token Type - a numeric identifier for the type of Token payload being transmitted. This type is defined by the IANA table "MOQT Auth Token Type" (see Section 15). Type 0 is reserved to indicate that the type is not defined in the table and is negotiated out-of-band between client and receiver.
Token Value - the payload of the Token. The contents and serialization of this payload are defined by the Token Type.

If the Token structure cannot be decoded, the receiver MUST close the Session with KEY_VALUE_FORMATTING_ERROR. The receiver of a message attempting to register an Alias which is already registered MUST close the Session with DUPLICATE_AUTH_TOKEN_ALIAS. The receiver of a message referencing an Alias that is not currently registered MUST reject the message with UNKNOWN_AUTH_TOKEN_ALIAS.

The receiver of a message containing a well-formed Token structure but otherwise invalid AUTHORIZATION TOKEN parameter MUST reject that message with an MALFORMED_AUTH_TOKEN error.

The receiver of a message carrying an AUTHORIZATION TOKEN with Alias Type REGISTER that does not result in a Session error MUST register the Token Alias in the token cache, even if the message fails for other reasons, including Unauthorized. This allows senders to pipeline messages that refer to previously registered tokens without potentially terminating the entire Session. A receiver MAY store an error code (eg: UNAUTHORIZED or MALFORMED_AUTH_TOKEN) in place of the Token Type and Token Alias if any future message referencing the Token Alias will result in that error. However, it is important to not store an error code for a token that might be valid in the future or due to some other property becoming fulfilled which currently isn't. The size of a registered cache entry includes the length of the Token Value, regardless of whether it is stored.

If a receiver detects that an authorization token has expired, it MUST retain the registered Alias until it is deleted by the sender, though it MAY discard other state associated with the token that is no longer needed. Expiration does not affect the size occupied by a token in the token cache. Any message that references an expired token with Alias Type USE_ALIAS fails with EXPIRED_AUTH_TOKEN.

Using an Alias to refer to a previously registered Token Type and Value is for efficiency only and has the same effect as if the Token Type and Value was included directly. Retiring an Alias that was previously used to authorize a message has no retroactive effect on the original authorization, nor does it prevent that same Token Type and Value from being re-registered.

Senders of tokens SHOULD only register tokens which they intend to re-use during the Session and SHOULD retire previously registered tokens once their utility has passed.

By registering a Token, the sender is requiring the receiver to store the Token Alias and Token Value until they are deleted, or the Session ends. The receiver can protect its resources by sending a Setup Option defining the MAX_AUTH_TOKEN_CACHE_SIZE limit (see Section 10.3.1.3) it is willing to accept. If a registration is attempted which would cause this limit to be exceeded, the receiver MUST terminate the Session with a AUTH_TOKEN_CACHE_OVERFLOW error.

The AUTHORIZATION TOKEN parameter MAY be repeated within a message as long as the combination of Token Type and Token Value are unique after resolving any aliases.

Messages carrying the AUTHORIZATION TOKEN parameter can appear on different control streams. Because stream processing order can be different than send order, the receiver and sender can have inconsistent views of the token cache state.

Senders MUST NOT send USE_ALIAS on one control stream for an alias registered on a different stream until the sender has received a response to the message containing the REGISTER. Senders MAY use USE_ALIAS on the same control stream as the REGISTER without waiting for a response.

Senders MUST NOT send DELETE for an alias while any message using USE_ALIAS with that alias has not received a response.

10.2.3. SUBGROUP_DELIVERY_TIMEOUT Parameter

The SUBGROUP_DELIVERY_TIMEOUT parameter (Parameter Type 0x06) is a varint. It MAY appear in a SUBSCRIBE, PUBLISH, or REQUEST_UPDATE message. Its semantics are defined in Section 8.

This parameter is intended to be specific to a subscription, so it SHOULD NOT be forwarded upstream by a relay that intends to serve multiple subscriptions for the same track.

10.2.4. OBJECT_DELIVERY_TIMEOUT Parameter

The OBJECT_DELIVERY_TIMEOUT parameter (Parameter Type 0x02) is a varint. It MAY appear in a SUBSCRIBE, PUBLISH, or REQUEST_UPDATE message. Its semantics are defined in Section 8.

This parameter is intended to be specific to a subscription, so it SHOULD NOT be forwarded upstream by a relay that intends to serve multiple subscriptions for the same track.

10.2.5. FILL TIMEOUT Parameter

The FILL_TIMEOUT parameter (Parameter Type 0x0A) MAY appear in a FETCH message, or inside a FILL_PARAMETERS parameter (see Section 10.2.15) in a SUBSCRIBE or REQUEST_UPDATE (for a subscription), where it applies to the fill fetch stream.

It is the maximum total duration in milliseconds a relay SHOULD spend waiting for upstream sources to provide Objects that are not immediately available before reporting them as Timed-Out gaps in the FETCH response. When a relay encounters Objects within the requested range that are not immediately available and have unknown status, it issues upstream FETCHes to retrieve them. The Fill Timeout represents a total budget for all such upstream FETCHes generated by this request. If the budget is exhausted, the relay reports any remaining unavailable Objects as Timed-Out gaps (End of Timed-Out Range, see Section 11.4.4.2) and continues delivering available Objects in the range.

A value of 0 indicates the subscriber only wants Objects that are immediately available; the relay MUST NOT wait for upstream delivery and MUST report any unavailable Objects as Timed-Out gaps.

If the Fill Timeout parameter is absent, the relay waits for an implementation specific duration before reporting Timed-Out gaps. If the subscriber specifies a Fill Timeout larger than the relay is willing to wait, the relay MAY use a shorter timeout without informing the subscriber.

10.2.6. RENDEZVOUS TIMEOUT Parameter

The RENDEZVOUS_TIMEOUT parameter (Parameter Type 0x04) MAY appear in a SUBSCRIBE message.

It is the duration in milliseconds the subscriber is willing to wait for a publisher to become available. This applies when a relay receives a SUBSCRIBE for a Track that has no current publisher.

If the RENDEZVOUS_TIMEOUT is present, the relay SHOULD hold the subscription and wait for a publisher to appear, up to the specified duration. The relay does not send SUBSCRIBE_OK until a publisher becomes available. If a publisher becomes available within this time, the relay proceeds with the subscription normally. If the timeout expires without a publisher, the relay SHOULD respond with REQUEST_ERROR with error code TIMEOUT.

The relay MAY use a shorter timeout than requested by the subscriber. For example, a relay might limit the maximum rendezvous timeout to protect its resources.

A value of 0 indicates the subscriber does not want to wait and expects an immediate response. The relay MUST immediately return REQUEST_ERROR with error code DOES_NOT_EXIST if no publisher is available

If RENDEZVOUS_TIMEOUT is absent, the default is 0.

10.2.7. SUBSCRIBER PRIORITY Parameter

The SUBSCRIBER_PRIORITY parameter (Parameter Type 0x20) is a uint8. It MAY appear in a SUBSCRIBE, PUBLISH, FETCH, or REQUEST_UPDATE (for a subscription or FETCH). It is an integer expressing the priority of a subscription relative to other subscriptions and fetch responses in the same session. Lower numbers get higher priority. See Section 7.

If omitted from SUBSCRIBE or FETCH, the publisher uses the value 128.

10.2.8. GROUP ORDER Parameter

The GROUP_ORDER parameter (Parameter Type 0x22) is a uint8. It MAY appear in a SUBSCRIBE, PUBLISH, SUBSCRIBE_TRACKS, or FETCH, or inside a FILL_PARAMETERS parameter (see Section 10.2.15).

Its value indicates how to prioritize Objects from different groups within the same subscription (see Section 7), or how to order Groups in a Fetch response (see Section 10.13). When it appears inside FILL_PARAMETERS, it governs the fill fetch stream and its ordering relative to subscription-delivered Objects (see Section 7). The allowed values are Ascending (0x1) or Descending (0x2). If an endpoint receives a value outside this range, it MUST close the session with PROTOCOL_VIOLATION.

If omitted from SUBSCRIBE or SUBSCRIBE_TRACKS, the publisher's preference from the Track is used. If omitted from FETCH, the receiver uses Ascending (0x1).

10.2.9. LOCATION FILTER Parameter

The LOCATION_FILTER parameter (Parameter Type 0x21) uses length-prefixed encoding. It MAY appear in a FETCH, SUBSCRIBE, PUBLISH, REQUEST_UPDATE (for a subscription) or PUBLISH_STATE_NOTIFY message. It is a Location Filter (see Section 5.1.2).

If omitted from FETCH or SUBSCRIBE, the fetch or subscription is unfiltered. If omitted from REQUEST_UPDATE or PUBLISH_STATE_NOTIFY, the value is unchanged. When sent in PUBLISH_STATE_NOTIFY, it reports the Location Filter now in effect at the publisher.

10.2.10. SUBGROUP FILTER Parameter

The SUBGROUP_FILTER parameter (Type 0x25) selects objects with specified Ranges of Subgroup ID. See Section 5.1.4.

10.2.11. OBJECTID FILTER Parameter

The OBJECTID_FILTER parameter (Type 0x26) selects objects with specified Ranges of Object ID. See Section 5.1.4.

10.2.12. PRIORITY FILTER Parameter

The PRIORITY_FILTER parameter (Type 0x27) selects objects with specified Ranges of Publisher Priority. See Section 5.1.4. If a decoded value exceeds 255, the endpoint MUST reject this with REQUEST_ERROR with error code INVALID_FILTER since Publisher Priority is an 8-bit field.

10.2.13. OBJECT PROPERTY FILTER Parameter

The OBJECT_PROPERTY_FILTER parameter (Type 0x28) selects objects with required Ranges of Property Value for a required Object Property Type which MUST be even, i.e. a single integer value (see Figure 2), otherwise the endpoint MUST reject this with REQUEST_ERROR with error code INVALID_FILTER. See Section 5.1.4.

10.2.14. TRACK PROPERTY FILTER Parameter

The TRACK_PROPERTY_FILTER parameter (Type 0x29) selects tracks with required Ranges of Property Value for a required Track Property Type which MUST be even, i.e. a single integer value (see Figure 2), otherwise the endpoint MUST reject this with REQUEST_ERROR with error code INVALID_FILTER. See Section 5.1.4.

10.2.15. FILL PARAMETERS Parameter

The FILL_PARAMETERS parameter (Parameter Type 0x23) uses length-prefixed encoding. It MAY appear in a SUBSCRIBE or REQUEST_UPDATE (for a subscription) message. Its value is a sequence of Parameters that apply to the fill fetch stream (see Section 5.1.3), encoded as if they were Parameters for a separate message (see Section 15.7). Its presence is what requests a fill fetch stream; a subscription with no FILL_PARAMETERS opens none.

The following parameters MAY appear inside FILL_PARAMETERS:

Table 6
Parameter Type	Parameter Name	Specification
0x0A	FILL_TIMEOUT	Section 10.2.5
0x20	SUBSCRIBER_PRIORITY	Section 10.2.7
0x21	LOCATION_FILTER	Section 10.2.9
0x22	GROUP_ORDER	Section 10.2.8
0x25	SUBGROUP_FILTER	Section 5.1.4
0x26	OBJECTID_FILTER	Section 5.1.4
0x27	PRIORITY_FILTER	Section 5.1.4
0x28	OBJECT_PROPERTY_FILTER	Section 5.1.4

The LOCATION_FILTER inside FILL_PARAMETERS selects the fill range and is evaluated using the rules for a Fetch (see Section 5.1.2); it is independent of the subscription's own Location filter.

A parameter that is omitted from FILL_PARAMETERS takes the value it has for the subscription; FILL_PARAMETERS therefore carries only the settings that differ. An endpoint that receives a parameter inside FILL_PARAMETERS that is not listed above MUST close the session with PROTOCOL_VIOLATION.

The value of FILL_PARAMETERS is a separate parameter scope. Parameters inside it are not considered to appear in the enclosing message for the purposes of Section 10.2, so a Parameter Type MAY appear both in the message and inside FILL_PARAMETERS.

FILL_PARAMETERS is not retained as subscription state. It applies only to the message that carries it, so the sticky-parameter rules in Section 10.9 do not apply to it.

10.2.16. EXPIRES Parameter

The EXPIRES parameter (Parameter Type 0x8) is a varint. It MAY appear in SUBSCRIBE_OK, PUBLISH, PUBLISH_OK, SUBSCRIBE_NAMESPACE_OK, SUBSCRIBE_TRACKS_OK, PUBLISH_NAMESPACE_OK, or REQUEST_UPDATE_OK. It encodes the time in milliseconds after which the sender of the parameter will terminate the subscription. The sender will terminate the subscription using PUBLISH_DONE or by cancelling the request (see Section 3.3.3). This value is advisory and the sender can terminate the subscription prior to or after the expiry time.

The receiver of the parameter can attempt to extend the subscription by sending a REQUEST_UPDATE with 0 or more updated parameters. If the receiver has one or more updated AUTHORIZATION_TOKENs, it SHOULD include those in the REQUEST_UPDATE. If the extension is granted, the sender includes a new EXPIRES value in REQUEST_UPDATE_OK. Relays that send this parameter and applications that receive it MAY introduce jitter to prevent many endpoints from updating simultaneously.

If the EXPIRES parameter is 0 or is not present in a message, the subscription does not expire or expires at an unknown time.

10.2.17. LARGEST OBJECT Parameter

The LARGEST_OBJECT parameter (Parameter Type 0x9) is a Location. It MAY appear in SUBSCRIBE_OK, PUBLISH, REQUEST_UPDATE_OK, TRACK_STATUS_OK, or PUBLISH_STATE_NOTIFY. It contains the largest Location (see Section 1.4.2) in the Track observed by the sending endpoint (see Section 5.1.2). If Objects have been published on this Track the Publisher MUST include this parameter.

If omitted from a message, the sending endpoint has not published or received any Objects in the Track.

A relay MUST set LARGEST_OBJECT to the largest of the following:

Any LARGEST_OBJECT value received from the upstream publisher in SUBSCRIBE_OK, PUBLISH, or REQUEST_UPDATE_OK
The largest Location of an Object received on an upstream subscription

10.2.18. FORWARD Parameter

The FORWARD parameter (Parameter Type 0x10) is a uint8. It MAY appear in SUBSCRIBE, REQUEST_UPDATE (for a subscription or a SUBSCRIBE_TRACKS request), PUBLISH, SUBSCRIBE_TRACKS and PUBLISH_STATE_NOTIFY. It specifies the Forwarding State on affected subscriptions (see Section 5.1). The allowed values are 0 (don't forward) or 1 (forward). If an endpoint receives a value outside this range, it MUST close the session with PROTOCOL_VIOLATION.

In the case of a REQUEST_UPDATE for SUBSCRIBE_TRACKS, it specifies the Forwarding State on future subscriptions that match the prefix. Existing subscriptions are unaffected.

If the parameter is omitted from REQUEST_UPDATE or PUBLISH_STATE_NOTIFY, the value for the subscription remains unchanged. If the parameter is omitted from any other message, the default value is 1. When sent in PUBLISH_STATE_NOTIFY, it reports the Forwarding State now in effect at the publisher.

10.2.19. NEW GROUP REQUEST Parameter

The NEW_GROUP_REQUEST parameter (Parameter Type 0x32) is a varint. It MAY appear in SUBSCRIBE or REQUEST_UPDATE for a subscription. It represents the largest Group ID in the Track known by the subscriber, plus 1. A value of 0 indicates that the subscriber has no Group information for the Track. A subscriber MUST NOT send this parameter in REQUEST_UPDATE if the Track did not include the DYNAMIC_GROUPS Property with value 1. A subscriber MAY include this parameter in SUBSCRIBE without foreknowledge of support. If the original publisher does not support dynamic Groups, it ignores the parameter in that case.

When an Original Publisher that supports dynamic Groups receives a NEW_GROUP_REQUEST with a value of 0 or a value larger than the current Group, it SHOULD end the current Group and begin a new Group as soon as practical. The Original Publisher MAY delay the NEW_GROUP_REQUEST subject to implementation specific concerns, for example, achieving a minimum duration for each Group. The Original Publisher chooses the next Group ID; there are no requirements that it be equal to the NEW_GROUP_REQUEST parameter value.

Relay Handling:

A relay that receives a NEW_GROUP_REQUEST for a Track without an Established subscription MUST include the NEW_GROUP_REQUEST when subscribing upstream.

A relay that receives a NEW_GROUP_REQUEST for an Established subscription with a value of 0 or a value larger than the Largest Group MUST send a REQUEST_UPDATE including the NEW_GROUP_REQUEST to the publisher unless:

The Track does not support dynamic Groups
There is already an outstanding NEW_GROUP_REQUEST from this Relay with a greater or equal value

If a relay receives a NEW_GROUP_REQUEST with a non-zero value less than or equal to the Largest Group, it does not send a NEW_GROUP_REQUEST upstream.

After sending a NEW_GROUP_REQUEST upstream, the request is considered outstanding until the Largest Group increases.

10.2.20. TRACK_NAMESPACE_PREFIX Parameter

The TRACK_NAMESPACE_PREFIX parameter (Parameter Type 0x34) uses the Track Namespace encoding described in Section 2.4.1. It MAY appear in REQUEST_UPDATE for a SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS request. It updates the Track Namespace Prefix for that subscription. If the new prefix would share a common prefix with another active subscription of the same type in the same session, the receiver MUST respond with REQUEST_ERROR with error code PREFIX_OVERLAP.

10.2.21. INCLUDE_PROPERTIES Parameter

The INCLUDE_PROPERTIES parameter (Parameter Type 0x35) is a uint8. It MAY appear in SUBSCRIBE, TRACK_STATUS, FETCH or SUBSCRIBE_TRACKS. It specifies whether the OK message sent in response includes Track Properties or whether the resulting PUBLISH messages include Track Properties in the case of SUBSCRIBE_TRACKS. If INCLUDE_PROPERTIES is 0, the Track Properties are still present in the message, but they SHOULD be empty. The allowed values are 0 (do not send Properties) or 1 (send Properties), and the default is 1. If an endpoint receives a value outside this range, it MUST close the session with PROTOCOL_VIOLATION.