diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index bc5e58d6b39..762ea095e52 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -21,6 +21,12 @@ namespace prefix is illegal before draft 16), so a link to a peer without the MoQ Solicit extension, such as moxygen, learns only what that peer announces unasked. moxygen announces nothing unasked on draft 14. +A track from a moq-transport publisher keeps its Object IDs, object properties, +and END\_OF\_GROUP status objects across a moq-lite-07 link, since relays +always offer the [ietf extension](/draft/moq-ietf) that carries them. Over an +older moq-lite link they are lost: a moq-transport subscriber behind it sees +consecutive objects with no properties. + When a moq-lite-04 or later peer withdraws a broadcast, the routes relayed through it go with it at once. A change of best route is announced after 300 ms, so stale paths are retracted once instead of advertised in turn; diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index b6c863dafce..f7cfa051330 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -35,6 +35,7 @@ bind = "/run/moq/internal.sock" allow.uid = [1001] [listen.extensions] # moq-transport SETUP extensions to offer, each on by default. + # The relay always offers ietf, for moq-lite-07 relay links. auth = false # Decline MoQ Auth (draft 17+). solicit = false # Decline MoQ Solicit, so peers may announce unasked. epoch = false # Decline MoQ Epoch, so routes over moq-transport carry no epoch (draft 17+). diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 2e9c0f6bfb2..59605edbf21 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -31,7 +31,7 @@ subset drops. What a peer actually observes against this implementation: - **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. On draft 17 and later, a `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. Message parameters follow the negotiated draft's lists: drafts 14 and 15 ignore an unknown or misplaced parameter, draft 16 ignores one defined only for another message but closes the session on an unknown one, and draft 17 and later close it on both. Other malformed control input closes the session with the draft's code too, such as a server `SETUP` carrying `PATH` or `AUTHORITY`, a request cut short by FIN, or a second `GOAWAY` on one stream; a first `GOAWAY` on a request stream is legal. - **One `SETUP` credential**, forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A second `SETUP` token closes the session. We advertise no token cache, so an alias reference in `SETUP` closes it with `PROTOCOL_VIOLATION`, one on a request with `UNKNOWN_AUTH_TOKEN_ALIAS`, and a registration on a request with `AUTH_TOKEN_CACHE_OVERFLOW`. Where the Rust side authorizes the peer or verifies tokens, a token on a `SUBSCRIBE` or `PUBLISH_NAMESPACE` is verified like an in-band session token and authorizes that one request alone, even where that authorization already covers it; it never widens the session. It is refused with `NOT_SUPPORTED` when nothing verifies it, when it is empty, or when its Token Type is anything but 0 (out of band). A side that does neither, JavaScript included, ignores the token. Rust refuses a request carrying more than one distinct token with `NOT_SUPPORTED`, since it verifies one; JavaScript, which verifies none, ignores them all. A token-authorized `SUBSCRIBE` still stays within the grant the peer gave us. A token-authorized `PUBLISH_NAMESPACE` needs a grant covering everything beneath the namespace, and the tracks we subscribe under it rely on that announce instead of our limit, ending with it. An update renews the token, except on a drafts 14 and 15 `PUBLISH_NAMESPACE`, which has no update, and a refused renewal ends only that request. Rust and JavaScript send the token a route names (`Route::auth`) on its `PUBLISH_NAMESPACE`, including the one drafts 14 and 15 answer a solicited `SUBSCRIBE_NAMESPACE` with, and swapping it renews the request with `REQUEST_UPDATE` from draft 16, or ends and re-sends it before; the inline `NAMESPACE` that answers a solicited `SUBSCRIBE_NAMESPACE` from draft 16 carries no token. The token belongs to the session that added it, so a reconnect means adding it again and re-announcing. A token on any other request is decoded and grants nothing, and a request repeating one is refused with `MALFORMED_AUTH_TOKEN`. `SUBSCRIBE_TRACKS` reads its namespace before refusal; its token is not decoded. On draft 17 and later, the negotiated [MoQ Auth extension](/concept/moq-lite#authorization) accepts additional session tokens in band. - **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, `SUBSCRIBE_TRACKS`, and the fetch forms above get `NOT_SUPPORTED`. Range Filters get `INVALID_FILTER` on draft 19 and later because the advertised filter limit is zero. On draft 21 and later, namespaces whose first tuple field is exactly `.` or `.session` get `DOES_NOT_EXIST` before application lookup; other dot prefixes still reach the application. Subscription updates accept priority, negotiated subscriber max age, and delivery timeouts; Rust also renews request tokens and judges `NEW_GROUP_REQUEST` as a join (see dynamic groups below). Other supported-but-unimplemented preferences end that subscription; a `TRACK_PROPERTY_FILTER` there closes the session with `PROTOCOL_VIOLATION`, since it belongs only to `SUBSCRIBE_TRACKS`. On draft 18 and later a namespace update may change its prefix; suffixes after the acknowledgement are relative to that new prefix. -- **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects. +- **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0, including across a moq-lite-07 hop between two relays that negotiate the [ietf](/draft/moq-ietf) extension. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. On a timed track the frame holds each object's time, so a mutable Timestamp that only repeats the immutable one is not restated; a status object has no frame, so it keeps its Timestamp among its properties. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects. - **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` (draft 15 and later) counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. A moq-lite-07 hop (`moq-lite-07-wip`, opt-in) carries the same demand natively: the ratio in `TRACK_INFO` and the asked-for group in `SUBSCRIBE_UPDATE`. Earlier moq-lite versions carry neither, so a track received over one never refreshes. - **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127. A relay's upstream subscription carries the highest priority its subscribers ask for and updates it as they come and go; its group order stays as the `SUBSCRIBE` asked, since no draft lets an update change it. - **Size.** An object extension block larger than 64 KiB ends that subgroup stream. The session stays up. This cap is ours, not the draft's. @@ -51,6 +51,11 @@ its `peek()` or `changed()` methods; session statistics do not request PROBE. Both libraries offer solicit, auth, and epoch (draft 17 and later) unless a side's `extensions` setting declines one, which connects it as a peer that does not speak that extension. The pooled JavaScript `Connection` has no such setting yet. +[ietf](/draft/moq-ietf) goes the other way: it extends moq-lite-07 to carry this +object state between relays. moq-lite-07 is still a work in progress +(`moq-lite-07-wip`), negotiated only when both sides enable it, so a peer that +does not offer it does not carry this state. Only Rust offers the extension, when +`extensions.ietf` is set, and `moq-relay` always does on moq-lite-07. [moq-e2ee](/draft/moq-e2ee) is not a transport extension. It encrypts application payloads, so relays still forward named tracks they cannot read. See [Encryption](/concept/hang#encryption). diff --git a/drafts/draft-lcurley-moq-ietf.md b/drafts/draft-lcurley-moq-ietf.md new file mode 100644 index 00000000000..bfab6d046f1 --- /dev/null +++ b/drafts/draft-lcurley-moq-ietf.md @@ -0,0 +1,277 @@ +--- +title: "MoQ IETF Extension" +abbrev: "moq-ietf" +category: info + +docname: draft-lcurley-moq-ietf-latest +submissiontype: IETF # also: "independent", "editorial", "IAB", or "IRTF" +number: +date: +v: 3 +area: wit +workgroup: moq + +author: + - + fullname: Luke Curley + email: kixelated@gmail.com + +normative: + moql: I-D.lcurley-moq-lite + moqt: I-D.ietf-moq-transport + +informative: + +--- abstract + +This document defines an extension for moq-lite {{moql}} that carries the object state of MoQ Transport {{moqt}} across a moq-lite session between two relays. +A track a MoQ Transport publisher sends through relay A, then over moq-lite to relay B, reaches a MoQ Transport subscriber of relay B as it would through one relay: with its Object IDs, gaps, properties, and END_OF_GROUP status. + +--- note_Note_to_Readers + +This document was generated by an AI model from the implementation at [github.com/moq-dev/moq](https://github.com/moq-dev/moq) and is maintained alongside it. +Submit an [issue](https://github.com/moq-dev/moq/issues) or [PR](https://github.com/moq-dev/moq/pulls) if this spec sucks and you want to fix anything. + +--- middle + +# Conventions and Definitions +{::boilerplate bcp14-tagged} + +A **relayed** group or datagram arrived from a MoQ Transport publisher, so it has object state that moq-lite cannot express. +A **plain** one has none: its Object IDs are its frame indices, it has no properties, and its group ends where its last frame does. + + +# Introduction +moq-lite numbers the frames of a group consecutively from 0 and carries nothing else about them. +{{moqt}} objects carry more: Object IDs that may skip, properties, and an END_OF_GROUP status object at its own Object ID. +A relay preserves this state between MoQ Transport peers, but loses it on a moq-lite hop, so a track crossing two relays arrives changed. + +This extension carries that state across the hop. +It is meant for relays: an endpoint that does not relay MoQ Transport content would receive state it can only discard. + + +# Setup Negotiation +An endpoint offers the extension with the following Setup Parameter ({{moql}} SETUP): + +|------------|------|-------------| +| ID | Name | Value | +|-----------:|:-----|:------------| +| 0x49455446 | IETF | (empty) | +|------------|------|-------------| + +The value MUST be empty; a receiver MUST close the session with a PROTOCOL_VIOLATION otherwise. +The extension is negotiated only when both endpoints offer it, and only on moq-lite-07 and later. +An endpoint MUST NOT send any field this document defines unless the extension is negotiated, and MUST NOT parse a Group Stream, FETCH response, Track Stream, or datagram from the peer until it has the peer's SETUP and so knows whether it was. +An endpoint MAY drop a datagram that arrives before then. + + +# Group Streams {#group} +When the extension is negotiated, a Group Stream carries a Group State after the GROUP message, and an Object Record before each FRAME. +A FETCH response carries the same, with the Group State first. + +~~~ +Group Stream { + GROUP Message + Group State (i) + Object (..) ... +} + +Object { + Object Record + [FRAME Message] +} +~~~ + +## Group State +A bit field describing the group's relay state, or 0 for a plain group: + +- `0x1` **RELAYED**: The group is relayed. Every other bit requires it. +- `0x2` **FIRST_OBJECT**: The first record is the group's first object, as the FIRST_OBJECT state of a {{moqt}} subgroup. +- `0x4` **EXTENSIONS**: The {{moqt}} subgroup header said its objects carry properties. Without it, every record's Properties are empty. +- `0x8` **END_OF_GROUP**: The stream's end ends the group, as a {{moqt}} subgroup that contains the end of its group. + +A receiver MUST reset the stream with a PROTOCOL_VIOLATION on any other bit, a bit without RELAYED, or a record with Properties when EXTENSIONS is clear. +A publisher MUST clear FIRST_OBJECT when the stream starts after the first frame it holds, and END_OF_GROUP when the stream may stop before the end of the group, such as at a subscription's end frame. +A stream that stops at an end frame carries no END_OF_GROUP record, even when that frame is the group's last. + +Only subgroup 0 of a {{moqt}} group is carried. + +## Object Record + +~~~ +Object Record { + Object (i) + Properties Length (i) + Properties (..) +} +~~~ + +**Object**: +`(Skip << 1) | End`. +`Skip` is the Object ID for the first record on the stream, and the number of Object IDs skipped since the previous record afterwards. +`End` is 1 for the END_OF_GROUP record, which has no FRAME and is the last record on the stream: a receiver MUST reset the stream with a PROTOCOL_VIOLATION if anything follows it. + +**Properties**: +The object's [properties](#properties), in `Properties Length` bytes. +An empty one means the object has none. +A receiver MUST reset the stream if the length exceeds 65,537, the largest Property Block beside an Encoding byte. + +In a plain group, every record has a `Skip` of 0 after the first, whose Object ID is the index of its frame, no properties, and `End` of 0. +A receiver MUST reset the stream with a PROTOCOL_VIOLATION on any other record in a plain group. + +A frame index stays the position of a FRAME in the group, as in {{moql}}. +The Object ID is relay state beside it, so a plain subscriber still reads consecutive frames. + + +# Properties {#properties} +An object's properties, as one block in the encoding of the {{moqt}} draft it arrived on. +A relay forwards the block to a peer of that encoding unchanged, so the block never grows on a hop, and holds it as received rather than as a decoded list many times its size. + +~~~ +Properties { + Encoding (i) + Property Block (..) +} +~~~ + +**Encoding**: +The {{moqt}} drafts the Property Block came from, which serialize it alike and give each property the same meaning: + +| Code | Drafts | IDs | Varints | +|-----:|:-------|:----|:--------| +| 1 | 14 and 15 | absolute | QUIC | +| 2 | 16 | delta | QUIC | +| 3 | 17 | delta | draft 17 | +| 4 | 18 | delta | draft 18 | +| 5 | 19 and later | delta | draft 18 | + +A receiver MUST treat any other code as malformed, including 0: an empty Properties says the object has none. +Codes 4 and 5 serialize alike, but only drafts 19 and later assign property 0x06 to SUBGROUP_DELIVERY_TIMEOUT, so a relay knows not to forward 0x06 to a draft that would read it differently. + +**Property Block**: +Every property of the object, serialized as the {{moqt}} drafts of its encoding serialize an object's properties, in ascending ID order. +Immutable Properties (0x0b) are in the same encoding, as the publisher sent them. +It MUST NOT be empty or longer than 65,536 bytes. +On a timed track an object with a FRAME, or a datagram without a Status, MUST NOT carry one longer than 65,526 bytes, leaving room for the largest Timestamp a relay restates ([Timestamps](#timestamps)): a one-byte key and a value of up to nine bytes. +A relay MUST refuse a {{moqt}} object whose properties, less its mutable Timestamp, exceed that, so every object it forwards fits. +A receiver MUST treat a block its encoding's drafts would refuse as malformed. +The Encoding names the drafts the object came from, so a receiver MUST also treat a block as malformed on an object none of them could send with properties. +Only draft 14 lets a status object carry them, so a block on the END_OF_GROUP record MUST have Encoding 1, and a datagram with a block MUST have fields an OBJECT_DATAGRAM Type of those drafts carries ([Datagrams](#datagrams)). +Other properties are opaque to this extension. + +## Timestamps {#timestamps} +On a timed track, the FRAME's Timestamp, or the datagram's for a datagram, is the object's time, and nothing else carries it. +The Property Block MUST NOT contain a mutable Timestamp (0x10) there; a receiver MUST treat one as malformed. +A relay forwarding the object to {{moqt}} restates the time as the mutable Timestamp, unless a Timestamp inside the Immutable Properties already says it. +A sealed Timestamp is in the track's Timescale ({{moql}} TRACK_INFO), and a relay MUST NOT forward one to a peer of other units, which would change its meaning. + +On an untimed track there is no FRAME Timestamp, so a mutable Timestamp stays in the Property Block as an opaque property. +Likewise, an object without a FRAME, such as the END_OF_GROUP record or a datagram with a non-zero Status, has no time of its own beside the block, so its mutable Timestamp stays there on any track. + + +# Track Stream {#track} +When the extension is negotiated, the publisher sends a TRACK_PROPERTIES message after TRACK_INFO. + +~~~ +TRACK_PROPERTIES Message { + Message Length (i) + Encoding (i) + Property List (..) +} +~~~ + +**Encoding**: +The drafts the Property List came from, with the codes of [Properties](#properties). +A message without properties MUST have an Encoding of 0 and an empty Property List. +Track Properties start at draft 16, so any other message with an Encoding of 0 or 1 is malformed. + +**Property List**: +The {{moqt}} Track Properties a relay forwards without interpreting, serialized as the publisher's draft serializes them: in ascending ID order, with delta-encoded IDs and the varints of that encoding. +A relay keeps the publisher's encoding, so a repeated ID still costs a one-byte delta and the list never grows on a hop. +Immutable Properties (0x0b), at most one, are forwarded as the publisher's bytes, in the same encoding. + +A message MUST NOT carry more than 64 properties, nor any a relay interprets rather than forwards: MAX_CACHE_DURATION (0x04), TIMESCALE (0x08), DEFAULT_PUBLISHER_PRIORITY (0x0e), DEFAULT_PUBLISHER_GROUP_ORDER (0x22), and DYNAMIC_GROUPS (0x30). +TRACK_INFO carries what a relay keeps of them, so a second copy could only contradict it. +A message that breaks either rule is malformed. + +A relay restates up to five of those from TRACK_INFO, so it forwards at most 59 properties, and it refuses a track with more, from a {{moqt}} publisher or over this extension, as unsupported. +Dropping those five can widen the delta that spans them, so a relay also refuses a {{moqt}} track whose remaining list would not fit a TRACK_PROPERTIES message, as unsupported. + +The Immutable Properties may still hold one of those five, which a relay forwards in place of the one it would restate. +A relay acts on TRACK_INFO, so a sealed value MUST equal the one it restates: MAX_CACHE_DURATION the Max Age in milliseconds, TIMESCALE the Timescale, DEFAULT_PUBLISHER_PRIORITY the priority, and DYNAMIC_GROUPS whether its Refresh is nonzero. +A sealed DEFAULT_PUBLISHER_GROUP_ORDER is advisory: a relay serves its own order and forwards the sealed value unchanged, whatever it says. +A relay refuses a track whose sealed value differs, from a {{moqt}} publisher or over this extension, as unsupported. + +A relay neither processes nor forwards a track with a Mandatory Track Property (0x4000 to 0x7FFF), mutable or inside the Immutable Properties, so a publisher never sends one. +A receiver refuses such a track as {{moqt}} ingress does, with an unsupported extension error. + +The receiver parses the keys inside the Immutable Properties from its value, which a relay MUST NOT restate as mutable. +It SHOULD read them from the value when needed rather than hold them beside it, as a list of IDs can cost several times the value. + + +# Datagrams {#datagrams} +When the extension is negotiated, a DATAGRAM carries a Datagram State after its Group Sequence. + +~~~ +DATAGRAM Body { + Subscribe ID (i) + Group Sequence (i) + Datagram State (i) + [Object ID (i)] + [Publisher Priority (8)] + [Status (i)] + [Properties Length (i), Properties (..)] + [Timestamp (i)] + Payload (b) +} +~~~ + +**Datagram State**: +A bit field, or 0 for a plain datagram, which has none of the optional fields before the Timestamp: + +- `0x1` **RELAYED**: The datagram is relayed, so its Properties follow. Every other bit requires it. +- `0x2` **OBJECT_ID**: The Object ID follows. +- `0x4` **PRIORITY**: The {{moqt}} Publisher Priority follows. +- `0x8` **END_OF_GROUP**: The object ends its group. +- `0x10` **STATUS**: The {{moqt}} Object Status follows. + +A receiver MUST drop a datagram with any other bit, or a bit without RELAYED. + +A datagram with a Status MUST have an empty Payload, as {{moqt}} sends no payload beside one; a Normal (0) Status is an empty object. +A non-zero Status carries no object: it has no Timestamp, even on a timed track. +A receiver MUST drop a datagram whose Status no {{moqt}} draft defines: only 0 (Normal), 1 (DOES_NOT_EXIST, drafts 14 and 15), 3 (END_OF_GROUP), and 4 (END_OF_TRACK) are relayed. +It MUST also drop one whose fields no {{moqt}} OBJECT_DATAGRAM Type can carry, such as STATUS with END_OF_GROUP. +With Properties, only the drafts of their Encoding count: from draft 17 on a non-zero Status carries no properties, so one needs Encoding 1 or 2, and DOES_NOT_EXIST needs Encoding 1. + + +# Security Considerations +A peer sets how much state a receiver holds for each object, up to a 65,536-byte Property Block. +A receiver SHOULD hold the block as received, not decoded, and charge it to the group's cache budget like a payload. +A TRACK_PROPERTIES message is bounded by its Message Length and the 64-property limit, and is held once per track. + +The extension adds no authority. +A relay applies the same authorization to a relayed group as to a plain one. + + +# IANA Considerations + +This document requests one registration in the moq-lite Setup Parameters registry, if one is established. +A high, distinctive value is used to avoid collisions with the low values {{moql}} assigns. + +| Value | Name | Reference | +|:-----------|:-----|:--------------| +| 0x49455446 | IETF | This Document | + + +--- back + +# Changelog + +## Since draft-lcurley-moq-ietf-00 (in progress) + +- Initial version. + +# Acknowledgments +{:numbered="false"} + +This document was drafted with the assistance of Claude, an AI assistant by Anthropic. diff --git a/quest/m1/ietf-extension/README.md b/quest/m1/ietf-extension/README.md index 2131bf38583..d31d0303840 100644 --- a/quest/m1/ietf-extension/README.md +++ b/quest/m1/ietf-extension/README.md @@ -83,7 +83,7 @@ Work owned by this README, after the children land: ## Required -- [Relay hops](/quest/m1/ietf-extension/lite.md) - the `ietf` SETUP extension carries every crate-private field across a lite-07 hop between relays +- [Ingress-version provenance](/quest/m1/ietf-extension/lite.md) - a track crossing a lite-07 hop carries its moq-transport ingress version once, replacing per-block Encoding codes ## Related diff --git a/quest/m1/ietf-extension/lite.md b/quest/m1/ietf-extension/lite.md index fb50d652786..b70fe90fcb9 100644 --- a/quest/m1/ietf-extension/lite.md +++ b/quest/m1/ietf-extension/lite.md @@ -1,88 +1,56 @@ -# [M] The ietf extension carries moq-transport fields between relays +# [M] The ietf extension records provenance as the ingress version ## Goal -Two relays that negotiate the `ietf` SETUP extension carry every -crate-private moq-transport field across a lite-07 hop. A track forwarded -moq-transport publisher -> relay A -> relay B -> moq-transport subscriber -arrives as it would through one relay. A session without the extension is -unchanged. +A track crossing a lite-07 hop with the `ietf` SETUP extension carries its +ingress moq-transport version once, instead of an Encoding code on every +Property Block and on TRACK_PROPERTIES. A track published over moq-lite +carries none, and a peer cannot attach moq-transport state to it. Behavior +across the hop is otherwise unchanged from +[moq-dev/moq#6058](https://github.com/moq-dev/moq/pull/6058), which landed +the extension with per-block codes. ## Plan -Decided 2026-10-13 (see the [epic](/quest/m1/ietf-extension/README.md)). - -- Negotiate with a SETUP extension, like auth and solicit, not a separate - ALPN. That avoids a Version variant per lite version and leaves the lite-07 - finalize rename alone. -- Add a documented `pub ietf: bool` field on `setup::Extensions`, default - `false`. moq-relay sets it. Both sides must offer it. -- Target the current wip version. If lite-07 has finalized before this - lands, use the next wip/version. Published versions get no incompatible - framing changes. -- When negotiated, the fields are always present, with no flag bits: - - The Group message gains the explicit FIRST_OBJECT state. The first - object ID alone cannot recover the FIRST_OBJECT bit. Subgroups other - than 0 are not carried (see the [epic](/quest/m1/ietf-extension/README.md)). - - Every frame gains a `skip` varint and a length-prefixed properties block, - 2 bytes per frame when empty. - - A terminal record after the frames carries the END_OF_GROUP status - position. It is not known when a live group's opening header is sent; - frames must flow before the publisher ends the group. - - Datagrams gain their object ID, properties, and status. - - Track info gains the unknown track properties: `track::Info::properties` - (`model::object::TrackProperties`), with its sealed keys. - - Track info carries the ingress moq-transport version once, or none for a - track published over moq-lite, which has no IETF provenance and no - properties to derive rules for. Lite ingress refuses a track with no - version that carries any IETF field (track, object, or datagram - properties, or object IDs), including on a later object. Immutable - properties keep their unchanged inner bytes. Downstream IETF egress - applies today's single-relay rules from that version: refuse an - incompatible immutable encoding (drafts 14/15 carry no immutable track - block, so egress there skips that check), and across draft 19, where - 0x06 becomes SUBGROUP_DELIVERY_TIMEOUT, drop a mutable 0x06 and refuse a - sealed one. -- Record provenance as the ingress version, decided 2026-10-20. In the - model, the track's optional ingress `ietf::Version` replaces - `object::Encoding` and the `delivery_timeout` flags on `Properties` and - `TrackProperties`; both - are functions of the ingress draft. One version per track suffices because - each publisher is its own stream; a different ingress is a new instance. +Decided 2026-10-20 in +[moq-dev/moq#6072](https://github.com/moq-dev/moq/pull/6072). + +- In the model, the track's optional ingress `ietf::Version` replaces + `object::Encoding` on `object::Block` and `TrackProperties`, which already + derives 0x06's meaning from the draft instead of a flag. One + version per track suffices because each publisher is its own stream; a + different ingress is a new instance. +- On the wire, track info carries the ingress version once, or none for a + track published over moq-lite, which has no IETF provenance and no + properties to derive rules for. Records and datagrams drop their Encoding + code. Update `drafts/draft-lcurley-moq-ietf.md` and pass + `just drafts check`. +- Lite ingress refuses a track with no version that carries any IETF field + (track, object, or datagram properties, or object IDs), including on a + later object. +- Immutable properties keep their unchanged inner bytes. Downstream IETF + egress applies today's single-relay rules from that version: refuse an + incompatible immutable encoding (drafts 14/15 carry no immutable track + block, so egress there skips that check), and across draft 19, where 0x06 + becomes SUBGROUP_DELIVERY_TIMEOUT, drop a mutable 0x06 and refuse a sealed + one. - Rejected 2026-10-20: a generic crate-private `unknown` KVP block on route, track, group, frame, and datagram, tagged by source version, that would also tunnel future lite fields through a lite-07 hop. A relay cannot act on fields it forwards blindly, and most lite additions (routes, refresh, ranges, auth) change relay behavior. With no must-understand marker, only - relay-ignorable end-to-end hints could tunnel safely. The cost was a - separate model refactor and more draft surface for a speculative benefit. - Like this extension, it would have been SETUP-gated, so a receiver opts in - and plain peers never see stuffed properties. -- Dynamic-group requests are not this extension's job. Native lite-07 - carries them as refresh (TRACK_INFO `Refresh` and SUBSCRIBE_UPDATE - `Wanted Group`), decided 2026-10-16. -- Write `drafts/draft-lcurley-moq-ietf.md` for the extension and pass - `just drafts check`. List it with the other project drafts in - `doc/concept/standard.md`, and note in `doc/bin/relay/` that relays enable - it. -- js/net does not implement it and never offers it. + relay-ignorable end-to-end hints could tunnel safely. -Tests: per-feature cases through a two-relay cluster. Cover a cluster peer -without the extension (no properties), and run -`just test interop --all`. -Prove that frames arrive through both relays while the upstream group is -still open, then preserve its terminal status position. Cover FIRST_OBJECT -both set and clear with the same nonzero starting object ID, immutable -encoding provenance, and 0x06 provenance: a draft-18 publisher's object and +Tests: 0x06 provenance across the hop: a draft-18 publisher's object and track properties exit draft 19 with a mutable 0x06 dropped and a sealed one refused. Both drafts share an encoding family, so only the carried version distinguishes them. Cover a lite-published track crossing the same hop with no ingress version, and a malformed peer that sends properties on a -versionless track, at track info and on a later frame and datagram. +versionless track, at track info and on a later frame and datagram. Run +`just test interop --all`. -Public API: `setup::Extensions::ietf`. Wire: a new lite-07 SETUP extension -and the framing above, only when negotiated. +Wire: lite-07-wip only, when the extension is negotiated. ## Related -- [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - the extension targets the wip version and does not gate the cut +- [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - this changes the lite-07 wire, so it lands before the cut diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 22d9f51b48b..2c0e9fed356 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -90,8 +90,8 @@ is published; older versions are unchanged. - [Compressed tracks in Rust](/quest/m1/compress/core.md) - TRACK_INFO carries the compress flag and the frame header each compressed frame's inflated size - [Compressed tracks in js/net](/quest/m1/compress/js.md) - JS reads and writes compressed lite-07 tracks instead of refusing them - [TRACKS](/quest/m1/archive/tracks.md) - lite-07 carries the request listing a broadcast's tracks as they appear +- [Ingress-version provenance](/quest/m1/ietf-extension/lite.md) - the `ietf` extension carries a track's ingress version once instead of a code per block ## Related -- [Relay hops](/quest/m1/ietf-extension/lite.md) - the `ietf` SETUP extension targets lite-07 wip and does not gate the cut - [The moq.pro mesh runs lite-07](/quest/m3/lite07-mesh.md) - the deployment condition that follows this diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index 77ac0a8c617..fa06045ed8b 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -95,7 +95,8 @@ impl Client { self } - /// Choose which moq-transport extensions to offer in SETUP. Defaults to all of them. + /// Choose which extensions to offer in SETUP. Defaults to every moq-transport one, and + /// not [`ietf`](setup::Extensions::ietf), which only relays turn on. pub fn with_extensions(mut self, extensions: setup::Extensions) -> Self { self.extensions = extensions; self @@ -200,6 +201,7 @@ impl Client { cost: self.cost, // Filled by `lite::start` from the attached origin handles. hop: None, + ietf: self.extensions.ietf && version.has_ietf(), } } else { lite::Setup::default() diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index c5bfe888d3d..29abae75ae5 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -35,10 +35,14 @@ pub fn object_group(frames: usize, properties: bool) -> (broadcast::Producer, tr std::sync::Arc::new(crate::model::object::Fields { id: id as u64, properties: crate::model::object::Properties { - values: vec![crate::model::object::Property { - id: 0x80, - value: crate::model::object::Value::Int(96_000), - }], + block: crate::ietf::object::block( + &[crate::model::object::Property { + id: 0x80, + value: crate::model::object::Value::Int(96_000), + }], + crate::model::object::Encoding::Draft19, + ) + .unwrap(), ..Default::default() }, }) @@ -99,7 +103,7 @@ const IETF_VERSIONS: &[ietf::Version] = &[ ]; /// How many types [`lite_wire`] dispatches over. -const LITE_KINDS: u8 = 21; +const LITE_KINDS: u8 = 22; /// How many types [`ietf_wire`] dispatches over. const IETF_KINDS: u8 = 40; @@ -146,20 +150,28 @@ where /// [`roundtrip`] for a datagram body, which runs to the end of its buffer. fn datagram(data: &[u8], version: lite::Version) -> bool { - // The body doesn't say whether it carries a timestamp, so try both readings. + // The body doesn't say whether it carries a timestamp, or whether the session + // negotiated the `ietf` extension, so try every reading. + let ietf: &[bool] = match version.has_ietf() { + true => &[false, true], + false => &[false], + }; let mut any = false; - for timed in [true, false] { - let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, |_| timed) else { - continue; - }; - any = true; + for &ietf in ietf { + for timescale in [Some(crate::Timescale::MILLI), None] { + let Ok(decoded) = lite::Datagram::decode(Bytes::copy_from_slice(data), version, ietf, |_| timescale) else { + continue; + }; + any = true; - let Ok(first) = decoded.encode_bytes(version) else { - continue; - }; + let Ok(first) = decoded.encode_bytes(version) else { + continue; + }; - let echo = lite::Datagram::decode(first, version, |_| timed).expect("could not decode our own encoding"); - assert_eq!(echo, decoded, "datagram did not survive a round trip"); + let echo = + lite::Datagram::decode(first, version, ietf, |_| timescale).expect("could not decode our own encoding"); + assert_eq!(echo, decoded, "datagram did not survive a round trip"); + } } any } @@ -197,6 +209,7 @@ pub fn lite_wire(data: &[u8]) -> bool { 18 => roundtrip::(rest, version), 19 => datagram(rest, version), 20 => roundtrip::(rest, version), + 21 => roundtrip::(rest, version), _ => unreachable!("kind is taken modulo LITE_KINDS"), } } @@ -432,6 +445,7 @@ impl LiteSample { sequence: 1_234, timestamp: Some(1_234_567_890), payload: bytes::Bytes::new(), + ietf: None, } .encode(w, version) .unwrap(), @@ -463,9 +477,11 @@ impl LiteSample { } Self::Group => lite::Group::decode(r, version).map(|_| 1).unwrap(), Self::Subscribe => lite::Subscribe::decode(r, version).map(|_| 1).unwrap(), - Self::Datagram => lite::Datagram::decode(bytes::Bytes::copy_from_slice(data), version, |_| true) - .map(|_| 1) - .unwrap(), + Self::Datagram => lite::Datagram::decode(bytes::Bytes::copy_from_slice(data), version, false, |_| { + Some(crate::Timescale::MILLI) + }) + .map(|_| 1) + .unwrap(), Self::Setup => lite::Setup::decode(r, version).map(|_| 1).unwrap(), } } diff --git a/rs/moq-net/src/ietf/datagram.rs b/rs/moq-net/src/ietf/datagram.rs index 4036dabb524..1383a620044 100644 --- a/rs/moq-net/src/ietf/datagram.rs +++ b/rs/moq-net/src/ietf/datagram.rs @@ -56,16 +56,9 @@ impl ObjectDatagram { _ => kind & !flag::ALL == 0 && !(kind & flag::STATUS != 0 && kind & flag::END_OF_GROUP != 0), } } -} - -/// Whether `version` lets a datagram of Object Status `status` carry properties: from -/// draft-17 on, only a Normal Object may. -pub(super) fn carries_properties(status: u64, version: Version) -> bool { - status == 0 || matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16) -} -impl Encode for ObjectDatagram { - fn encode(&self, w: &mut Encoder<'_>, version: Version) -> Result<(), EncodeError> { + /// The Type bits this datagram's fields set. + fn kind(&self) -> u64 { let mut kind = 0; if self.properties.is_some() { kind |= flag::PROPERTIES; @@ -82,6 +75,51 @@ impl Encode for ObjectDatagram { if matches!(self.body, DatagramBody::Status(_)) { kind |= flag::STATUS; } + kind + } +} + +impl crate::model::datagram::Wire { + /// Whether a moq-transport draft defines a datagram of this shape, as its ingress checks + /// one, and a draft of its block's encoding when it has one: that draft sent it. Egress + /// resolves the Object ID and priority each draft needs. + pub(crate) fn defined(&self) -> bool { + let shape = ObjectDatagram { + track_alias: 0, + group_id: 0, + object_id: self.object_id, + publisher_priority: self.priority, + end_of_group: self.end_of_group, + properties: self.properties.block.is_some().then(Vec::new), + body: match self.status { + Some(status) => DatagramBody::Status(status), + None => DatagramBody::Payload(Bytes::new()), + }, + }; + let kind = shape.kind(); + let family = self.properties.block.as_ref().map(|block| block.encoding); + Version::ALL + .into_iter() + .filter(|version| family.is_none_or(|family| super::object::encoding(*version) == family)) + .any(|version| { + ObjectDatagram::valid(kind, version) + && self.status.is_none_or(|status| { + super::object::status_defined(status, version) + && (family.is_none() || carries_properties(status, version)) + }) + }) + } +} + +/// Whether `version` lets a datagram of Object Status `status` carry properties: from +/// draft-17 on, only a Normal Object may. +pub(super) fn carries_properties(status: u64, version: Version) -> bool { + status == 0 || matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16) +} + +impl Encode for ObjectDatagram { + fn encode(&self, w: &mut Encoder<'_>, version: Version) -> Result<(), EncodeError> { + let kind = self.kind(); if !Self::valid(kind, version) { return Err(EncodeError::InvalidState); } diff --git a/rs/moq-net/src/ietf/group.rs b/rs/moq-net/src/ietf/group.rs index 74c504afda7..5e27e089b33 100644 --- a/rs/moq-net/src/ietf/group.rs +++ b/rs/moq-net/src/ietf/group.rs @@ -15,7 +15,7 @@ const PROP_TIMESTAMP: u64 = 0x10; /// Implementation limit for an object's extension (property) block, independent of the /// IETF draft. Checked at the length prefix, before the block is buffered. -pub(super) const MAX_OBJECT_EXTENSIONS: usize = 64 * 1024; +pub(crate) const MAX_OBJECT_EXTENSIONS: usize = 64 * 1024; /// The length prefix of an object's extension block, refused past [`MAX_OBJECT_EXTENSIONS`]. #[derive(Debug)] diff --git a/rs/moq-net/src/ietf/mod.rs b/rs/moq-net/src/ietf/mod.rs index fb9b4ecdef0..6b08cb6ea84 100644 --- a/rs/moq-net/src/ietf/mod.rs +++ b/rs/moq-net/src/ietf/mod.rs @@ -28,10 +28,10 @@ mod location; pub(crate) mod max_age; pub mod message; mod namespace; -mod object; +pub(crate) mod object; pub mod peer; mod priority; -mod properties; +pub(crate) mod properties; mod publish; mod publish_namespace; #[cfg(feature = "async")] diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index 748951d0811..e95fab140fa 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -3,30 +3,76 @@ use bytes::Bytes; use super::Version; use crate::{ Error, Timescale, Timestamp, - coding::{Decoder, Encoder}, + coding::{Decoder, Encoder, Form}, model::object::{Encoding, Properties, Property, Value}, }; -pub(super) fn encoding(version: Version) -> Encoding { +pub(crate) fn encoding(version: Version) -> Encoding { match version { - Version::Draft14 | Version::Draft15 => Encoding::Absolute, - Version::Draft16 => Encoding::DeltaQuic, - Version::Draft17 => Encoding::Delta { seven: false }, - _ => Encoding::Delta { seven: true }, + Version::Draft14 | Version::Draft15 => Encoding::Draft14, + Version::Draft16 => Encoding::Draft16, + Version::Draft17 => Encoding::Draft17, + Version::Draft18 => Encoding::Draft18, + _ => Encoding::Draft19, } } +/// Whether lists in encodings `a` and `b` are the same bytes: the same keys and varints. +pub(crate) fn same_bytes(a: Encoding, b: Encoding) -> bool { + let form = |encoding| (encoding == Encoding::Draft14, Form::from(family(encoding))); + form(a) == form(b) +} + +/// Whether property 0x06 means SUBGROUP_DELIVERY_TIMEOUT in a list from `encoding`. +pub(crate) fn delivery_timeout(encoding: Encoding) -> bool { + has_delivery_timeout(family(encoding)) +} + +/// The drafts that serialize properties in the `family` encoding, one of which sent any +/// block claiming it. +pub(crate) fn drafts(family: Encoding) -> impl Iterator { + Version::ALL + .into_iter() + .filter(move |version| encoding(*version) == family) +} + /// Draft-19 assigns property 0x06 to SUBGROUP_DELIVERY_TIMEOUT. -pub(super) fn has_delivery_timeout(version: Version) -> bool { +pub(crate) fn has_delivery_timeout(version: Version) -> bool { !matches!( version, Version::Draft14 | Version::Draft15 | Version::Draft16 | Version::Draft17 | Version::Draft18 ) } +/// Object status: the object does not exist, defined by drafts 14 and 15 only. +pub(crate) const DOES_NOT_EXIST: u64 = 0x1; +/// Object status: no object at or past this location in the group exists. +pub(crate) const END_OF_GROUP: u64 = 0x3; +/// Object status: no object at or past this location exists (every implemented draft). +pub(crate) const END_OF_TRACK: u64 = 0x4; + +/// Whether `version` defines the Object Status `status`, 0 being Normal. +pub(crate) fn status_defined(status: u64, version: Version) -> bool { + match status { + 0 | END_OF_GROUP | END_OF_TRACK => true, + DOES_NOT_EXIST => matches!(version, Version::Draft14 | Version::Draft15), + _ => false, + } +} + +/// Refuse the properties of an object with a frame on a track in `timescale` if they +/// leave no room for the Timestamp egress restates. +pub(crate) fn check_frame(properties: &Properties, timescale: Option) -> Result<(), Error> { + // A list at the limit with a small Timestamp cannot take back a larger one on egress. + match properties.heap() > max_block(timescale) as u64 { + true => Err(Error::Unsupported), + false => Ok(()), + } +} + /// Only draft-14 lets a status object, such as END_OF_GROUP, carry properties. #[cfg(feature = "async")] -pub(super) fn status_has_properties(version: Version) -> bool { +pub(crate) fn status_has_properties(version: Version) -> bool { version == Version::Draft14 } @@ -39,34 +85,66 @@ pub(super) fn check_status(version: Version, properties: &Properties) -> Result< } } -pub(super) struct Decoded { +pub(crate) struct Decoded { pub properties: Properties, pub timestamp: Option, pub gap: Option, } +/// The largest properties block an object may carry, which a relay forwards unchanged. +pub(crate) const MAX_BLOCK: usize = super::group::MAX_OBJECT_EXTENSIONS; + +/// The largest block a relay holds for an object on a track in `timescale`. +/// +/// On a timed track, egress adds the frame's Timestamp to the block, so the block leaves +/// room for the largest one any draft encodes. Refusing a larger block on ingress keeps +/// every egress within [`MAX_BLOCK`]. +pub(crate) fn max_block(timescale: Option) -> usize { + if timescale.is_none() { + return MAX_BLOCK; + } + // A Timestamp's value is a QUIC varint at most, and its key, a delta of at most 0x10, + // only shrinks the key of the property after it. + let largest = [Version::Draft14, Version::Draft16, Version::Draft17, Version::Draft18] + .into_iter() + .map(|version| { + let form = version.into(); + crate::coding::varint::size(0x10, form).unwrap() + crate::coding::varint::size((1 << 62) - 1, form).unwrap() + }) + .max() + .unwrap(); + MAX_BLOCK - largest +} + struct List { - properties: Properties, + /// In arrival order, without the mutable Timestamp. Values borrow the input. + values: Vec, + timestamp: Option, time: Option, gap: Option, - sealed_time: bool, + sealed_time: Option, + immutable: bool, } -fn list(data: &Bytes, version: Version, immutable: bool) -> Result { +/// Parse a property list. `lift` takes the mutable Timestamp out of `values`, as a timed +/// track's frame holds it. +fn list(data: &Bytes, version: Version, immutable: bool, lift: bool) -> Result { let keys = encoding(version); let mut decoder = Decoder::new(data, version.into()); let mut result = List { - properties: Properties::default(), + values: Vec::new(), + timestamp: None, time: None, gap: None, - sealed_time: false, + sealed_time: None, + immutable: false, }; let mut previous = 0u64; while !decoder.is_empty() { let key = decoder.varint()?; let id = match keys { - Encoding::Absolute => key, - Encoding::Delta { .. } | Encoding::DeltaQuic => previous.checked_add(key).ok_or(Error::MalformedTrack)?, + Encoding::Draft14 => key, + _ => previous.checked_add(key).ok_or(Error::MalformedTrack)?, }; previous = id; let value = if id % 2 == 0 { @@ -76,10 +154,12 @@ fn list(data: &Bytes, version: Version, immutable: bool) -> Result } if id == 0x10 { result.time = Some(value); - if result.properties.timestamp.replace(value).is_some() { + if result.timestamp.replace(value).is_some() { return Err(Error::MalformedTrack); } - continue; + if lift { + continue; + } } Value::Int(value) } else { @@ -87,14 +167,13 @@ fn list(data: &Bytes, version: Version, immutable: bool) -> Result if bytes.len() > u16::MAX as usize { return Err(Error::MalformedTrack); } - // A small cached property must not pin the reader's larger receive buffer. - let bytes = Bytes::copy_from_slice(bytes); + let bytes = data.slice_ref(bytes); if id == 0x0b { - if immutable || result.properties.immutable.replace(keys).is_some() { + if immutable || std::mem::replace(&mut result.immutable, true) { return Err(Error::MalformedTrack); } - let nested = list(&bytes, version, true).map_err(|_| Error::MalformedTrack)?; - result.sealed_time = nested.time.is_some(); + let nested = list(&bytes, version, true, true).map_err(|_| Error::MalformedTrack)?; + result.sealed_time = nested.time; result.time = result.time.or(nested.time); if let Some(gap) = nested.gap && result.gap.replace(gap).is_some() @@ -104,108 +183,241 @@ fn list(data: &Bytes, version: Version, immutable: bool) -> Result } Value::Bytes(bytes) }; - result.properties.values.push(Property { id, value }); + result.values.push(Property { id, value }); } Ok(result) } -pub(super) fn read(data: &Bytes, version: Version, timescale: Option) -> Result { - let mut parsed = list(data, version, false)?; - parsed.properties.timescale = timescale.filter(|_| parsed.time.is_some()); - parsed.properties.sealed_time = parsed.sealed_time; - parsed.properties.delivery_timeout = has_delivery_timeout(version); - let timestamp = match (parsed.time, timescale) { - (Some(value), Some(timescale)) => Some(Timestamp::new(value, timescale).map_err(|_| Error::MalformedTrack)?), - _ => None, - }; - Ok(Decoded { - properties: parsed.properties, - timestamp, +/// Serialize `values` as `encoding` does, in ascending ID order. Equal IDs keep their order. +fn serialize<'a>(values: impl IntoIterator, encoding: Encoding) -> Result, Error> { + let mut sorted: Vec<_> = values.into_iter().collect(); + sorted.sort_by_key(|property| property.id); + let mut out = Vec::new(); + let mut encoder = Encoder::new(&mut out, family(encoding).into()); + let mut previous = 0; + for property in sorted { + encoder.varint(match encoding { + Encoding::Draft14 => property.id, + _ => property.id - previous, + })?; + previous = property.id; + match &property.value { + Value::Int(value) => encoder.varint(*value)?, + Value::Bytes(value) => encoder.bytes(value)?, + } + } + Ok(out) +} + +/// Encode `values` as the block of an object whose properties arrived as `encoding`, or +/// `None` without any. +/// +/// Sorting a delta-encoded list, which arrives ascending, and dropping its Timestamp +/// never grows it, so the block fits wherever the publisher's list did. +pub(crate) fn block(values: &[Property], encoding: Encoding) -> Result, Error> { + if values.is_empty() { + return Ok(None); + } + Ok(Some(crate::model::object::Block { + bytes: serialize(values, encoding)?.into(), + encoding, + immutable: values.iter().any(|property| property.id == 0x0b), + })) +} + +/// What a received [`Block`](crate::model::object::Block) holds beside its bytes. +pub(crate) struct Checked { + pub immutable: bool, + pub sealed_time: Option, + pub gap: Option, +} + +/// Validate a block received as `encoding` on a track in `timescale`, as moq-transport +/// ingress validates a list, for an object that is `framed` or a frameless status. +/// +/// A framed object's mutable Timestamp on a timed track is its frame's, so one inside is +/// malformed, as is an empty block, which is sent as none. Absolute IDs must ascend, as +/// delta ones do, since egress may forward the block unchanged; Immutable Properties stay +/// as the publisher sent them. +pub(crate) fn check( + bytes: &Bytes, + encoding: Encoding, + timescale: Option, + framed: bool, +) -> Result { + let lifted = timescale.filter(|_| framed); + if bytes.is_empty() || bytes.len() > max_block(lifted) { + return Err(Error::MalformedTrack); + } + let parsed = list(bytes, family(encoding), false, lifted.is_some())?; + if lifted.is_some() && parsed.timestamp.is_some() { + return Err(Error::MalformedTrack); + } + if !parsed.values.is_sorted_by_key(|property| property.id) { + return Err(Error::MalformedTrack); + } + Ok(Checked { + immutable: parsed.immutable, + sealed_time: timed(parsed.sealed_time, timescale)?, gap: parsed.gap, }) } -/// Serialize relayed properties for `version`, with Timestamps in the `timescale` the -/// egress declares, if any. -pub(super) fn write(properties: &Properties, version: Version, timescale: Option) -> Result, Error> { - if properties - .immutable - .is_some_and(|original| original != encoding(version)) - { +/// A Timestamp `value` in the track's `timescale`, or none on an untimed track. +fn timed(value: Option, timescale: Option) -> Result, Error> { + value + .zip(timescale) + .map(|(value, timescale)| Timestamp::new(value, timescale).map_err(|_| Error::MalformedTrack)) + .transpose() +} + +/// Every property a block holds, decoded, for tests to inspect. +#[cfg(test)] +pub(crate) fn listed(properties: &Properties) -> Vec { + properties + .block + .as_ref() + .map_or_else(Vec::new, |block| values(block).unwrap()) +} + +/// Decode a block's properties, whose values borrow its bytes. +pub(crate) fn values(block: &crate::model::object::Block) -> Result, Error> { + Ok(list(&block.bytes, family(block.encoding), false, false)?.values) +} + +/// Read an object's property list on a track in `timescale`. A timed track's frame holds +/// the object's time, its mutable Timestamp or else a sealed one, so the block does not. +/// +/// The caller applies [`check_frame`] once the object has a frame: a draft-14 status +/// object, whose list arrives before its status, may fill the whole block. +pub(crate) fn read(data: &Bytes, version: Version, timescale: Option) -> Result { + decode(data, version, timescale, true) +} + +/// Read the property list of an object without a frame, such as an END_OF_GROUP status, +/// on a track in `timescale`. No frame holds its time, so a mutable Timestamp stays in the +/// block, as on an untimed track. +pub(crate) fn unframed(data: &Bytes, version: Version, timescale: Option) -> Result { + Ok(decode(data, version, timescale, false)?.properties) +} + +fn decode(data: &Bytes, version: Version, timescale: Option, framed: bool) -> Result { + let lifted = timescale.filter(|_| framed); + let parsed = list(data, version, false, lifted.is_some())?; + let properties = Properties { + sealed_time: timed(parsed.sealed_time, timescale)?, + block: block(&parsed.values, encoding(version))?, + }; + if properties.heap() > MAX_BLOCK as u64 { return Err(Error::Unsupported); } - // An untimed ingress forwards its Timestamps as is. A timed one to an egress that - // declares no units drops them, as a plain frame there carries none. - let unstamped = properties.timescale.is_some() && timescale.is_none(); - let convert = match (properties.timescale, timescale) { - (Some(from), Some(to)) if from != to => Some((from, to)), - _ => None, + Ok(Decoded { + properties, + timestamp: timed(parsed.time, timescale)?, + gap: parsed.gap, + }) +} + +/// The mutable Timestamp to send for an object whose `frame` holds its time, on a timed +/// track, in the `timescale` an egress declares. +/// +/// None when the sealed Timestamp already says it, or when the egress declares no units, +/// as a plain frame there carries none. Rewriting or dropping a sealed Timestamp would +/// break it, so that is refused. +pub(crate) fn egress_time( + properties: &Properties, + frame: Option, + timescale: Option, +) -> Result, Error> { + let Some(frame) = frame else { + return Ok(None); }; - let time = |value: u64| -> Result { - Ok(Value::Int(match convert { - Some((from, to)) => Timestamp::new(value, from) - .and_then(|timestamp| timestamp.convert(to)) - .map_err(|_| Error::Unsupported)? - .value(), - None => value, - })) + if let Some(sealed) = properties.sealed_time { + if timescale != Some(sealed.scale()) { + return Err(Error::Unsupported); + } + if frame.convert(sealed.scale()).is_ok_and(|frame| frame == sealed) { + return Ok(None); + } + } + timescale + .map(|timescale| { + frame + .convert(timescale) + .map(|time| time.value()) + .map_err(|_| Error::Unsupported) + }) + .transpose() +} + +/// A draft that serializes properties in the `encoding` family. Any draft in the family +/// parses its keys and integers the same way. +pub(crate) fn family(encoding: Encoding) -> Version { + match encoding { + Encoding::Draft14 => Version::Draft14, + Encoding::Draft16 => Version::Draft16, + Encoding::Draft17 => Version::Draft17, + Encoding::Draft18 => Version::Draft18, + Encoding::Draft19 => Version::Draft19, + } +} + +/// Serialize relayed properties for `version`, with the `frame`'s time as the mutable +/// Timestamp in the `timescale` the egress declares, if any. +pub(crate) fn write( + properties: &Properties, + frame: Option, + version: Version, + timescale: Option, +) -> Result, Error> { + let target = encoding(version); + let timestamp = egress_time(properties, frame, timescale)?; + let timestamp = timestamp.map(|value| Property { + id: 0x10, + value: Value::Int(value), + }); + let Some(block) = &properties.block else { + return serialize(×tamp, target); }; - // Rewriting or dropping an immutable Timestamp would break it; forwarding it would - // change its meaning. - if properties.sealed_time && (convert.is_some() || unstamped) { + if block.immutable && !same_bytes(block.encoding, target) { return Err(Error::Unsupported); } // Across draft-19, forwarding 0x06 would give it a different meaning. // A mutable one is dropped; a sealed one is refused. - let flipped = properties.delivery_timeout != has_delivery_timeout(version); - if flipped && sealed_key(properties, version, 0x06)? { + let flipped = delivery_timeout(block.encoding) != has_delivery_timeout(version); + // The common case: the block is already what this draft would send. + if timestamp.is_none() && !flipped && same_bytes(block.encoding, target) { + return Ok(block.bytes.to_vec()); + } + let values = values(block)?; + if flipped && sealed_key(&values, version, 0x06)? { return Err(Error::Unsupported); } - let timestamp = properties - .timestamp - .filter(|_| !unstamped) - .map(|value| { - Ok::<_, Error>(Property { - id: 0x10, - value: time(value)?, - }) - }) - .transpose()?; - let mut sorted: Vec<_> = properties - .values - .iter() - .filter(|property| property.id != 0x06 || !flipped) - .chain(timestamp.as_ref()) - .collect(); - // Delta keys require ascending order. Equal keys retain the publisher's order. - sorted.sort_by_key(|property| property.id); - let mut out = Vec::new(); - let mut encoder = Encoder::new(&mut out, version.into()); - let mut previous = 0; - for property in sorted { - encoder.varint(match encoding(version) { - Encoding::Absolute => property.id, - Encoding::Delta { .. } | Encoding::DeltaQuic => property.id - previous, - })?; - previous = property.id; - match &property.value { - Value::Int(value) => encoder.varint(*value)?, - Value::Bytes(value) => encoder.bytes(value)?, - } + let out = serialize( + values + .iter() + .filter(|property| property.id != 0x06 || !flipped) + .chain(×tamp), + target, + )?; + // Ingress leaves room for the Timestamp, but another draft's varints can be wider, so a + // block re-encoded for it may not fit: refused, as the receiver would refuse it. + if out.len() > MAX_BLOCK { + return Err(Error::Unsupported); } Ok(out) } -/// Whether the immutable block holds a property with `id`. -fn sealed_key(properties: &Properties, version: Version, id: u64) -> Result { - let Some(sealed) = properties.values.iter().find(|property| property.id == 0x0b) else { +/// Whether the immutable block among `values` holds a property with `id`. +fn sealed_key(values: &[Property], version: Version, id: u64) -> Result { + let Some(sealed) = values.iter().find(|property| property.id == 0x0b) else { return Ok(false); }; let Value::Bytes(bytes) = &sealed.value else { return Err(Error::MalformedTrack); }; - let nested = list(bytes, version, true)?; - Ok(nested.properties.values.iter().any(|property| property.id == id)) + let nested = list(bytes, version, true, true)?; + Ok(nested.values.iter().any(|property| property.id == id)) } #[cfg(test)] @@ -231,10 +443,10 @@ mod tests { ] { let decoded = read(&bytes, version, Some(Timescale::MILLI)).unwrap(); assert_eq!(decoded.timestamp, None, "{version}"); - assert!(!decoded.properties.sealed_time, "{version}"); + assert_eq!(decoded.properties.sealed_time, None, "{version}"); for timescale in [Some(Timescale::MICRO), None] { assert_eq!( - write(&decoded.properties, version, timescale).unwrap(), + write(&decoded.properties, decoded.timestamp, version, timescale).unwrap(), bytes, "{version}" ); @@ -275,7 +487,7 @@ mod tests { drop(received); assert!(dropped.load(Ordering::Relaxed)); assert_eq!( - decoded.properties.values[0].value, + listed(&decoded.properties)[0].value, Value::Bytes(Bytes::from_static(&[42])) ); } @@ -285,23 +497,29 @@ mod tests { let bytes = Bytes::from_static(&[0x0b, 2, 0x10, 42]); let decoded = read(&bytes, Version::Draft22, Some(Timescale::MILLI)).unwrap(); assert_eq!(decoded.timestamp, Some(Timestamp::from_millis(42).unwrap())); - assert_eq!(decoded.properties.timestamp, None); + assert_eq!(decoded.properties.sealed_time, decoded.timestamp); let milli = Some(Timescale::MILLI); - assert_eq!(write(&decoded.properties, Version::Draft18, milli).unwrap(), bytes); + assert_eq!( + write(&decoded.properties, decoded.timestamp, Version::Draft18, milli).unwrap(), + bytes + ); assert!(matches!( - write(&decoded.properties, Version::Draft17, milli), + write(&decoded.properties, decoded.timestamp, Version::Draft17, milli), Err(Error::Unsupported) )); // Its units cannot follow the egress's, or vanish with them, without rewriting the block. for timescale in [Some(Timescale::MICRO), None] { assert!(matches!( - write(&decoded.properties, Version::Draft18, timescale), + write(&decoded.properties, decoded.timestamp, Version::Draft18, timescale), Err(Error::Unsupported) )); } // An untimed ingress has no units to lose. let untimed = read(&bytes, Version::Draft22, None).unwrap(); - assert_eq!(write(&untimed.properties, Version::Draft18, None).unwrap(), bytes); + assert_eq!( + write(&untimed.properties, untimed.timestamp, Version::Draft18, None).unwrap(), + bytes + ); } /// The cache keeps a timed track in its own units, so a relayed Timestamp must leave @@ -311,24 +529,132 @@ mod tests { for version in [Version::Draft18, Version::Draft22] { let bytes = Bytes::from_static(&[0x10, 42, 0x20, 7]); let decoded = read(&bytes, version, Some(Timescale::MILLI)).unwrap(); - let written = write(&decoded.properties, version, Some(Timescale::MICRO)).unwrap(); + let written = write(&decoded.properties, decoded.timestamp, version, Some(Timescale::MICRO)).unwrap(); let again = read(&Bytes::from(written), version, Some(Timescale::MICRO)).unwrap(); let micros = Timestamp::new(42_000, Timescale::MICRO).unwrap(); assert_eq!(again.timestamp, Some(micros), "{version}"); - assert_eq!(again.properties.values.last().unwrap().value, Value::Int(7)); + assert_eq!(listed(&again.properties).last().unwrap().value, Value::Int(7)); // An egress that declares no units drops it, as a plain frame there has none. - let written = write(&decoded.properties, version, None).unwrap(); + let written = write(&decoded.properties, decoded.timestamp, version, None).unwrap(); let again = read(&Bytes::from(written), version, None).unwrap(); - assert_eq!(again.properties.timestamp, None, "{version}"); - assert_eq!(again.properties.values.len(), 1, "{version}"); - assert_eq!(again.properties.values[0].value, Value::Int(7)); + assert_eq!(again.timestamp, None, "{version}"); + assert_eq!(listed(&again.properties).len(), 1, "{version}"); + assert_eq!(listed(&again.properties)[0].value, Value::Int(7)); // An untimed ingress forwards it untouched. let untimed = read(&bytes, version, None).unwrap(); - assert_eq!(write(&untimed.properties, version, None).unwrap(), bytes); + assert_eq!( + write(&untimed.properties, untimed.timestamp, version, None).unwrap(), + bytes + ); } } + /// A timed track's frame holds an object's time, so egress restates it as the mutable + /// Timestamp unless the sealed one already says it. Nothing else holds a second copy that + /// could disagree. + #[test] + fn the_frame_holds_a_timed_objects_time() { + let milli = Some(Timescale::MILLI); + let at = |millis| Some(Timestamp::from_millis(millis).unwrap()); + + // Kept properties that say nothing of time still leave with the frame's. + let written = write(&Properties::default(), at(500), Version::Draft22, milli).unwrap(); + let again = read(&Bytes::from(written), Version::Draft22, milli).unwrap(); + assert_eq!(again.timestamp, at(500)); + + // A mutable Timestamp beside a different sealed one is restated from the frame. + let both = Bytes::from_static(&[0x0b, 2, 0x10, 42, 0x10 - 0x0b, 50]); + let decoded = read(&both, Version::Draft22, milli).unwrap(); + assert_eq!((decoded.timestamp, decoded.properties.sealed_time), (at(50), at(42))); + assert_eq!( + write(&decoded.properties, decoded.timestamp, Version::Draft22, milli).unwrap(), + both + ); + + // One equal to the sealed one adds nothing to it. + let equal = Bytes::from_static(&[0x0b, 2, 0x10, 42, 0x10 - 0x0b, 42]); + let decoded = read(&equal, Version::Draft22, milli).unwrap(); + assert_eq!( + write(&decoded.properties, decoded.timestamp, Version::Draft22, milli).unwrap(), + [0x0b, 2, 0x10, 42] + ); + } + + /// A timed block leaves room for the Timestamp egress restates from the frame, so even + /// the largest one leaves within [`MAX_BLOCK`]. A byte more is refused at ingress. + #[test] + fn a_timed_block_leaves_room_for_its_timestamp() { + let milli = Some(Timescale::MILLI); + let limit = max_block(milli); + assert_eq!(limit, MAX_BLOCK - 10, "a one-byte key and a nine-byte value"); + // A draft-22 block of `len` bytes: 0x20 = 1 and zero deltas, one value taking two + // bytes for an odd length. Its list adds a Timestamp in front. + let block = |len: usize| { + let mut block = vec![0x20, 1]; + if len % 2 == 1 { + block.extend([0, 0x80, 0xc8]); + } + while block.len() < len { + block.extend([0, 1]); + } + assert_eq!(block.len(), len); + Bytes::from(block) + }; + let list = |len: usize| { + let mut list = vec![0x10, 1, 0x10]; + list.extend(&block(len)[1..]); + Bytes::from(list) + }; + let decoded = read(&list(limit), Version::Draft22, milli).unwrap(); + assert_eq!(decoded.properties.heap(), limit as u64); + assert!(check_frame(&decoded.properties, milli).is_ok()); + let latest = Timestamp::new((1 << 62) - 1, Timescale::MILLI).unwrap(); + let written = write(&decoded.properties, Some(latest), Version::Draft22, milli).unwrap(); + assert_eq!(written.len(), MAX_BLOCK); + + let over = read(&list(limit + 1), Version::Draft22, milli).unwrap(); + assert!(matches!(check_frame(&over.properties, milli), Err(Error::Unsupported))); + // An untimed track has no Timestamp to restate, so its block may fill the limit. + let untimed = read(&list(MAX_BLOCK - 2), Version::Draft22, None).unwrap(); + assert!(check_frame(&untimed.properties, None).is_ok()); + + // The same bound on a block arriving over the lite hop. + let encoding = Encoding::Draft19; + assert!(check(&block(limit), encoding, milli, true).is_ok()); + assert!(check(&block(limit + 1), encoding, milli, true).is_err()); + assert!(check(&block(limit + 1), encoding, None, true).is_ok()); + } + + /// A status object has no frame to hold its time, so its mutable Timestamp stays in the + /// block on a timed track, where a framed object's is lifted out. + #[test] + fn a_status_object_keeps_its_timestamp() { + let milli = Some(Timescale::MILLI); + let list = Bytes::from_static(&[0x10, 7, 0x3e, 1]); + let framed = read(&list, Version::Draft14, milli).unwrap(); + assert_eq!(framed.timestamp, Some(Timestamp::new(7, Timescale::MILLI).unwrap())); + let status = unframed(&list, Version::Draft14, milli).unwrap(); + assert_eq!(write(&status, None, Version::Draft14, None).unwrap(), list.to_vec()); + + // Over the lite hop, only a status block may hold it. + let block = status.block.unwrap().bytes; + assert!(check(&block, Encoding::Draft14, milli, false).is_ok()); + assert!(check(&block, Encoding::Draft14, milli, true).is_err()); + } + + /// A draft-14 block crosses the lite hop in ascending order, as ingress sorts it, so + /// one whose absolute IDs descend is malformed. Its Immutable Properties may not ascend. + #[test] + fn a_draft14_block_ascends() { + let milli = Some(Timescale::MILLI); + assert!(check(&Bytes::from_static(&[0x02, 1, 0x20, 1]), Encoding::Draft14, milli, true).is_ok()); + assert!(check(&Bytes::from_static(&[0x02, 1, 0x02, 2]), Encoding::Draft14, milli, true).is_ok()); + assert!(check(&Bytes::from_static(&[0x20, 1, 0x02, 1]), Encoding::Draft14, milli, true).is_err()); + let sealed = Bytes::from_static(&[0x02, 1, 0x0b, 4, 0x20, 1, 0x02, 1]); + assert!(check(&sealed, Encoding::Draft14, milli, true).is_ok()); + } + /// Draft-19 assigns 0x06 to SUBGROUP_DELIVERY_TIMEOUT, so it cannot cross that boundary. #[test] fn key_six_follows_its_draft() { @@ -337,27 +663,39 @@ mod tests { let decoded = read(&bytes, Version::Draft22, milli).unwrap(); assert_eq!(decoded.timestamp, None); for timescale in [Some(Timescale::MICRO), None] { - assert_eq!(write(&decoded.properties, Version::Draft19, timescale).unwrap(), bytes); + assert_eq!( + write(&decoded.properties, decoded.timestamp, Version::Draft19, timescale).unwrap(), + bytes + ); } // Across draft-19 neither reading survives: a mutable one is dropped. let modern = Bytes::from_static(&[0x20, 7]); - assert_eq!(write(&decoded.properties, Version::Draft18, milli).unwrap(), modern); + assert_eq!( + write(&decoded.properties, decoded.timestamp, Version::Draft18, milli).unwrap(), + modern + ); let legacy = read(&bytes, Version::Draft18, milli).unwrap(); - assert_eq!(write(&legacy.properties, Version::Draft19, milli).unwrap(), modern); + assert_eq!( + write(&legacy.properties, legacy.timestamp, Version::Draft19, milli).unwrap(), + modern + ); // A sealed one is refused. let sealed = Bytes::from_static(&[0x0b, 2, 0x06, 42]); let decoded = read(&sealed, Version::Draft22, milli).unwrap(); - assert!(!decoded.properties.sealed_time); - assert_eq!(write(&decoded.properties, Version::Draft22, None).unwrap(), sealed); + assert_eq!(decoded.properties.sealed_time, None); + assert_eq!( + write(&decoded.properties, decoded.timestamp, Version::Draft22, None).unwrap(), + sealed + ); assert!(matches!( - write(&decoded.properties, Version::Draft18, milli), + write(&decoded.properties, decoded.timestamp, Version::Draft18, milli), Err(Error::Unsupported) )); let legacy = read(&sealed, Version::Draft18, milli).unwrap(); assert!(matches!( - write(&legacy.properties, Version::Draft19, milli), + write(&legacy.properties, legacy.timestamp, Version::Draft19, milli), Err(Error::Unsupported) )); } @@ -370,10 +708,13 @@ mod tests { // Draft-18 permits this nonminimal seven-byte value; draft-17 cannot read it. let bytes = Bytes::from_static(&[0x0b, 8, 2, 0xfc, 0, 0, 0, 0, 0, 1]); let decoded = read(&bytes, Version::Draft18, None).unwrap(); - assert_eq!(write(&decoded.properties, Version::Draft22, None).unwrap(), bytes); + assert_eq!( + write(&decoded.properties, decoded.timestamp, Version::Draft22, None).unwrap(), + bytes + ); assert!(read(&bytes, Version::Draft17, None).is_err()); assert!(matches!( - write(&decoded.properties, Version::Draft17, None), + write(&decoded.properties, decoded.timestamp, Version::Draft17, None), Err(Error::Unsupported) )); } diff --git a/rs/moq-net/src/ietf/properties.rs b/rs/moq-net/src/ietf/properties.rs index 8befea3a33b..bbdf0442a9d 100644 --- a/rs/moq-net/src/ietf/properties.rs +++ b/rs/moq-net/src/ietf/properties.rs @@ -19,7 +19,8 @@ use crate::model::object::{Property, TrackProperties, Value}; use super::{GroupOrder, Version}; -const MAX_PROPERTIES: u64 = 64; +/// The most Track Properties a message may carry, which also bounds what a relay forwards. +pub(crate) const MAX_PROPERTIES: u64 = 64; /// Maximum byte value length per spec Section 1.4.3. const MAX_KVP_VALUE_LEN: usize = (1 << 16) - 1; @@ -87,6 +88,21 @@ impl Properties { !matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16) } + /// The properties a relay states for a track it serves, from the `info` it acts on. + /// + /// We serve the newest group first by default, matching moq-lite. + pub(crate) fn restated(info: &crate::track::Info) -> Self { + Self { + max_cache_duration: info.max_age, + timescale: info.timescale, + priority: Some(super::priority::to_wire(info.priority)), + group_order: Some(GroupOrder::Descending), + // A track opted in to refresh answers a NEW_GROUP_REQUEST as a join. + dynamic_groups: info.refresh.is_some(), + unknown: TrackProperties::default(), + } + } + /// Write the block, which is the final field of the message: no count and no length, /// so the caller must not append anything after it. /// @@ -131,7 +147,7 @@ impl Properties { let mut properties: Vec<_> = known .iter() - .filter(|property| !self.unknown.sealed.contains(&property.id)) + .filter(|property| !self.unknown.sealed().any(|id| id == property.id)) .chain(&self.unknown.values) .collect(); // Delta types require ascending order. Equal types keep the publisher's order. @@ -206,16 +222,10 @@ impl Properties { let value = r.slice(len)?; if abs == IMMUTABLE { // A second block would leave the sealed list ambiguous. - if properties - .unknown - .immutable - .replace(super::object::encoding(version)) - .is_some() - { + if properties.unknown.immutable().is_some() { return Err(DecodeError::InvalidValue); } - let sealed = sealed(&mut Decoder::new(value, version.into()), &mut properties, &mut seen)?; - properties.unknown.sealed = sealed; + sealed(&mut Decoder::new(value, version.into()), &mut properties, &mut seen)?; } // A small kept property must not pin the message's larger buffer. properties.unknown.values.push(Property { @@ -225,9 +235,9 @@ impl Properties { } } - // Recorded only beside a value it describes, so a set with nothing to forward stays empty. - properties.unknown.delivery_timeout = - !properties.unknown.values.is_empty() && super::object::has_delivery_timeout(version); + // Recorded only beside a value they describe, so a set with nothing to forward stays empty. + let forwarded = !properties.unknown.values.is_empty(); + properties.unknown.encoding = forwarded.then(|| super::object::encoding(version)); Ok(properties) } @@ -265,6 +275,126 @@ impl Properties { } } +/// The Track Properties moq-net applies itself, which a relay restates from the track's +/// info rather than forwarding the publisher's. +const UNDERSTOOD: [u64; 5] = [ + MAX_CACHE_DURATION, + TIMESCALE, + DEFAULT_PUBLISHER_PRIORITY, + DEFAULT_PUBLISHER_GROUP_ORDER, + DYNAMIC_GROUPS, +]; + +/// Whether moq-net applies the Track Property `id` itself. +pub(crate) fn understood(id: u64) -> bool { + UNDERSTOOD.contains(&id) +} + +/// The most Track Properties a relay forwards, leaving room for every one it restates +/// within the [`MAX_PROPERTIES`] a message may carry. +pub(crate) const MAX_FORWARDED: usize = MAX_PROPERTIES as usize - UNDERSTOOD.len(); + +/// Check a Track Properties' Immutable Properties `block`, serialized in the `encoding` +/// family, as [`Properties::decode`] does. +pub(crate) fn check_immutable(block: &[u8], encoding: crate::model::object::Encoding) -> Result<(), DecodeError> { + // Track Properties start at draft-16, whose families all delta-encode their keys. + if encoding == crate::model::object::Encoding::Draft14 { + return Err(DecodeError::InvalidValue); + } + let version = super::object::family(encoding); + sealed( + &mut Decoder::new(block, version.into()), + &mut Properties::default(), + &mut Vec::new(), + ) +} + +impl TrackProperties { + /// The Immutable Properties block, serialized as [`Self::encoding`] says. + pub(crate) fn immutable(&self) -> Option<&Bytes> { + self.values + .iter() + .find_map(|property| match (property.id, &property.value) { + (IMMUTABLE, Value::Bytes(block)) => Some(block), + _ => None, + }) + } + + /// The keys inside Immutable Properties, which egress must not restate as mutable. + /// + /// Read from the block each time rather than held as a list, which could be many times + /// its size. Ingress checked the block, so a malformed key cannot occur and ends it. + pub(crate) fn sealed(&self) -> impl Iterator + '_ { + let mut r = self + .immutable() + .zip(self.encoding) + .map(|(block, encoding)| Decoder::new(block, super::object::family(encoding).into())); + let mut id: u64 = 0; + std::iter::from_fn(move || { + let r = r.as_mut().filter(|r| !r.is_empty())?; + id = id.checked_add(r.varint().ok()?)?; + match id.is_multiple_of(2) { + true => r.varint().ok().map(drop)?, + false => r.bytes().ok().map(drop)?, + } + Some(id) + }) + } + + /// Why a track carrying these beside `info` is neither processed nor forwarded, if it + /// is not: every ingress, moq-transport or a relay hop, refuses it here. + pub(crate) fn refused(&self, info: &crate::track::Info) -> Option { + if self.mandatory() { + return Some(crate::Error::UnsupportedExtension); + } + // Egress forwards a sealed value in place of restating `info`, so the two must agree. + if self.contradicts(&Properties::restated(info)) { + return Some(crate::Error::Unsupported); + } + // Egress could not restate the track's info beside them without overflowing. + if self.values.len() > MAX_FORWARDED { + return Some(crate::Error::Unsupported); + } + // Nor could a relay hop carry them in one message. + if !crate::lite::ietf::fits(self) { + return Some(crate::Error::Unsupported); + } + None + } + + /// Whether Immutable Properties seal a property we understand at another value than + /// the `restated` one the relay acts on. + fn contradicts(&self, restated: &Properties) -> bool { + let Some((block, encoding)) = self.immutable().zip(self.encoding) else { + return false; + }; + let mut sealed = Properties::default(); + let mut seen = Vec::new(); + let r = &mut Decoder::new(block, super::object::family(encoding).into()); + // Ingress checked the block, so a malformed one cannot occur and is refused. + if self::sealed(r, &mut sealed, &mut seen).is_err() { + return true; + } + seen.into_iter().any(|id| match id { + MAX_CACHE_DURATION => sealed.max_cache_duration != restated.max_cache_duration, + TIMESCALE => sealed.timescale != restated.timescale, + DEFAULT_PUBLISHER_PRIORITY => sealed.priority != restated.priority, + // Advisory: a relay serves its own order and forwards the publisher's preference. + DEFAULT_PUBLISHER_GROUP_ORDER => false, + DYNAMIC_GROUPS => sealed.dynamic_groups != restated.dynamic_groups, + _ => unreachable!("only the understood properties are seen"), + }) + } + + /// Whether one is a Mandatory Track Property (0x4000-0x7FFF), which by definition is + /// one moq-net does not understand: the track must be neither processed nor forwarded. + fn mandatory(&self) -> bool { + const MANDATORY: std::ops::RangeInclusive = 0x4000..=0x7fff; + self.values.iter().any(|property| MANDATORY.contains(&property.id)) + || self.sealed().any(|id| MANDATORY.contains(&id)) + } +} + /// A DYNAMIC_GROUPS value, which is a boolean: anything but 0 or 1 is malformed. pub(super) fn dynamic_groups(value: u64) -> Result { match value { @@ -274,11 +404,10 @@ pub(super) fn dynamic_groups(value: u64) -> Result { } } -/// The keys inside an Immutable Properties value, applying the ones we understand, which -/// the draft makes a processor search too. Its pairs are delta-encoded like the outer +/// Check the keys inside an Immutable Properties value, applying the ones we understand, +/// which the draft makes a processor search too. Its pairs are delta-encoded like the outer /// list, and nesting another Immutable Properties makes the track malformed. -fn sealed(r: &mut Decoder<'_>, properties: &mut Properties, seen: &mut Vec) -> Result, DecodeError> { - let mut ids = Vec::new(); +fn sealed(r: &mut Decoder<'_>, properties: &mut Properties, seen: &mut Vec) -> Result<(), DecodeError> { let mut id: u64 = 0; while !r.is_empty() { id = id.checked_add(r.varint()?).ok_or(DecodeError::BoundsExceeded)?; @@ -290,9 +419,8 @@ fn sealed(r: &mut Decoder<'_>, properties: &mut Properties, seen: &mut Vec) } r.bytes()?; } - ids.push(id); } - Ok(ids) + Ok(()) } #[cfg(test)] @@ -566,9 +694,9 @@ mod tests { let (properties, written) = round_trip(version, &block); assert_eq!(written, block, "{version}"); assert_eq!(properties.unknown.values.len(), 3, "{version}"); - assert_eq!(properties.unknown.sealed, [0x02], "{version}"); + assert!(properties.unknown.sealed().eq([0x02]), "{version}"); assert_eq!( - properties.unknown.immutable, + properties.unknown.encoding, Some(super::super::object::encoding(version)), "{version}" ); @@ -629,6 +757,147 @@ mod tests { )); } + /// A relay forwards only as many properties as leave room for every one it restates, so + /// what it sends always decodes. One more is refused at ingress. + #[test] + fn forwarded_properties_leave_room_for_the_restated() { + let unknown = |count: usize| TrackProperties { + values: (0..count as u64) + .map(|i| Property { + id: 0x40 + 2 * i, + value: Value::Int(1), + }) + .collect(), + encoding: Some(crate::model::object::Encoding::Draft19), + }; + let properties = Properties { + max_cache_duration: Some(Duration::from_secs(1)), + timescale: Some(Timescale::MILLI), + priority: Some(1), + group_order: Some(GroupOrder::Descending), + dynamic_groups: true, + unknown: unknown(MAX_FORWARDED), + }; + assert!(properties.unknown.refused(&crate::track::Info::default()).is_none()); + let mut buf = Vec::new(); + properties + .encode(&mut Encoder::new(&mut buf, Version::Draft22.into()), Version::Draft22) + .unwrap(); + assert_eq!(decode_draft22(&buf).unwrap(), properties); + + assert!(matches!( + unknown(MAX_FORWARDED + 1).refused(&crate::track::Info::default()), + Some(crate::Error::Unsupported) + )); + } + + /// Why a track whose publisher sealed `value` as the understood property `id` is + /// refused beside an info that restates 7s, 1000 Hz, priority 9, Descending, and + /// DYNAMIC_GROUPS. + fn seal(id: u64, value: u64) -> Option { + let version = Version::Draft22; + let mut block = Vec::new(); + let w = &mut Encoder::new(&mut block, version.into()); + w.varint(id).unwrap(); + w.varint(value).unwrap(); + let unknown = TrackProperties { + values: vec![Property { + id: IMMUTABLE, + value: Value::Bytes(block.into()), + }], + encoding: Some(super::super::object::encoding(version)), + }; + let info = crate::track::Info::default() + .with_max_age(Duration::from_secs(7)) + .with_timescale(Timescale::MILLI) + .with_priority(9) + .with_refresh(0); + unknown.refused(&info) + } + + /// A sealed value of a property the relay restates must be the one it acts on, since + /// egress forwards the sealed one in its place. + #[test] + fn a_sealed_max_cache_duration_matches_the_track() { + assert!(seal(MAX_CACHE_DURATION, 7000).is_none()); + assert!(matches!( + seal(MAX_CACHE_DURATION, 7001), + Some(crate::Error::Unsupported) + )); + } + + #[test] + fn a_sealed_timescale_matches_the_track() { + assert!(seal(TIMESCALE, 1000).is_none()); + assert!(matches!(seal(TIMESCALE, 900), Some(crate::Error::Unsupported))); + // Zero declares no timeline, which contradicts one. + assert!(matches!(seal(TIMESCALE, 0), Some(crate::Error::Unsupported))); + } + + #[test] + fn a_sealed_priority_matches_the_track() { + let wire = u64::from(super::super::priority::to_wire(9)); + assert!(seal(DEFAULT_PUBLISHER_PRIORITY, wire).is_none()); + assert!(matches!( + seal(DEFAULT_PUBLISHER_PRIORITY, wire + 1), + Some(crate::Error::Unsupported) + )); + } + + #[test] + fn a_sealed_group_order_is_advisory() { + // The relay serves the newest group first, but forwards the publisher's preference. + for order in [1, 2] { + assert!(seal(DEFAULT_PUBLISHER_GROUP_ORDER, order).is_none(), "{order}"); + } + + // Egress forwards the sealed block unchanged and restates no mutable order beside it. + let version = Version::Draft22; + let mut sealed = Vec::new(); + let w = &mut Encoder::new(&mut sealed, version.into()); + w.varint(DEFAULT_PUBLISHER_GROUP_ORDER).unwrap(); + w.varint(1).unwrap(); + let unknown = TrackProperties { + values: vec![Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.clone().into()), + }], + encoding: Some(super::super::object::encoding(version)), + }; + let egress = Properties { + unknown: unknown.clone(), + ..Properties::restated(&crate::track::Info::default()) + }; + let mut buf = Vec::new(); + egress + .encode(&mut Encoder::new(&mut buf, version.into()), version) + .unwrap(); + let decoded = decode_draft22(&buf).unwrap(); + assert_eq!(decoded.group_order, Some(GroupOrder::Ascending)); + assert_eq!(decoded.unknown, unknown); + } + + #[test] + fn sealed_dynamic_groups_match_the_track() { + assert!(seal(DYNAMIC_GROUPS, 1).is_none()); + assert!(matches!(seal(DYNAMIC_GROUPS, 0), Some(crate::Error::Unsupported))); + } + + /// Every property the relay restates has a sealed check above. + #[test] + fn every_understood_property_is_checked_when_sealed() { + assert_eq!( + UNDERSTOOD, + [ + MAX_CACHE_DURATION, + TIMESCALE, + DEFAULT_PUBLISHER_PRIORITY, + DEFAULT_PUBLISHER_GROUP_ORDER, + DYNAMIC_GROUPS + ] + ); + } + /// 0x4000-0x7FFF are Mandatory Track Properties, mutable or sealed. #[test] fn mandatory_properties_are_found() { diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 5670e6347db..4e7d6e9ef59 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -44,8 +44,7 @@ fn serving_subscription(subscriber_priority: u8) -> Subscription { /// INCLUDE_PROPERTIES=0, which keeps the block present but empty. /// /// Declaring the timescale is what opts the track into timestamps; every object Timestamp -/// is in these units. We serve the newest group first by default, matching moq-lite. A draft -/// without room for a property drops it on encode. +/// is in these units. A draft without room for a property drops it on encode. /// /// Fails with [`Error::Unsupported`] for Immutable Properties the draft cannot carry: /// rewriting them for its encoding would break them, and forwarding them unchanged would @@ -57,28 +56,26 @@ fn track_properties(info: &track::Info, wanted: bool, version: Version) -> Resul let mut unknown = info.properties.as_deref().cloned().unwrap_or_default(); let block = !matches!(version, Version::Draft14 | Version::Draft15); if block - && unknown - .immutable - .is_some_and(|ingress| ingress != super::object::encoding(version)) + && unknown.immutable().is_some() + && !unknown + .encoding + .is_some_and(|encoding| super::object::same_bytes(encoding, super::object::encoding(version))) { return Err(Error::Unsupported); } // Across draft-19, forwarding 0x06 would give it a different meaning, as for object // properties. A mutable one is dropped; a sealed one is refused. - if !unknown.values.is_empty() && unknown.delivery_timeout != super::object::has_delivery_timeout(version) { - if block && unknown.sealed.contains(&0x06) { + if unknown.encoding.is_some_and(|encoding| { + super::object::delivery_timeout(encoding) != super::object::has_delivery_timeout(version) + }) { + if block && unknown.sealed().any(|id| id == 0x06) { return Err(Error::Unsupported); } unknown.values.retain(|property| property.id != 0x06); } Ok(ietf::Properties { - max_cache_duration: info.max_age, - timescale: info.timescale, - priority: Some(super::priority::to_wire(info.priority)), - group_order: Some(GroupOrder::Descending), - // A track opted in to refresh answers a NEW_GROUP_REQUEST as a join. - dynamic_groups: info.refresh.is_some(), unknown, + ..ietf::Properties::restated(info) }) } @@ -184,10 +181,12 @@ async fn read_fetch( } // Relayed Object IDs need not match frame ordinals, so a relayed group is read from // its first frame and filtered by ID. Its marked gaps cover the IDs between where it - // starts and its first object; a start below that misses to the upstream. + // starts and its first object; a start below that misses to the upstream. A miss may + // be relayed too, which only the upstream knows, so it fetches the whole group. let frame_start = match (&wire, &cached) { (Some(_), Some(group)) => skip.min(group.first_frame()), - _ => skip, + (None, Some(_)) => skip, + (_, None) => 0, }; let mut group = track .fetch_group( @@ -2063,7 +2062,7 @@ where // timestamp only on drafts that can declare its units. let timescale = timescale.filter(|_| ietf::Properties::sends_timescale(version)); let properties = if let Some(fields) = fields { - let properties = super::object::write(&fields.properties, version, timescale)?; + let properties = super::object::write(&fields.properties, timestamp, version, timescale)?; (!properties.is_empty()).then_some(properties) } else { match timescale { @@ -2453,9 +2452,12 @@ where .info .timescale .filter(|_| ietf::Properties::sends_timescale(self.version)); - let fields = group.frames.iter().filter_map(|frame| frame.fields.as_deref()); - for fields in fields.chain(group.end_object.as_deref()) { - if let Err(err) = super::object::write(&fields.properties, self.version, timescale) { + let frames = group + .frames + .iter() + .filter_map(|frame| Some((frame.fields.as_deref()?, frame.timestamp))); + for (fields, frame) in frames.chain(group.end_object.as_deref().map(|end| (end, None))) { + if let Err(err) = super::object::write(&fields.properties, frame, self.version, timescale) { return self.reject_fetch(stream, msg.request_id, &err, &err.to_string()).await; } } @@ -4409,7 +4411,10 @@ impl TrackServe { Some(wire) => { // A datagram this draft cannot carry is dropped like an oversized one: it // is best-effort, and the track's groups do not depend on it. - if wire.status == Some(1) && !matches!(self.version, Version::Draft14 | Version::Draft15) { + if wire + .status + .is_some_and(|status| !super::object::status_defined(status, self.version)) + { tracing::debug!(sequence, "dropping a datagram status this draft cannot carry"); continue; } @@ -4423,7 +4428,12 @@ impl TrackServe { true => &stripped, false => &wire.properties, }; - let properties = match super::object::write(forwarded, self.version, self.timescale) { + let properties = match super::object::write( + forwarded, + datagram.datagram.timestamp, + self.version, + self.timescale, + ) { Ok(properties) => properties, Err(err) => { tracing::debug!(%err, sequence, "dropping a datagram whose properties cannot be forwarded"); @@ -5094,9 +5104,7 @@ impl GroupServe { } } -/// Object status: no object at or past this location exists. -const END_OF_GROUP: u64 = 0x3; -const END_OF_TRACK: u64 = 0x4; +use super::object::{END_OF_GROUP, END_OF_TRACK}; /// An object's header, with private relay fields when it came from an IETF peer. struct Object<'a> { @@ -5145,7 +5153,12 @@ fn buffer_object( writer.buffer_varint(object.delta)?; if encoding.extensions { let ext = match object.fields { - Some(fields) => super::object::write(&fields.properties, encoding.version, encoding.timescale)?, + Some(fields) => super::object::write( + &fields.properties, + object.timestamp, + encoding.version, + encoding.timescale, + )?, None => { let mut ext = Vec::new(); if let Some(timescale) = encoding.timescale { diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 59b24a830d0..d590a411019 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -480,6 +480,11 @@ fn accepted_info(properties: &ietf::Properties) -> track::Info { info } +/// Why a track answered with `properties` is neither processed nor forwarded, if it is not. +fn refused(properties: &ietf::Properties) -> Option { + properties.unknown.refused(&accepted_info(properties)) +} + /// The Largest Group a subscription knows: its SUBSCRIBE_OK's, or a newer one since. fn largest_group(track: &track::Producer, answer: Option) -> Option { answer.map(|largest| largest.group).max(track.latest_sequence()) @@ -2911,10 +2916,11 @@ where // SUBSCRIBE_OK commits the model's immutable metadata before the alias releases // any data stream that arrived ahead of this control response. let accepted = match response { - // A track that needs a property we do not understand is neither processed nor - // forwarded: the subscription is cancelled and the subscribers refused. - Ok(Some(accepted)) if accepted.properties.unknown.mandatory() => { - let err = Error::UnsupportedExtension; + // A track that needs a property we do not understand, or carries more than we + // could forward, is neither processed nor forwarded: the subscription is + // cancelled and the subscribers refused. + Ok(Some(accepted)) if refused(&accepted.properties).is_some() => { + let err = refused(&accepted.properties).expect("checked by the guard"); tracing::debug!(broadcast = %self.origin.absolute(broadcast_path), track = %track_name, %err, "subscribe refused"); // Refuse before waiting on the peer to acknowledge the cancellation. if let Some(pending) = self.take_pending(request_id) { @@ -3844,7 +3850,10 @@ where let _ = stream.writer.finish(); let ok = match response { // A track that needs a property we do not understand is not forwarded. - Ok(ok) if ok.properties.unknown.mandatory() => Err(Error::UnsupportedExtension), + Ok(ok) => match refused(&ok.properties) { + Some(err) => Err(err), + None => Ok(ok), + }, res => res, }; let ok = match ok { @@ -4080,12 +4089,9 @@ where let (payload, status) = match datagram.body { ietf::DatagramBody::Payload(payload) => (payload, None), - ietf::DatagramBody::Status(status @ (0 | END_OF_GROUP | END_OF_TRACK)) => { + ietf::DatagramBody::Status(status) if super::object::status_defined(status, self.version) => { (bytes::Bytes::new(), Some(status)) } - ietf::DatagramBody::Status(1) if matches!(self.version, Version::Draft14 | Version::Draft15) => { - (bytes::Bytes::new(), Some(1)) - } ietf::DatagramBody::Status(_) => return Err(Error::Session(SessionError::ProtocolViolation)), }; @@ -4104,14 +4110,25 @@ where // Like a subgroup object: a track that declared no timescale is untimed. One on a // timed track without a Timestamp is refused by the model. let properties = bytes::Bytes::from(datagram.properties.unwrap_or_default()); - let decoded = super::object::read(&properties, self.version, track.timescale)?; + // A status object has no frame to hold its time, so its block keeps it. + let (timestamp, properties) = match status.is_some_and(|status| status != 0) { + true => ( + None, + super::object::unframed(&properties, self.version, track.timescale)?, + ), + false => { + let decoded = super::object::read(&properties, self.version, track.timescale)?; + super::object::check_frame(&decoded.properties, track.timescale)?; + (decoded.timestamp, decoded.properties) + } + }; let Some(producer) = track.producer.as_mut() else { return Ok(()); }; producer.insert_wire_datagram(crate::model::datagram::Stored { datagram: crate::Datagram { sequence, - timestamp: decoded.timestamp, + timestamp, payload, }, wire: Some(std::sync::Arc::new(crate::model::datagram::Wire { @@ -4119,7 +4136,7 @@ where priority: datagram.publisher_priority, end_of_group: datagram.end_of_group, status, - properties: decoded.properties, + properties, })), })?; Ok(()) @@ -4168,11 +4185,7 @@ enum Ended { Track { object: u64, properties: bool }, } -/// Object status: no object at or past this location in the group exists (draft-14, 15). -const END_OF_GROUP: u64 = 0x3; - -/// Object status: no object at or past this location exists (every implemented draft). -const END_OF_TRACK: u64 = 0x4; +use super::object::{END_OF_GROUP, END_OF_TRACK}; /// The start of a subgroup stream's first object, peeked before its group is created. #[derive(Debug, Clone, Copy)] @@ -4403,6 +4416,8 @@ struct GroupIngest { prior_object: Option, start: Option, properties: crate::model::object::Properties, + /// The property list `properties` was read from, for a status object, which has no frame. + raw: bytes::Bytes, gap: Option, /// The object being read is one the group started past, so it is read and dropped. dropping: bool, @@ -4443,6 +4458,7 @@ impl GroupIngest { prior_object: None, start, properties: Default::default(), + raw: bytes::Bytes::new(), gap: None, dropping: false, phase: IngestPhase::Delta, @@ -4693,11 +4709,8 @@ where continue; } - let decoded = super::object::read( - &bytes::Bytes::from(object.properties.unwrap_or_default()), - self.version, - timescale, - )?; + let raw = bytes::Bytes::from(object.properties.unwrap_or_default()); + let decoded = super::object::read(&raw, self.version, timescale)?; let expected = head .as_ref() .filter(|(sequence, _, _)| group.is_none_or(|group| group == *sequence)) @@ -4752,6 +4765,7 @@ where producer, FetchPayload { decoded, + raw, timescale, keep, id, @@ -4777,6 +4791,7 @@ where ) -> Result { let FetchPayload { decoded, + raw, timescale, keep, id, @@ -4787,23 +4802,26 @@ where let size = stream.varint().await?; if size == 0 && matches!(self.version, Version::Draft14 | Version::Draft15) { let status = stream.varint().await?; - if status != 0 { - super::object::check_status(self.version, &decoded.properties)?; - } - match status { - 0 => {} - END_OF_GROUP => { + // A status object has no frame to hold its time, so its block keeps it. + let unframed = match status { + 0 => None, + _ => { + let properties = super::object::unframed(&raw, self.version, timescale)?; + super::object::check_status(self.version, &properties)?; + Some(properties) + } + }; + match (status, unframed) { + (0, _) => {} + (END_OF_GROUP, Some(properties)) => { if keep { - producer.set_end_object(crate::model::object::Fields { - id, - properties: decoded.properties, - })?; + producer.set_end_object(crate::model::object::Fields { id, properties })?; } return Ok(Fetched::EndOfGroup); } // END_OF_TRACK is track-level, so there is nowhere to keep its properties. - END_OF_TRACK if !decoded.properties.is_empty() => return Err(Error::Unsupported), - END_OF_TRACK => return Ok(Fetched::EndOfTrack), + (END_OF_TRACK, Some(properties)) if !properties.is_empty() => return Err(Error::Unsupported), + (END_OF_TRACK, _) => return Ok(Fetched::EndOfTrack), _ => return Err(Error::Unsupported), } } @@ -4812,10 +4830,9 @@ where std::future::poll_fn(|cx| stream.poll_skip(cx, &mut remaining)).await?; return Ok(Fetched::Frame); } + super::object::check_frame(&decoded.properties, timescale)?; let timestamp = object_time(timescale, decoded.timestamp)?; - let plain = id == producer.frame_count() as u64 - && decoded.properties.is_plain() - && decoded.properties.timestamp == timestamp.map(|time| time.value()); + let plain = id == producer.frame_count() as u64 && decoded.properties.is_empty(); let fields = (!plain).then(|| { std::sync::Arc::new(crate::model::object::Fields { id, @@ -5273,11 +5290,8 @@ where if group.is_some_and(|group| group != sequence) || id < next { return Err(Error::ProtocolViolation); } - let decoded = super::object::read( - &bytes::Bytes::from(object.properties.unwrap_or_default()), - self.version, - timescale, - )?; + let raw = bytes::Bytes::from(object.properties.unwrap_or_default()); + let decoded = super::object::read(&raw, self.version, timescale)?; if id > next && decoded.gap.is_none_or(|gap| gap < id - next) { return Err(Error::Unsupported); } @@ -5287,6 +5301,7 @@ where producer, FetchPayload { decoded, + raw, timescale, keep: true, id, @@ -5337,6 +5352,8 @@ enum Fetched { struct FetchPayload { decoded: super::object::Decoded, + /// The property list `decoded` was read from, for a status object, which has no frame. + raw: bytes::Bytes, timescale: Option, keep: bool, id: u64, @@ -5548,11 +5565,10 @@ fn object_time( impl GroupIngest { fn header(&mut self, group: &group::Producer, info: frame::Info) -> Result { + super::object::check_frame(&self.properties, self.timescale)?; let id = self.prior_object.expect("payload follows object ID"); group.mark_gap(self.prior_object.expect("properties follow Object ID"), self.gap)?; - let plain = id == group.frame_count() as u64 - && self.properties.is_plain() - && self.properties.timestamp == info.timestamp.map(|time| time.value()); + let plain = id == group.frame_count() as u64 && self.properties.is_empty(); let fields = (!plain).then(|| { std::sync::Arc::new(crate::model::object::Fields { id, @@ -5581,6 +5597,7 @@ impl GroupIngest { let id = next_object_id(self.prior_object, id_delta, self.start)?; self.prior_object = Some(id); self.properties = Default::default(); + self.raw = bytes::Bytes::new(); self.gap = None; self.dropping = self.start.is_some() && id < group.frame_count() as u64; self.phase = match self.has_extensions { @@ -5597,6 +5614,7 @@ impl GroupIngest { let decoded = super::object::read(&ext, self.version, self.timescale)?; let timestamp = decoded.timestamp; self.properties = decoded.properties; + self.raw = ext; self.gap = decoded.gap; self.phase = IngestPhase::Size { timestamp }; } @@ -5631,6 +5649,8 @@ impl GroupIngest { self.phase = IngestPhase::Delta; continue; } + // A status object has no frame to hold its time, so its block keeps it. + self.properties = super::object::unframed(&self.raw, self.version, self.timescale)?; super::object::check_status(self.version, &self.properties)?; if status == END_OF_GROUP { group.mark_gap(self.prior_object.expect("properties follow Object ID"), self.gap)?; @@ -12168,12 +12188,67 @@ mod stitch_tests { /// Relay `script` through a track the ingress times in `timescale`, which the cache /// normalizes to microseconds like [`accepted_info`]. + /// + /// Also relays it through a second relay behind a moq-lite hop with the `ietf` + /// extension, which must not change a byte. async fn relay_passthrough_timed( script: Vec, ingress: Version, egress: Version, fetch: Option<(u64, u64)>, timescale: Option, + ) -> (Vec, crate::lite::test_transport::Log) { + let direct = relay_passthrough_via(script.clone(), ingress, egress, fetch, timescale, false).await; + let hopped = relay_passthrough_via(script, ingress, egress, fetch, timescale, true).await; + let fetch_ok = |bytes: &[u8]| { + let mut decoder = Decoder::new(bytes, egress.into()); + (decoder.varint().ok()? == ietf::FetchOk::ID).then_some(())?; + let ok = ietf::FetchOk::decode(&mut decoder, egress).ok()?; + Some((ok, bytes[bytes.len() - decoder.remaining()..].to_vec())) + }; + match (fetch_ok(&direct.0), fetch_ok(&hopped.0)) { + // A moq-lite FETCH says nothing of the track, so only a subscription tells the + // second relay that the track ended. Everything else must match. + (Some((direct_ok, direct_rest)), Some((hopped_ok, hopped_rest))) + if direct_ok.end_of_track && !hopped_ok.end_of_track => + { + // Without End of Track, the End Location is the requested end rather than the + // track's, which can only reach further. + assert!( + (hopped_ok.end_location.group, hopped_ok.end_location.object) + >= (direct_ok.end_location.group, direct_ok.end_location.object), + "{ingress} -> {egress}" + ); + assert_eq!( + hopped_ok, + ietf::FetchOk { + end_of_track: false, + end_location: hopped_ok.end_location, + ..direct_ok + }, + "{ingress} -> {egress}: only End of Track and its End Location may differ" + ); + assert_eq!( + hopped_rest, direct_rest, + "{ingress} -> {egress}: the hop changed the objects" + ); + } + _ => assert_eq!( + hopped.0, direct.0, + "{ingress} -> {egress}: the moq-lite hop changed the relayed objects" + ), + } + direct + } + + /// [`relay_passthrough_timed`] through one relay, or two joined by a moq-lite `hop`. + async fn relay_passthrough_via( + script: Vec, + ingress: Version, + egress: Version, + fetch: Option<(u64, u64)>, + timescale: Option, + hop: bool, ) -> (Vec, crate::lite::test_transport::Log) { use crate::lite::test_transport::Sent; let origin = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); @@ -12193,6 +12268,13 @@ mod stitch_tests { let mut stream = h.stream().await.with_version(ingress); h.subscriber.clone().recv_group(&mut stream).await.unwrap(); track.finish().unwrap(); + let (served, _sessions) = match hop { + true => { + let (served, sessions) = crate::lite::ietf::test_hop(&origin, "room", [true, true]).await; + (served, Some(sessions)) + } + false => (origin, None), + }; let mut downstream = ScriptedSession::per_stream(vec![vec![]]); let peer = peer::PeerSetup::default(); @@ -12200,7 +12282,7 @@ mod stitch_tests { let publisher = crate::ietf::Publisher::new( crate::time::sim(), downstream.clone(), - origin.consume(), + served.consume(), Control::new(None, false), None, peer, @@ -12358,7 +12440,7 @@ mod stitch_tests { let relayed = bytes::Bytes::copy_from_slice(decoder.bytes().unwrap()); let decoded = super::super::object::read(&relayed, version, Some(Timescale::MILLI)).unwrap(); assert_eq!(decoded.timestamp, Some(Timestamp::new(42, Timescale::MILLI).unwrap())); - assert_eq!(decoded.properties.values.len(), 1); + assert_eq!(super::super::object::listed(&decoded.properties).len(), 1); } fn object_stream(version: Version, first: bool, objects: &[(u64, &[u8], Option)]) -> Vec { @@ -12514,7 +12596,9 @@ mod stitch_tests { ); if let Some(end) = end_object { assert_eq!( - end.properties.values.first().map(|property| property.id), + super::super::object::listed(&end.properties) + .first() + .map(|property| property.id), legacy.then_some(0x3e) ); } @@ -12582,6 +12666,141 @@ mod stitch_tests { assert!(decoder.is_empty()); } + /// Draft-14 lets a status object carry properties, and it has no frame to hold its + /// time, so a mutable Timestamp stays in its block on a timed track: through a subgroup + /// and a FETCH, and out again as it arrived. + #[moq_clock::test] + async fn a_status_object_keeps_its_timestamp() { + use futures::FutureExt; + + let version = Version::Draft14; + let status = [0x10, 7]; + let leaves = |properties: &crate::model::object::Properties| { + super::super::object::write(properties, None, version, None).unwrap() + }; + + let script = object_stream( + version, + true, + &[(0, &[0x10, 5], None), (1, &status, Some(END_OF_GROUP))], + ); + let mut h = Harness::with_timescale(Fill::Done, vec![script], Some(Timescale::MILLI)); + h.subscriber.version = version; + let mut consumer = h.track.subscribe(None); + let mut stream = h.stream().await.with_version(version); + h.subscriber.clone().recv_group(&mut stream).await.unwrap(); + let group = consumer.recv_group().now_or_never().unwrap().unwrap().unwrap(); + let end = group.end_object().expect("the END_OF_GROUP object"); + assert_eq!(leaves(&end.properties), status, "subgroup"); + + // A draft-14 FETCH object: Group, Subgroup, Object, priority, then its properties, + // an empty payload, and the status. + let mut objects = Vec::new(); + let w = &mut Encoder::new(&mut objects, version.into()); + for value in [SEQUENCE, 0, 0] { + w.varint(value).unwrap(); + } + w.u8(128); + w.bytes(&status).unwrap(); + w.varint(0u64).unwrap(); + w.varint(END_OF_GROUP).unwrap(); + let mut run = GroupFetchRun::new(version, objects).await; + let mut producer = crate::recv::Group::new(run.track.create_group(group::Info { sequence: SEQUENCE }).unwrap()); + run.subscriber + .recv_group_fetch_objects(&mut run.stream, &mut producer, 0, Some(1), Some(Timescale::MILLI)) + .await + .unwrap(); + let end = producer + .into_inner() + .consume() + .end_object() + .expect("the END_OF_GROUP object"); + assert_eq!(leaves(&end.properties), status, "fetch"); + } + + /// A draft-14 status object has no frame, so its block may fill the whole limit on a + /// timed track, though its list arrives before the status says so. A framed object's + /// block leaves room for the Timestamp egress restates. + #[moq_clock::test] + async fn a_status_object_fills_the_whole_block() { + let version = Version::Draft14; + let milli = Some(Timescale::MILLI); + // A block of `size` held bytes: one opaque property, its key, a four-byte length, + // then bytes. A framed object's list adds its Timestamp, which the frame holds. + let block = |size: usize, framed: bool| { + let mut block = Vec::new(); + let w = &mut Encoder::new(&mut block, version.into()); + if framed { + w.varint(0x10u64).unwrap(); + w.varint(5u64).unwrap(); + } + w.varint(0x21u64).unwrap(); + w.bytes(&vec![7; size - 5]).unwrap(); + block + }; + let full = block(super::super::object::MAX_BLOCK, false); + let limit = super::super::object::max_block(milli); + + for (properties, status, ok) in [ + (&full, Some(END_OF_GROUP), true), + (&block(limit + 1, true), None, false), + (&block(limit, true), None, true), + ] { + let script = object_stream(version, true, &[(0, properties, status)]); + let mut h = Harness::with_timescale(Fill::Done, vec![script], milli); + h.subscriber.version = version; + let mut stream = h.stream().await.with_version(version); + let result = h.subscriber.clone().recv_group(&mut stream).await; + match ok { + true => assert!(result.is_ok(), "subgroup {}: {result:?}", properties.len()), + false => assert!(matches!(result, Err(Error::Unsupported)), "subgroup: {result:?}"), + } + + // The fetch harness's track is untimed, so a framed object it keeps cannot be timed. + if ok && status.is_none() { + continue; + } + // A draft-14 FETCH object: Group, Subgroup, Object, priority, then its properties, + // and an empty payload with its status or a one-byte payload. + let mut objects = Vec::new(); + let w = &mut Encoder::new(&mut objects, version.into()); + for value in [SEQUENCE, 0, 0] { + w.varint(value).unwrap(); + } + w.u8(128); + w.bytes(properties).unwrap(); + match status { + Some(status) => { + w.varint(0u64).unwrap(); + w.varint(status).unwrap(); + } + None => { + w.varint(1u64).unwrap(); + w.u8(99); + } + } + let mut run = GroupFetchRun::new(version, objects).await; + let mut producer = + crate::recv::Group::new(run.track.create_group(group::Info { sequence: SEQUENCE }).unwrap()); + let result = run + .subscriber + .recv_group_fetch_objects(&mut run.stream, &mut producer, 0, Some(1), milli) + .await; + match ok { + true => assert!(result.is_ok(), "fetch {}: {result:?}", properties.len()), + false => assert!(matches!(result, Err(Error::Unsupported)), "fetch: {result:?}"), + } + if status.is_some() { + let end = producer + .into_inner() + .consume() + .end_object() + .expect("the END_OF_GROUP object"); + assert_eq!(end.properties.heap(), full.len() as u64); + } + } + } + #[moq_clock::test] async fn passthrough_refuses_contradictory_gap_properties() { for properties in [vec![0x3e, 2], vec![0x3e, 3], vec![0x3e, 1, 0, 1]] { @@ -12633,7 +12852,10 @@ mod stitch_tests { .unwrap() .unwrap(); assert_eq!(frame.fields.as_ref().unwrap().id, id); - assert_eq!(frame.fields.as_ref().unwrap().properties.values[0].id, 0x3e); + assert_eq!( + super::super::object::listed(&frame.fields.as_ref().unwrap().properties)[0].id, + 0x3e + ); } let tail = object_stream(version, false, &[(9, &[], None)]); @@ -12727,7 +12949,8 @@ mod stitch_tests { ] { let script = object_stream(ingress, true, &[(0, &properties, None)]); let (bytes, log) = relay_passthrough_stream(script, ingress, egress).await; - if super::super::object::encoding(ingress) != super::super::object::encoding(egress) { + let encoding = super::super::object::encoding; + if !super::super::object::same_bytes(encoding(ingress), encoding(egress)) { assert!(!log.resets().is_empty(), "incompatible immutable bytes must be refused"); continue; } @@ -12742,10 +12965,13 @@ mod stitch_tests { #[moq_clock::test] async fn passthrough_preserves_datagram_objects_through_dispatch() { - for version in [Version::Draft15, Version::Draft22] { - for ranged in [false, true] - .into_iter() - .filter(|ranged| !*ranged || version == Version::Draft22) + // Also through a second relay behind a moq-lite hop with the `ietf` extension. + for (version, ranged, hop) in [Version::Draft15, Version::Draft22] + .into_iter() + .flat_map(|version| [(version, false), (version, true)]) + .filter(|(version, ranged)| !*ranged || *version == Version::Draft22) + .flat_map(|(version, ranged)| [(version, ranged, false), (version, ranged, true)]) + { { let origin = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); let broadcast = origin.publish("room", crate::origin::Route::default()).unwrap(); @@ -12781,13 +13007,20 @@ mod stitch_tests { original.push(datagram); } track.finish().unwrap(); + let (served, _sessions) = match hop { + true => { + let (served, sessions) = crate::lite::ietf::test_hop(&origin, "room", [true, true]).await; + (served, Some(sessions)) + } + false => (origin, None), + }; let mut downstream = ScriptedSession::per_stream(vec![vec![]]).with_datagrams(65535); let peer = peer::PeerSetup::default(); peer.set(peer::Peer::default()); let publisher = crate::ietf::Publisher::new( crate::time::sim(), downstream.clone(), - origin.consume(), + served.consume(), Control::new(None, false), None, peer, @@ -12834,7 +13067,7 @@ mod stitch_tests { .await; let sent = downstream.log.datagrams.lock().unwrap(); original.retain(|datagram| !ranged || datagram.object_id == Some(7)); - assert_eq!(sent.len(), original.len()); + assert_eq!(sent.len(), original.len(), "{version} ranged={ranged} hop={hop}"); let inherited = super::super::priority::to_wire(track.publisher_priority()); for (bytes, mut expected) in sent.iter().zip(original) { expected.track_alias = 3; @@ -15980,7 +16213,7 @@ mod track_property_tests { .clone() .expect("the properties were dropped"); assert_eq!(properties.values, unknown, "{version}"); - assert_eq!(properties.immutable, None, "{version}"); + assert!(properties.immutable().is_none(), "{version}"); } } @@ -16012,6 +16245,37 @@ mod track_property_tests { } } + /// A sealed DEFAULT_PUBLISHER_GROUP_ORDER is advisory: the relay accepts the track, serves + /// its own order, and keeps the sealed block to forward unchanged. + #[moq_clock::test] + async fn a_sealed_group_order_the_relay_does_not_serve_is_accepted() { + for version in VERSIONS { + for order in [2, 1] { + let sealed = Property { + id: 0x0b, + value: Value::Bytes( + block( + version, + &[Property { + id: 0x22, + value: Value::Int(order), + }], + ) + .into(), + ), + }; + let (subscribed, _probe) = subscribe(version, &block(version, std::slice::from_ref(&sealed))).await; + let subscriber = subscribed.unwrap_or_else(|err| panic!("{version}: {order}: {err}")); + let properties = subscriber + .info() + .properties + .clone() + .expect("the sealed block was dropped"); + assert_eq!(properties.values, [sealed], "{version}: {order}"); + } + } + } + /// A TIMESCALE keeps the publisher's units, mutable or sealed: a sealed one travels /// downstream unchanged, and a mutable one matches a copy that arrived over another route. #[moq_clock::test] diff --git a/rs/moq-net/src/ietf/version.rs b/rs/moq-net/src/ietf/version.rs index 0e29f184548..3eddd2be5a8 100644 --- a/rs/moq-net/src/ietf/version.rs +++ b/rs/moq-net/src/ietf/version.rs @@ -15,6 +15,21 @@ pub enum Version { Draft22, } +impl Version { + /// Every implemented draft, oldest first. + pub(crate) const ALL: [Self; 9] = [ + Self::Draft14, + Self::Draft15, + Self::Draft16, + Self::Draft17, + Self::Draft18, + Self::Draft19, + Self::Draft20, + Self::Draft21, + Self::Draft22, + ]; +} + impl fmt::Display for Version { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self { diff --git a/rs/moq-net/src/lite/datagram.rs b/rs/moq-net/src/lite/datagram.rs index e573d9e99be..3b243b0f4fd 100644 --- a/rs/moq-net/src/lite/datagram.rs +++ b/rs/moq-net/src/lite/datagram.rs @@ -6,6 +6,7 @@ //! the datagram boundary, so unlike a [`super::Message`] there is no inner length prefix. The model //! counterpart is [`crate::Datagram`]. +use crate::Timescale; use bytes::Bytes; use crate::coding::{DecodeError, Decoder, Encode, EncodeError, Encoder}; @@ -24,6 +25,9 @@ pub struct Datagram { pub timestamp: Option, /// The frame payload, delimited by the datagram boundary. pub payload: Bytes, + /// With the `ietf` extension negotiated, the moq-transport state a relay preserves, or + /// `Some(None)` for a plain datagram. `None` without the extension. + pub ietf: Option>, } impl Encode for Datagram { @@ -39,6 +43,20 @@ impl Encode for Datagram { w.varint(self.subscribe)?; w.varint(self.sequence)?; + if let Some(wire) = &self.ietf { + if !version.has_ietf() { + return Err(EncodeError::Version); + } + // Any status object carries no payload, which moq-transport could not send beside + // it, and a non-zero one carries no object and so no time either. + let status = wire.as_ref().and_then(|wire| wire.status); + if status.is_some() && !self.payload.is_empty() + || status.is_some_and(|status| status != 0) && self.timestamp.is_some() + { + return Err(EncodeError::InvalidState); + } + super::ietf::encode_datagram(w, wire.as_ref(), version)?; + } if let Some(timestamp) = self.timestamp { w.varint(timestamp)?; } @@ -52,26 +70,50 @@ impl Encode for Datagram { impl Datagram { /// Decode a whole datagram body. The payload shares `buf` rather than copying it. /// - /// `timed` reports whether the track of the given subscribe ID carries a timestamp, - /// which the body itself does not say. - pub fn decode(buf: Bytes, version: Version, timed: impl FnOnce(u64) -> bool) -> Result { - if !version.has_datagrams() { + /// `ietf` says whether the session negotiated the extension, and `timescale` gives the + /// units of the track of the given subscribe ID, if it is timed, which the body itself + /// does not say. + pub fn decode( + buf: Bytes, + version: Version, + ietf: bool, + timescale: impl FnOnce(u64) -> Option, + ) -> Result { + if !version.has_datagrams() || (ietf && !version.has_ietf()) { return Err(DecodeError::Version); } let mut r = Decoder::new(&buf, version.into()); let subscribe = r.varint()?; let sequence = r.varint()?; - let timestamp = if timed(subscribe) { Some(r.varint()?) } else { None }; + let timescale = timescale(subscribe); + let ietf = ietf + .then(|| super::ietf::decode_datagram(&mut r, timescale, version)) + .transpose()?; + // Any status object carries no payload, which moq-transport could not send beside + // it, and a non-zero one carries no object and so no time either. + let status = ietf + .as_ref() + .and_then(|wire| wire.as_ref()) + .and_then(|wire| wire.status); + let timestamp = if timescale.is_some() && status.is_none_or(|status| status == 0) { + Some(r.varint()?) + } else { + None + }; // Everything remaining is the payload (the datagram boundary delimits it). let payload = buf.slice(buf.len() - r.remaining()..); + if status.is_some() && !payload.is_empty() { + return Err(DecodeError::InvalidValue); + } Ok(Self { subscribe, sequence, timestamp, payload, + ietf, }) } } @@ -87,9 +129,10 @@ mod test { sequence: 42, timestamp: Some(1_000), payload: Bytes::from_static(b"hello"), + ietf: None, }; let buf = original.encode_bytes(Version::Lite05).unwrap(); - let decoded = Datagram::decode(buf, Version::Lite05, |_| true).unwrap(); + let decoded = Datagram::decode(buf, Version::Lite05, false, |_| Some(Timescale::MILLI)).unwrap(); assert_eq!(decoded, original, "payload has no trailing length prefix"); } @@ -100,9 +143,10 @@ mod test { sequence: 0, timestamp: Some(0), payload: Bytes::new(), + ietf: None, }; let buf = original.encode_bytes(Version::Lite05).unwrap(); - let decoded = Datagram::decode(buf, Version::Lite05, |_| true).unwrap(); + let decoded = Datagram::decode(buf, Version::Lite05, false, |_| Some(Timescale::MILLI)).unwrap(); assert_eq!(decoded, original); } @@ -115,6 +159,7 @@ mod test { sequence: 2, timestamp: Some(3), payload: Bytes::from_static(b"world"), + ietf: None, }; let buf = dg.encode_bytes(Version::Lite05).unwrap(); // 1 + 1 + 1 (single-byte varints) + 5 payload = 8 bytes, no length byte. @@ -129,13 +174,14 @@ mod test { sequence: 2, timestamp: None, payload: Bytes::from_static(b"world"), + ietf: None, }; let buf = dg.encode_bytes(Version::Lite07).unwrap(); assert_eq!(buf.len(), 7); assert_eq!(&buf[2..], b"world"); - let decoded = Datagram::decode(buf, Version::Lite07, |id| { + let decoded = Datagram::decode(buf, Version::Lite07, false, |id| { assert_eq!(id, 1); - false + None }) .unwrap(); assert_eq!(decoded, dg); @@ -148,6 +194,7 @@ mod test { sequence: 2, timestamp: None, payload: Bytes::from_static(b"world"), + ietf: None, }; for version in [Version::Lite05, Version::Lite06] { assert!( @@ -157,6 +204,81 @@ mod test { } } + /// A timed datagram's Timestamp is its only time: its relayed properties cannot hold a + /// second, mutable one that could disagree. + #[test] + fn relayed_properties_hold_no_timestamp_on_a_timed_track() { + let dg = |id: u64| Datagram { + subscribe: 1, + sequence: 2, + timestamp: Some(500), + payload: Bytes::from_static(b"x"), + ietf: Some(Some(crate::model::datagram::Wire { + object_id: None, + priority: None, + end_of_group: false, + status: None, + properties: crate::model::object::Properties { + block: crate::ietf::object::block( + &[crate::model::object::Property { + id, + value: crate::model::object::Value::Int(7), + }], + crate::model::object::Encoding::Draft19, + ) + .unwrap(), + ..Default::default() + }, + })), + }; + let decode = |dg: Datagram| { + let buf = dg.encode_bytes(Version::Lite07).unwrap(); + Datagram::decode(buf, Version::Lite07, true, |_| Some(Timescale::MILLI)) + }; + assert!(decode(dg(0x20)).is_ok()); + assert!(matches!(decode(dg(0x10)), Err(DecodeError::InvalidValue))); + } + + /// A Normal status (0) is an empty object, which moq-transport sends as a status with + /// no payload, so a STATUS field beside a payload is refused whatever its value. + #[test] + fn a_status_carries_no_payload() { + for status in [0, 3] { + let dg = |payload: &'static [u8]| Datagram { + subscribe: 1, + sequence: 2, + timestamp: (status == 0).then_some(500), + payload: Bytes::from_static(payload), + ietf: Some(Some(crate::model::datagram::Wire { + object_id: None, + priority: None, + end_of_group: false, + status: Some(status), + properties: Default::default(), + })), + }; + assert!( + matches!(dg(b"x").encode_bytes(Version::Lite07), Err(EncodeError::InvalidState)), + "{status}" + ); + let empty = dg(b""); + let mut buf = empty.encode_bytes(Version::Lite07).unwrap().to_vec(); + let decoded = Datagram::decode(Bytes::from(buf.clone()), Version::Lite07, true, |_| { + Some(Timescale::MILLI) + }) + .unwrap(); + assert_eq!(decoded, empty, "{status}"); + buf.push(b'x'); + assert!( + matches!( + Datagram::decode(Bytes::from(buf), Version::Lite07, true, |_| Some(Timescale::MILLI)), + Err(DecodeError::InvalidValue) + ), + "{status}" + ); + } + } + #[test] fn rejects_old_versions() { let dg = Datagram { @@ -164,11 +286,14 @@ mod test { sequence: 2, timestamp: Some(3), payload: Bytes::from_static(b"x"), + ietf: None, }; assert!(matches!(dg.encode_bytes(Version::Lite04), Err(EncodeError::Version))); assert!(matches!( - Datagram::decode(Bytes::from_static(b"\x01\x02\x03x"), Version::Lite04, |_| true), + Datagram::decode(Bytes::from_static(b"\x01\x02\x03x"), Version::Lite04, false, |_| Some( + Timescale::MILLI + )), Err(DecodeError::Version) )); } diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs new file mode 100644 index 00000000000..e52389bb764 --- /dev/null +++ b/rs/moq-net/src/lite/ietf.rs @@ -0,0 +1,1418 @@ +//! The `ietf` extension (draft-lcurley-moq-ietf): the moq-transport object state a relay +//! preserves, carried across a lite-07 hop when both SETUPs offer it. +//! +//! Every field here is crate-private relay metadata (see `model::object`). Plain readers +//! never see it, and a session without the extension sends none of it. + +use std::sync::Arc; + +use bytes::Bytes; + +use crate::{ + Error, Timescale, + coding::{DecodeError, Decoder, EncodeError, Encoder}, + group, + model::object::{Encoding, Fields, Properties, Property, Value}, +}; + +use super::{Message, Version}; + +/// The largest record body a peer may make us buffer: the largest block moq-transport +/// admits, beside a Flags byte. +pub(crate) const MAX_PROPERTIES: usize = crate::ietf::object::MAX_BLOCK + 1; + +// Group State bits. +const RELAYED: u64 = 0x1; +const FIRST_OBJECT: u64 = 0x2; +const EXTENSIONS: u64 = 0x4; +const END_OF_GROUP: u64 = 0x8; + +// Datagram State bits, after RELAYED. +const OBJECT_ID: u64 = 0x2; +const PRIORITY: u64 = 0x4; +const DATAGRAM_END: u64 = 0x8; +const STATUS: u64 = 0x10; + +/// Immutable Properties, whose keys TRACK_PROPERTIES derives its sealed list from. +const IMMUTABLE: u64 = 0x0b; + +/// The Group State a stream sends for its group's `wire` state. +/// +/// `whole` when the stream starts at the copy's first frame, so FIRST_OBJECT still holds, +/// and `capped` when it stops before the group may end, so its FIN cannot end the group. +pub(crate) fn encode_state(wire: Option<&group::Wire>, whole: bool, capped: bool) -> u64 { + let Some(wire) = wire else { + return 0; + }; + let mut state = RELAYED; + if wire.first_object && whole { + state |= FIRST_OBJECT; + } + if wire.extensions { + state |= EXTENSIONS; + } + if wire.has_end && !capped { + state |= END_OF_GROUP; + } + state +} + +/// The relay state a received Group State describes, or `None` for a plain group. +/// +/// The first object's ID is learned from the first record, so it starts at `frame_start`. +pub(crate) fn decode_state(state: u64, frame_start: u64) -> Result, Error> { + if state == 0 { + return Ok(None); + } + if state & RELAYED == 0 || state & !(RELAYED | FIRST_OBJECT | EXTENSIONS | END_OF_GROUP) != 0 { + return Err(Error::ProtocolViolation); + } + Ok(Some(group::Wire { + sparse: false, + first_object: state & FIRST_OBJECT != 0, + first_id: frame_start, + extensions: state & EXTENSIONS != 0, + has_end: state & END_OF_GROUP != 0, + fetchable: true, + last: None, + })) +} + +/// The first varint of an object record: the Object ID delta from `prior`, or the absolute +/// ID for the first record, with the END_OF_GROUP status in the low bit. +pub(crate) fn encode_object(prior: Option, id: u64, end: bool) -> Result { + let delta = match prior { + None => id, + Some(prior) => id + .checked_sub(prior) + .and_then(|step| step.checked_sub(1)) + .ok_or(Error::MalformedTrack)?, + }; + if delta > u64::MAX >> 1 { + return Err(Error::BoundsExceeded(crate::coding::BoundsExceeded)); + } + Ok(delta << 1 | u64::from(end)) +} + +/// The Object ID and END_OF_GROUP status an object record's first varint names. +pub(crate) fn decode_object(prior: Option, code: u64) -> Result<(u64, bool), Error> { + let delta = code >> 1; + let id = match prior { + None => Some(delta), + Some(prior) => prior.checked_add(1).and_then(|next| next.checked_add(delta)), + }; + Ok((id.ok_or(Error::ProtocolViolation)?, code & 1 != 0)) +} + +fn encode_encoding(encoding: Option) -> u64 { + match encoding { + None => 0, + Some(Encoding::Draft14) => 1, + Some(Encoding::Draft16) => 2, + Some(Encoding::Draft17) => 3, + Some(Encoding::Draft18) => 4, + Some(Encoding::Draft19) => 5, + } +} + +fn decode_encoding(code: u64) -> Result, DecodeError> { + Ok(match code { + 0 => None, + 1 => Some(Encoding::Draft14), + 2 => Some(Encoding::Draft16), + 3 => Some(Encoding::Draft17), + 4 => Some(Encoding::Draft18), + 5 => Some(Encoding::Draft19), + _ => return Err(DecodeError::InvalidValue), + }) +} + +/// Track Properties delta-encoded in the family they arrived in, as moq-transport sent +/// them less the properties TRACK_INFO carries, so the list is never wider than it arrived. +/// +/// An even ID has an integer value, an odd one bytes. +fn encode_list(properties: &crate::model::object::TrackProperties) -> Result, EncodeError> { + let mut out = Vec::new(); + let Some(encoding) = properties.encoding else { + return match properties.values.is_empty() { + true => Ok(out), + false => Err(EncodeError::InvalidState), + }; + }; + let w = &mut Encoder::new(&mut out, crate::ietf::object::family(encoding).into()); + let mut prior = 0; + for property in &properties.values { + w.varint(property.id.checked_sub(prior).ok_or(EncodeError::InvalidState)?)?; + prior = property.id; + match (&property.value, property.id % 2) { + (Value::Int(value), 0) => w.varint(*value)?, + (Value::Bytes(value), 1) => w.bytes(value)?, + _ => return Err(EncodeError::InvalidState), + } + } + Ok(out) +} + +/// Whether TRACK_PROPERTIES can carry `properties` across a hop. +/// +/// Dropping the understood properties can widen the delta that spans them, so a list that +/// fit its moq-transport message may still not fit, though only by a byte or two. +pub(crate) fn fits(properties: &crate::model::object::TrackProperties) -> bool { + // The Flags beside it are one byte. + encode_list(properties).is_ok_and(|list| list.len() < super::message::MAX_MESSAGE_SIZE) +} + +/// Decode Track Properties to the end of `r`, delta-encoded in the `encoding` family. +/// +/// No more than moq-transport ingress keeps, which is all a relay forwards. +fn decode_list(r: &mut Decoder<'_>, encoding: Encoding) -> Result, DecodeError> { + let r = &mut Decoder::new(r.rest(), crate::ietf::object::family(encoding).into()); + let mut values: Vec = Vec::new(); + let mut prior = 0u64; + while !r.is_empty() { + if values.len() as u64 >= crate::ietf::properties::MAX_PROPERTIES { + return Err(DecodeError::TooMany); + } + let id = prior.checked_add(r.varint()?).ok_or(DecodeError::BoundsExceeded)?; + prior = id; + let value = match id % 2 { + 0 => Value::Int(r.varint()?), + // A small cached property must not pin the reader's larger receive buffer. + _ => Value::Bytes(Bytes::copy_from_slice(r.bytes()?)), + }; + values.push(Property { id, value }); + } + Ok(values) +} + +/// Encode an object's properties as a record body, empty when it has none. +/// +/// The block is sent as it is held. A timed track's mutable Timestamp is the frame's, so +/// it is never sent here. +pub(crate) fn encode_properties(properties: &Properties, version: Version) -> Result, EncodeError> { + let mut out = Vec::new(); + let Some(block) = &properties.block else { + return Ok(out); + }; + let w = &mut Encoder::new(&mut out, version.into()); + w.varint(encode_encoding(Some(block.encoding)))?; + w.slice(&block.bytes); + Ok(out) +} + +/// An object's decoded properties and the Prior Object ID Gap they mark, if any. +pub(crate) struct Decoded { + pub properties: Properties, + pub gap: Option, +} + +/// Decode an object's record body on a track in `timescale`, the units the track +/// declares, which its sealed Timestamp is in. A `framed` object's frame holds its time; +/// a status object's block holds it. +/// +/// Only the canonical form is accepted, so what decodes re-encodes to the same bytes. +pub(crate) fn decode_properties( + body: &[u8], + timescale: Option, + framed: bool, + version: Version, +) -> Result { + if body.is_empty() { + return Ok(Decoded { + properties: Properties::default(), + gap: None, + }); + } + let r = &mut Decoder::new(body, version.into()); + // An empty body is how nothing at all is sent. + let encoding = decode_encoding(r.varint()?)?.ok_or(DecodeError::InvalidValue)?; + // A small cached block must not pin the reader's larger receive buffer. + let bytes = Bytes::copy_from_slice(&body[body.len() - r.remaining()..]); + let checked = + crate::ietf::object::check(&bytes, encoding, timescale, framed).map_err(|_| DecodeError::InvalidValue)?; + Ok(Decoded { + properties: Properties { + sealed_time: checked.sealed_time, + block: Some(crate::model::object::Block { + bytes, + encoding, + immutable: checked.immutable, + }), + }, + gap: checked.gap, + }) +} + +/// Decode the END_OF_GROUP record's body on a track in `timescale`. It is a status +/// object, so a block must claim a draft that lets one carry properties. +#[cfg(feature = "async")] +pub(crate) fn decode_end(body: &[u8], timescale: Option, version: Version) -> Result { + let decoded = decode_properties(body, timescale, false, version)?; + if let Some(block) = &decoded.properties.block + && !crate::ietf::object::drafts(block.encoding).any(crate::ietf::object::status_has_properties) + { + return Err(DecodeError::InvalidValue); + } + Ok(decoded) +} + +/// A group stream's object records on egress, sent before each frame once the extension +/// is negotiated. +#[cfg(feature = "async")] +pub(crate) struct Records { + /// The previous record's Object ID, `None` before the first. + prior: Option, + /// The stream stops at a frame cap, so its Group State promised no END_OF_GROUP. + capped: bool, + /// The units the track declares, which a sealed Timestamp must already be in. + timescale: Option, + version: Version, +} + +#[cfg(feature = "async")] +impl Records { + /// Buffer the Group State for a stream serving `group` from its current index, and + /// return the records its frames need. + /// + /// `capped` when the stream stops before the group may end. Writes nothing and returns + /// `None` unless the session negotiated the extension. + pub fn start( + writer: &mut crate::coding::Writer, + ietf: bool, + group: &group::Consumer, + capped: bool, + timescale: Option, + version: Version, + ) -> Result, Error> { + if !ietf { + return Ok(None); + } + let wire = group.wire(); + let whole = group.index() <= group.first_frame(); + writer.buffer_varint(encode_state(wire.as_ref(), whole, capped))?; + Ok(Some(Self { + prior: None, + capped, + timescale, + version, + })) + } + + /// Buffer the record for the frame at `index`, ahead of its timestamp and size. + pub fn frame( + &mut self, + writer: &mut crate::coding::Writer, + index: u64, + fields: Option<&Fields>, + ) -> Result<(), Error> { + self.record(writer, fields.map_or(index, |fields| fields.id), fields, false) + } + + /// Buffer the END_OF_GROUP record once every frame is written, if the group has one. + pub fn end( + &mut self, + writer: &mut crate::coding::Writer, + group: &group::Consumer, + ) -> Result<(), Error> { + // A capped stream stops at its cap even when that is the last frame, and one capped + // short of the last frame stops before the end. + if self.capped || group.index() < group.frame_count() as u64 { + return Ok(()); + } + match group.end_object() { + Some(end) => self.record(writer, end.id, Some(&end), true), + None => Ok(()), + } + } + + fn record( + &mut self, + writer: &mut crate::coding::Writer, + id: u64, + fields: Option<&Fields>, + end: bool, + ) -> Result<(), Error> { + writer.buffer_varint(encode_object(self.prior, id, end)?)?; + self.prior = Some(id); + let block = match fields { + Some(fields) => { + // A sealed Timestamp keeps its units, which the receiver reads as the track's. + if fields + .properties + .sealed_time + .is_some_and(|sealed| self.timescale != Some(sealed.scale())) + { + return Err(Error::Unsupported); + } + encode_properties(&fields.properties, self.version)? + } + None => Vec::new(), + }; + writer.buffer_varint(block.len() as u64)?; + writer.buffer_raw(&block); + Ok(()) + } +} + +/// The moq-transport Track Properties a relay forwards, sent on the Track Stream right +/// after TRACK_INFO when the extension is negotiated. +#[derive(Clone, Debug, Default)] +pub struct TrackProperties(pub Option>); + +impl Message for TrackProperties { + fn encode_msg(&self, w: &mut Encoder<'_>, _: Version) -> Result<(), EncodeError> { + // An encoding only ever describes values, so none at all is a lone 0. + let Some(properties) = self.0.as_ref().filter(|properties| !properties.values.is_empty()) else { + return w.varint(0); + }; + w.varint(encode_encoding(properties.encoding))?; + w.slice(&encode_list(properties)?); + Ok(()) + } + + fn decode_msg(r: &mut Decoder<'_>, _: Version) -> Result { + let code = r.varint()?; + if r.is_empty() { + // Only the canonical form, so what decodes re-encodes to the same bytes. + return match code { + 0 => Ok(Self(None)), + _ => Err(DecodeError::InvalidValue), + }; + } + // Track Properties start at draft-16, whose families all delta-encode their keys. + let encoding = decode_encoding(code)? + .filter(|encoding| *encoding != Encoding::Draft14) + .ok_or(DecodeError::InvalidValue)?; + let properties = crate::model::object::TrackProperties { + values: decode_list(r, encoding)?, + encoding: Some(encoding), + }; + // TRACK_INFO carries these, so a second copy could only contradict it. + if properties + .values + .iter() + .any(|property| crate::ietf::properties::understood(property.id)) + { + return Err(DecodeError::InvalidValue); + } + // Egress reads the sealed keys from the block, so it must be the one ingress would keep. + if properties + .values + .iter() + .filter(|property| property.id == IMMUTABLE) + .count() > 1 + { + return Err(DecodeError::InvalidValue); + } + if let Some(block) = properties.immutable() { + crate::ietf::properties::check_immutable(block, encoding)?; + } + Ok(Self(Some(Arc::new(properties)))) + } +} + +/// Encode a datagram's relay state after its Group Sequence, or a plain one's as 0. +pub(crate) fn encode_datagram( + w: &mut Encoder<'_>, + wire: Option<&crate::model::datagram::Wire>, + version: Version, +) -> Result<(), EncodeError> { + let Some(wire) = wire else { + return w.varint(0); + }; + let mut state = RELAYED; + for (set, bit) in [ + (wire.object_id.is_some(), OBJECT_ID), + (wire.priority.is_some(), PRIORITY), + (wire.end_of_group, DATAGRAM_END), + (wire.status.is_some(), STATUS), + ] { + if set { + state |= bit; + } + } + w.varint(state)?; + if let Some(id) = wire.object_id { + w.varint(id)?; + } + if let Some(priority) = wire.priority { + w.u8(priority); + } + if let Some(status) = wire.status { + w.varint(status)?; + } + w.bytes(&encode_properties(&wire.properties, version)?) +} + +/// Decode a datagram's relay state on a track in `timescale`. +pub(crate) fn decode_datagram( + r: &mut Decoder<'_>, + timescale: Option, + version: Version, +) -> Result, DecodeError> { + let state = r.varint()?; + if state == 0 { + return Ok(None); + } + if state & RELAYED == 0 || state & !(RELAYED | OBJECT_ID | PRIORITY | DATAGRAM_END | STATUS) != 0 { + return Err(DecodeError::InvalidValue); + } + let object_id = (state & OBJECT_ID != 0).then(|| r.varint()).transpose()?; + let priority = (state & PRIORITY != 0).then(|| r.u8()).transpose()?; + let status = (state & STATUS != 0).then(|| r.varint()).transpose()?; + // A status object has no frame to hold its time. + let framed = status.is_none_or(|status| status == 0); + let block = r.bytes()?; + let properties = decode_properties(block, timescale, framed, version)?.properties; + let wire = crate::model::datagram::Wire { + object_id, + priority, + end_of_group: state & DATAGRAM_END != 0, + status, + properties, + }; + // A relay holds and forwards it, so it must be one moq-transport ingress would accept. + if !wire.defined() { + return Err(DecodeError::InvalidValue); + } + Ok(Some(wire)) +} + +#[cfg(test)] +mod tests { + use super::*; + + const V: Version = Version::Lite07; + + #[test] + fn object_codes_round_trip() { + for (prior, id, end) in [ + (None, 0, false), + (None, 7, true), + (Some(3), 4, false), + (Some(3), 9, true), + ] { + let code = encode_object(prior, id, end).unwrap(); + assert_eq!(decode_object(prior, code).unwrap(), (id, end)); + } + // A plain frame after its predecessor costs one byte. + assert_eq!(encode_object(Some(4), 5, false).unwrap(), 0); + assert!(matches!(encode_object(Some(4), 4, false), Err(Error::MalformedTrack))); + assert!(decode_object(Some(u64::MAX), 0).is_err()); + } + + #[test] + fn group_state_round_trips() { + let wire = group::Wire { + sparse: true, + first_object: true, + first_id: 9, + extensions: true, + has_end: true, + fetchable: false, + last: Some(12), + }; + let state = encode_state(Some(&wire), true, false); + let decoded = decode_state(state, 2).unwrap().unwrap(); + assert!(decoded.first_object && decoded.extensions && decoded.has_end); + assert_eq!(decoded.first_id, 2); + assert!(decoded.fetchable && !decoded.sparse); + + let partial = decode_state(encode_state(Some(&wire), false, true), 0) + .unwrap() + .unwrap(); + assert!(!partial.first_object && !partial.has_end); + + assert_eq!(encode_state(None, true, false), 0); + assert!(decode_state(0, 0).unwrap().is_none()); + assert!(decode_state(FIRST_OBJECT, 0).is_err(), "state without RELAYED"); + assert!(decode_state(RELAYED | 0x10, 0).is_err(), "unknown bit"); + } + + #[test] + fn properties_round_trip_with_their_provenance() { + // An immutable block in the draft-16 family holding a gap of 2 (0x3e) and a timestamp. + let mut sealed = Vec::new(); + let e = &mut Encoder::new(&mut sealed, crate::ietf::Version::Draft16.into()); + for value in [0x10u64, 77, 0x3e - 0x10, 2] { + e.varint(value).unwrap(); + } + let values = [ + Property { + id: 0x06, + value: Value::Int(5), + }, + Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.into()), + }, + ]; + let properties = Properties { + sealed_time: Some(crate::Timestamp::new(77, Timescale::MILLI).unwrap()), + block: crate::ietf::object::block(&values, Encoding::Draft16).unwrap(), + }; + let body = encode_properties(&properties, V).unwrap(); + let decoded = decode_properties(&body, Some(Timescale::MILLI), true, V).unwrap(); + assert_eq!(decoded.properties, properties); + assert_eq!(decoded.gap, Some(2)); + + // None at all is an empty body. + assert!(encode_properties(&Properties::default(), V).unwrap().is_empty()); + let empty = decode_properties(&[], Some(Timescale::MILLI), true, V).unwrap(); + assert_eq!(empty.properties, Properties::default()); + + // An untimed track's Timestamp has no frame to hold it, so it stays in the block. + let untimed = [4, 0x10, 7]; + let decoded = decode_properties(&untimed, None, true, V).unwrap(); + assert_eq!(encode_properties(&decoded.properties, V).unwrap(), untimed); + } + + /// Only the canonical form decodes, so whatever decodes re-encodes to the same bytes. + #[test] + fn properties_refuse_what_is_not_canonical() { + let delta = 4; + for (body, reason) in [ + (&[0][..], "an encoding saying nothing"), + (&[delta][..], "an encoding with an empty block"), + (&[6, 0x20, 1][..], "an unknown encoding"), + ( + &[delta, 0x10, 5][..], + "a timed track's mutable Timestamp, which its frame holds", + ), + (&[0, 0x20, 1][..], "a block without an encoding"), + (&[delta, 0x0b, 2, 0x0b, 0][..], "a nested Immutable Properties"), + ] { + assert!( + decode_properties(body, Some(Timescale::MILLI), true, V).is_err(), + "accepted {reason}" + ); + } + } + + /// The worst case for re-encoding, a full moq-transport list of zero-delta properties + /// after a large first ID, crosses the hop byte for byte and is held at its wire size. + #[test] + fn a_full_block_crosses_at_its_wire_size() { + for version in [crate::ietf::Version::Draft16, crate::ietf::Version::Draft22] { + let mut list = Vec::new(); + let e = &mut Encoder::new(&mut list, version.into()); + // A Timestamp, then IDs from 2^40 on, each repeated as a two-byte zero delta. + for value in [0x10, 77, (1 << 40) - 0x10, 1] { + e.varint(value).unwrap(); + } + // The largest a timed track's block may be, once its Timestamp leaves it. + while list.len() <= crate::ietf::object::max_block(Some(Timescale::MILLI)) { + list.extend([0, 1]); + } + let list = Bytes::from(list); + let decoded = crate::ietf::object::read(&list, version, Some(Timescale::MILLI)).unwrap(); + let frame = decoded.timestamp; + let properties = decoded.properties; + let block = properties.block.as_ref().unwrap(); + assert!(block.bytes.len() < list.len(), "{version}"); + assert_eq!(properties.heap(), block.bytes.len() as u64, "{version}: decoded state"); + + let body = encode_properties(&properties, V).unwrap(); + assert!(body.len() <= MAX_PROPERTIES, "{version}: {} bytes", body.len()); + let received = decode_properties(&body, Some(Timescale::MILLI), true, V).unwrap(); + assert_eq!(received.properties, properties, "{version}"); + let written = + crate::ietf::object::write(&received.properties, frame, version, Some(Timescale::MILLI)).unwrap(); + assert_eq!(written, list, "{version}: the hop changed the list"); + } + } + + #[test] + fn track_properties_round_trip() { + let properties = crate::model::object::TrackProperties { + values: vec![ + Property { + id: IMMUTABLE, + value: Value::Bytes(Bytes::from_static(&[0x02, 0x01])), + }, + Property { + id: 0x41, + value: Value::Bytes(Bytes::from_static(b"opaque")), + }, + ], + encoding: Some(Encoding::Draft19), + }; + let msg = TrackProperties(Some(Arc::new(properties.clone()))); + let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); + let decoded = + >::decode(&mut Decoder::new(&buf, V.into()), V).unwrap(); + assert_eq!(decoded.0.as_deref(), Some(&properties)); + + let none = crate::coding::Encode::encode_bytes(&TrackProperties(None), V).unwrap(); + let decoded = + >::decode(&mut Decoder::new(&none, V.into()), V).unwrap(); + assert!(decoded.0.is_none()); + } + + /// A peer cannot make a relay hold or forward more than moq-transport ingress would, + /// restate what TRACK_INFO carries, or claim sealed keys its block does not hold. + #[test] + fn track_properties_refuse_what_ingress_would_not_keep() { + let wire = |values: &[Property], code: u64| { + let mut buf = Vec::new(); + let w = &mut Encoder::new(&mut buf, V.into()); + w.varint(code).unwrap(); + let list = encode_list(&crate::model::object::TrackProperties { + values: values.to_vec(), + encoding: Some(Encoding::Draft18), + }) + .unwrap(); + w.slice(&list); + buf + }; + let decode = |buf: &[u8]| TrackProperties::decode_msg(&mut Decoder::new(buf, V.into()), V); + let opaque = |id| Property { + id, + value: Value::Int(1), + }; + + let max = crate::ietf::properties::MAX_PROPERTIES; + let list: Vec<_> = (0..=max).map(|i| opaque(0x40 + 2 * i)).collect(); + assert!(decode(&wire(&list[..max as usize], 4)).is_ok()); + assert!(decode(&wire(&list, 4)).is_err(), "more than ingress keeps"); + // TIMESCALE belongs to TRACK_INFO. + assert!(decode(&wire(&[opaque(0x08)], 4)).is_err(), "an understood property"); + assert!(decode(&wire(&[opaque(0x40)], 0)).is_err(), "a list needs its encoding"); + assert!(decode(&[2]).is_err(), "an encoding without a list"); + assert!( + decode(&wire(&[opaque(0x40)], 1)).is_err(), + "track properties never use absolute keys" + ); + + // The sealed keys come from the block, never the sender. + let sealed = Property { + id: IMMUTABLE, + value: Value::Bytes(Bytes::from_static(&[0x20, 0x01, 0x04, 0x05])), + }; + let decoded = decode(&wire(std::slice::from_ref(&sealed), 4)).unwrap().0.unwrap(); + assert!(decoded.sealed().eq([0x20, 0x24])); + assert!( + decode(&wire(&[sealed.clone(), sealed], 4)).is_err(), + "a second block leaves the sealed keys ambiguous" + ); + } + + /// Sealed keys are read from the Immutable Properties block, never held beside it as a + /// list that could cost several times the block. + #[test] + fn track_properties_hold_sealed_keys_in_their_block() { + // Nearly as many two-byte keys as a lite message holds: 0x20 = 1, then zero deltas. + let count = 32_000; + let mut sealed = vec![0x20, 1]; + sealed.extend([0, 1].repeat(count - 1)); + let msg = TrackProperties(Some(Arc::new(crate::model::object::TrackProperties { + values: vec![Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.into()), + }], + encoding: Some(Encoding::Draft18), + }))); + let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); + let decoded = >::decode(&mut Decoder::new(&buf, V.into()), V) + .unwrap() + .0 + .unwrap(); + assert_eq!(decoded.values.len(), 1); + assert_eq!(decoded.sealed().count(), count); + assert!(decoded.sealed().all(|id| id == 0x20)); + } + + /// Track Properties cross in the delta encoding moq-transport sent, where a repeated ID + /// is a one-byte zero. Written with absolute IDs, a list that filled its moq-transport + /// message would no longer fit a lite one. + #[test] + fn track_properties_cross_at_their_wire_size() { + for version in [ + crate::ietf::Version::Draft16, + crate::ietf::Version::Draft17, + crate::ietf::Version::Draft22, + ] { + // As many repeats of an ID from 2^60 as moq-transport forwards, then one value + // that fills the rest of a lite message beside its Flags. + let id = (1 << 60) + 1; + let repeats = crate::ietf::properties::MAX_FORWARDED - 1; + let mut list = Vec::new(); + let e = &mut Encoder::new(&mut list, version.into()); + e.varint(id).unwrap(); + e.bytes(&[]).unwrap(); + for _ in 1..repeats { + e.varint(0).unwrap(); + e.bytes(&[]).unwrap(); + } + let rest = super::super::message::MAX_MESSAGE_SIZE - 1 - list.len() - 1; + let fill = (1..=8) + .map(|prefix| rest - prefix) + .find(|fill| { + crate::coding::varint::size(*fill as u64, version.into()).is_ok_and(|size| size == rest - fill) + }) + .unwrap(); + let e = &mut Encoder::new(&mut list, version.into()); + e.varint(0).unwrap(); + e.bytes(&vec![0; fill]).unwrap(); + assert_eq!(list.len(), super::super::message::MAX_MESSAGE_SIZE - 1, "{version}"); + + let ingress = crate::ietf::Properties::decode(&mut Decoder::new(&list, version.into()), version).unwrap(); + assert_eq!(ingress.unknown.values.len(), repeats + 1, "{version}"); + assert!( + ingress.unknown.refused(&crate::track::Info::default()).is_none(), + "{version}" + ); + + let msg = TrackProperties(Some(Arc::new(ingress.unknown.clone()))); + let buf = crate::coding::Encode::encode_bytes(&msg, V).unwrap(); + let decoded = + >::decode(&mut Decoder::new(&buf, V.into()), V) + .unwrap(); + assert_eq!(decoded.0.as_deref(), Some(&ingress.unknown), "{version}"); + + let mut written = Vec::new(); + let egress = crate::ietf::Properties { + unknown: decoded.0.unwrap().as_ref().clone(), + ..Default::default() + }; + egress + .encode(&mut Encoder::new(&mut written, version.into()), version) + .unwrap(); + assert_eq!(written, list, "{version}: the hop changed the list"); + } + } + + /// Dropping an understood property can widen the delta that spans it, so a list that + /// could not cross is refused where it arrives rather than where it would be sent. + #[test] + fn track_properties_that_cannot_cross_are_refused_at_ingress() { + let version = crate::ietf::Version::Draft16; + // The most a draft-16 answer holds beside a Request ID and an empty parameter count. + let size = super::super::message::MAX_MESSAGE_SIZE - 2; + // DYNAMIC_GROUPS, then the last ID whose delta from it fits four bytes. + let id = 0x30 + (1 << 30) - 1; + let mut list = Vec::new(); + let e = &mut Encoder::new(&mut list, version.into()); + for value in [0x30, 1, id - 0x30] { + e.varint(value).unwrap(); + } + let fill = size - list.len() - 4; + let e = &mut Encoder::new(&mut list, version.into()); + e.bytes(&vec![0; fill]).unwrap(); + assert_eq!(list.len(), size); + + // The delta from zero takes eight bytes once DYNAMIC_GROUPS leaves the list. + let ingress = crate::ietf::Properties::decode(&mut Decoder::new(&list, version.into()), version).unwrap(); + assert!(ingress.dynamic_groups); + assert!(!fits(&ingress.unknown)); + assert!(matches!( + ingress.unknown.refused(&crate::track::Info::default()), + Some(crate::Error::Unsupported) + )); + } + + /// A relay holds and forwards a datagram's Status, so one moq-transport does not define + /// would close the session it reached: it is refused where it arrives. + #[test] + fn datagram_statuses_are_ones_moq_transport_defines() { + for (status, ok) in [(0, true), (1, true), (2, false), (3, true), (4, true), (5, false)] { + let wire = crate::model::datagram::Wire { + object_id: None, + priority: None, + end_of_group: false, + status: Some(status), + properties: Properties::default(), + }; + let mut buf = Vec::new(); + encode_datagram(&mut Encoder::new(&mut buf, V.into()), Some(&wire), V).unwrap(); + let decoded = decode_datagram(&mut Decoder::new(&buf, V.into()), None, V); + assert_eq!(decoded.is_ok(), ok, "{status}"); + } + } + + /// No moq-transport draft defines a status datagram that also ends the group, so one + /// is refused where it arrives, by the check moq-transport ingress applies. + #[test] + fn a_status_datagram_cannot_end_the_group() { + let wire = crate::model::datagram::Wire { + object_id: Some(3), + priority: Some(9), + end_of_group: true, + status: Some(3), + properties: Properties::default(), + }; + let mut buf = Vec::new(); + encode_datagram(&mut Encoder::new(&mut buf, V.into()), Some(&wire), V).unwrap(); + assert!(decode_datagram(&mut Decoder::new(&buf, V.into()), None, V).is_err()); + } + + #[test] + fn datagram_state_round_trips() { + for (end_of_group, status) in [(false, Some(3)), (true, None)] { + let wire = crate::model::datagram::Wire { + object_id: Some(3), + priority: Some(9), + end_of_group, + status, + properties: Properties::default(), + }; + let mut buf = Vec::new(); + encode_datagram(&mut Encoder::new(&mut buf, V.into()), Some(&wire), V).unwrap(); + let decoded = decode_datagram(&mut Decoder::new(&buf, V.into()), None, V).unwrap(); + assert_eq!(decoded, Some(wire)); + } + + let mut plain = Vec::new(); + encode_datagram(&mut Encoder::new(&mut plain, V.into()), None, V).unwrap(); + assert_eq!(plain, [0]); + assert_eq!( + decode_datagram(&mut Decoder::new(&plain, V.into()), None, V).unwrap(), + None + ); + } + + /// A retained datagram holds its properties as the bytes they arrived as, not a decoded + /// list many times their size. + #[test] + fn datagram_properties_are_held_at_their_wire_size() { + const COUNT: usize = 500; + let mut block = vec![0x20, 1]; + for _ in 1..COUNT { + block.extend([0, 1]); + } + let mut body = vec![4]; + body.extend(&block); + let mut buf = Vec::new(); + let w = &mut Encoder::new(&mut buf, V.into()); + w.varint(RELAYED).unwrap(); + w.bytes(&body).unwrap(); + let wire = decode_datagram(&mut Decoder::new(&buf, V.into()), None, V) + .unwrap() + .unwrap(); + assert_eq!(wire.properties.heap(), block.len() as u64); + assert!(wire.properties.heap() < (COUNT * size_of::()) as u64 / 10); + } + + /// A body holding property 0x20 = 1, which every family serializes alike, claiming the + /// encoding `code`. + fn claiming(code: u8) -> [u8; 3] { + [code, 0x20, 1] + } + + /// Each code names the drafts a block came from, so whether 0x06 means + /// SUBGROUP_DELIVERY_TIMEOUT follows from it: only for code 5, drafts 19 and later. + #[test] + fn encoding_codes_name_their_drafts() { + for code in 1..=5 { + let decoded = decode_properties(&claiming(code), None, true, V).unwrap(); + let encoding = decoded.properties.block.unwrap().encoding; + assert_eq!(encode_encoding(Some(encoding)), u64::from(code)); + assert_eq!(crate::ietf::object::delivery_timeout(encoding), code == 5, "{code}"); + let list = TrackProperties::decode_msg(&mut Decoder::new(&claiming(code), V.into()), V); + // Track Properties start at draft-16. + assert_eq!(list.is_ok(), code != 1, "{code}"); + } + assert!(decode_properties(&claiming(6), None, true, V).is_err()); + + // A draft-18 0x06 is dropped on its way to draft-19, where it would mean a timeout. + for (code, kept) in [(4, false), (5, true)] { + let decoded = decode_properties(&[code, 0x06, 42], None, true, V).unwrap(); + let written = + crate::ietf::object::write(&decoded.properties, None, crate::ietf::Version::Draft19, None).unwrap(); + assert_eq!(!written.is_empty(), kept, "{code}"); + } + } + + /// Only draft-14 lets a status object carry properties, so the END_OF_GROUP record's + /// block must claim the drafts 14 and 15 encoding. + #[cfg(feature = "async")] + #[test] + fn an_end_record_block_claims_a_draft_that_carries_one() { + for code in 1..=5 { + assert_eq!(decode_end(&claiming(code), None, V).is_ok(), code == 1, "{code}"); + } + assert!(decode_end(&[], None, V).is_ok()); + } + + /// A datagram's block names its family, so one of those drafts must define the whole + /// datagram: from draft-17 on a non-zero Status carries no properties, and only drafts + /// 14 and 15 define DOES_NOT_EXIST. + #[test] + fn a_datagram_block_claims_a_draft_that_sends_its_shape() { + for (status, codes) in [(0, &[1, 2, 3, 4, 5][..]), (1, &[1]), (3, &[1, 2]), (4, &[1, 2])] { + for code in 1..=5 { + let mut buf = Vec::new(); + let w = &mut Encoder::new(&mut buf, V.into()); + w.varint(RELAYED | STATUS).unwrap(); + w.varint(status).unwrap(); + w.bytes(&claiming(code)).unwrap(); + let decoded = decode_datagram(&mut Decoder::new(&buf, V.into()), None, V); + assert_eq!(decoded.is_ok(), codes.contains(&code), "{status}: {code}"); + } + } + } +} + +/// Peer a relay behind `upstream` over moq-lite 07, the way a cluster does. The client +/// (downstream) and server (upstream) each offer the `ietf` extension per `offer`. +/// Returns the downstream origin once it learned of `broadcast`, and the sessions to hold. +#[cfg(all(test, feature = "async"))] +pub(crate) async fn test_hop( + upstream: &crate::origin::Producer, + broadcast: &str, + offer: [bool; 2], +) -> (crate::origin::Producer, [crate::Session; 2]) { + use crate::model::ProduceTest; + let version = crate::Version::Lite(Version::Lite07); + let downstream = crate::origin::Config::new(crate::Hop::new(3).unwrap()).produce(); + let (client, server) = crate::transport::memory::pair(crate::transport::memory::Config { + protocol: Some(version.alpn().to_string()), + ..Default::default() + }); + let extensions = |ietf| crate::setup::Extensions { + ietf, + ..Default::default() + }; + let dial = crate::Client::new() + .with_versions(version.into()) + .with_extensions(extensions(offer[0])) + .with_subscriber(downstream.clone()); + let serve = crate::Server::new() + .with_versions(version.into()) + .with_extensions(extensions(offer[1])) + .with_publisher(upstream.consume()); + let (client, server) = futures::join!( + async { + let (session, driver) = dial.connect(moq_clock::now(), client).await.unwrap(); + drop(moq_clock::sim::spawn(crate::time::run(driver))); + session + }, + async { + let (session, driver) = serve.accept(moq_clock::now(), server).await.unwrap(); + drop(moq_clock::sim::spawn(crate::time::run(driver))); + session + }, + ); + downstream + .consume() + .routed(broadcast) + .await + .expect("the hop announced the broadcast"); + (downstream, [client, server]) +} + +#[cfg(all(test, feature = "async"))] +mod hop_tests { + use super::*; + use crate::{Timestamp, frame, model::ProduceTest, track}; + use std::time::Duration; + + const TIMEOUT: Duration = Duration::from_secs(5); + /// Prior Object ID Gap. + const GAP: u64 = 0x3e; + + fn ts(millis: u64) -> Timestamp { + Timestamp::new(millis, Timescale::MILLI).unwrap() + } + + fn property(id: u64, value: u64) -> Property { + Property { + id, + value: Value::Int(value), + } + } + + /// The block a draft-22 publisher's `values` arrive as. + fn block(values: &[Property]) -> Option { + crate::ietf::object::block(values, Encoding::Draft19).unwrap() + } + + /// Write a frame carrying relay `fields`, as moq-transport ingress does, returning the + /// group's writer. + fn write( + group: group::Producer, + millis: u64, + fields: Option, + payload: &[u8], + ) -> group::Producer { + let mut frame = group + .create_frame_owned( + frame::Header { + info: frame::Info { + size: payload.len() as u64, + timestamp: Some(ts(millis)), + }, + fields: fields.map(Arc::new), + }, + &frame::Budget::default(), + ) + .unwrap(); + frame.write(Bytes::copy_from_slice(payload)).unwrap(); + frame.finish().unwrap() + } + + /// A frame's Object ID and properties, when it keeps any. + fn fields(frame: &frame::Object) -> Option<(u64, Properties)> { + frame + .fields + .as_ref() + .map(|fields| (fields.id, fields.properties.clone())) + } + + async fn next(group: &mut group::Consumer) -> Option { + moq_clock::timeout(TIMEOUT, kio::wait(|waiter| group.poll_read_object(waiter))) + .await + .expect("no frame") + .unwrap() + } + + async fn subscribe(origin: &crate::origin::Producer) -> (track::Consumer, track::Subscriber) { + let broadcast = moq_clock::timeout(TIMEOUT, origin.consume().request_broadcast("room", None)) + .await + .expect("no broadcast") + .unwrap(); + let track = broadcast.track("video").unwrap(); + let subscriber = moq_clock::timeout(TIMEOUT, track.subscribe(None)) + .await + .expect("no subscription") + .unwrap(); + (track, subscriber) + } + + async fn recv(subscriber: &mut track::Subscriber) -> group::Consumer { + moq_clock::timeout(TIMEOUT, subscriber.recv_group()) + .await + .expect("no group") + .unwrap() + .expect("track finished") + } + + /// A relayed group crosses the hop frame by frame while it is still open, with its + /// Object IDs, properties, and END_OF_GROUP position, and its track's properties. + /// A side that does not offer the extension gets the plain frames alone. The track info + /// moq-transport egress restates as Track Properties crosses either way. + #[moq_clock::test] + async fn relayed_state_crosses_while_the_group_is_open() { + for offer in [[true, true], [true, false], [false, true]] { + let negotiated = offer == [true, true]; + let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); + let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); + let mut info = track::Info::timed().with_timescale(Timescale::MILLI); + info.max_age = Some(Duration::from_secs(7)); + info.priority = 9; + info.refresh = Some(0); + let track_properties = crate::model::object::TrackProperties { + values: vec![property(0x40, 3)], + encoding: Some(Encoding::Draft19), + }; + info.properties = Some(Arc::new(track_properties.clone())); + let track = broadcast.create_track("video", info).unwrap(); + + let mut group = track.create_group(group::Info { sequence: 0 }).unwrap(); + group + .set_wire(group::Wire { + sparse: false, + first_object: true, + first_id: 6, + extensions: true, + has_end: true, + fetchable: true, + last: None, + }) + .unwrap(); + let first = crate::model::object::Fields { + id: 6, + properties: Properties { + block: block(&[property(0x20, 1), property(GAP, 6)]), + ..Default::default() + }, + }; + group.mark_gap(6, Some(6)).unwrap(); + group = write(group, 0, Some(first.clone()), b"a"); + + let (downstream, _sessions) = test_hop(&upstream, "room", offer).await; + let (copy, mut subscriber) = subscribe(&downstream).await; + let mut received = recv(&mut subscriber).await; + + // The upstream group is still open. + let frame = next(&mut received).await.unwrap(); + assert_eq!(&frame.payload[..], b"a"); + assert_eq!(frame.timestamp, Some(ts(0))); + match negotiated { + true => { + assert_eq!(fields(&frame), Some((first.id, first.properties.clone())), "{offer:?}"); + let wire = received.wire().expect("relay state"); + assert!(wire.first_object && wire.extensions && wire.has_end); + assert_eq!(wire.first_id, 6); + } + false => { + assert!(frame.fields.is_none(), "{offer:?}"); + assert!(received.wire().is_none(), "{offer:?}"); + } + } + + // Object 9 marks the two it skipped, then the group ends at Object 10. + let second = crate::model::object::Fields { + id: 9, + properties: Properties { + block: block(&[property(GAP, 2)]), + ..Default::default() + }, + }; + group.mark_gap(9, Some(2)).unwrap(); + group = write(group, 1, Some(second.clone()), b"b"); + group.mark_gap(10, None).unwrap(); + group + .set_end_object(crate::model::object::Fields { + id: 10, + properties: Properties::default(), + }) + .unwrap(); + group.finish().unwrap(); + + let frame = next(&mut received).await.unwrap(); + assert_eq!(&frame.payload[..], b"b"); + assert!(next(&mut received).await.is_none()); + let info = moq_clock::timeout(TIMEOUT, copy.query()).await.unwrap().unwrap(); + assert_eq!( + (info.max_age, info.timescale, info.priority, info.refresh), + (Some(Duration::from_secs(7)), Some(Timescale::MILLI), 9, Some(0)), + "{offer:?}" + ); + match negotiated { + true => { + assert_eq!(fields(&frame), Some((second.id, second.properties.clone()))); + assert_eq!(received.end_object().map(|end| end.id), Some(10)); + assert!(received.wire().unwrap().fetchable, "every jump was marked"); + assert_eq!(info.properties.as_deref(), Some(&track_properties)); + } + false => { + assert!(frame.fields.is_none()); + assert!(received.end_object().is_none()); + assert!(info.properties.is_none()); + } + } + } + } + + /// A subscription capped at a group's last frame stops there: its Group State promises + /// no END_OF_GROUP, so the END_OF_GROUP record past the cap is not sent either. + #[moq_clock::test] + async fn a_capped_stream_carries_no_end_record() { + let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); + let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); + let track = broadcast + .create_track("video", track::Info::timed().with_timescale(Timescale::MILLI)) + .unwrap(); + let mut group = track.create_group(group::Info { sequence: 0 }).unwrap(); + group + .set_wire(group::Wire { + sparse: false, + first_object: true, + first_id: 0, + extensions: false, + has_end: true, + fetchable: true, + last: None, + }) + .unwrap(); + for (index, payload) in [b"a", b"b"].into_iter().enumerate() { + let fields = crate::model::object::Fields { + id: index as u64, + properties: Properties::default(), + }; + group = write(group, index as u64, Some(fields), payload); + } + group.mark_gap(2, None).unwrap(); + group + .set_end_object(crate::model::object::Fields { + id: 2, + properties: Properties::default(), + }) + .unwrap(); + group.finish().unwrap(); + + let (downstream, _sessions) = test_hop(&upstream, "room", [true, true]).await; + let broadcast = moq_clock::timeout(TIMEOUT, downstream.consume().request_broadcast("room", None)) + .await + .expect("no broadcast") + .unwrap(); + let capped = track::Subscription::default().with_end(track::Position::after(0, 1)); + let mut subscriber = moq_clock::timeout(TIMEOUT, broadcast.track("video").unwrap().subscribe(capped)) + .await + .expect("no subscription") + .unwrap(); + let mut received = recv(&mut subscriber).await; + assert_eq!(&next(&mut received).await.unwrap().payload[..], b"a"); + assert_eq!(&next(&mut received).await.unwrap().payload[..], b"b"); + assert!(next(&mut received).await.is_none()); + assert!(!received.wire().expect("relay state").has_end); + assert!(received.end_object().is_none(), "an END_OF_GROUP past the cap"); + } + + /// Subscribe across a negotiated hop to a timed track carrying `properties`. + async fn subscribe_across(properties: crate::model::object::TrackProperties) -> Result<(), crate::Error> { + let mut info = track::Info::timed().with_timescale(Timescale::MILLI); + info.properties = Some(Arc::new(properties)); + subscribe_across_info(info).await + } + + /// Subscribe across a negotiated hop to a track with `info`. + async fn subscribe_across_info(info: track::Info) -> Result<(), crate::Error> { + let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); + let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); + let _track = broadcast.create_track("video", info).unwrap(); + + let (downstream, _sessions) = test_hop(&upstream, "room", [true, true]).await; + let broadcast = moq_clock::timeout(TIMEOUT, downstream.consume().request_broadcast("room", None)) + .await + .expect("no broadcast") + .unwrap(); + moq_clock::timeout(TIMEOUT, broadcast.track("video").unwrap().subscribe(None)) + .await + .expect("no answer") + .map(drop) + } + + /// A track with a Mandatory Track Property, mutable or sealed, is refused across the hop + /// as moq-transport ingress refuses it: one we do not understand is neither processed + /// nor forwarded. + #[moq_clock::test] + async fn mandatory_track_properties_are_refused() { + let mut sealed = Vec::new(); + let e = &mut Encoder::new(&mut sealed, crate::ietf::Version::Draft22.into()); + e.varint(0x4000).unwrap(); + e.varint(1).unwrap(); + for values in [ + vec![property(0x4000, 1)], + vec![Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.into()), + }], + ] { + let res = subscribe_across(crate::model::object::TrackProperties { + values: values.clone(), + encoding: Some(Encoding::Draft19), + }) + .await; + assert!( + matches!(res, Err(crate::Error::UnsupportedExtension)), + "{values:?}: {res:?}" + ); + } + } + + /// A sealed TIMESCALE that contradicts TRACK_INFO is refused across the hop: the relay + /// times frames by TRACK_INFO, while egress would forward the sealed one. + #[moq_clock::test] + async fn a_sealed_property_must_match_track_info() { + for (timescale, ok) in [(1000, true), (900, false), (0, false)] { + let mut sealed = Vec::new(); + let e = &mut Encoder::new(&mut sealed, crate::ietf::Version::Draft22.into()); + e.varint(0x08).unwrap(); + e.varint(timescale).unwrap(); + let res = subscribe_across(crate::model::object::TrackProperties { + values: vec![Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.into()), + }], + encoding: Some(Encoding::Draft19), + }) + .await; + match ok { + true => assert!(res.is_ok(), "{timescale}: {res:?}"), + false => assert!(matches!(res, Err(crate::Error::Unsupported)), "{timescale}: {res:?}"), + } + } + } + + /// A sealed DYNAMIC_GROUPS must match the refresh TRACK_INFO carries across the hop, + /// which moq-transport egress restates as DYNAMIC_GROUPS. + #[moq_clock::test] + async fn a_sealed_dynamic_groups_must_match_track_info() { + for (refresh, value, ok) in [ + (Some(0), 1, true), + (None, 0, true), + (Some(0), 0, false), + (None, 1, false), + ] { + let mut sealed = Vec::new(); + let e = &mut Encoder::new(&mut sealed, crate::ietf::Version::Draft22.into()); + e.varint(0x30).unwrap(); + e.varint(value).unwrap(); + let mut info = track::Info::timed().with_timescale(Timescale::MILLI); + info.refresh = refresh; + info.properties = Some(Arc::new(crate::model::object::TrackProperties { + values: vec![Property { + id: IMMUTABLE, + value: Value::Bytes(sealed.into()), + }], + encoding: Some(Encoding::Draft19), + })); + let res = subscribe_across_info(info).await; + match ok { + true => assert!(res.is_ok(), "{refresh:?} {value}: {res:?}"), + false => assert!( + matches!(res, Err(crate::Error::Unsupported)), + "{refresh:?} {value}: {res:?}" + ), + } + } + } + + /// A relay forwards only as many Track Properties as leave room for the ones it + /// restates from TRACK_INFO, so one more is refused across the hop. + #[moq_clock::test] + async fn forwarded_track_properties_leave_room_for_track_info() { + let max = crate::ietf::properties::MAX_FORWARDED; + for (count, ok) in [(max, true), (max + 1, false)] { + let res = subscribe_across(crate::model::object::TrackProperties { + values: (0..count as u64).map(|i| property(0x40 + 2 * i, 1)).collect(), + encoding: Some(Encoding::Draft19), + }) + .await; + match ok { + true => assert!(res.is_ok(), "{count}: {res:?}"), + false => assert!(matches!(res, Err(crate::Error::Unsupported)), "{count}: {res:?}"), + } + } + } + + /// Groups and datagrams from a moq-lite publisher cross a negotiated hop as plain as + /// they left: no relay state appears on the way. + #[moq_clock::test] + async fn plain_media_crosses_unchanged() { + let upstream = crate::origin::Config::new(crate::Hop::new(2).unwrap()).produce(); + let broadcast = upstream.publish("room", crate::origin::Route::default()).unwrap(); + let mut track = broadcast + .create_track("video", track::Info::timed().with_timescale(Timescale::MILLI)) + .unwrap(); + let (downstream, sessions) = test_hop(&upstream, "room", [true, true]).await; + let (_copy, mut subscriber) = subscribe(&downstream).await; + + let mut group = track.append_group().unwrap(); + group.write_frame(ts(5), b"key".to_vec()).unwrap(); + let mut received = recv(&mut subscriber).await; + let frame = next(&mut received).await.unwrap(); + assert_eq!((frame.timestamp, &frame.payload[..]), (Some(ts(5)), &b"key"[..])); + assert!(frame.fields.is_none() && received.wire().is_none()); + group.write_frame(ts(6), b"delta".to_vec()).unwrap(); + group.finish().unwrap(); + let frame = next(&mut received).await.unwrap(); + assert_eq!((frame.timestamp, &frame.payload[..]), (Some(ts(6)), &b"delta"[..])); + assert!(frame.fields.is_none()); + assert!(next(&mut received).await.is_none()); + assert!(received.end_object().is_none()); + + track.insert_datagram(7, ts(9), b"datagram".to_vec()).unwrap(); + let datagram = moq_clock::timeout(TIMEOUT, kio::wait(|waiter| subscriber.poll_recv_wire_datagram(waiter))) + .await + .expect("no datagram") + .unwrap() + .unwrap(); + assert_eq!((datagram.sequence, datagram.timestamp), (7, Some(ts(9)))); + assert_eq!(&datagram.payload[..], b"datagram"); + assert!(datagram.wire.is_none()); + drop(sessions); + } +} diff --git a/rs/moq-net/src/lite/mod.rs b/rs/moq-net/src/lite/mod.rs index 656338a4e66..d80b29e8c73 100644 --- a/rs/moq-net/src/lite/mod.rs +++ b/rs/moq-net/src/lite/mod.rs @@ -16,6 +16,7 @@ pub(crate) mod error; mod fetch; mod goaway; mod group; +pub(crate) mod ietf; mod info; pub mod message; mod parameters; diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 54cf9c24421..2850cf0f487 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1933,10 +1933,11 @@ impl Request for TrackInfoServe { fn poll( &mut self, - _: &Shared, + shared: &Shared, writer: &mut Writer, waiter: &kio::Waiter, ) -> Poll, Error>> { + let ietf = ready!(shared.peer_setup.poll_ietf(waiter)); let info = ready!(self.querying.poll_ok(waiter))?; // TRACK_INFO only flows on Lite05+ (the encode errors otherwise). @@ -1946,6 +1947,9 @@ impl Request for TrackInfoServe { max_age: info.max_age, timescale: info.timescale, })?; + if ietf { + writer.buffer(&lite::ietf::TrackProperties(info.properties.clone()))?; + } Poll::Ready(Ok(ControlFlow::Break(()))) } } @@ -2032,6 +2036,7 @@ impl Request for SubscribeServe { loop { match self { Self::Confirm { subscribing, .. } => { + let ietf = ready!(shared.peer_setup.poll_ietf(waiter)); let mut track = ready!(subscribing.poll_ok(waiter))?; let Self::Confirm { msg, latest, update, .. @@ -2089,6 +2094,7 @@ impl Request for SubscribeServe { timescale, runtime: shared.runtime.clone(), outcomes: Default::default(), + ietf, }; let bounds = Bounds::from(msg.as_ref()); @@ -2149,11 +2155,16 @@ enum FetchServe { prev_ts: u64, frame: Option, chunk: Option, - batch: Box, + batch: Box, batch_pos: usize, + /// The `ietf` extension's object records, when negotiated. + records: Option, }, } +/// A batch of frames with their relay metadata, which the `ietf` extension forwards. +type Objects = arrayvec::ArrayVec; + impl Request for FetchServe { const KIND: &'static str = "fetch"; const FETCH: bool = true; @@ -2200,6 +2211,8 @@ impl Request for FetchServe { loop { match self { Self::Fetch { msg, fetching } => { + // Before the group: a fetched group polled while this waited would be lost. + let ietf = ready!(shared.peer_setup.poll_ietf(waiter)); let mut group = ready!(kio::Task::poll(fetching, waiter))?; // The response carries no header, so a short run is indistinguishable @@ -2216,6 +2229,8 @@ impl Request for FetchServe { // Matches the timescale TRACK_INFO declared for the track. let timescale = shared.version.wire_timescale(group.timescale()); + let capped = msg.end_frame.is_some(); + let records = lite::ietf::Records::start(writer, ietf, &group, capped, timescale, shared.version)?; *self = Self::Serve { group, @@ -2223,8 +2238,9 @@ impl Request for FetchServe { prev_ts: 0, frame: None, chunk: None, - batch: Box::new(frame::Buffer::new()), + batch: Box::default(), batch_pos: 0, + records, }; } Self::Serve { @@ -2235,6 +2251,7 @@ impl Request for FetchServe { chunk, batch, batch_pos, + records, } => { let mut cx = waiter.context(); loop { @@ -2250,7 +2267,11 @@ impl Request for FetchServe { None => *frame = None, } } else if *batch_pos < batch.len() { - let batched = &mut batch.filled_mut()[*batch_pos]; + let index = group.index() - batch.len() as u64 + *batch_pos as u64; + let batched = &mut batch[*batch_pos]; + if let Some(records) = records { + records.frame(writer, index, batched.fields.as_deref())?; + } buffer_frame_info( writer, batched.timestamp, @@ -2259,24 +2280,32 @@ impl Request for FetchServe { prev_ts, &shared.runtime, )?; - let payload = std::mem::take(&mut batched.payload); + let payload = std::mem::take(&mut batched.frame.payload); if !payload.is_empty() { *chunk = Some(payload); } *batch_pos += 1; group.keep_alive(); } else { - match group.poll_read_frames(waiter, batch) { + match group.poll_read_objects(waiter, batch) { Poll::Ready(Ok(count)) if count > 0 => { *batch_pos = 0; return Poll::Ready(Ok(ControlFlow::Continue(()))); } - Poll::Ready(Ok(_)) => return Poll::Ready(Ok(ControlFlow::Break(()))), + Poll::Ready(Ok(_)) => { + if let Some(records) = records { + records.end(writer, group)?; + } + return Poll::Ready(Ok(ControlFlow::Break(()))); + } Poll::Ready(Err(err)) => return Poll::Ready(Err(err)), Poll::Pending => {} } match ready!(group.poll_next_frame(waiter))? { Some(next) => { + if let Some(records) = records { + records.frame(writer, group.index() - 1, next.fields.as_deref())?; + } buffer_frame_info( writer, next.timestamp, @@ -2288,7 +2317,12 @@ impl Request for FetchServe { *frame = Some(next); return Poll::Ready(Ok(ControlFlow::Continue(()))); } - None => return Poll::Ready(Ok(ControlFlow::Break(()))), + None => { + if let Some(records) = records { + records.end(writer, group)?; + } + return Poll::Ready(Ok(ControlFlow::Break(()))); + } } } } @@ -3287,7 +3321,7 @@ fn buffer_zigzag_delta( #[allow(clippy::large_enum_variant)] enum Recv { Group(group::Consumer), - Datagram(crate::Datagram), + Datagram(crate::model::datagram::Stored), Boundary(u64), Finished, } @@ -3326,7 +3360,7 @@ fn poll_recv_next( Poll::Pending => {} } if datagrams { - match track.poll_recv_datagram(waiter)? { + match track.poll_recv_wire_datagram(waiter)? { Poll::Ready(Some(datagram)) => return Poll::Ready(Ok(Recv::Datagram(datagram))), // Datagram side finished but groups are still paused/pending: keep waiting on groups. Poll::Ready(None) => {} @@ -3482,6 +3516,8 @@ struct Subscription { runtime: crate::time::Deadlines, /// Outcomes shared by the subscription and every group it serves. outcomes: Arc, + /// Whether the session negotiated the `ietf` extension, so streams carry relay state. + ietf: bool, } /// Group outcomes the subscription must report even if no header reached the peer. @@ -3501,19 +3537,44 @@ impl Subscription { /// The datagram is dropped (there is no group fallback) if the encoded body doesn't fit the /// transport's datagram limit or the send fails (congestion / no capacity right now). /// Returns whether it was handed to the transport. - fn serve_datagram(&mut self, datagram: crate::Datagram) -> bool { + fn serve_datagram(&mut self, datagram: crate::model::datagram::Stored) -> bool { + // Only the `ietf` extension can say a datagram is a status rather than a payload. + let status = datagram + .wire + .as_ref() + .is_some_and(|wire| wire.status.is_some_and(|status| status != 0)); + if status && !self.ietf { + return false; + } let Ok(timestamp) = self .timescale + .filter(|_| !status) .map(|timescale| wire_timestamp(datagram.timestamp, timescale, &self.runtime)) .transpose() else { return false; }; + let ietf = match (self.ietf, &datagram.wire) { + (false, _) => None, + (true, None) => Some(None), + // A sealed Timestamp keeps its units, which the receiver reads as the track's. + (true, Some(wire)) + if wire + .properties + .sealed_time + .is_some_and(|sealed| self.timescale != Some(sealed.scale())) => + { + return false; + } + (true, Some(wire)) => Some(Some(wire.as_ref().clone())), + }; + let sequence = datagram.sequence; let body = lite::Datagram { subscribe: self.id, - sequence: datagram.sequence, + sequence, timestamp, - payload: datagram.payload, + payload: datagram.datagram.payload, + ietf, }; // has_datagrams is checked before this runs, and the timescale is set wherever the // version needs a timestamp, so encoding never hits a version guard. @@ -3524,7 +3585,7 @@ impl Subscription { let max = self.session.max_datagram_size(); if body.len() > max { tracing::debug!( - sequence = datagram.sequence, + sequence, size = body.len(), max, "dropping datagram larger than the transport limit" @@ -3533,7 +3594,7 @@ impl Subscription { } // The run loop may not have served a group since the last SUBSCRIBE_UPDATE. - let priority = crate::priority::in_group(datagram.sequence, 0, self.steer_current().order); + let priority = crate::priority::in_group(sequence, 0, self.steer_current().order); let options = SendOptions { group: self.group.as_ref(), priority, @@ -3577,6 +3638,7 @@ impl Subscription { self, sequence, frame_start, + false, Rank::Queue(priority), group, )); @@ -3775,7 +3837,7 @@ impl TrackRun { Poll::Pending => { self.first = Some(group); if self.datagrams - && let Poll::Ready(Some(datagram)) = self.track.poll_recv_datagram(waiter)? + && let Poll::Ready(Some(datagram)) = self.track.poll_recv_wire_datagram(waiter)? { self.serve_datagram(datagram); return Poll::Ready(Ok(ControlFlow::Continue(()))); @@ -3894,7 +3956,7 @@ impl TrackRun { } /// Send a datagram, recording its sequence once it went out. - fn serve_datagram(&mut self, datagram: crate::Datagram) { + fn serve_datagram(&mut self, datagram: crate::model::datagram::Stored) { let sequence = datagram.sequence; if self.ctx.serve_datagram(datagram) { self.mark_served(sequence); @@ -4012,6 +4074,8 @@ impl TrackRun { fn serve(&mut self, group: group::Consumer) { let sequence = group.sequence; let frame_start = group.index(); + // The stream stops at the end frame, before the group may end. + let capped = self.end_frame.is_some_and(|(end, _)| end == sequence); self.mark_served(sequence); tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, sequence, "serving group"); @@ -4028,8 +4092,14 @@ impl TrackRun { .insert(Priority::new(steer.priority, self.ctx.id, sequence).with_order(steer.order)), ), }; - self.children - .push(GroupServe::new(self.ctx.clone(), sequence, frame_start, rank, group)); + self.children.push(GroupServe::new( + self.ctx.clone(), + sequence, + frame_start, + capped, + rank, + group, + )); } } @@ -4049,6 +4119,8 @@ struct GroupServe { group: group::Consumer, sequence: u64, frame_start: u64, + /// The stream stops at a subscription's end frame, so its FIN cannot end the group. + capped: bool, // Lite05+ delta-encodes per-frame timestamps within the group. The first // frame's delta is absolute (against an implicit prev value of 0), every // subsequent delta is signed against the previous frame. @@ -4070,8 +4142,10 @@ enum GroupState { writer: Writer, frame: Option, chunk: Option, - batch: Box, + batch: Box, batch_pos: usize, + /// The `ietf` extension's object records, when negotiated. + records: Option, }, /// Every frame is written and the FIN sent: wait for the acknowledgement so a /// late cancel or expiry can still reset the stream. @@ -4086,6 +4160,7 @@ impl GroupServe { ctx: Subscription, sequence: u64, frame_start: u64, + capped: bool, rank: Rank>, group: group::Consumer, ) -> Self { @@ -4095,6 +4170,7 @@ impl GroupServe { group, sequence, frame_start, + capped, prev_ts: 0, state: GroupState::Open, budget: kio::coop::Budget::new(32), @@ -4184,21 +4260,36 @@ impl GroupServe { sequence: self.sequence, frame_start: self.frame_start, }; - if let Err(err) = writer.buffer(&lite::DataType::Group).and_then(|()| writer.buffer(&msg)) { - // The header wrote nothing, so the group-stream reset has nothing to pin - // it to this subscription. The run loop reads the slot and resets the - // subscribe stream instead. - self.ctx.note_unencodable(&err); - self.state = GroupState::Done; - writer.abort(&err); - return Poll::Ready(Err(err)); - } + let header = writer.buffer(&lite::DataType::Group).and_then(|()| writer.buffer(&msg)); + let records = header.and_then(|()| { + lite::ietf::Records::start( + &mut writer, + self.ctx.ietf, + &self.group, + self.capped, + self.ctx.timescale, + self.ctx.version, + ) + }); + let records = match records { + Ok(records) => records, + Err(err) => { + // The header wrote nothing, so the group-stream reset has nothing to pin + // it to this subscription. The run loop reads the slot and resets the + // subscribe stream instead. + self.ctx.note_unencodable(&err); + self.state = GroupState::Done; + writer.abort(&err); + return Poll::Ready(Err(err)); + } + }; self.state = GroupState::Serve { writer, frame: None, chunk: None, - batch: Box::new(frame::Buffer::new()), + batch: Box::default(), batch_pos: 0, + records, }; } GroupState::Serve { @@ -4207,6 +4298,7 @@ impl GroupServe { chunk, batch, batch_pos, + records, } => { let mut cx = waiter.context(); @@ -4258,51 +4350,80 @@ impl GroupServe { Poll::Pending => return Poll::Pending, } } else if *batch_pos < batch.len() { - let batched = &mut batch.filled_mut()[*batch_pos]; - let buffered = buffer_frame_info( - writer, - batched.timestamp, - batched.payload.len() as u64, - self.ctx.timescale, - &mut self.prev_ts, - &self.ctx.runtime, - ); + let index = self.group.index() - batch.len() as u64 + *batch_pos as u64; + let batched = &mut batch[*batch_pos]; + let buffered = records + .as_mut() + .map_or(Ok(()), |records| { + records.frame(writer, index, batched.fields.as_deref()) + }) + .and_then(|()| { + buffer_frame_info( + writer, + batched.timestamp, + batched.payload.len() as u64, + self.ctx.timescale, + &mut self.prev_ts, + &self.ctx.runtime, + ) + }); if let Err(err) = buffered { break 'serve Err(err); } - let payload = std::mem::take(&mut batched.payload); + let payload = std::mem::take(&mut batched.frame.payload); if !payload.is_empty() { *chunk = Some(payload); } *batch_pos += 1; self.group.keep_alive(); } else { - match self.group.poll_read_frames(waiter, batch) { + match self.group.poll_read_objects(waiter, batch) { Poll::Ready(Ok(count)) if count > 0 => { *batch_pos = 0; continue; } - Poll::Ready(Ok(_)) => break 'serve Ok(()), + // Taken, so the next pass finishes once the record flushed. + Poll::Ready(Ok(_)) => match records.take() { + Some(mut records) => match records.end(writer, &self.group) { + Ok(()) => continue, + Err(err) => break 'serve Err(err), + }, + None => break 'serve Ok(()), + }, Poll::Ready(Err(err)) => break 'serve Err(err), Poll::Pending => {} } match self.group.poll_next_frame(waiter) { Poll::Ready(Ok(Some(next))) => { - let buffered = buffer_frame_info( - writer, - next.timestamp, - next.size, - self.ctx.timescale, - &mut self.prev_ts, - &self.ctx.runtime, - ); + let index = self.group.index() - 1; + let buffered = records + .as_mut() + .map_or(Ok(()), |records| { + records.frame(writer, index, next.fields.as_deref()) + }) + .and_then(|()| { + buffer_frame_info( + writer, + next.timestamp, + next.size, + self.ctx.timescale, + &mut self.prev_ts, + &self.ctx.runtime, + ) + }); if let Err(err) = buffered { break 'serve Err(err); } *frame = Some(next); } - Poll::Ready(Ok(None)) => break 'serve Ok(()), + Poll::Ready(Ok(None)) => match records.take() { + Some(mut records) => match records.end(writer, &self.group) { + Ok(()) => continue, + Err(err) => break 'serve Err(err), + }, + None => break 'serve Ok(()), + }, Poll::Ready(Err(err)) => break 'serve Err(err), Poll::Pending => return Poll::Pending, } @@ -4521,6 +4642,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4566,6 +4688,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4615,6 +4738,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4664,6 +4788,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4731,6 +4856,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4807,6 +4933,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4855,6 +4982,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4902,6 +5030,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let track = track::Producer::new( @@ -4961,6 +5090,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: Default::default(), + ietf: false, }; let bounds = Bounds { start_group: Some(0), @@ -6091,6 +6221,7 @@ mod serve_group_test { timescale: Some(crate::Timescale::MILLI), runtime: crate::time::sim(), outcomes: outcomes.clone(), + ietf: false, }; let bounds = Bounds { start_group: Some(start_group), diff --git a/rs/moq-net/src/lite/session.rs b/rs/moq-net/src/lite/session.rs index 25e6e7eb1a0..3e671e20999 100644 --- a/rs/moq-net/src/lite/session.rs +++ b/rs/moq-net/src/lite/session.rs @@ -269,7 +269,7 @@ where // reads the peer's Setup stream; capability-gated streams (PROBE) wait on it. // When the caller already read it (a gated server accept), seed the slot so the // Setup stream isn't expected on the wire again. - let peer_setup_slot = PeerSetup::new(client, session.binding()); + let peer_setup_slot = PeerSetup::new(client, session.binding()).offer_ietf(our_setup.ietf); let early = if let Some(accepted) = peer_setup { peer_setup_slot.set(accepted.setup); accepted.early diff --git a/rs/moq-net/src/lite/setup.rs b/rs/moq-net/src/lite/setup.rs index df7fd821a4d..52254dd4360 100644 --- a/rs/moq-net/src/lite/setup.rs +++ b/rs/moq-net/src/lite/setup.rs @@ -15,6 +15,8 @@ const PARAM_ROLE: u64 = 0x3; const PARAM_COST: u64 = 0x4; /// Setup Parameter id for the endpoint's Hop ID. const PARAM_HOP: u64 = 0x5; +/// Setup Parameter id offering the `ietf` extension (draft-lcurley-moq-ietf): "IETF" in ASCII. +const PARAM_IETF: u64 = 0x4945_5446; /// The cost of crossing a link that neither end priced. /// @@ -182,6 +184,9 @@ pub struct Setup { /// applies). `None` when the endpoint has no meaningful identity (a /// leaf that never forwards); a wire value of 0 decodes as `None`. pub hop: Option, + /// Whether this endpoint offers the `ietf` extension (lite-07+). Negotiated only when + /// both endpoints offer it. + pub ietf: bool, } impl Message for Setup { @@ -215,6 +220,13 @@ impl Message for Setup { if let Some(hop) = self.hop { params.set_varint(PARAM_HOP, hop.id(), version)?; } + if self.ietf { + // The framing it changes is unpublished, so a published version cannot offer it. + if !version.has_ietf() { + return Err(EncodeError::Version); + } + params.set_bytes(PARAM_IETF, Vec::new()); + } params.encode(w, version) } @@ -256,6 +268,14 @@ impl Message for ReceivedSetup { let hop = params .get_varint(PARAM_HOP, version)? .and_then(|id| crate::Hop::new(id).ok()); + // An older version does not know the parameter, so it ignores it like any other. + let ietf = match params.get_bytes(PARAM_IETF) { + Some(value) if version.has_ietf() => match value.is_empty() { + true => true, + false => return Err(DecodeError::InvalidValue), + }, + _ => false, + }; Ok(Self { role_present: role_code.is_some(), @@ -265,6 +285,7 @@ impl Message for ReceivedSetup { role, cost, hop, + ietf, }, }) } @@ -285,6 +306,8 @@ pub(crate) struct PeerSetup(kio::Shared); struct PeerSetupState { client: bool, binding: crate::transport::Binding, + /// Whether our own SETUP offers the `ietf` extension. + ietf: bool, seen: bool, setup: Option, } @@ -294,6 +317,7 @@ impl PeerSetup { Self(kio::Shared::new(PeerSetupState { client, binding, + ietf: false, seen: false, setup: None, })) @@ -311,6 +335,31 @@ impl PeerSetup { Ok(()) } + /// Note whether our own SETUP offers the `ietf` extension, before any stream depends on it. + pub fn offer_ietf(self, ietf: bool) -> Self { + self.0.lock().ietf = ietf; + self + } + + /// Poll whether the `ietf` extension is negotiated: both SETUPs offer it. + /// + /// Resolves at once when we did not offer it, and otherwise once the peer's SETUP arrives. + pub fn poll_ietf(&self, waiter: &kio::Waiter) -> std::task::Poll { + if !self.0.lock().ietf { + return std::task::Poll::Ready(false); + } + self.poll_get(waiter, |setup| setup.ietf) + } + + /// Whether the `ietf` extension is negotiated, or `None` before the peer's SETUP arrives. + pub fn ietf(&self) -> Option { + let state = self.0.lock(); + match state.ietf { + false => Some(false), + true => state.setup.as_ref().map(|setup| setup.ietf), + } + } + /// Record the peer's SETUP. pub fn set(&self, setup: Setup) { let mut state = self.0.lock(); @@ -455,6 +504,33 @@ mod tests { } } + /// The `ietf` offer is an empty parameter that only a version with the extension sends, + /// and an older one ignores like any unknown parameter. + #[test] + fn ietf_offer_is_lite07_only() { + let msg = Setup { + ietf: true, + ..Default::default() + }; + let buf = msg.encode_bytes(Version::Lite07).unwrap(); + assert_eq!(Setup::decode_slice(&buf, Version::Lite07).unwrap().0, msg); + assert!(msg.encode_bytes(Version::Lite06).is_err()); + + // Length, one parameter, its 8-byte QUIC varint ID, and an empty value. + let older = [0x0a, 0x01, 0xc0, 0, 0, 0, 0x49, 0x45, 0x54, 0x46, 0x00]; + assert_eq!( + Setup::decode_slice(&older, Version::Lite06).unwrap().0, + Setup::default() + ); + + // A value it does not define is refused. + let mut valued = buf.to_vec(); + assert_eq!(valued.pop(), Some(0), "the offer ends in its empty value"); + valued.extend([1, 7]); + valued[0] += 1; + assert!(Setup::decode_slice(&valued, Version::Lite07).is_err()); + } + /// Never emit a SETUP our own receiver would refuse. #[test] fn encode_enforces_the_setup_limit() { diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 9009ddc4d75..5cd894cff5d 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -504,10 +504,15 @@ impl Subscriber { // is a handful of atomic bumps on every datagram, and a producer held past its // removal would keep the track (its cached groups, its stats subscription) alive. // The group path already writes to a producer under this lock. + // Its framing is unknown until the peer's SETUP says whether the `ietf` extension is + // negotiated, and a best-effort datagram is not worth waiting for. + let Some(ietf) = self.peer_setup.ietf() else { + return Ok(()); + }; let mut subscribes = self.subscribes.lock(); // An unknown subscription's datagram is dropped below, however it parses. - let dg = lite::Datagram::decode(payload, self.version, |id| { - subscribes.get(&id).is_some_and(|entry| entry.timescale.is_some()) + let dg = lite::Datagram::decode(payload, self.version, ietf, |id| { + subscribes.get(&id).and_then(|entry| entry.timescale) })?; let Some(entry) = subscribes.get_mut(&dg.subscribe) else { // Unknown or already-closed subscription: drop the datagram. @@ -528,7 +533,15 @@ impl Subscriber { // A datagram says where the live feed is as well as a group does. Inserted first, so // the copy goes live with it already showing. let live = entry.producer.is_live(); - entry.producer.insert_datagram(dg.sequence, timestamp, dg.payload)?; + let wire = dg.ietf.flatten().map(Arc::new); + entry.producer.insert_wire_datagram(crate::model::datagram::Stored { + datagram: crate::Datagram { + sequence: dg.sequence, + timestamp, + payload: dg.payload, + }, + wire, + })?; if !live { entry.producer.set_live(Some(Position::group(dg.sequence))); } @@ -864,6 +877,8 @@ impl GroupRecv { loop { match &mut self.state { GroupRecvState::Header => { + // Before the header, which a wait after it would lose. + let ietf = ready!(self.subscriber.peer_setup.poll_ietf(waiter)); let mut cx = waiter.context(); let hdr = ready!(self.reader.poll_decode::(&mut cx))?; @@ -924,7 +939,7 @@ impl GroupRecv { self.state = GroupRecvState::Serve { group: crate::recv::Group::new(group), track, - ingest: FrameIngest::new(&self.subscriber, timescale), + ingest: FrameIngest::new(&self.subscriber, timescale, ietf, hdr.frame_start), shown: false, _reading: reading, }; @@ -1008,9 +1023,39 @@ struct FrameIngest { prev_ts: u64, phase: IngestPhase, budget: frame::Budget, + version: Version, + /// Where the stream's frames start, the first Object ID until a record names it. + frame_start: u64, + /// `Some` once the Group State of the `ietf` extension arrived: every frame follows an + /// object record. + records: Option, +} + +/// A group's object records on ingest, under the `ietf` extension. +struct RecordIngest { + /// The Group State carried relay state. Otherwise every record is plain: its Object ID + /// is the frame's index, with no properties and no END_OF_GROUP. + relayed: bool, + /// The Group State set EXTENSIONS, without which no record has properties. + extensions: bool, + /// The previous record's Object ID, `None` before the first. + prior: Option, + /// The record of the frame being read: its Object ID and properties block. + /// + /// It is checked when the frame is created, which charges it to the cache, so a stalled + /// stream holds only the bytes it read. + pending: Option<(u64, bytes::Bytes)>, } enum IngestPhase { + /// Reading the `ietf` extension's Group State. + State, + /// Reading the next object record. Stream end here means the group has no more objects. + Object, + /// Reading the record's properties block, whose size comes first. + Properties { id: u64, end: bool, size: Option }, + /// The END_OF_GROUP record arrived, so only the stream end may follow. + Ended, /// Reading the timestamp delta (skipped without a timescale). Stream end here /// means the group has no more frames. Timing, @@ -1022,12 +1067,44 @@ enum IngestPhase { } impl FrameIngest { - fn new(subscriber: &Subscriber, timescale: Option) -> Self { + /// `ietf` when the session negotiated the extension, so the stream starts with a Group State. + fn new( + subscriber: &Subscriber, + timescale: Option, + ietf: bool, + frame_start: u64, + ) -> Self { Self { timescale, prev_ts: 0, - phase: IngestPhase::Timing, + phase: match ietf { + true => IngestPhase::State, + false => IngestPhase::Timing, + }, budget: subscriber.frames.clone(), + version: subscriber.version, + frame_start, + records: None, + } + } + + /// The phase that starts the next frame. + fn next_frame(&self) -> IngestPhase { + match self.records { + Some(_) => IngestPhase::Object, + None => IngestPhase::Timing, + } + } + + /// Read a frame header varint. Only a plain group may end in its place. + fn poll_header_varint( + &self, + reader: &mut Reader, + cx: &mut std::task::Context<'_>, + ) -> Poll, Error>> { + match self.records { + Some(_) => reader.poll_varint(cx).map_ok(Some), + None => reader.poll_varint_maybe(cx), } } @@ -1043,13 +1120,80 @@ impl FrameIngest { let mut cx = waiter.context(); loop { match &mut self.phase { + IngestPhase::State => { + let state = ready!(reader.poll_varint(&mut cx))?; + let wire = lite::ietf::decode_state(state, self.frame_start)?; + let relayed = wire.is_some(); + let extensions = wire.as_ref().is_some_and(|wire| wire.extensions); + if let Some(wire) = wire { + group.set_wire(wire)?; + } + self.records = Some(RecordIngest { + relayed, + extensions, + prior: None, + pending: None, + }); + self.phase = IngestPhase::Object; + } + IngestPhase::Object => { + let Some(code) = ready!(reader.poll_varint_maybe(&mut cx))? else { + return Poll::Ready(Ok(())); + }; + let records = self.records.as_mut().expect("the Group State came first"); + let (id, end) = lite::ietf::decode_object(records.prior, code)?; + if records.prior.is_none() + && let Some(mut wire) = group.wire() + { + wire.first_id = id; + group.set_wire(wire)?; + } + records.prior = Some(id); + self.phase = IngestPhase::Properties { id, end, size: None }; + } + IngestPhase::Properties { id, end, size } => { + let len = match size { + Some(len) => *len, + None => { + let len = ready!(reader.poll_varint(&mut cx))?; + if len > lite::ietf::MAX_PROPERTIES as u64 { + return Poll::Ready(Err(Error::BoundsExceeded(crate::coding::BoundsExceeded))); + } + *size.insert(len as usize) + } + }; + let block = ready!(reader.poll_read_exact(&mut cx, len))?; + let (id, end) = (*id, *end); + let records = self.records.as_mut().expect("the Group State came first"); + if (end && !records.relayed) || (!block.is_empty() && !records.extensions) { + return Poll::Ready(Err(Error::ProtocolViolation)); + } + if end { + let decoded = lite::ietf::decode_end(&block, self.timescale, self.version)?; + group.mark_gap(id, decoded.gap)?; + group.set_end_object(crate::model::object::Fields { + id, + properties: decoded.properties, + })?; + self.phase = IngestPhase::Ended; + } else { + records.pending = Some((id, block)); + self.phase = IngestPhase::Timing; + } + } + IngestPhase::Ended => { + if ready!(reader.poll_has_more(&mut cx))? { + return Poll::Ready(Err(Error::ProtocolViolation)); + } + return Poll::Ready(Ok(())); + } IngestPhase::Timing => { let Some(scale) = self.timescale else { self.phase = IngestPhase::Size { timestamp: None }; continue; }; // The timestamp delta doubles as the per-frame sentinel. - let Some(zz) = ready!(reader.poll_varint_maybe(&mut cx))? else { + let Some(zz) = ready!(self.poll_header_varint(reader, &mut cx))? else { return Poll::Ready(Ok(())); }; let next: u64 = (self.prev_ts as i128 + crate::coding::varint::unzigzag(zz) as i128) @@ -1063,17 +1207,33 @@ impl FrameIngest { }; } IngestPhase::Size { timestamp } => { - let Some(size) = ready!(reader.poll_varint_maybe(&mut cx))? else { + let timestamp = *timestamp; + let Some(size) = ready!(self.poll_header_varint(reader, &mut cx))? else { return Poll::Ready(Ok(())); }; + // A frame that says nothing a plain frame would not keeps no fields. + let fields = match &mut self.records { + Some(records) => { + let (id, block) = records.pending.take().expect("a record precedes each frame"); + let lite::ietf::Decoded { properties, gap } = + lite::ietf::decode_properties(&block, self.timescale, true, self.version)?; + group.mark_gap(id, gap)?; + let plain = id == group.frame_count() as u64 && properties.is_empty(); + if !plain && !records.relayed { + return Poll::Ready(Err(Error::ProtocolViolation)); + } + (!plain).then(|| Arc::new(crate::model::object::Fields { id, properties })) + } + None => None, + }; // `create_frame_owned` is the allocation chokepoint: it rejects an // oversized `size` and allocates up front only within the budget, so // no pre-check is needed. No wire timestamp (pre-lite-05) means an // untimed frame. let frame = group.create_frame_owned( - frame::Info { - size, - timestamp: *timestamp, + frame::Header { + info: frame::Info { size, timestamp }, + fields, }, &self.budget, )?; @@ -1082,7 +1242,8 @@ impl FrameIngest { IngestPhase::Payload { frame } => { let failed = ready!(reader.poll_read_frame(&mut cx, frame)).err(); - let IngestPhase::Payload { frame } = std::mem::replace(&mut self.phase, IngestPhase::Timing) else { + let next = self.next_frame(); + let IngestPhase::Payload { frame } = std::mem::replace(&mut self.phase, next) else { unreachable!() }; match failed { @@ -2273,6 +2434,175 @@ mod tests { } } + /// Receive group 0 of a track in `timescale` over a lite-07 session that negotiated the + /// `ietf` extension, its stream holding `body` after the GROUP header. Also returns the + /// cache pool the track charges. + async fn receive_ietf( + timescale: Option, + body: &[u64], + ) -> (Result<(), Error>, track::Producer, crate::cache::Pool) { + use crate::transport::poll::Session as _; + + let version = Version::Lite07; + let mut script = Vec::new(); + let mut encoder = crate::coding::Encoder::new(&mut script, version.into()); + lite::Group { + subscribe: 7, + sequence: 0, + frame_start: 0, + } + .encode(&mut encoder, version) + .unwrap(); + for value in body { + encoder.varint(*value).unwrap(); + } + let mut session = crate::lite::test_transport::ScriptedSession::eof(script); + let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Binding::InBand).offer_ietf(true); + peer_setup.set(lite::Setup { + ietf: true, + ..Default::default() + }); + let subscriber = Subscriber::new(SubscriberConfig { + runtime: crate::time::sim(), + session: session.clone(), + origin: origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + recv_bandwidth: None, + version, + peer_setup, + peer_hop: None, + cost: None, + going_away: Default::default(), + auth: crate::auth::Handle::new(false), + }); + let pool = crate::cache::Pool::unbounded(); + let track = track::Producer::new( + std::sync::Arc::new(crate::broadcast::Info { + pool: pool.clone(), + ..Default::default() + }), + "video", + crate::track::Info::default().with_timescale(timescale), + ); + subscriber.subscribes.lock().insert( + 7, + TrackEntry { + producer: track.clone(), + timescale, + tail: Default::default(), + }, + ); + + let (_, recv) = session.open_bi(Default::default()).await.unwrap(); + let mut group = GroupRecv::new(subscriber, Reader::new(recv, version)); + let res = kio::wait(|waiter| group.poll_serve(waiter)).await; + (res, track, pool) + } + + /// Object records: `(Skip << 1) | END`, the properties block's length, then the frame. + #[moq_clock::test] + async fn ietf_records_frame_a_group() { + // A plain group: Group State 0, then frame 0 with an empty record. + let (res, track, _) = receive_ietf(None, &[0, 0, 0, 1, u64::from(b'x')]).await; + res.unwrap(); + let mut group = track.consume().peek_group(0).unwrap(); + assert_eq!( + group.read_frame().now_or_never().unwrap().unwrap().unwrap().payload, + b"x"[..] + ); + + // A relayed group starting at Object 4, then END_OF_GROUP at Object 6. + let (res, track, _) = receive_ietf(None, &[0x1, 4 << 1, 0, 1, u64::from(b'x'), (1 << 1) | 1, 0]).await; + res.unwrap(); + let group = track.consume().peek_group(0).unwrap(); + assert_eq!(group.end_object().map(|end| end.id), Some(6)); + assert_eq!(group.wire().map(|wire| wire.first_id), Some(4)); + } + + /// A record the Group State does not allow, or bytes past END_OF_GROUP, are refused. + #[moq_clock::test] + async fn ietf_records_refuse_what_their_group_cannot_hold() { + for (body, reason) in [ + (&[0x20][..], "an unknown Group State bit"), + (&[0x2][..], "relay state without RELAYED"), + (&[0, 1 << 1, 0, 1, 0], "a plain group skipping an Object ID"), + (&[0, 1, 0], "a plain group with END_OF_GROUP"), + (&[0, 0, 2, 0x10, 0], "a plain group with properties"), + (&[0x1, 1, 0, 0], "a byte after END_OF_GROUP"), + (&[0x1, 0, 0], "a stream ending inside a frame"), + ] { + let (res, ..) = receive_ietf(None, body).await; + assert!(res.is_err(), "accepted {reason}"); + } + } + + /// A relayed group's records carry properties only when its Group State sets EXTENSIONS, + /// as the moq-transport subgroup it mirrors could hold none otherwise. + #[moq_clock::test] + async fn ietf_records_need_extensions_for_properties() { + // Object 0 with a draft-18 block holding 0x20 = 1, or an untimed Timestamp. + for record in [&[3, 4, 0x20, 1][..], &[3, 4, 0x10, 7]] { + for (state, ok) in [(0x1 | 0x4, true), (0x1, false)] { + let mut body = vec![state, 0]; + body.extend(record); + body.push(0); + let (res, ..) = receive_ietf(None, &body).await; + assert_eq!(res.is_ok(), ok, "Group State {state:#x}, record {record:?}"); + } + } + } + + /// On a timed track, the frame holds an object's time, so a record cannot carry a second, + /// mutable Timestamp that could disagree with it. Records that say nothing of time, or + /// seal a Timestamp moq-transport egress cannot rewrite, cross beside the frame's. + #[moq_clock::test] + async fn ietf_records_leave_time_to_their_frame() { + let frame = crate::coding::varint::zigzag(500); + // Each record after its Object code: Object 0 unless it says otherwise. + for (record, ok, reason) in [ + (&[0, 0][..], true, "nothing at all"), + (&[0, 4, 4, 0x10, 500], false, "a mutable Timestamp"), + (&[0, 3, 4, 0x20, 1], true, "properties without a Timestamp"), + (&[0, 6, 4, 0x0b, 3, 0x10, 499], true, "a sealed Timestamp"), + (&[1 << 1, 0], true, "Object 1 without properties"), + ] { + let mut body = vec![0x1 | 0x4]; + body.extend(record); + body.extend([frame, 0]); + let (res, track, _) = receive_ietf(Some(Timescale::MILLI), &body).await; + assert_eq!(res.is_ok(), ok, "{reason}: {res:?}"); + if ok { + let mut group = track.consume().peek_group(0).unwrap(); + let frame = group.read_frame().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(frame.timestamp, Some(Timestamp::from_millis(500).unwrap()), "{reason}"); + } + } + } + + /// A record's properties stay the bytes they arrived as, which the cache charges, rather + /// than a decoded list costing many times as much. + #[moq_clock::test] + async fn ietf_records_hold_properties_at_their_wire_size() { + const COUNT: u64 = 1000; + // A relayed group's Object 0, whose draft-18 block holds COUNT two-byte properties + // (0x20 = 1, then zero deltas), then an empty frame. + let mut body = vec![0x1 | 0x4, 0, 1 + 2 * COUNT, 4, 0x20, 1]; + for _ in 1..COUNT { + body.extend([0, 1]); + } + body.push(0); + let (res, track, pool) = receive_ietf(None, &body).await; + res.unwrap(); + let group = track.consume().peek_group(0).unwrap(); + assert_eq!(group.frame_count(), 1); + let decoded = COUNT * size_of::() as u64; + assert!( + (2 * COUNT..decoded / 2).contains(&pool.used()), + "{} cached for a {}-byte block", + pool.used(), + 2 * COUNT + ); + } + /// Receive group 5 starting at 500ms over `version`, on a received timed track whose /// group 4 starts at 1000ms, returning the stream's result and the track. async fn receive_rewind(version: Version) -> (Result<(), Error>, track::Producer) { @@ -2678,6 +3008,7 @@ mod tests { sequence, timestamp: Some(sequence), payload: bytes::Bytes::from_static(b"x"), + ietf: None, } .encode_bytes(VERSION) .unwrap() @@ -5755,8 +6086,17 @@ struct TrackInfoFetch { enum TrackInfoState { Open, - Send { stream: Stream }, - Read { stream: Stream }, + Send { + stream: Stream, + }, + Read { + stream: Stream, + }, + /// Reading the TRACK_PROPERTIES the `ietf` extension sends after TRACK_INFO. + Properties { + stream: Stream, + info: track::Info, + }, } impl TrackInfoFetch { @@ -5808,6 +6148,7 @@ impl TrackInfoFetch { if let Poll::Ready(err) = self.closed.poll_closed(&mut cx) { return Poll::Ready(Err(crate::lite::error::from_transport(err))); } + let ietf = ready!(serve.subscriber.peer_setup.poll_ietf(waiter)); let info = ready!(stream.reader.poll_decode::(&mut cx))?; let TrackInfoState::Read { stream } = std::mem::replace(&mut self.state, TrackInfoState::Open) else { @@ -5823,7 +6164,27 @@ impl TrackInfoFetch { .with_max_age(info.max_age) .with_priority(info.priority) .with_refresh(info.refresh); - return Poll::Ready(Ok((model, HeldTrack(stream)))); + if !ietf { + return Poll::Ready(Ok((model, HeldTrack(stream)))); + } + self.state = TrackInfoState::Properties { stream, info: model }; + } + TrackInfoState::Properties { stream, info } => { + if let Poll::Ready(err) = self.closed.poll_closed(&mut cx) { + return Poll::Ready(Err(crate::lite::error::from_transport(err))); + } + let properties = ready!(stream.reader.poll_decode::(&mut cx))?; + // Refused as moq-transport ingress refuses it. + if let Some(err) = properties.0.as_ref().and_then(|properties| properties.refused(info)) { + return Poll::Ready(Err(err)); + } + let TrackInfoState::Properties { stream, mut info } = + std::mem::replace(&mut self.state, TrackInfoState::Open) + else { + unreachable!() + }; + info.properties = properties.0; + return Poll::Ready(Ok((info, HeldTrack(stream)))); } } } @@ -6616,6 +6977,7 @@ impl kio::Task for FetchServeRun { }; } FetchRunState::Answer { stream, .. } => { + let ietf = ready!(self.serve.subscriber.peer_setup.poll_ietf(waiter)); // Lite has no FETCH_OK: a publisher without the group resets the // stream instead. Accepting before the first byte (or a FIN, for an // empty group) would resolve every joined `fetch_group` to a group @@ -6667,7 +7029,12 @@ impl kio::Task for FetchServeRun { stream, producer: crate::recv::Group::new(producer), joined, - ingest: Box::new(FrameIngest::new(&self.serve.subscriber, self.timescale)), + ingest: Box::new(FrameIngest::new( + &self.serve.subscriber, + self.timescale, + ietf, + frame_start, + )), }; } FetchRunState::Ingest { diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index 37ae7bb9637..51eed85f5f0 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -273,6 +273,18 @@ impl Version { } } + /// Whether a session may negotiate the `ietf` extension (draft-lcurley-moq-ietf), which + /// carries moq-transport object state between relays. Added on lite-07; published + /// versions get no framing changes. + #[allow(clippy::match_like_matches_macro)] + pub(crate) fn has_ietf(self) -> bool { + // Match form so future versions default forward (AGENTS.md convention). + match self { + Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 => false, + _ => true, + } + } + /// Whether the announce stream has ANNOUNCE_RESTART: another publisher instance /// replacing an advertisement in place. Added in lite-07. Older versions send an /// ANNOUNCE_END then an ANNOUNCE_START. diff --git a/rs/moq-net/src/model/object.rs b/rs/moq-net/src/model/object.rs index fa7a9dae0ea..1d5dcd8f3a6 100644 --- a/rs/moq-net/src/model/object.rs +++ b/rs/moq-net/src/model/object.rs @@ -1,15 +1,23 @@ //! Private relay metadata; public readers see only the frame or datagram payload. use bytes::Bytes; -use crate::Timescale; +use crate::Timestamp; -/// How the publisher serialized the keys inside immutable properties. +/// The moq-transport drafts a list of properties came from, which share its key and +/// integer encoding and what each property means. #[derive(Clone, Copy, Debug, PartialEq, Eq)] // private: passthrough pub(crate) enum Encoding { - Absolute, - DeltaQuic, - Delta { seven: bool }, + /// Drafts 14 and 15: absolute keys and QUIC varints. + Draft14, + /// Draft 16: delta keys and QUIC varints. + Draft16, + /// Draft 17: delta keys and leading-ones varints without the seven-byte form. + Draft17, + /// Draft 18: delta keys and leading-ones varints. + Draft18, + /// Draft 19 and later: as draft 18, with property 0x06 as SUBGROUP_DELIVERY_TIMEOUT. + Draft19, } #[derive(Clone, Debug, PartialEq, Eq)] @@ -26,43 +34,43 @@ pub(crate) struct Property { pub value: Value, } -/// The common timestamp needs no vector allocation; all other properties stay opaque. +/// An object's relay properties, held as one encoded [`Block`]. +/// +/// On a timed track, the mutable Timestamp is never held: it is the frame's, which egress +/// restates. On an untimed one it has no units, so it stays in the block like any other. #[derive(Clone, Debug, Default, PartialEq, Eq)] // private: passthrough pub(crate) struct Properties { - pub timestamp: Option, - pub values: Vec, - pub immutable: Option, - /// The units of the Timestamps above, when the track declared any. The cache keeps the - /// track in its own units, so egress converts mutable ones to the units it declares. - pub timescale: Option, - /// The immutable block holds a Timestamp, which keeps its ingress units. - pub sealed_time: bool, - /// Property 0x06 means SUBGROUP_DELIVERY_TIMEOUT on the ingress draft. - pub delivery_timeout: bool, + /// The Timestamp the block's Immutable Properties hold on a timed track, which keeps + /// its ingress units. + pub sealed_time: Option, + /// The properties, if there are any. + pub block: Option, } -impl Properties { - #[cfg(feature = "async")] - pub fn is_plain(&self) -> bool { - self.values.is_empty() - } +/// An object's properties, but for a timed track's mutable Timestamp, as one encoded list. +/// +/// Kept encoded because a decoded list costs many times its wire size, and a relay holds +/// one per cached object. Egress decodes it only to re-encode for another draft. +#[derive(Clone, Debug, PartialEq, Eq)] +// private: passthrough +pub(crate) struct Block { + /// The properties in ascending ID order, serialized as `encoding` does. Never empty. + pub bytes: Bytes, + /// How `bytes` is serialized: its key and integer encoding. + pub encoding: Encoding, + /// `bytes` holds Immutable Properties (0x0b), serialized as `encoding` does. + pub immutable: bool, +} +impl Properties { #[cfg(feature = "async")] pub fn is_empty(&self) -> bool { - self.timestamp.is_none() && self.values.is_empty() + self.block.is_none() } pub fn heap(&self) -> u64 { - (self.values.capacity() * size_of::()) as u64 - + self - .values - .iter() - .map(|property| match &property.value { - Value::Bytes(bytes) => bytes.len() as u64, - Value::Int(_) => 0, - }) - .sum::() + self.block.as_ref().map_or(0, |block| block.bytes.len() as u64) } } @@ -70,25 +78,12 @@ impl Properties { #[derive(Clone, Debug, Default, PartialEq, Eq)] // private: passthrough pub(crate) struct TrackProperties { - /// In arrival order, with Immutable Properties (0x0b) as its serialized bytes. + /// In arrival order, which is ascending, with Immutable Properties (0x0b) as its + /// serialized bytes. pub values: Vec, - /// How the publisher serialized the keys inside Immutable Properties, when present. - pub immutable: Option, - /// The keys inside Immutable Properties, which egress must not restate as mutable. - pub sealed: Vec, - /// Property 0x06 means SUBGROUP_DELIVERY_TIMEOUT on the ingress draft. - pub delivery_timeout: bool, -} - -impl TrackProperties { - /// Whether one is a Mandatory Track Property (0x4000-0x7FFF), which by definition is - /// one moq-net does not understand: the track must be neither processed nor forwarded. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - pub fn mandatory(&self) -> bool { - const MANDATORY: std::ops::RangeInclusive = 0x4000..=0x7fff; - self.values.iter().any(|property| MANDATORY.contains(&property.id)) - || self.sealed.iter().any(|id| MANDATORY.contains(id)) - } + /// How the publisher serialized the list and the keys inside Immutable Properties. + /// Set beside any values, and never [`Encoding::Draft14`], which predates the list. + pub encoding: Option, } /// Object numbering is separate from the public frame's ordinal in its group. diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index b11c377a365..f8ed4444ec4 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -7734,12 +7734,13 @@ mod test { sequence: d.sequence, timestamp: Some(d.timestamp.unwrap().value()), payload: d.payload.clone(), + ietf: None, } .encode_bytes(version) .unwrap(); // Subscriber decodes the body and writes it downstream, preserving the sequence. - let wire = lite::Datagram::decode(body, version, |_| true).unwrap(); + let wire = lite::Datagram::decode(body, version, false, |_| Some(crate::Timescale::MICRO)).unwrap(); let mut downstream = track_producer("test", Info::timed()); let mut downstream_dg = downstream.subscribe(None); downstream diff --git a/rs/moq-net/src/server.rs b/rs/moq-net/src/server.rs index d338b256de5..27f5c9fc705 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -121,7 +121,8 @@ impl Server { self } - /// Choose which moq-transport extensions to offer in SETUP. Defaults to all of them. + /// Choose which extensions to offer in SETUP. Defaults to every moq-transport one, and + /// not [`ietf`](setup::Extensions::ietf), which only relays turn on. pub fn with_extensions(mut self, extensions: setup::Extensions) -> Self { self.extensions = extensions; self @@ -167,6 +168,7 @@ impl Server { cost: None, // Filled by `lite::start` from the attached origin handles. hop: None, + ietf: self.extensions.ietf && version.has_ietf(), } } else { lite::Setup::default() @@ -1184,6 +1186,7 @@ mod tests { role, cost: None, hop, + ietf: false, } .encode(&mut crate::coding::Encoder::new(&mut buf, v.into()), v) .unwrap(); diff --git a/rs/moq-net/src/setup.rs b/rs/moq-net/src/setup.rs index cb33a75f0b5..1e8eb5dcfd9 100644 --- a/rs/moq-net/src/setup.rs +++ b/rs/moq-net/src/setup.rs @@ -25,10 +25,10 @@ const SERVER_SETUP: u8 = 0x21; #[cfg_attr(not(feature = "async"), allow(dead_code))] pub(crate) const SETUP_V17: u64 = 0x2F00; -/// The moq-transport Setup Options this side offers, each on by default. +/// The SETUP extensions this side offers. /// /// Turning one off connects as a peer that does not speak that extension. moq-lite carries -/// them in its core, so this only changes moq-transport sessions. +/// auth, solicit, and epoch in its core, so those only change moq-transport sessions. #[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)] #[serde(default, deny_unknown_fields)] #[non_exhaustive] @@ -41,6 +41,9 @@ pub struct Extensions { /// The MoQ Epoch extension: announcements and requests carry the publisher's /// [`Epoch`](crate::Epoch), as moq-lite 07 does (draft-17+). pub epoch: bool, + /// The MoQ IETF extension, off by default: a moq-lite 07 hop between relays carries the + /// moq-transport object state a relay preserves, such as Object IDs and properties. + pub ietf: bool, } impl Default for Extensions { @@ -49,6 +52,7 @@ impl Default for Extensions { auth: true, solicit: true, epoch: true, + ietf: false, } } } diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index fdc8c2116f9..a72b0dd1480 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -143,6 +143,7 @@ fn lite_varint_interop() { sequence: 300, timestamp: Some((1 << 50) + 5), payload: bytes::Bytes::from_static(b"x"), + ietf: None, } .encode_bytes(version) .unwrap(); @@ -156,6 +157,7 @@ fn lite_varint_interop() { sequence: 1 << 30, timestamp: None, payload: bytes::Bytes::from_static(b"untimed"), + ietf: None, } .encode_bytes(version); let untimed_datagram = match untimed { diff --git a/rs/moq-relay/src/relay.rs b/rs/moq-relay/src/relay.rs index d65e405fb3c..34e2674b852 100644 --- a/rs/moq-relay/src/relay.rs +++ b/rs/moq-relay/src/relay.rs @@ -123,6 +123,10 @@ impl Relay { async fn load_inner(mut config: Config) -> anyhow::Result { config.resolve()?; + // A relay keeps the moq-transport object state it forwards across a moq-lite hop to + // another relay. Only negotiated when both sides offer it, so other peers never see it. + config.listen.extensions.ietf = true; + config.connect.extensions.ietf = true; // Every TLS listener serves the ACME certificate, so install it before any is built. let acme = config.acme.init(&config.listen.tls, &config.web.https)?; if let Some(acme) = &acme { diff --git a/rs/moq-tokio/src/connect.rs b/rs/moq-tokio/src/connect.rs index d88d369d461..e1767221ab8 100644 --- a/rs/moq-tokio/src/connect.rs +++ b/rs/moq-tokio/src/connect.rs @@ -479,7 +479,7 @@ failover_delay = "1s" } } -/// Whether `extensions` offers every extension, the default a config leaves out. +/// Whether `extensions` is the default a config leaves out. pub(crate) fn all_extensions(extensions: &moq_net::setup::Extensions) -> bool { *extensions == moq_net::setup::Extensions::default() } @@ -641,7 +641,7 @@ pub struct Config { )] pub version: Vec, - /// The moq-transport extensions to offer in SETUP, all by default. + /// The extensions to offer in SETUP, every moq-transport one by default. #[serde(default, skip_serializing_if = "crate::connect::all_extensions")] #[usage(skip)] pub extensions: moq_net::setup::Extensions, diff --git a/rs/moq-tokio/src/listen.rs b/rs/moq-tokio/src/listen.rs index 417bb0f2372..d30a1f5b010 100644 --- a/rs/moq-tokio/src/listen.rs +++ b/rs/moq-tokio/src/listen.rs @@ -146,7 +146,7 @@ pub struct Config { )] pub version: Vec, - /// The moq-transport extensions to offer in SETUP, all by default. + /// The extensions to offer in SETUP, every moq-transport one by default. #[serde(default, skip_serializing_if = "crate::connect::all_extensions")] #[usage(skip)] pub extensions: moq_net::setup::Extensions,