diff --git a/draft-ietf-moq-transport.md b/draft-ietf-moq-transport.md index 1b27df947..8c1e2f1f2 100644 --- a/draft-ietf-moq-transport.md +++ b/draft-ietf-moq-transport.md @@ -252,11 +252,6 @@ x (L): : Indicates that x is L bits long. -x (i): - -: Indicates that x holds an integer value using the variable-length - encoding as described in ({{?RFC9000, Section 16}}). - x (..): : Indicates that x can be any length including zero bits long. Values @@ -271,9 +266,56 @@ x (L) ...: : Indicates that x is repeated zero or more times and that each instance has a length of L. -To reduce unnecessary use of bandwidth, variable length integers SHOULD -be encoded using the least number of bytes possible to represent the -required value. +x (vi64): + +: Indicates that x holds an integer value using the variable-length + encoding as described below. + +### Variable-Length Integers + +MoQT requires a variable-length integer encoding with the following properties: + +1. The encoded length can be determined from the first encoded byte. +2. The range of 1 byte values is as large as possible. +3. All 64 bit numbers can be encoded. + +The variable-length integer encoding uses the most significant one to four +bits of the first byte to indicate the length of the encoding in bytes. The +remaining bits represent the integer value, encoded in network byte order. + +Integers are encoded in 1, 2, 4, 8, or 9 bytes and can encode 7-, 14-, 29-, 60-, +or 64-bit values, respectively. The following table summarizes the encoding +properties. + +|--------------|----------------|-------------|------------------------| +| Leading Bits | Length (bytes) | Usable Bits | Range | +|--------------|----------------|-------------|------------------------| +| 0 | 1 | 7 | 0-127 | +|--------------|----------------|-------------|------------------------| +| 10 | 2 | 14 | 0-16383 | +|--------------|----------------|-------------|------------------------| +| 110 | 4 | 29 | 0-536870911 | +|--------------|----------------|-------------|------------------------| +| 1110 | 8 | 60 | 0-1152921504606846975 | +|--------------|----------------|-------------|------------------------| +| 11110000 | 9 | 64 | 0-18446744073709551615 | +|--------------|----------------|-------------|------------------------| +{: format title="Summary of Integer Encodings"} + +For example, the nine-byte sequence 0xf0ffffffffffffffff decodes to the decimal +value 18,446,744,073,709,551,615; the eight-byte sequence 0xe2197c5eff14e88c +decodes to the decimal value 151,288,809,941,952,652; the four-byte sequence +0xdd7f3e7d decodes to 494,878,333; the two-byte sequence 0xbbbd decodes to +15,293; and the single byte 0x25 decodes to 37 (as does the two-byte sequence +0x8025). + +The four least significant bits of the first byte in 9-byte encodings MUST be +set to 0000. An endpoint that receives any other value MUST close the session +with a `PROTOCOL_VIOLATION`. + +To reduce unnecessary use of bandwidth, variable length integers SHOULD be +encoded using the least number of bytes possible to represent the required +value. ### Location Structure @@ -281,8 +323,8 @@ Location identifies a particular Object in a Group within a Track. ~~~ Location { - Group (i), - Object (i) + Group (vi64), + Object (vi64) } ~~~ {: #moq-location format title="Location structure"} @@ -306,8 +348,8 @@ is optimized for use in the data plane. ~~~ Key-Value-Pair { - Type (i), - [Length (i),] + Type (vi64), + [Length (vi64),] Value (..) } ~~~ @@ -333,7 +375,7 @@ information about the error condition, where appropriate. ~~~ Reason Phrase { - Reason Phrase Length (i), + Reason Phrase Length (vi64), Reason Phrase Value (..) } ~~~ @@ -480,7 +522,7 @@ encoded as follows: ~~~ Track Namespace { - Number of Track Namespace Fields (i), + Number of Track Namespace Fields (vi64), Track Namespace Field (..) ... } ~~~ @@ -492,7 +534,7 @@ Each Track Namespace Field is encoded as follows: ~~~ Track Namespace Field { - Track Namespace Field Length (i), + Track Namespace Field Length (vi64), Track Namespace Field Value (..) } ~~~ @@ -1439,7 +1481,7 @@ formatted as follows: ~~~ MOQT Control Message { - Message Type (i), + Message Type (vi64), Message Length (16), Message Payload (..), } @@ -1585,9 +1627,9 @@ follows: ~~~ Token { - Alias Type (i), - [Token Alias (i),] - [Token Type (i),] + Alias Type (vi64), + [Token Alias (vi64),] + [Token Type (vi64),] [Token Value (..)] } ~~~ @@ -1748,19 +1790,19 @@ The wire format of the Setup messages are as follows: ~~~ CLIENT_SETUP Message { - Type (i) = 0x20, + Type (vi64) = 0x20, Length (16), - Number of Supported Versions (i), - Supported Versions (i) ..., - Number of Parameters (i), + Number of Supported Versions (vi64), + Supported Versions (vi64) ..., + Number of Parameters (vi64), Setup Parameters (..) ..., } SERVER_SETUP Message { - Type (i) = 0x21, + Type (vi64) = 0x21, Length (16), - Selected Version (i), - Number of Parameters (i), + Selected Version (vi64), + Number of Parameters (vi64), Setup Parameters (..) ..., } ~~~ @@ -1885,9 +1927,9 @@ The endpoint MUST terminate the session with a `PROTOCOL_VIOLATION` ~~~ GOAWAY Message { - Type (i) = 0x10, + Type (vi64) = 0x10, Length (16), - New Session URI Length (i), + New Session URI Length (vi64), New Session URI (..), } ~~~ @@ -1915,9 +1957,9 @@ value is a `PROTOCOL_VIOLATION`. ~~~ MAX_REQUEST_ID Message { - Type (i) = 0x15, + Type (vi64) = 0x15, Length (16), - Max Request ID (i), + Max Request ID (vi64), } ~~~ {: #moq-transport-max-request-id format title="MOQT MAX_REQUEST_ID Message"} @@ -1947,9 +1989,9 @@ sending REQUESTS_BLOCKED is not required. ~~~ REQUESTS_BLOCKED Message { - Type (i) = 0x1A, + Type (vi64) = 0x1A, Length (16), - Maximum Request ID (i), + Maximum Request ID (vi64), } ~~~ {: #moq-transport-requests-blocked format title="MOQT REQUESTS_BLOCKED Message"} @@ -1966,10 +2008,10 @@ request. ~~~ REQUEST_ERROR Message { - Type (i) = 0x5, + Type (vi64) = 0x5, Length (16), - Request ID (i), - Error Code (i), + Request ID (vi64), + Error Code (vi64), Error Reason (Reason Phrase), } ~~~ @@ -2058,19 +2100,19 @@ The format of SUBSCRIBE is as follows: ~~~ SUBSCRIBE Message { - Type (i) = 0x3, + Type (vi64) = 0x3, Length (16), - Request ID (i), + Request ID (vi64), Track Namespace (..), - Track Name Length (i), + Track Name Length (vi64), Track Name (..), Subscriber Priority (8), Group Order (8), Forward (8), - Filter Type (i), + Filter Type (vi64), [Start Location (Location),] - [End Group (i),] - Number of Parameters (i), + [End Group (vi64),] + Number of Parameters (vi64), Parameters (..) ... } ~~~ @@ -2127,15 +2169,15 @@ subscriptions. ~~~ SUBSCRIBE_OK Message { - Type (i) = 0x4, + Type (vi64) = 0x4, Length (16), - Request ID (i), - Track Alias (i), - Expires (i), + Request ID (vi64), + Track Alias (vi64), + Expires (vi64), Group Order (8), Content Exists (8), [Largest Location (Location),] - Number of Parameters (i), + Number of Parameters (vi64), Parameters (..) ... } ~~~ @@ -2200,15 +2242,15 @@ The format of SUBSCRIBE_UPDATE is as follows: ~~~ SUBSCRIBE_UPDATE Message { - Type (i) = 0x2, + Type (vi64) = 0x2, Length (16), - Request ID (i), - Subscription Request ID (i), + Request ID (vi64), + Subscription Request ID (vi64), Start Location (Location), - End Group (i), + End Group (vi64), Subscriber Priority (8), Forward (8), - Number of Parameters (i), + Number of Parameters (vi64), Parameters (..) ... } ~~~ @@ -2246,9 +2288,9 @@ The format of `UNSUBSCRIBE` is as follows: ~~~ UNSUBSCRIBE Message { - Type (i) = 0xA, + Type (vi64) = 0xA, Length (16), - Request ID (i) + Request ID (vi64) } ~~~ {: #moq-transport-unsubscribe-format title="MOQT UNSUBSCRIBE Message"} @@ -2263,18 +2305,18 @@ track. The receiver verifies the publisher is authorized to publish this track. ~~~ PUBLISH Message { - Type (i) = 0x1D, + Type (vi64) = 0x1D, Length (16), - Request ID (i), + Request ID (vi64), Track Namespace (..), - Track Name Length (i), + Track Name Length (vi64), Track Name (..), - Track Alias (i), + Track Alias (vi64), Group Order (8), Content Exists (8), [Largest Location (Location),] Forward (8), - Number of Parameters (i), + Number of Parameters (vi64), Parameters (..) ... } ~~~ @@ -2322,16 +2364,16 @@ authorization and acceptance of a PUBLISH message, and establish a subscription. ~~~ PUBLISH_OK Message { - Type (i) = 0x1E, + Type (vi64) = 0x1E, Length (16), - Request ID (i), + Request ID (vi64), Forward (8), Subscriber Priority (8), Group Order (8), - Filter Type (i), + Filter Type (vi64), [Start Location (Location),] - [End Group (i),] - Number of Parameters (i), + [End Group (vi64),] + Number of Parameters (vi64), Parameters (..) ..., } ~~~ @@ -2393,11 +2435,11 @@ The format of `PUBLISH_DONE` is as follows: ~~~ PUBLISH_DONE Message { - Type (i) = 0xB, + Type (vi64) = 0xB, Length (16), - Request ID (i), - Status Code (i), - Stream Count (i), + Request ID (vi64), + Status Code (vi64), + Stream Count (vi64), Error Reason (Reason Phrase) } ~~~ @@ -2477,7 +2519,7 @@ A Standalone Fetch includes this structure: ~~~ Standalone Fetch { Track Namespace (..), - Track Name Length (i), + Track Name Length (vi64), Track Name (..), Start Location (Location), End Location (Location) @@ -2519,8 +2561,8 @@ A Joining Fetch includes this structure: ~~~ Joining Fetch { - Joining Request ID (i), - Joining Start (i) + Joining Request ID (vi64), + Joining Start (vi64) } ~~~ @@ -2558,15 +2600,15 @@ The format of FETCH is as follows: ~~~ FETCH Message { - Type (i) = 0x16, + Type (vi64) = 0x16, Length (16), - Request ID (i), + Request ID (vi64), Subscriber Priority (8), Group Order (8), - Fetch Type (i), + Fetch Type (vi64), [Standalone (Standalone Fetch),] [Joining (Joining Fetch),] - Number of Parameters (i), + Number of Parameters (vi64), Parameters (..) ... } ~~~ @@ -2648,13 +2690,13 @@ but the FETCH_OK MUST NOT be sent until the End Location is known. ~~~ FETCH_OK Message { - Type (i) = 0x18, + Type (vi64) = 0x18, Length (16), - Request ID (i), + Request ID (vi64), Group Order (8), End Of Track (8), End Location (Location), - Number of Parameters (i), + Number of Parameters (vi64), Parameters (..) ... } ~~~ @@ -2702,9 +2744,9 @@ The format of `FETCH_CANCEL` is as follows: ~~~ FETCH_CANCEL Message { - Type (i) = 0x17, + Type (vi64) = 0x17, Length (16), - Request ID (i) + Request ID (vi64) } ~~~ {: #moq-transport-fetch-cancel title="MOQT FETCH_CANCEL Message"} @@ -2748,11 +2790,11 @@ publisher is authorized to publish tracks under this namespace. ~~~ PUBLISH_NAMESPACE Message { - Type (i) = 0x6, + Type (vi64) = 0x6, Length (16), - Request ID (i), + Request ID (vi64), Track Namespace (..), - Number of Parameters (i), + Number of Parameters (vi64), Parameters (..) ... } ~~~ @@ -2772,9 +2814,9 @@ successful authorization and acceptance of a PUBLISH_NAMESPACE message. ~~~ PUBLISH_NAMESPACE_OK Message { - Type (i) = 0x7, + Type (vi64) = 0x7, Length (16), - Request ID (i) + Request ID (vi64) } ~~~ {: #moq-transport-pub-ns-ok format title="MOQT PUBLISH_NAMESPACE_OK Message"} @@ -2789,8 +2831,9 @@ intent to stop serving new subscriptions for tracks within the provided Track Namespace. ~~~ + PUBLISH_NAMESPACE_DONE Message { - Type (i) = 0x9, + Type (vi64) = 0x9, Length (16), Track Namespace (..) } @@ -2808,10 +2851,10 @@ within the provided Track Namespace. ~~~ PUBLISH_NAMESPACE_CANCEL Message { - Type (i) = 0xC, + Type (vi64) = 0xC, Length (16), Track Namespace (..), - Error Code (i), + Error Code (vi64), Error Reason (Reason Phrase) } ~~~ @@ -2835,11 +2878,11 @@ subscriptions, as well as future updates to the set. ~~~ SUBSCRIBE_NAMESPACE Message { - Type (i) = 0x11, + Type (vi64) = 0x11, Length (16), - Request ID (i), + Request ID (vi64), Track Namespace Prefix (..), - Number of Parameters (i), + Number of Parameters (vi64), Parameters (..) ... } ~~~ @@ -2887,9 +2930,9 @@ namespace subscriptions. ~~~ SUBSCRIBE_NAMESPACE_OK Message { - Type (i) = 0x12, + Type (vi64) = 0x12, Length (16), - Request ID (i), + Request ID (vi64), } ~~~ {: #moq-transport-sub-ann-ok format title="MOQT SUBSCRIBE_NAMESPACE_OK @@ -2909,7 +2952,7 @@ The format of `UNSUBSCRIBE_NAMESPACE` is as follows: ~~~ UNSUBSCRIBE_NAMESPACE Message { - Type (i) = 0x14, + Type (vi64) = 0x14, Length (16), Track Namespace Prefix (..) } @@ -3072,7 +3115,7 @@ Key-Value-Pairs, in bytes. ~~~ Extensions { - Extension Headers Length (i), + Extension Headers Length (vi64), Extension headers (..), } ~~~ @@ -3109,13 +3152,13 @@ An `OBJECT_DATAGRAM` carries a single object in a datagram. ~~~ OBJECT_DATAGRAM { - Type (i) = 0x0-0x7,0x20-21,0x24-25 - Track Alias (i), - Group ID (i), - [Object ID (i),] + Type (vi64) = 0x0-0x7,0x20-21,0x24-25 + Track Alias (vi64), + Group ID (vi64), + [Object ID (vi64),] [Publisher Priority (8),] [Extensions (..),] - [Object Status (i),] + [Object Status (vi64),] [Object Payload (..),] } ~~~ @@ -3215,10 +3258,10 @@ flow control, while the sender waits for flow control to send the message. ~~~ SUBGROUP_HEADER { - Type (i) = 0x10..0x1D, - Track Alias (i), - Group ID (i), - [Subgroup ID (i),] + Type (vi64) = 0x10..0x1D, + Track Alias (vi64), + Group ID (vi64), + [Subgroup ID (vi64),] [Publisher Priority (8),] } ~~~ @@ -3320,10 +3363,10 @@ unless there is an Prior Object ID Gap extesnion header (see ~~~ { - Object ID Delta (i), + Object ID Delta (vi64), [Extensions (..),] - Object Payload Length (i), - [Object Status (i),] + Object Payload Length (vi64), + [Object Status (vi64),] [Object Payload (..),] } ~~~ @@ -3441,8 +3484,8 @@ track requested in the Fetch message identified by `Request ID`. ~~~ FETCH_HEADER { - Type (i) = 0x5, - Request ID (i), + Type (vi64) = 0x5, + Request ID (vi64), } ~~~ {: #fetch-header-format title="MOQT FETCH_HEADER"} @@ -3452,13 +3495,13 @@ Each object sent on a fetch stream after the FETCH_HEADER has the following form ~~~ { - Group ID (i), - Subgroup ID (i), - Object ID (i), + Group ID (vi64), + Subgroup ID (vi64), + Object ID (vi64), Publisher Priority (8), Extensions (..), - Object Payload Length (i), - [Object Status (i),] + Object Payload Length (vi64), + [Object Status (vi64),] [Object Payload (..),] } ~~~ @@ -3572,7 +3615,7 @@ Headers of the Object. ~~~ Immutable Extensions { Type (0xB), - Length (i), + Length (vi64), Key-Value-Pair (..) ... } ~~~