Parameters

9.2.1.1. AUTHORIZATION TOKEN Parameter

The AUTHORIZATION TOKEN parameter (Parameter Type 0x03) MAY appear in a CLIENT_SETUP, SERVER_SETUP, PUBLISH, SUBSCRIBE, SUBSCRIBE_UPDATE, SUBSCRIBE_NAMESPACE, 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 (i),
  [Token Alias (i),]
  [Token Type (i),]
  [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 CLIENT_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 13). 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 parameter defining the MAX_AUTH_TOKEN_CACHE_SIZE limit (see Section 9.3.1.4) it is willing to accept. If a registration is attempted which would cause this limit to be exceeded, the receiver MUST termiate 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.

9.2.1.2. DELIVERY TIMEOUT Parameter

The DELIVERY TIMEOUT parameter (Parameter Type 0x02) MAY appear in a TRACK_STATUS, REQUEST_OK (in response to TRACK_STATUS), PUBLISH, PUBLISH_OK, SUBSCRIBE, SUBSCRIBE_OK, or SUBSCRIBE_UDPATE message.

It is the duration in milliseconds the relay SHOULD continue to attempt forwarding Objects after they have been received. The start time for the timeout is based on when the Object Headers are received, and does not depend upon the forwarding preference. There is no explicit signal that an Object was not sent because the delivery timeout was exceeded.

If both the subscriber and publisher specify the parameter, they use the min of the two values for the subscription. The publisher SHOULD always specify the value received from an upstream subscription when there is one, and nothing otherwise.

Publishers can, at their discretion, discontinue forwarding Objects earlier than the negotiated DELIVERY TIMEOUT, subject to stream closure and ordering constraints described in Section 10.4.3. However, if neither the subscriber nor publisher specifies DELIVERY TIMEOUT, all Objects in the track matching the subscription filter are delivered as indicated by their Group Order and Priority. If a subscriber fails to consume Objects at a sufficient rate, causing the publisher to exceed its resource limits, the publisher MAY terminate the subscription with error TOO_FAR_BEHIND.

If an object in a subgroup exceeds the delivery timeout, the publisher MUST reset the underlying transport stream (see Section 10.4.3).

When sent by a subscriber, 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.

Publishers SHOULD consider whether the entire Object can likely be successfully delivered within the timeout period before sending any data for that Object, taking into account priorities, congestion control, and any other relevant information.

9.2.1.3. MAX CACHE DURATION Parameter

The MAX_CACHE_DURATION parameter (Parameter Type 0x04) MAY appear in a PUBLISH, SUBSCRIBE_OK, FETCH_OK or REQUEST_OK (in response to TRACK_STATUS) message.

It is an integer expressing the number of milliseconds an Object can be served from a cache. If present, the relay MUST NOT start forwarding any individual Object received through this subscription or fetch after the specified number of milliseconds has elapsed since the beginning of the Object was received. This means Objects earlier in a multi-object stream will expire earlier than Objects later in the stream. Once Objects have expired from cache, their state becomes unknown, and a relay that handles a downstream request that includes those Objects re-requests them.

If the MAX_CACHE_DURATION parameter is not sent by the publisher, the Objects can be cached until implementation constraints cause them to be evicted.

9.2.1.4. PUBLISHER PRIORITY Parameter

The PUBLISHER PRIORITY parameter (Parameter Type 0x0E) specifies the priority of a subscription relative to other subscriptions in the same session. The value is from 0 to 255 and lower numbers get higher priority. See Section 7. Priorities above 255 are invalid. The PUBLISHER PRIORITY parameter is valid in SUBSCRIBE_OK and PUBLISH. Subgroups and Datagrams for this subscription inherit this priority, unless they specifically override it.

The subscription has Publisher Priorty 128 if this parameter is omitted.

9.2.1.5. SUBSCRIBER PRIORITY Parameter

The SUBSCRIBER_PRIORITY parameter (Parameter Type 0x20) MAY appear in a SUBSCRIBE, SUBSCRIBE_UPDATE, TRACK_STATUS, PUBLISH_OK or FETCH 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. The range is restricted to 0-255. If a publisher receives a value outside this range, it MUST close the session with PROTOCOL_VIOLATION.

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

9.2.1.6. GROUP ORDER Parameter

The GROUP_ORDER parameter (Parameter Type 0x22) MAY appear in a SUBSCRIBE, SUBSCRIBE_OK, TRACK_STATUS, REQUEST_OK (in response to TRACK_STATUS), PUBLISH, PUBLISH_OK or FETCH.

It is an enum indicating 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 9.16.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 TRACK_STATUS, the publisher's preference from SUBSCRIBE_OK or REQUEST_OK is used. If omitted in PUBLISH_OK, the publisher's preference from PUBLISH is used. If omitted from SUBSCRIBE_OK, REQUEST_OK, PUBLISH or FETCH, the receiver uses Ascending (0x1).

9.2.1.7. SUBSCRIPTION FILTER Parameter

The SUBSCRIPTION_FILTER parameter (Parameter Type 0x21) MAY appear in a SUBSCRIBE, TRACK_STATUS, PUBLISH_OK or SUBSCRIBE_UPDATE message. It is a length-prefixed Subscription Filter (see Section 5.1.2). If the length of the Subscription Filter does not match the parameter length, the publisher MUST close the session with PROTOCOL_VIOLATION.

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

9.2.1.8. EXPIRES Parameter

The EXPIRES parameter (Parameter Type 0x8) MAY appear in SUBSCRIBE_OK, PUBLISH or PUBLISH_OK (TODO: or REQUEST_OK). It is a variable length integer encoding 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 UNSUBSCRIBE, depending on its role. This value is advisory and the sender can terminate the subscription prior to or after the expiry time.

The receiver of the parameter can extend the subscription by sending a SUBSCRIBE_UPDATE (TODO: SUBSCRIPTION_UPDATE). If the receiver of the parameter has one or more updated AUTHORIZATION_TOKENs, it SHOULD include those in the SUBSCRIBE_UPDATE. 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.

9.2.1.9. LARGEST OBJECT Parameter

The LARGEST_OBJECT parameter (Parameter Type 0x9) MAY appear in SUBSCRIBE_OK, PUBLISH or in REQUEST_OK in response to SUBSCRIBE_UPDATE. It is a length-prefixed Location structure (see Section 1.4.1) containing the largest Location 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.

9.2.1.10. FORWARD Parameter

The FORWARD parameter (Parameter Type 0x10) MAY appear in SUBSCRIBE, SUBSCRIBE_UPDATE, PUBLISH, PUBLISH_OK, TRACK_STATUS, TRACK_STATUS_OK, and SUBSCRIBE_NAMESPACE. It is a variable length integer specifying 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 SUBSCRIBE_UPDATE, the value for the subscription remains unchanged. If the parameter is omitted from any other message, the default value is 1.

9.2.1.11. DYNAMIC GROUPS Parameter

The DYNAMIC_GROUPS parameter (parameter type 0x30) MAY appear in PUBLISH or SUBSCRIBE_OK. Values larger than 1 are a Protocol Violation. When the value is 1, it indicates that the subscriber can request the Original Publisher to start a new Group by including the NEW_GROUP_REQUEST parameter in PUBLISH_OK or SUBSCRIBE_UPDATE for this Track.

Relays MUST preserve the value of this parameter received from an upstream publisher in SUBSCRIBE_OK or PUBLISH when sending these messages to downstream subscribers.

9.2.1.12. NEW GROUP REQUEST Parameter

The NEW_GROUP_REQUEST parameter (parameter type 0x32) MAY appear in PUBLISH_OK, SUBSCRIBE or SUBSCRIBE_UPDATE. It is an integer representing 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 SUBSCRIBE_UPDATE if the publisher did not include DYNAMIC_GROUPS=1 when establishing the subscription. 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, acheiving 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 SUBSCRIBE_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.