Message Parameters

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.

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 (..)]
}

• 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 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 the 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 PUBLISH_OK, SUBSCRIBE, 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 PUBLISH_OK, SUBSCRIBE, 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.

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 Unknown 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 Unknown gaps 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 Unknown gaps.

If the Fill Timeout parameter is absent, the relay waits for an implementation specific duration before reporting Unknown 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, FETCH, REQUEST_UPDATE (for a subscription or FETCH), or PUBLISH_OK message. 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, PUBLISH_OK 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, SUBSCRIBE_TRACKS, or FETCH.

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.12.3). 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 SUBSCRIBE, PUBLISH_OK or REQUEST_UPDATE (for a subscription) message. It is a Location Filter (see Section 5.1.2).

If omitted from SUBSCRIBE or PUBLISH_OK, the subscription is unfiltered. If omitted from REQUEST_UPDATE, the value is unchanged.

10.2.10. SUBGROUP FILTER Parameter

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

10.2.11. OBJECTID FILTER Parameter

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

10.2.12. PRIORITY FILTER Parameter

The PRIORITY_FILTER parameter (Type 0x27) selects objects with specified Ranges of Publisher Priority. See Section 5.1.3. 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.3.

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

10.2.15. 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.16. LARGEST OBJECT Parameter

The LARGEST_OBJECT parameter (Parameter Type 0x9) is a Location. It MAY appear in SUBSCRIBE_OK, PUBLISH, REQUEST_UPDATE_OK, or TRACK_STATUS_OK. 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:

1. Any LARGEST_OBJECT value received from the upstream publisher in SUBSCRIBE_OK, PUBLISH, or REQUEST_UPDATE_OK

2. The largest Location of an Object received on an upstream subscription

10.2.17. FORWARD Parameter

The FORWARD parameter (Parameter Type 0x10) is a uint8. It MAY appear in SUBSCRIBE, REQUEST_UPDATE (for a subscription), PUBLISH, PUBLISH_OK and SUBSCRIBE_TRACKS. 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.

If the parameter is omitted from REQUEST_UPDATE, the value for the subscription remains unchanged. If the parameter is omitted from any other message, the default value is 1.

10.2.18. NEW GROUP REQUEST Parameter

The NEW_GROUP_REQUEST parameter (Parameter Type 0x32) is a varint. It MAY appear in PUBLISH_OK, 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 PUBLISH_OK or 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:

1. The Track does not support dynamic Groups

2. 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.19. 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.