§9.2.

Parameters

draft-16 draft-15 draft-14 draft-13 draft-12 draft-11 draft-10 draft-09 draft-08 draft-07 · View on IETF ↗

Some messages include a Parameters field that encodes optional message elements. Parameters in the CLIENT_SETUP and SERVER_SETUP messages are called Setup Parameters. Parameters in other control messages are Message Parameters. Receivers ignore unrecognized Setup Parameters. All Message Parameters MUST be defined in the negotiated version of MOQT or negotiated via Setup Parameters. An endpoint that receives an unknown Message Parameter MUST close the session with PROTOCOL_VIOLATION.

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 as a PROTOCOL_VIOLATION if found. Receivers MUST allow duplicates of unknown Setup Parameters.

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

Parameters are serialized as Key-Value-Pairs Figure 2.

Setup Parameters use a namespace that is constant across all MOQT versions. All other messages use a version-specific namespace. For example, the integer '1' can refer to different parameters for Setup messages and for all other message types. SETUP message parameter types are defined in Section 9.3.1. Version-specific parameter types are defined in Section 9.2.2.

Message Parameters in SUBSCRIBE, PUBLISH_OK 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.

9.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. Any Track metadata sent by the publisher that is forwarded to subscribers is sent as Track Extension header.

9.2.2. Message Parameters

Each message parameter definition indicates the message types in which it can appear. If it appears in some other type of message, it MUST be ignored. Note that since Setup parameters use a separate namespace, it is impossible for these parameters to appear in Setup messages.

9.2.2.1. AUTHORIZATION TOKEN Parameter

The AUTHORIZATION TOKEN parameter (Parameter Type 0x03) MAY appear in a PUBLISH, SUBSCRIBE, REQUEST_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 (..)]
}
Figure 4: 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 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.2.2. DELIVERY TIMEOUT Parameter

The DELIVERY TIMEOUT parameter (Parameter Type 0x02) MAY appear in a PUBLISH_OK, SUBSCRIBE, or REQUEST_UPDATE 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. Objects with forwarding preference 'Datagram' are not retransmitted when lost, so the Delivery Timeout only limits the amount of time they can be queued before being sent. There is no explicit signal that an Object was not sent because the delivery timeout was exceeded.

DELIVERY_TIMEOUT, if present, MUST contain a value greater than 0. If an endpoint receives a DELIVERY_TIMEOUT equal to 0 it MUST close the session with PROTOCOL_VIOLATION.

If both the subscriber specifies this parameter and the Track has a DELIVERY_TIMEOUT extension, the endpoints use the min of the two values for the subscription.

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) and SHOULD NOT attempt to open a new stream to deliver additional Objects in that Subgroup.

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.2.3. SUBSCRIBER PRIORITY Parameter

The SUBSCRIBER_PRIORITY parameter (Parameter Type 0x20) MAY appear in a SUBSCRIBE, FETCH, REQUEST_UPDATE (for a subscription or FETCH), 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. 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, PUBLISH_OK or FETCH, the publisher uses the value 128.

9.2.2.4. GROUP ORDER Parameter

The GROUP_ORDER parameter (Parameter Type 0x22) MAY appear in a SUBSCRIBE, 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, the publisher's preference from the Track is used. If omitted from FETCH, the receiver uses Ascending (0x1).

9.2.2.5. SUBSCRIPTION FILTER Parameter

The SUBSCRIPTION_FILTER parameter (Parameter Type 0x21) MAY appear in a SUBSCRIBE, PUBLISH_OK or REQUEST_UPDATE (for a subscription) 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 or PUBLISH_OK, the subscription is unfiltered. If omitted from REQUEST_UPDATE, the value is unchanged.

9.2.2.6. 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 REQUEST_UPDATE. If the receiver of the parameter has one or more updated AUTHORIZATION_TOKENs, it SHOULD include those in the REQUEST_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.2.7. LARGEST OBJECT Parameter

The LARGEST_OBJECT parameter (Parameter Type 0x9) MAY appear in SUBSCRIBE_OK, PUBLISH or in REQUEST_OK (in response to REQUEST_UPDATE or TRACK_STATUS). 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.2.8. FORWARD Parameter

The FORWARD parameter (Parameter Type 0x10) MAY appear in SUBSCRIBE, REQUEST_UPDATE (for a subscription), PUBLISH, PUBLISH_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 REQUEST_UPDATE, the value for the subscription remains unchanged. If the parameter is omitted from any other message, the default value is 1.

9.2.2.9. NEW GROUP REQUEST Parameter

The NEW_GROUP_REQUEST parameter (parameter type 0x32) MAY appear in PUBLISH_OK, SUBSCRIBE or REQUEST_UPDATE for a subscription. 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 REQUEST_UPDATE if the Track did not include the DYNAMIC_GROUPS Extension 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, 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 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.

This is one section of the MoQT specification, rendered per-section for quick reference and citation. The authoritative text is draft-ietf-moq-transport-16 at the IETF.

All draft-16 sections What is MoQT? Debug MoQT with moqtap