diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 17551662fe6..8699269a2bb 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -25,8 +25,9 @@ maps everything else to "not supported" or a harmless equivalent. The [moq-lite page](/concept/moq-lite#what-moq-lite-leaves-out) lists what the subset drops. What a peer actually observes against this implementation: -- **Pull.** Subscribers ask. Single-track `PUBLISH` offers are declined; announce a namespace and serve the resulting subscriptions. Announcements go out unsolicited, and we also ask for every prefix we may discover. The solicit `SETUP` option makes us wait to be asked. Without it, a draft 16+ peer also gets each match as a `NAMESPACE` on its `SUBSCRIBE_NAMESPACE` stream, so it hears the namespace twice. We send `PUBLISH` only to answer a `SUBSCRIBE_TRACKS` (below): on drafts 16 and 17 a `SUBSCRIBE_NAMESPACE` asking only for `PUBLISH` is refused, one asking for both gets only `NAMESPACE`, and any other Subscribe Options value closes the session. -- **`SUBSCRIBE_TRACKS` lists, it never pushes.** On draft 18 and later, it lists every track of every broadcast under its prefix, later ones included. With `FORWARD=0`, each track gets a paused `PUBLISH` carrying its Track Properties, and an error `PUBLISH_DONE` once the track is no longer listed, never `TRACK_ENDED`, since the track may go on elsewhere. A `REQUEST_UPDATE` with `FORWARD=1` resumes one, served from the cache like a `SUBSCRIBE` with the update's filter and answered with `LARGEST_OBJECT`; `FORWARD=0` pauses it again. Each paused `PUBLISH` holds a subscription slot, and past the cap a track gets `PUBLISH_SKIPPED` (`PUBLISH_BLOCKED` on draft 18) instead. A listing that omits `FORWARD` or sets it to 1 asks for every track's objects: from draft 19 each track gets `PUBLISH_SKIPPED`, and the subscriber `SUBSCRIBE`s to what it wants; draft 18 has no such skip, so the request is refused with `NOT_SUPPORTED`. A prefix overlapping another listing gets `PREFIX_OVERLAP`, a `TRACK_PROPERTY_FILTER` gets `NOT_SUPPORTED`, and a `REQUEST_UPDATE` on the listing itself ends it. On draft 18, a `SUBSCRIBE` to a track we `PUBLISH`ed gets `DUPLICATE_SUBSCRIPTION`. Cancelling the listing stops new `PUBLISH`es, while those sent live on. A broadcast is listed only while our publish grant covers it, from scratch once it does. Neither implementation sends `SUBSCRIBE_TRACKS` upstream. +- **Pull.** Subscribers ask. Single-track `PUBLISH` offers are declined, unless they answer our `SUBSCRIBE_TRACKS` (below); announce a namespace and serve the resulting subscriptions. Announcements go out unsolicited, and we also ask for every prefix we may discover. The solicit `SETUP` option makes us wait to be asked. Without it, a draft 16+ peer also gets each match as a `NAMESPACE` on its `SUBSCRIBE_NAMESPACE` stream, so it hears the namespace twice. We send `PUBLISH` only to answer a `SUBSCRIBE_TRACKS` (below): on drafts 16 and 17 a `SUBSCRIBE_NAMESPACE` asking only for `PUBLISH` is refused, one asking for both gets only `NAMESPACE`, and any other Subscribe Options value closes the session. +- **`SUBSCRIBE_TRACKS` lists, it never pushes.** On draft 18 and later, it lists every track of every broadcast under its prefix, later ones included. With `FORWARD=0`, each track gets a paused `PUBLISH` carrying its Track Properties, and an error `PUBLISH_DONE` once the track is no longer listed, never `TRACK_ENDED`, since the track may go on elsewhere. A `REQUEST_UPDATE` with `FORWARD=1` resumes one, served from the cache like a `SUBSCRIBE` with the update's filter and answered with `LARGEST_OBJECT`; `FORWARD=0` pauses it again. Each paused `PUBLISH` holds a subscription slot, and past the cap a track gets `PUBLISH_SKIPPED` (`PUBLISH_BLOCKED` on draft 18) instead. A listing that omits `FORWARD` or sets it to 1 asks for every track's objects: from draft 19 each track gets `PUBLISH_SKIPPED`, and the subscriber `SUBSCRIBE`s to what it wants; draft 18 has no such skip, so the request is refused with `NOT_SUPPORTED`. A prefix overlapping another listing gets `PREFIX_OVERLAP`, a `TRACK_PROPERTY_FILTER` gets `NOT_SUPPORTED`, and a `REQUEST_UPDATE` on the listing itself ends it. On draft 18, a `SUBSCRIBE` to a track we `PUBLISH`ed gets `DUPLICATE_SUBSCRIPTION`. Cancelling the listing stops new `PUBLISH`es, while those sent live on. A broadcast is listed only while our publish grant covers it, from scratch once it does. Rust sends it upstream for a listing (below); JavaScript does not. +- **A Rust TRACKS listing sends `SUBSCRIBE_TRACKS` upstream, only on demand.** Listing a broadcast from a moq-transport peer on draft 18 and later sends `SUBSCRIBE_TRACKS` with `FORWARD=0` while someone lists it, never on connect, announce, or subscribe, so a peer that refuses, resets, or ignores it affects only that listing. Before draft 18 the listing is refused as unsupported. Each listed track's paused `PUBLISH` is its upstream copy, which a reader resumes rather than subscribing again. Only a `PUBLISH_DONE` with `TRACK_ENDED` removes a listed track; any other end, including the error our own answerer sends for an unlisted track, fails the listing, and readers list again. - **History is one group.** In Rust, Object ID gaps must be marked by Prior Object ID Gap properties for a group to be fetchable. A `FETCH` returns one group from the cache, or on drafts 14 through 19 the saved prefix of the group a new subscription just joined. A range of groups is refused, as is a draft 20+ `LOCATION_FILTER` that ends at Largest Object rather than an absolute End Location. On draft 20 and later, `FETCH_OK`'s End Location is the requested end, capped at Largest Object: a range holding no objects gets an empty fetch stream, and only a start past Largest Object is refused, with `INVALID_RANGE`. A relay's copy with no upstream subscription can't know Largest Object short of the track's end, so it echoes the requested end instead. JavaScript publishing refuses every `FETCH`. Datagrams are never fetchable. A Rust reader that only fetches learns the track from `TRACK_STATUS` instead of subscribing, so a finished track stays fetchable; draft 17 still subscribes, since its `TRACK_STATUS` answer cannot say whether the track is timed, and so does a reader whose publisher refuses `TRACK_STATUS` as `NOT_SUPPORTED`. - **Compression.** Rust peers on draft 17 and later exchange compressed tracks when both offer the [Flate extension](/draft/moq-flate). Older peers receive one shared inflated copy. A publisher that seals the compression declaration makes that fallback unavailable: an incompatible peer is refused, preserving the sealed metadata. JavaScript does not offer the IETF extension. - **Timing.** A track whose `SUBSCRIBE_OK` declares no `TIMESCALE` is untimed, as is every track on drafts 14 through 16. A Rust reader that never subscribed takes the units from `TRACK_STATUS` on draft 18 and later. @@ -105,8 +106,8 @@ choices. They follow the product model. termination code, so we close the session with it. - **Deduplicated subscriptions and discovery.** Shared subscriptions and overlapping - namespace prefixes are coalesced internally, so `DUPLICATE_SUBSCRIPTION` and - `PREFIX_OVERLAP` are never sent. + namespace prefixes are coalesced internally. Only `SUBSCRIBE_TRACKS`, described + above, sends `PREFIX_OVERLAP`, and on draft 18 `DUPLICATE_SUBSCRIPTION`. - **Subscriber max age is negotiated.** The [Timestamp extension](/draft/moq-timestamp) carries a subscriber's `max_delay` in `SUBSCRIBE` and `REQUEST_UPDATE` only diff --git a/quest/m1/README.md b/quest/m1/README.md index aa019494bf8..0422b3d46ab 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -92,6 +92,8 @@ tracks, so per-group stats stop costing cluster announces. - [A widened max age re-offers cached groups](/quest/m1/resolved-demand.md) - a warm relay serves a reader with a wider max age the cached groups a cold relay would, with no wire change - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 - [Broadcast archives](/quest/m1/archive/README.md) - ANNOUNCE, TRACKS, and a SUBSCRIBE per track record every track under a prefix to any object_store, a host serves a stored broadcast back, and the catalog drops its archive pointer for an opt-in `hls` field +- [Pause an IETF SUBSCRIBE](/quest/m1/ietf-subscribe-pause.md) - Forward=0 pauses a SUBSCRIBE without demand upstream and Forward=1 resumes it, instead of ending it +- [A listing says whether a removed track finished](/quest/m1/listing-end-reason.md) - a listing removal carries whether the track finished, at every hop, so the IETF answerer ends a finished track's PUBLISH with TRACK_ENDED and a Rust-to-Rust IETF listing removes it without a reset - [Compressed tracks](/quest/m1/compress/README.md) - a track flagged `compress` is DEFLATEd per group by moq-net, forwarded compressed, and inflated once on the relay for peers that cannot signal it; `catalog.json.z` and moq-flate go away - [lite-06 max sequence](/quest/m1/lite06-max-sequence.md) - group sequence 2^62-1 reaches a lite-06 subscriber or is refused loudly, instead of vanishing - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it @@ -100,7 +102,6 @@ tracks, so per-group stats stop costing cluster announces. - [A public model](/quest/m1/public-model/README.md) - every model item a built-in session reaches is public, unnecessary, or marked deliberately private, so a custom publisher, subscriber, or relay builds from the public model alone - [A smaller, safer API than release](/quest/m1/api-audit/README.md) - every surface added since release has a consumer or is gone, overlapping operations are collapsed, names mirror across Rust, JS, and the bindings, and every break has its MIGRATE entry - [FETCH_OK whole group](/quest/m1/ietf-fetch-end-location.md) - on drafts 14 to 19, FETCH_OK End Object 0 means the whole group in both directions, and a FETCH ending at the maximum group is refused as unsupported -- [Pause an IETF SUBSCRIBE](/quest/m1/ietf-subscribe-pause.md) - Forward=0 pauses a SUBSCRIBE without demand upstream and Forward=1 resumes it, instead of ending it - [JavaScript FETCH](/quest/m1/js-fetch.md) - browser publishers answer IETF FETCH through the JS ranges request surface - [IETF fill timeout](/quest/m1/ietf-fill-timeout.md) - native FILL_TIMEOUT bounds upstream waiting on drafts 18-22, alongside local content-age enforcement - [Rust identity enforcement](/quest/m1/catalog-identity-rs.md) - `moq-mux` refuses a redefined rendition, and every Rust publisher mints a new rendition name for a decoder identity change and updates everything else in place diff --git a/quest/m1/archive/README.md b/quest/m1/archive/README.md index 4107786e706..1be0c7cb79a 100644 --- a/quest/m1/archive/README.md +++ b/quest/m1/archive/README.md @@ -31,9 +31,8 @@ archive (per-track `.timeline.z` records named by the catalog's root track, gating the lite-07 cut (`broadcast::Consumer::tracks` in Rust, `broadcast.Consumer.tracks()` in JS). moq-transport answers SUBSCRIBE_TRACKS through the same hook in Rust and - JavaScript, and learns an - IETF peer's tracks with a FORWARD=0 SUBSCRIBE_TRACKS - ([outbound SUBSCRIBE_TRACKS](/quest/m1/archive/subscribe-tracks-outbound.md)). Rejected: + JavaScript and, in Rust, learns an IETF peer's tracks with a FORWARD=0 + SUBSCRIBE_TRACKS whose held PUBLISHes resume for data. Rejected: SUBSCRIBE_ALL, whose relay had to merge pushed feeds into pulled copies ([moq-dev/moq#5931](https://github.com/moq-dev/moq/pull/5931)). The archive no longer selects tracks from a catalog. @@ -87,7 +86,6 @@ from a host. Each child fixes the stale docs it touches. - [Archive consumer](/quest/m1/archive/consumer.md) - `archive::Consumer` serves a stored prefix as a broadcast from its key listing, and `moq export/import archive` use the new pair - [Catalog HLS field](/quest/m1/archive/catalog-hls.md) - the root `archive` section is gone; an opt-in per-rendition `hls` field marks each aligned HLS segment's first group and pts and declares its nominal duration -- [Outbound SUBSCRIBE_TRACKS](/quest/m1/archive/subscribe-tracks-outbound.md) - an IETF peer's tracks are listed through the TRACKS hook by a FORWARD=0 SUBSCRIBE_TRACKS, whose held PUBLISH resumes for data - [Fixed HLS target duration](/quest/m1/archive/hls-target.md) - one `EXT-X-TARGETDURATION` for the run, from the declared `hls` duration; an overrun is listed with a warning - [History from the retained floor](/quest/m1/archive/history-floor.md) - HLS history over an archive consumer broadcast whose start was pruned lists from its oldest stored segment diff --git a/quest/m1/archive/subscribe-tracks-outbound.md b/quest/m1/archive/subscribe-tracks-outbound.md deleted file mode 100644 index a44489c106c..00000000000 --- a/quest/m1/archive/subscribe-tracks-outbound.md +++ /dev/null @@ -1,103 +0,0 @@ -# [L] Outbound SUBSCRIBE_TRACKS - -## Goal - -A lite TRACKS whose broadcast is served by a moq-transport peer (draft-18 on) -learns that peer's tracks by sending SUBSCRIBE_TRACKS with FORWARD=0 and -reading the PUBLISH each track produces, without its objects. A listed -track's data comes by resuming that same subscription when a reader wants it. -Today the Rust subscriber never sends SUBSCRIBE_TRACKS, so a lite listing over -a moq-transport upstream lists nothing. - -An unsolicited inbound PUBLISH stays refused: moq-net never merges a pushed -track into a pulled copy. A FORWARD=0 PUBLISH answering our own -SUBSCRIBE_TRACKS carries data only once we resume it with the filter our own -SUBSCRIBE would send, so it is a pull, not that merge. - -## Plan - -Split from the inbound half, which answers a peer's SUBSCRIBE_TRACKS through -`broadcast::Consumer::tracks` (`rs/moq-net/src/ietf/publisher/tracks.rs`). -The maintainer's 2026-10-19 decisions, recorded with TRACKS: "we don't need an -extension; we could issue forward=0 to learn about all tracks from IETF peers". - -TRACKS' events map as follows: - -| TRACKS event | We send SUBSCRIBE_TRACKS with FORWARD=0 | -|---|---| -| Track added, with TRACK_INFO | a PUBLISH, TRACK_INFO from its Track Properties; or a PUBLISH_SKIPPED (PUBLISH_BLOCKED on draft-18), TRACK_INFO from the SUBSCRIBE_OK of a paused SUBSCRIBE we open for it | -| Synced | not needed: the lite side sends SYNCED for this hop at once, and PUBLISHes arrive as live adds | -| Track removed | PUBLISH_DONE with TRACK_ENDED on the held paused PUBLISH or SUBSCRIBE; any other status fails the listing | - -- **One subscription per track: the held PUBLISH carries the data.** - PUBLISH_DONE is the only removal signal, so an outbound PUBLISH is accepted - paused (PUBLISH_OK, FORWARD=0) and held as the listing entry. It is also - the track's upstream copy: when a reader wants the data, REQUEST_UPDATE it - to FORWARD=1 with the filter our SUBSCRIBE would have sent - (SUBSCRIPTION_FILTER through draft-19, LOCATION_FILTER and FILL_PARAMETERS - from draft-20, whose section 3.6.2 names this join), and back to FORWARD=0 - when the last reader leaves, rather than unsubscribing. On draft-18 and - draft-19 a filter does not deliver objects already published, so a start - below the Largest Object also sends a Joining FETCH on the held - subscription's request ID, as the existing pre-draft-20 SUBSCRIBE path - does. Draft-18 section 5.1 allows one subscription per track per role and - fails a second with DUPLICATE_SUBSCRIPTION; draft-19 on allow several. - The upstream copy is one subscription carrying the union of reader ranges - either way, and the existing SUBSCRIBE path adopts a held PUBLISH as the - track's copy instead of opening one. Conversely, a PUBLISH for a track we - already SUBSCRIBEd (established or pending) is redundant: the existing - SUBSCRIBE becomes the entry, and the PUBLISH is refused with - DUPLICATE_SUBSCRIPTION on draft-18 and UNINTERESTED from draft-19. Only - TRACK_ENDED is a removal. Any other status fails the listing loudly: the - lite TRACKS stream resets and the lister requests again, never turning it - into a removal that would hide a live track for good. -- **A skipped track is still listed.** A PUBLISH_SKIPPED (PUBLISH_BLOCKED on - draft-18) names a track that exists, so open a paused SUBSCRIBE (FORWARD=0) - for it and hold that as the entry and the copy. Its SUBSCRIBE_OK supplies - the TRACK_INFO, so the add goes downstream once it arrives, and its - PUBLISH_DONE with TRACK_ENDED is the removal. A refused paused SUBSCRIBE, - or one ending with another status, fails the listing loudly. -- **One SUBSCRIBE_TRACKS per nesting chain, never widened in place.** Two - prefixes overlap only when one is a prefix of the other, which the peer - refuses with PREFIX_OVERLAP. Siblings get separate requests. A nested - listing under a broader request reuses it and filters locally. A broader - listing cancels the nested requests, keeping the PUBLISH subscriptions they - made, and opens only once the peer has closed every cancelled stream: close - our sending half (FIN on draft-18, RESET_STREAM from draft-19), keep - reading until the peer closes its half, and delay STOP_SENDING. If the - broader request is refused, every listing it was meant to serve resets - loudly and re-requests. Rejected: widening in place with REQUEST_UPDATE, - and one request per session at the common ancestor. -- **Push inventory only.** An IETF relay lists the tracks it has been - PUBLISHed or already holds. A track served only on request is unlisted, - which matches TRACKS' rule. -- **Properties.** A property TRACK_INFO needs but PUBLISH lacks takes the - same default it takes from SUBSCRIBE_OK today. -- **Draft-22 parameters.** Draft-22 section 9.18 drops SUBSCRIBER_PRIORITY, - LOCATION_FILTER, and NEW_GROUP_REQUEST from SUBSCRIBE_TRACKS, while section - 3.6.2 still allows any subscription parameter. Send only the section 9.18 - set on draft-22 (`ietf::SubscribeTracks` encodes all of them today), and put - the join filter on the resuming REQUEST_UPDATE. The inbound decoder accepts - both readings. -- **A non-conforming peer** may send objects despite FORWARD=0; stop reading - them rather than buffer. - -Untrusted input: a hostile publisher can PUBLISH without bound. Each held -paused PUBLISH counts against the session's `announces` cap, as a lite listed -track does; past it, refuse the PUBLISH (EXCESSIVE_LOAD). The stream and -request-ID credit we grant bounds what is in flight. - -Test on mock time over drafts 18 and later: a lite TRACKS over a -moq-transport upstream lists its tracks with FORWARD=0; a lite SUBSCRIBE -resumes the held PUBLISH with its join filter and gets a new track's first -group with no second upstream SUBSCRIBE; a past start on draft-18 and -draft-19 gets cached groups through a Joining FETCH; the last reader leaving -pauses it and keeps the entry; TRACK_ENDED removes the entry and another -status resets the listing; a skipped track lists once its paused SUBSCRIBE -answers; TRACKS(`/a/b`) after TRACKS(`/a`) sends nothing; TRACKS(`/a`) after -TRACKS(`/a/b`) and TRACKS(`/a/c`) cancels both and opens only after the peer -closes them; a PUBLISH for a track we already SUBSCRIBEd is refused; an -unsolicited PUBLISH is refused. - -Public API: none beyond the TRACKS hook. Wire: moq-transport support for an -existing message. diff --git a/quest/m1/ietf-subscribe-pause.md b/quest/m1/ietf-subscribe-pause.md index 319846d446a..04fa6bd39a8 100644 --- a/quest/m1/ietf-subscribe-pause.md +++ b/quest/m1/ietf-subscribe-pause.md @@ -31,7 +31,7 @@ paused wait watches only listing removal, session close, and the auth gate, so a SUBSCRIBE paused there would never see its track end. Keep a watcher for the track's end while paused, so a track that ends sends PUBLISH_DONE with TRACK_ENDED, which the paused-SUBSCRIBE removal in -[outbound SUBSCRIBE_TRACKS](/quest/m1/archive/subscribe-tracks-outbound.md) +outbound SUBSCRIBE_TRACKS ([moq-dev/moq#6280](https://github.com/moq-dev/moq/pull/6280)) relies on. Carry the SUBSCRIBE's grant across the pause too: `apply_subscription_update` returns `Served::Paused` before it starts `verify_renewal`, and the paused loop refuses AUTHORIZATION TOKEN. A @@ -58,4 +58,4 @@ served instead of refused. ## Related -- [Outbound SUBSCRIBE_TRACKS](/quest/m1/archive/subscribe-tracks-outbound.md) - the subscriber side that sends Forward=0 and toggles it +- [Broadcast archives](/quest/m1/archive/README.md) - lists an IETF peer's tracks through SUBSCRIBE_TRACKS, which sends Forward=0 and toggles it diff --git a/quest/m1/listing-end-reason.md b/quest/m1/listing-end-reason.md new file mode 100644 index 00000000000..8825201dc58 --- /dev/null +++ b/quest/m1/listing-end-reason.md @@ -0,0 +1,41 @@ +# [M] A listing says whether a removed track finished + +## Goal + +A track listing's removal says whether the track finished or left unfinished +(its producer dropped or aborted, or its broadcast's route withdrawn), at every +hop. The Rust moq-transport answerer then ends a finished track's +SUBSCRIBE_TRACKS PUBLISH with TRACK_ENDED, so a Rust-to-Rust IETF listing +([moq-dev/moq#6280](https://github.com/moq-dev/moq/pull/6280)) removes a +finished track quietly. An unfinished one keeps ending in error, which fails +the listing loudly as today. + +Today the answerer cannot tell: `TracksEvent::Removed` carries only the name, +and the instance that left is gone from the front the answerer reads through, +so it ends every unlisted PUBLISH in error and each removal resets the listing. +Decided by the maintainer on 2026-10-22: outbound removes only on TRACK_ENDED, +and the answerer sends TRACK_ENDED only for a track that really finished. + +## Plan + +Decided 2026-10-22 (maintainer), public API and wire: + +- Rust and JS gain a `TracksEvent::Finished { name }` variant beside + `Removed { name }`, which now means unfinished, and `Lister::finish(name)` + beside `remove`. Rejected: a `finished: bool` flag, and an `End` enum on + `Removed`. +- lite-07 gains a TRACKS_FINISH event type on the Tracks Stream, with the same + body as TRACKS_REMOVE, so a relay chain keeps the distinction. TRACKS_REMOVE + keeps its meaning. Rejected: a reason field on TRACKS_REMOVE. Update + `drafts/draft-lcurley-moq-lite.md` and js/net in the same change. +- It lands before the lite-07 freeze: [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) + Requires it. +- A relay's copy reports what its upstream reported, never what its cache + happens to know. +- Test Rust-to-Rust over drafts 18-22: a finished track is removed, an + aborted one fails the listing. + +## Related + +- [Broadcast archives](/quest/m1/archive/README.md) - lists an IETF peer's tracks through SUBSCRIBE_TRACKS +- [Pause an IETF SUBSCRIBE](/quest/m1/ietf-subscribe-pause.md) - the other gap in a clean Rust-to-Rust IETF listing diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 3ec28c55922..fe62f21d807 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -99,6 +99,7 @@ Timestamp provenance landed in - [Drop set](/quest/m1/drop-set.md) - lite-07's SUBSCRIBE_DROP carries `Max Age`, so a widening re-offers groups reported dropped - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - SUBSCRIBE carries ranges and an order and lite FETCH is gone, in Rust and JS - [Announcement takeover](/quest/m1/announce-takeover.md) - ANNOUNCE_TAKEOVER preserves a proven instance under a new independent route +- [Listing end reason](/quest/m1/listing-end-reason.md) - lite-07's TRACKS_FINISH says a listed track finished, so an IETF answerer can end it with TRACK_ENDED - [lite-06 max sequence](/quest/m1/lite06-max-sequence.md) - the refusal boundary for an uncarriable sequence is settled before lite-07 freezes ## Related diff --git a/rs/moq-net/src/ietf/adapter.rs b/rs/moq-net/src/ietf/adapter.rs index 20f4ec4403b..d1ede2624a0 100644 --- a/rs/moq-net/src/ietf/adapter.rs +++ b/rs/moq-net/src/ietf/adapter.rs @@ -1573,6 +1573,7 @@ mod tests { forward: Some(false), filter: Some(ietf::Filter::NextObject), authorization_token: None, + fill: None, }; let body = encode_body(&update, version); let raw = encode_raw(ietf::SubscribeUpdate::ID, &body, version); @@ -2240,6 +2241,7 @@ mod tests { forward: Some(true), filter: Some(ietf::Filter::NextObject), authorization_token: None, + fill: None, }; let update = encode_raw(ietf::SubscribeUpdate::ID, &encode_body(&update, VERSION), VERSION); // The target is in the window and the update's own ID is past it. diff --git a/rs/moq-net/src/ietf/error.rs b/rs/moq-net/src/ietf/error.rs index 23e5abb67df..de60a3a2142 100644 --- a/rs/moq-net/src/ietf/error.rs +++ b/rs/moq-net/src/ietf/error.rs @@ -194,6 +194,9 @@ pub(crate) mod request { /// A second subscription to a track the peer already subscribes to. Draft-16 and later. pub(crate) const DUPLICATE_SUBSCRIPTION: u64 = 0x19; + /// The endpoint is overloaded and cannot process the request. Draft-18 and later. + pub(crate) const EXCESSIVE_LOAD: u64 = 0x9; + /// A SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS prefix overlapping an established one. /// Draft-15 and later. pub(crate) const PREFIX_OVERLAP: u64 = 0x30; diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 0bca2db91b2..61a96af3a0d 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -7327,6 +7327,7 @@ mod serve_tests { forward: Some(forward), filter: None, authorization_token: None, + fill: None, } .encode_msg(&mut Encoder::new(&mut body, version.into()), version) .unwrap(); @@ -7445,6 +7446,7 @@ mod serve_tests { forward: None, filter: None, authorization_token: None, + fill: None, } .encode_msg(&mut Encoder::new(&mut body, version.into()), version) .unwrap(); @@ -7641,6 +7643,7 @@ mod serve_tests { forward: Some(true), filter: None, authorization_token: None, + fill: None, } .encode_msg(&mut Encoder::new(&mut body, version.into()), version) .unwrap(); @@ -11659,6 +11662,7 @@ mod serve_tests { forward: Some(true), filter: None, authorization_token: Some(request_token()), + fill: None, }; writer.varint(ietf::SubscribeUpdate::ID).await.unwrap(); writer.encode(&msg).await.unwrap(); @@ -11973,6 +11977,7 @@ mod serve_tests { forward: Some(true), filter: None, authorization_token: Some(request_token()), + fill: None, }; writer.varint(ietf::SubscribeUpdate::ID).await.unwrap(); writer.encode(&msg).await.unwrap(); @@ -12000,6 +12005,7 @@ mod serve_tests { forward: Some(true), filter: None, authorization_token: None, + fill: None, }; writer.varint(ietf::SubscribeUpdate::ID).await.unwrap(); writer.encode(&msg).await.unwrap(); diff --git a/rs/moq-net/src/ietf/publisher/tracks.rs b/rs/moq-net/src/ietf/publisher/tracks.rs index 01f220e8aa7..e3a6a4144c3 100644 --- a/rs/moq-net/src/ietf/publisher/tracks.rs +++ b/rs/moq-net/src/ietf/publisher/tracks.rs @@ -1377,6 +1377,7 @@ mod tests { authorization_token: None, new_group: None, max_age: None, + fill: None, } } @@ -1863,7 +1864,8 @@ mod tests { } async fn resume_asks_for_a_new_group(on_listing: bool) { - let version = Version::Draft22; + // Draft-22 sends no NEW_GROUP_REQUEST on SUBSCRIBE_TRACKS. + let version = Version::Draft21; let mut h = harness(version); let live = h .broadcast @@ -2048,11 +2050,12 @@ mod tests { } } - /// A paused listing's FILL_PARAMETERS (draft-20+) open no fill, even once a PUBLISH - /// resumes without its own (draft-22 section 3.4.1). + /// A paused listing's FILL_PARAMETERS (draft-20 and draft-21; draft-22 sends none on + /// SUBSCRIBE_TRACKS) open no fill, even once a PUBLISH resumes without its own + /// (draft-22 section 3.4.1). #[moq_clock::test] async fn a_listing_fill_opens_nothing() { - for version in [Version::Draft20, Version::Draft22] { + for version in [Version::Draft20, Version::Draft21] { let mut h = harness(version); let video = h.tracks.remove("video").unwrap(); let mut group = video.append_group().unwrap(); @@ -2151,9 +2154,10 @@ mod tests { /// From draft-20 each PUBLISH states the listing's subscription parameters, which the /// subscriber otherwise takes as the defaults; earlier drafts carry them on PUBLISH_OK. + /// Draft-22 sends none of them on SUBSCRIBE_TRACKS. #[moq_clock::test] async fn a_listing_states_its_parameters_on_each_publish() { - for version in DRAFTS { + for version in DRAFTS.into_iter().filter(|version| *version != Version::Draft22) { let mut h = harness(version); let request = ietf::SubscribeTracks { subscriber_priority: Some(7), diff --git a/rs/moq-net/src/ietf/subscribe.rs b/rs/moq-net/src/ietf/subscribe.rs index 5fca49b1b10..d21ced962c9 100644 --- a/rs/moq-net/src/ietf/subscribe.rs +++ b/rs/moq-net/src/ietf/subscribe.rs @@ -434,6 +434,9 @@ pub struct SubscribeUpdate { pub new_group: Option, /// Subscriber max age in milliseconds (MoQ Timestamp), if negotiated. pub max_age: Option, + /// FILL_PARAMETERS (0x23, draft-20+): the backfill a paused PUBLISH subscription takes as + /// it resumes (draft-20 section 3.6.2). + pub fill: Option, } impl Message for SubscribeUpdate { @@ -484,6 +487,7 @@ impl Message for SubscribeUpdate { 0x10 => self.forward, 0x20 => self.subscriber_priority, 0x21 => self.filter, + 0x23 => self.fill.filter(|_| Filter::is_draft20(version)), 0x32 => self.new_group, super::max_age::PARAMETER => self.max_age, ); @@ -519,6 +523,7 @@ impl Message for SubscribeUpdate { authorization_token, new_group: None, max_age: super::max_age::validate(max_age)?, + fill: None, }) } Version::Draft15 | Version::Draft16 => { @@ -545,6 +550,7 @@ impl Message for SubscribeUpdate { authorization_token: super::token::single(authorization_token)?, new_group, max_age: super::max_age::validate(max_age)?, + fill: None, }) } _ => { @@ -553,7 +559,7 @@ impl Message for SubscribeUpdate { if matches!(version, Version::Draft17) { let _required_request_id_delta = r.varint()?; } - // Nothing reads an update's FILL_PARAMETERS or Range Filters yet; they are + // Nothing reads an update's Range Filters yet; they are // consumed so a legal update does not fail the session. decode_params!(r, version, 0x02 => _object_delivery_timeout: Option, @@ -562,7 +568,7 @@ impl Message for SubscribeUpdate { 0x10 => forward: Option, 0x20 => subscriber_priority: Option, 0x21 => filter: Option, - 0x23 => _fill: Option where Filter::is_draft20(version), + 0x23 => fill: Option where Filter::is_draft20(version), 0x25 => _subgroup_filter: Vec where has_range_filters(version), 0x26 => _object_id_filter: Vec where has_range_filters(version), 0x27 => _priority_filter: Vec where has_range_filters(version), @@ -583,6 +589,7 @@ impl Message for SubscribeUpdate { authorization_token: super::token::single(authorization_token)?, new_group, max_age: super::max_age::validate(max_age)?, + fill, }) } } @@ -650,6 +657,7 @@ mod tests { filter: None, authorization_token: None, new_group: None, + fill: None, }; let decoded: SubscribeUpdate = decode_message(&encode_message(&update, version), version).unwrap(); assert_eq!(decoded.max_age, max_age, "{version}"); @@ -766,6 +774,7 @@ mod tests { forward: None, filter: None, authorization_token: None, + fill: None, }; let decoded: SubscribeUpdate = decode_message(&encode_message(&update, version), version).unwrap(); assert_eq!(decoded.new_group, expected, "{version}: REQUEST_UPDATE"); @@ -1144,6 +1153,7 @@ mod tests { forward: Some(true), filter: Some(Filter::NextObject), authorization_token: None, + fill: None, }; let encoded = encode_message(&msg, Version::Draft15); @@ -1168,6 +1178,7 @@ mod tests { forward: Some(true), filter: Some(Filter::NextObject), authorization_token: None, + fill: None, }; let encoded = encode_message(&msg, Version::Draft14); @@ -1281,6 +1292,7 @@ mod tests { forward: Some(true), filter: Some(Filter::NextObject), authorization_token: None, + fill: None, }; let encoded = encode_message(&msg, Version::Draft17); @@ -1533,6 +1545,7 @@ mod tests { forward: Some(true), filter: Some(Filter::NextObject), authorization_token: None, + fill: None, }; let encoded = encode_message(&msg, Version::Draft18); @@ -1560,6 +1573,7 @@ mod tests { forward: Some(true), filter: Some(Filter::NextObject), authorization_token: None, + fill: None, }; let v18_msg = SubscribeUpdate { ..v17_msg.clone() }; diff --git a/rs/moq-net/src/ietf/subscribe_tracks.rs b/rs/moq-net/src/ietf/subscribe_tracks.rs index 64c7b2a26d0..5dba72a7103 100644 --- a/rs/moq-net/src/ietf/subscribe_tracks.rs +++ b/rs/moq-net/src/ietf/subscribe_tracks.rs @@ -58,16 +58,19 @@ impl Message for SubscribeTracks<'_> { encode_namespace(w, &self.prefix)?; // Absent means 1, so only a paused listing writes it. let include_properties = (!self.properties_wanted && Filter::is_draft20(version)).then_some(false); - // Draft-18 allows only AUTHORIZATION_TOKEN and FORWARD here. + // Draft-18 allows only AUTHORIZATION_TOKEN and FORWARD here. Draft-22 section 9.18 + // lists GROUP_ORDER but no longer SUBSCRIBER_PRIORITY, LOCATION_FILTER, + // FILL_PARAMETERS, or NEW_GROUP_REQUEST, which a resuming REQUEST_UPDATE carries. let defaults = version != Version::Draft18; + let subscription = defaults && version != Version::Draft22; encode_params!(w, version, 0x03 => self.authorization_token.clone(), 0x10 => (!self.forward).then_some(false), - 0x20 => self.subscriber_priority.filter(|_| defaults), - 0x21 => self.filter.filter(|_| defaults), + 0x20 => self.subscriber_priority.filter(|_| subscription), + 0x21 => self.filter.filter(|_| subscription), 0x22 => self.group_order.filter(|_| defaults), - 0x23 => self.fill.filter(|_| Filter::is_draft20(version)), - 0x32 => self.new_group.filter(|_| defaults), + 0x23 => self.fill.filter(|_| subscription && Filter::is_draft20(version)), + 0x32 => self.new_group.filter(|_| subscription), 0x35 => include_properties, ); Ok(()) @@ -269,6 +272,37 @@ mod tests { assert!(decode::(&bytes, Version::Draft18).is_err()); } + /// Draft-22 section 9.18 no longer lists SUBSCRIBER_PRIORITY, LOCATION_FILTER, + /// FILL_PARAMETERS, or NEW_GROUP_REQUEST, so none is sent there; GROUP_ORDER still is. + /// Section 3.6.2 still allows any subscription parameter, so one received is read. + #[test] + fn draft_22_sends_only_its_listed_parameters() { + let listing = SubscribeTracks { + subscriber_priority: Some(7), + filter: Some(Filter::NextObject), + fill: Some(super::super::Fill { + filter: Some(Filter::NextObject), + range_filters: false, + }), + new_group: Some(0), + ..paused() + }; + let ordered = SubscribeTracks { + group_order: Some(GroupOrder::Ascending), + ..paused() + }; + let with_order = SubscribeTracks { + group_order: Some(GroupOrder::Ascending), + ..listing.clone() + }; + let version = Version::Draft22; + assert_eq!(encode(&listing, version), encode(&paused(), version)); + assert_eq!(encode(&with_order, version), encode(&ordered, version)); + let decoded: SubscribeTracks = decode(&encode(&listing, Version::Draft21), version).unwrap(); + assert_eq!(decoded.subscriber_priority, Some(7)); + assert_eq!(decoded.new_group, Some(0)); + } + #[test] fn subscribe_tracks_starts_at_draft_18() { let mut buf = Vec::new(); diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 7207dd3a500..86c2a9a64f1 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -19,6 +19,8 @@ use crate::tail::{Reading, Settle, Tail}; use kio::Lock; +mod tracks; + const TRACK_ALIAS_TIMEOUT: Duration = Duration::from_secs(1); /// How many cancelled aliases to remember. Objects keep arriving for about a round trip @@ -60,6 +62,24 @@ enum Alias { /// promptly is what bounds the exposure, since it caps the arrival window at a round /// trip rather than leaving it open for the life of the session. Retired, + + /// A paused subscription a listing holds: the alias stays its own, but a group carrying + /// it is refused rather than buffered, since nothing reads the track. + Paused(RequestId), + + /// A paused subscription resuming, whose REQUEST_UPDATE is not answered yet. Its groups + /// can overtake the answer, so they wait on it as they would on a SUBSCRIBE_OK. + Resuming(RequestId), +} + +impl Alias { + /// The subscription holding the alias, if any. + fn holder(self) -> Option { + match self { + Self::Active(id) | Self::Paused(id) | Self::Resuming(id) => Some(id), + Self::Retired => None, + } + } } /// The aliases a remote publisher has bound on this session, plus the cancelled ones we @@ -94,7 +114,10 @@ fn insert_track_alias(aliases: &TrackAliases, alias: u64, request_id: RequestId) table.retired.retain(|&retired| retired != alias); Ok(()) } - Entry::Occupied(entry) if *entry.get() == Alias::Active(request_id) => Ok(()), + Entry::Occupied(mut entry) if entry.get().holder() == Some(request_id) => { + entry.insert(Alias::Active(request_id)); + Ok(()) + } Entry::Occupied(_) => Err(Error::Duplicate), Entry::Vacant(entry) => { entry.insert(Alias::Active(request_id)); @@ -121,6 +144,19 @@ pub(super) fn is_protocol_violation(err: &Error) -> bool { ) } +/// Move `alias` to `to` (paused, resuming, or active again), unless another subscription +/// than `request_id` holds it. +fn rebind_track_alias(aliases: &TrackAliases, alias: u64, request_id: RequestId, to: Alias) { + let Ok(mut aliases) = aliases.write() else { + return; + }; + if let Some(held) = aliases.map.get_mut(&alias) + && held.holder() == Some(request_id) + { + *held = to; + } +} + /// Retire an alias, so groups still in flight for it are dropped promptly rather than /// reported as unknown (draft-19 section 11.1). /// @@ -132,7 +168,7 @@ fn retire_track_alias(aliases: &TrackAliases, alias: u64, request_id: RequestId) }; let table = &mut *aliases; - if table.map.get(&alias) != Some(&Alias::Active(request_id)) { + if table.map.get(&alias).and_then(|held| held.holder()) != Some(request_id) { return; } @@ -758,8 +794,11 @@ pub(super) struct Subscriber { going_away: crate::goaway::GoingAway, // Our grant (MoQ Auth): a subscription it stops covering is cancelled. auth: crate::auth::Handle, - // Namespaces the peer may have announced at once (`session::Limits::announces`). + // Namespaces the peer may have announced at once (`session::Limits::announces`), and + // tracks it lists to us. pub(super) announces: crate::session::Slots, + // What SUBSCRIBE_TRACKS lists of the peer's tracks. + listings: Lock>, } /// The prefixes to issue SUBSCRIBE_NAMESPACE for: `origin`'s permitted scope, @@ -804,8 +843,10 @@ async fn resolve_track_alias( // our STOP_SENDING. Discard the group now rather than waiting out the timeout // for a binding that is never coming. Some(Alias::Retired) => Poll::Ready(Err(Error::Cancel)), - None if aliases.ended => Poll::Ready(Err(Error::Cancel)), - None => Poll::Pending, + // Nothing reads a paused subscription, so its groups are refused. + Some(Alias::Paused(_)) => Poll::Ready(Err(Error::Cancel)), + Some(Alias::Resuming(_)) | None if aliases.ended => Poll::Ready(Err(Error::Cancel)), + Some(Alias::Resuming(_)) | None => Poll::Pending, }); if let Poll::Ready(result) = resolved { return Poll::Ready(result.unwrap_or(Err(Error::Cancel))); @@ -853,6 +894,7 @@ where going_away, auth: crate::auth::Handle::new(false), announces: Default::default(), + listings: Default::default(), validity: Default::default(), epoch: None, } @@ -1056,11 +1098,19 @@ where Ok(()) } + /// Move the alias the subscription with `request_id` is bound to into `to`. + fn rebind_alias(&self, request_id: RequestId, to: Alias) { + let state = self.state.lock(); + if let Some(alias) = state.subscribes.get(&request_id).and_then(|track| track.alias) { + rebind_track_alias(&state.aliases, alias, request_id, to); + } + } + /// Whether the subscription already holding `alias` is for the same full track name as /// `request_id`, making the repeat legal sharing rather than a collision. fn alias_names_same_track(&self, state: &State, alias: u64, request_id: RequestId) -> bool { let aliases = state.aliases.read(); - let Some(Alias::Active(holder)) = aliases.map.get(&alias).copied() else { + let Some(holder) = aliases.map.get(&alias).and_then(|held| held.holder()) else { return false; }; @@ -1379,7 +1429,7 @@ where } tracing::debug!(message = ?msg, "received publish"); async move { - if let Err(err) = this.run_publish_stream(stream, msg).await { + if let Err(err) = this.serve_publish(stream, msg).await { tracing::debug!(%err, "publish stream error"); } } @@ -2566,6 +2616,13 @@ where ) -> Result<(), Error> { let mut subscribes = TaskSet::owned(); let mut closed_session = self.session.clone(); + // Answers the source's listings with the peer's tracks, while anyone lists it. + let lister = std::sync::Arc::new( + broadcast + .lister() + .expect("only the source answers its broadcast's listings"), + ); + let mut listening = None; loop { let next = subscribes .drive(|waiter| { @@ -2573,6 +2630,7 @@ where if closed_session.poll_closed(&mut cx).is_ready() { return Poll::Ready(None); } + self.poll_listing(&path, &lister, &mut listening, waiter); loop { if let Poll::Ready(next) = broadcast.poll_requested_track(waiter) { return Poll::Ready(Some(next)); @@ -2596,6 +2654,7 @@ where Some(Ok(request)) => request, Some(Err(err)) => { tracing::debug!(%err, "broadcast closed"); + drop(listening.take()); // No new tracks, but those in flight run to their own end. self.drain(&mut subscribes).await; break; @@ -2617,6 +2676,43 @@ where Ok(()) } + /// Answer the source's listings while anyone lists it, from a SUBSCRIBE_TRACKS covering + /// it; a failed listing ends its readers, which ask again. + fn poll_listing( + &self, + path: &Path<'_>, + lister: &std::sync::Arc, + listening: &mut Option>, + waiter: &kio::Waiter, + ) { + loop { + match listening { + None => { + if !matches!(lister.poll_used(waiter), Poll::Ready(Ok(()))) { + return; + } + if !super::subscribe_tracks::has_subscribe_tracks(self.version) { + // An empty answer would claim the peer lists nothing. + lister.abort(Error::Unsupported); + continue; + } + *listening = Some(self.listen(path.to_owned(), lister.clone())); + } + Some(_) if lister.poll_unused(waiter).is_ready() => { + *listening = None; + lister.clear(); + } + Some(current) => match current.poll_failed(waiter) { + Poll::Ready(err) => { + *listening = None; + lister.abort(err); + } + Poll::Pending => return, + }, + } + } + } + async fn run_subscribe( &mut self, broadcast_path: Path<'_>, @@ -2730,39 +2826,92 @@ where // pre-draft-20 join is one, since its joining FETCH carries that group alone. let live = start.is_none() || join.fetch; - let mut opening = self.session.clone(); - let mut stream = match kio::wait(|waiter| { - if gate.poll_denied(waiter).is_ready() { - return Poll::Ready(Err(Error::Unauthorized)); - } - validity.check(waiter)?; - Stream::poll_open(&mut opening, self.version, &mut waiter.context()) - }) - .await - { - Ok(stream) => stream, - Err(err) => { - target.fail(err); - return None; + // A listed track's paused subscription is already this track's upstream copy, so + // resume it rather than open a second one. + let key: tracks::TrackKey = (broadcast_path.to_owned(), track_name.into()); + let adopted = match &self.want(&key) { + None => None, + Some(handoff) => { + let adopted = kio::wait(|waiter| { + if gate.poll_denied(waiter).is_ready() { + return Poll::Ready(Err(Error::Unauthorized)); + } + validity.check(waiter)?; + Self::poll_handoff(handoff, waiter).map(Ok) + }) + .await; + match adopted { + Ok(adopted) => adopted, + Err(err) => { + self.unwant(key, handoff); + target.fail(err); + return None; + } + } } }; - // Opening spends no ID. Once allocated, drafts 14-16 must receive the request - // to return its MAX_REQUEST_ID credit; the response wait cancels it instead. - let mut timeout = crate::time::Deadline::after(&self.runtime, Control::REQUEST_ID_TIMEOUT); - let request_id = kio::wait(|waiter| { - if gate.poll_denied(waiter).is_ready() { - return Poll::Ready(Err(Error::Unauthorized)); + // The resumed subscription's alias, properties, and owed answers, when resuming one. + let mut held: Option = None; + let (request_id, mut stream, mut messages) = match adopted { + Some(upstream) => { + self.adopted(&key, upstream.request_id); + let tracks::Upstream { + stream, + messages, + request_id, + alias, + properties, + owed, + // This subscription forwards into the copy itself from here. + copy: _, + } = upstream; + held = Some(tracks::Resumed { + alias, + properties, + owed, + ended: None, + }); + (request_id, stream, messages) } - validity.check(waiter)?; - self.control.poll_credit(waiter, &mut timeout) - }) - .await; - let request_id = match request_id { - Ok(id) => id, - Err(err) => { - target.fail(err); - return None; + None => { + let mut opening = self.session.clone(); + let stream = match kio::wait(|waiter| { + if gate.poll_denied(waiter).is_ready() { + return Poll::Ready(Err(Error::Unauthorized)); + } + validity.check(waiter)?; + Stream::poll_open(&mut opening, self.version, &mut waiter.context()) + }) + .await + { + Ok(stream) => stream, + Err(err) => { + target.fail(err); + return None; + } + }; + + // Opening spends no ID. Once allocated, drafts 14-16 must receive the request + // to return its MAX_REQUEST_ID credit; the response wait cancels it instead. + let mut timeout = crate::time::Deadline::after(&self.runtime, Control::REQUEST_ID_TIMEOUT); + let request_id = kio::wait(|waiter| { + if gate.poll_denied(waiter).is_ready() { + return Poll::Ready(Err(Error::Unauthorized)); + } + validity.check(waiter)?; + self.control.poll_credit(waiter, &mut timeout) + }) + .await; + let request_id = match request_id { + Ok(id) => id, + Err(err) => { + target.fail(err); + return None; + } + }; + let messages = super::request_stream::Messages::new(self.session.clone(), self.control.client()); + (request_id, stream, messages) } }; @@ -2774,6 +2923,16 @@ where }); { let mut state = self.state.lock(); + // A resumed subscription keeps the alias it is bound to and the data streams it + // counted while it forwarded before. + let (alias, tail) = match held.is_some() { + true => state + .subscribes + .remove(&request_id) + .map(|held| (held.alias, held.tail)) + .unwrap_or_default(), + false => Default::default(), + }; state.subscribes.insert( request_id, TrackState { @@ -2784,6 +2943,8 @@ where // A resumed copy is the session's to abort from here on. producer: target.producer().cloned(), epoch: self.epoch.clone(), + alias, + tail, ..TrackState::pending(track_name.to_owned(), broadcast_path.to_owned(), fill.clone()) }, ); @@ -2808,34 +2969,54 @@ where let new_group = target .new_group() .filter(|_| super::subscribe::has_new_group_request(self.version)); - let written = async { - stream.writer.varint(ietf::Subscribe::ID).await?; - stream - .writer - .encode(&ietf::Subscribe { - max_age, - new_group, - request_id, - track_namespace: broadcast_path.to_owned(), - track_name: track_name.into(), - subscriber_priority: super::priority::to_wire(priority), - group_order: order.into(), - filter: join.filter, - fill: join.fill, - // A resumed copy already knows the track, from the answer that accepted it. - properties_wanted: matches!(target, Target::Request(_)), + let written = match &held { + // Resume the held subscription: its group order is the one it was made with, + // since no update can change it. Its groups wait on the answer from here. + Some(held) => { + self.rebind_alias(request_id, Alias::Resuming(request_id)); + let forward = tracks::Forward { forward: true, - rendezvous: false, - range_filters: false, - authorization_token: None, - epoch: self.epoch.clone(), - }) + filter: Some(join.filter), + fill: join.fill, + priority: Some(priority), + max_age, + // Only a track declaring DYNAMIC_GROUPS takes one on an update. + new_group: new_group.filter(|_| held.properties.dynamic_groups), + }; + self.write_forward(&mut stream.writer, &forward).await + } + None => { + async { + stream.writer.varint(ietf::Subscribe::ID).await?; + stream + .writer + .encode(&ietf::Subscribe { + max_age, + new_group, + request_id, + track_namespace: broadcast_path.to_owned(), + track_name: track_name.into(), + subscriber_priority: super::priority::to_wire(priority), + group_order: order.into(), + filter: join.filter, + fill: join.fill, + // A resumed copy already knows the track, from the answer that accepted it. + properties_wanted: matches!(target, Target::Request(_)), + forward: true, + rendezvous: false, + range_filters: false, + authorization_token: None, + epoch: self.epoch.clone(), + }) + .await + } .await - } - .await; + } + }; if let Err(err) = written { tracing::debug!(%err, "failed to write subscribe"); self.remove_subscribe(request_id); + self.entry_ended(&key, request_id, Err(err.clone())); target.fail(err); return None; } @@ -2871,11 +3052,10 @@ where Gone, } - let mut messages = super::request_stream::Messages::new(self.session.clone(), self.control.client()); // A local terminal ended the wait, so the peer still holds the request to cancel. let mut unanswered = false; let setup = { - let mut response = std::pin::pin!(self.read_subscribe_response(&mut stream, &mut messages)); + let mut response = std::pin::pin!(self.read_answer(&mut stream, &mut messages, held.as_mut())); loop { let setup = kio::wait(|waiter| { let response = waiter.poll_future(response.as_mut()); @@ -2953,6 +3133,23 @@ where track = %track_name, "subscribe abandoned before it was accepted" ); + // A held subscription is still the track's entry: pause it again, owing the + // answer to the resume as well. + if let Some(held) = held + && self.state.lock().subscribes.contains_key(&request_id) + { + let upstream = tracks::Upstream { + stream, + messages, + request_id, + alias: held.alias, + properties: held.properties, + owed: held.owed + 1, + copy: resumed.as_ref().map(|idle| idle.track.clone()), + }; + self.pause(key, upstream).await; + return resumed; + } // The publisher may already be serving before it answers. A session abort // already rejected the parked request; dropping what remains is not a second one. let aborted = self.remove_subscribe(request_id).is_none(); @@ -2978,6 +3175,7 @@ where pending.reject(err.clone()); } self.remove_subscribe(request_id); + self.entry_ended(&key, request_id, Err(err.clone())); if let Some(idle) = resumed { let _ = idle.track.abort(err); } @@ -2990,6 +3188,7 @@ where pending.reject(Error::UnexpectedMessage); } self.remove_subscribe(request_id); + self.entry_ended(&key, request_id, Err(Error::UnexpectedMessage)); if let Some(idle) = resumed { let _ = idle.track.abort(Error::UnexpectedMessage); } @@ -3002,10 +3201,22 @@ where pending.reject(err.clone()); } self.remove_subscribe(request_id); + // A held subscription that the publisher ended before answering ends its + // entry as the PUBLISH_DONE says; one whose resume failed fails it, and is + // cancelled since its PUBLISH_DONE has yet to come. + let ended = held.as_mut().and_then(|held| held.ended.take()); + let cancel = unanswered || (held.is_some() && ended.is_none()); + let finished = matches!(ended, Some(Ok(()))); + self.entry_ended(&key, request_id, ended.unwrap_or_else(|| Err(err.clone()))); + // A resumed copy whose track finished before the resume was answered cannot + // place the end, so it lingers again and its reader's SUBSCRIBE learns it. + if finished && resumed.is_some() { + return resumed; + } if let Some(idle) = resumed { let _ = idle.track.abort(err); } - if unanswered { + if cancel { self.cancel_subscribe(stream, request_id).await; } return None; @@ -3016,6 +3227,8 @@ where properties, largest, } = accepted; + // What a pause holds again: the properties the track was listed with. + let held_properties = properties.clone(); // A resumed copy opts out of the properties from draft-20, so it keeps the units it // learned. Before that the answer declares them again. let timescale = properties @@ -3101,7 +3314,11 @@ where } } } - if let Err(err) = self.register_alias(request_id, alias) { + self.entry_info(&key, request_id, track.info()); + // A resumed subscription stays bound to the alias it was held with. + if held.is_some() { + self.rebind_alias(request_id, Alias::Active(request_id)); + } else if let Err(err) = self.register_alias(request_id, alias) { if matches!(err, Error::Duplicate) { tracing::warn!(track_alias = %alias, "publisher reused a live track alias for another track"); self.session.close( @@ -3127,7 +3344,7 @@ where Idle, Revoked, Unjoined(Error), - Done(Result), + Done(Result, Error>), Fetch(group::Request), Update(Update), } @@ -3159,6 +3376,8 @@ where // Our grant stopped covering the track, or its join failed: it is aborted rather than // kept lingering. let mut failed = false; + // How the upstream subscription ended, which ends a listing entry it held. + let mut ended: Option> = None; let mut demand = track.demand(); // Nobody subscribing at all (only fetches asked) needs no subscription. let mut subscribed = track.subscription().is_some(); @@ -3253,6 +3472,7 @@ where let (asked, new_group, asked_age) = (update.priority, update.new_group, update.max_age); if let Err(err) = self.write_update(&mut stream.writer, request_id, update).await { tracing::debug!(%err, "failed to update the subscription"); + ended = Some(Err(err.clone())); let _ = track.clone().abort(err); break false; } @@ -3273,12 +3493,14 @@ where tracing::info!(broadcast = %self.origin.absolute(broadcast_path), track = %track_name, "subscription no longer authorized"); let _ = track.clone().abort(Error::Unauthorized); failed = true; + ended = Some(Err(Error::Unauthorized)); break true; } End::Unjoined(err) => { tracing::debug!(%err, "joining FETCH failed"); - let _ = track.clone().abort(err); + let _ = track.clone().abort(err.clone()); failed = true; + ended = Some(Err(err)); break true; } End::Fetch(request) => { @@ -3295,7 +3517,13 @@ where break true; } End::Done(res) => { - match res { + // Only TRACK_ENDED ends a listing entry quietly; a clean end of another + // kind, such as SUBSCRIPTION_ENDED, leaves the track's fate unknown. + ended = Some(match &res { + Ok(done) => tracks::listing_end(done, self.version), + Err(err) => Err(err.clone()), + }); + match res.map(|done| done.stream_count) { Ok(count) => { tracing::info!(broadcast = %self.origin.absolute(broadcast_path), track = %track_name, "subscribe complete"); // The publisher sends PUBLISH_DONE once every data stream it opened @@ -3357,6 +3585,29 @@ where // Release an unallocated join now, or let the session finish its committed header. drop(fetching); + if let Some(end) = ended { + self.entry_ended(&key, request_id, end); + } else if idle && self.is_entry(&key, request_id) && self.state.lock().subscribes.contains_key(&request_id) { + // A listed track's subscription pauses rather than ends, held again as its entry. + track.set_idle(); + let upstream = tracks::Upstream { + stream, + messages, + request_id, + alias, + properties: held_properties, + owed: unanswered.load(Ordering::Relaxed), + copy: Some(track.clone()), + }; + self.pause(key, upstream).await; + return Some(Idle { + demand: track.demand(), + track, + dynamic, + timescale, + }); + } + // Clean up let aborted = self.remove_subscribe(request_id).is_none(); @@ -3503,17 +3754,17 @@ where version: Version, unanswered: &AtomicU64, messages: &mut super::request_stream::Messages, - ) -> Result { + ) -> Result, Error> { // A refused update is followed by PUBLISH_DONE, which ends the subscription. Its // count stays, so no further update goes out meanwhile, and no answer is owed. let mut refused = false; loop { let super::request_stream::Framed(type_id, body) = messages.message(reader).await?; if type_id == ietf::PublishDone::ID { - let msg: ietf::PublishDone = body.message(version)?; + let msg: ietf::PublishDone<'static> = body.message(version)?; tracing::debug!(message = ?msg, "received publish done"); msg.end(version)?; - return Ok(msg.stream_count); + return Ok(msg); } let answer = matches!(type_id, ietf::RequestOk::ID | ietf::RequestError::ID) && !refused && unanswered.load(Ordering::Relaxed) > 0; @@ -3560,6 +3811,7 @@ where filter: None, authorization_token: None, new_group: update.new_group, + fill: None, }) .await } @@ -5759,7 +6011,7 @@ mod tests { ) .await; if clean { - assert_eq!(result.unwrap(), 0); + assert_eq!(result.unwrap().stream_count, 0); } else { assert!(matches!(result, Err(Error::ProtocolViolation))); } diff --git a/rs/moq-net/src/ietf/subscriber/tracks.rs b/rs/moq-net/src/ietf/subscriber/tracks.rs new file mode 100644 index 00000000000..22a4417acac --- /dev/null +++ b/rs/moq-net/src/ietf/subscriber/tracks.rs @@ -0,0 +1,1871 @@ +//! Lists a moq-transport peer's tracks through the TRACKS hook (draft-18+). +//! +//! A listed broadcast sends SUBSCRIBE_TRACKS with FORWARD=0, and each track it lists is +//! one paused subscription held for the session: the PUBLISH the peer answers with, +//! accepted paused, or for a track the peer skips, a SUBSCRIBE we open paused. That +//! subscription is both the listing entry, removed only by its PUBLISH_DONE with TRACK_ENDED, +//! and the track's upstream copy: a reader resumes it with REQUEST_UPDATE and pauses it +//! again once the last one leaves, rather than opening a second subscription. +//! +//! One SUBSCRIBE_TRACKS covers each nesting chain of listed broadcasts, since the peer +//! refuses an overlapping prefix: a nested listing reuses the broader request and filters +//! locally, and a broader one replaces the nested requests once the peer has closed them, +//! keeping the subscriptions they made. Any end of a held subscription other than +//! TRACK_ENDED fails every listing its request serves, which then asks again, rather +//! than hide a track that may still be live. +//! +//! Nothing goes out until a broadcast is listed: many peers do not implement +//! SUBSCRIBE_TRACKS yet, and one that refuses, resets, or ignores it fails or empties only +//! that listing, leaving the session and its SUBSCRIBEs alone. + +use std::sync::Arc; + +use super::*; +use crate::AsPath as _; +use crate::ietf::request_stream::{self, Framed, Messages}; + +/// A listed track, by its namespace and name. +pub(super) type TrackKey = (PathOwned, Arc); + +/// How a PUBLISH_DONE leaves the listing: only TRACK_ENDED removes the track. Any other +/// status, INTERNAL_ERROR included, fails the listing, so it asks again rather than hide a +/// track that may still be live. +pub(super) fn listing_end(done: &ietf::PublishDone, version: Version) -> Result<(), Error> { + match done.status_code == ietf::PublishDoneStatus::TrackEnded.code(version) { + true => Ok(()), + false => Err(done + .end(version) + .err() + .unwrap_or(Error::Remote(u32::try_from(done.status_code).unwrap_or(u32::MAX)))), + } +} + +/// A paused upstream subscription and the request stream that controls it. +pub(super) struct Upstream { + pub(super) stream: Stream, + pub(super) messages: Messages, + pub(super) request_id: RequestId, + pub(super) alias: u64, + /// The Track Properties the PUBLISH or SUBSCRIBE_OK declared. + pub(super) properties: ietf::Properties, + /// REQUEST_UPDATE answers still owed, read before anything else. + pub(super) owed: u64, + /// The copy a reader left lingering, which a failed upstream aborts. + pub(super) copy: Option, +} + +/// Hands a paused subscription from the task watching it to a subscription resuming it. +pub(super) struct Handoff { + /// A subscription asked for it. + wanted: bool, + /// Handed over by the watcher. + upstream: Option>, + /// The entry was let go, so the watcher cancels the subscription. + gone: bool, +} + +impl Default for Handoff { + fn default() -> Self { + Self { + wanted: false, + upstream: None, + gone: false, + } + } +} + +/// One listed track and the upstream subscription that holds it. +struct Entry { + /// Its TRACK_INFO, once known: a paused SUBSCRIBE learns it from its SUBSCRIBE_OK. + info: Option, + /// The subscription holding it, once known. + request_id: Option, + /// Set while it is paused, or still opening, and a watcher owns it. `None` while a + /// subscription forwarding it owns it. + handoff: Option>>, + /// Discovery state the peer makes us hold, as for a lite listed track. + _slot: crate::session::Slot, +} + +impl Drop for Entry { + fn drop(&mut self) { + if let Some(handoff) = &self.handoff { + handoff.lock().gone = true; + } + } +} + +/// A broadcast listed through this session. +struct Listener { + path: PathOwned, + lister: Arc, + /// Set to the error that fails the listing. + failed: kio::Producer>, +} + +/// One SUBSCRIBE_TRACKS, from when it is wanted until the peer has closed it. +struct Request { + prefix: PathOwned, + /// Dropped to cancel it; `None` once cancelled, while it leaves the wire. + live: Option>, + /// Closes once it is off the wire, so an overlapping one may go out. + gone: kio::Consumer<()>, +} + +/// The session's listings of the peer's tracks. +pub(super) struct Listings { + listeners: HashMap, + requests: HashMap, + entries: HashMap>, + next: u64, +} + +impl Default for Listings { + fn default() -> Self { + Self { + listeners: HashMap::new(), + requests: HashMap::new(), + entries: HashMap::new(), + next: 0, + } + } +} + +/// A SUBSCRIBE_TRACKS for its task to send. +struct Opening { + key: u64, + prefix: PathOwned, + /// The overlapping requests that must leave the wire first. + blockers: Vec>, + live: kio::Consumer<()>, + gone: kio::Producer<()>, +} + +impl Listings { + fn key(&mut self) -> u64 { + self.next += 1; + self.next + } + + /// The standing request that covers `namespace`; at most one does. + fn covering(&self, namespace: &PathOwned) -> Option { + self.requests + .iter() + .find(|(_, request)| request.live.is_some() && namespace.has_prefix(&request.prefix)) + .map(|(key, _)| *key) + } + + fn listers<'a>(&'a self, namespace: &'a PathOwned) -> impl Iterator + 'a { + self.listeners + .values() + .filter(move |listener| &listener.path == namespace) + .map(|listener| &*listener.lister) + } + + fn listen( + &mut self, + path: PathOwned, + lister: Arc, + ) -> (u64, kio::Consumer>, Option) { + // What a broader listing already holds is listed at once. + for ((namespace, name), entry) in &self.entries { + if namespace == &path + && let Some(info) = &entry.info + { + let _ = lister.add(name.clone(), info.clone()); + } + } + // This hop never waits on its upstream: later tracks follow as live adds. + lister.synced(); + let failed = kio::Producer::new(None); + let consumer = failed.consume(); + let key = self.key(); + self.listeners.insert( + key, + Listener { + path: path.clone(), + lister, + failed, + }, + ); + if self.covering(&path).is_some() { + return (key, consumer, None); + } + // Nested requests give way to this broader one, which keeps what they hold. + for request in self.requests.values_mut() { + if request.prefix.has_prefix(&path) { + request.live = None; + } + } + let blockers = self + .requests + .values() + .filter(|request| request.prefix.has_prefix(&path) || path.has_prefix(&request.prefix)) + .map(|request| request.gone.clone()) + .collect(); + let live = kio::Producer::new(()); + let gone = kio::Producer::new(()); + let request = self.key(); + self.requests.insert( + request, + Request { + prefix: path.clone(), + gone: gone.consume(), + live: Some(live.clone()), + }, + ); + let opening = Opening { + key: request, + prefix: path, + blockers, + live: live.consume(), + gone, + }; + (key, consumer, Some(opening)) + } + + fn unlisten(&mut self, key: u64) { + self.listeners.remove(&key); + self.release(); + } + + /// Cancel each standing request nobody lists under, and let go of each held track no + /// standing request covers. + fn release(&mut self) { + for request in self.requests.values_mut() { + if request.live.is_some() + && !self + .listeners + .values() + .any(|listener| listener.path.has_prefix(&request.prefix)) + { + request.live = None; + } + } + let standing: Vec = self + .requests + .values() + .filter(|request| request.live.is_some()) + .map(|request| request.prefix.clone()) + .collect(); + self.entries + .retain(|(namespace, _), _| standing.iter().any(|prefix| namespace.has_prefix(prefix))); + } + + /// Fail every listing the request covering `namespace` serves with `err`, and cancel it: + /// they ask again rather than miss a track that may still be live. + fn fail(&mut self, namespace: &PathOwned, err: Error) { + let Some(key) = self.covering(namespace) else { + return; + }; + let request = self.requests.get_mut(&key).expect("covering"); + request.live = None; + let prefix = request.prefix.clone(); + tracing::debug!(%prefix, %err, "track listing failed"); + for listener in self.listeners.values() { + if listener.path.has_prefix(&prefix) + && let Ok(mut failed) = listener.failed.write() + { + *failed = Some(err.clone()); + } + } + self.release(); + } + + fn insert(&mut self, key: TrackKey, entry: Entry) { + if let Some(info) = &entry.info { + for lister in self.listers(&key.0) { + let _ = lister.add(key.1.clone(), info.clone()); + } + } + self.entries.insert(key, entry); + } + + fn remove(&mut self, key: &TrackKey) { + let Some(entry) = self.entries.remove(key) else { + return; + }; + if entry.info.is_some() { + for lister in self.listers(&key.0) { + let _ = lister.remove(&key.1); + } + } + } + + /// The entry held by the subscription with `request_id`, if this is it. + fn held_by(&mut self, key: &TrackKey, request_id: RequestId) -> Option<&mut Entry> { + self.entries + .get_mut(key) + .filter(|entry| entry.request_id == Some(request_id)) + } + + /// The entry `handoff` belongs to, if it still stands. + fn watched_by(&mut self, key: &TrackKey, handoff: &kio::Shared>) -> Option<&mut Entry> { + self.entries + .get_mut(key) + .filter(|entry| entry.handoff.as_ref().is_some_and(|held| held.same_channel(handoff))) + } + + /// End the entry held by the subscription with `request_id`: TRACK_ENDED unlists it, + /// and anything else fails its listings. + fn ended(&mut self, key: &TrackKey, request_id: RequestId, end: Result<(), Error>) { + if self.held_by(key, request_id).is_none() { + return; + } + match end { + Ok(()) => self.remove(key), + Err(err) => { + self.remove(key); + self.fail(&key.0, err); + } + } + } +} + +/// A broadcast's listing through this session, until dropped. +pub(super) struct Listening { + listings: kio::Lock>, + key: u64, + failed: kio::Consumer>, +} + +impl Listening { + /// Ready with the error that failed the listing. + pub(super) fn poll_failed(&self, waiter: &kio::Waiter) -> Poll { + match self.failed.poll(waiter, |failed| match &**failed { + Some(err) => Poll::Ready(err.clone()), + None => Poll::Pending, + }) { + Poll::Ready(Ok(err)) => Poll::Ready(err), + Poll::Ready(Err(_)) => Poll::Ready(Error::Cancel), + Poll::Pending => Poll::Pending, + } + } +} + +impl Drop for Listening { + fn drop(&mut self) { + self.listings.lock().unlisten(self.key); + } +} + +/// What to do with a PUBLISH. +enum Offer { + /// No listing asked for it. + Unsolicited, + /// Refused with this code and reason. + Refuse(u64, &'static str), + /// Accepted paused and held as the entry `handoff` watches. + Hold(kio::Shared>), +} + +impl Subscriber +where + S: crate::transport::poll::Boxable, +{ + /// List `path`'s tracks into `lister` until the returned guard drops, through a + /// SUBSCRIBE_TRACKS covering it. + pub(super) fn listen(&self, path: PathOwned, lister: Arc) -> Listening { + let (key, failed, opening) = self.listings.lock().listen(path, lister); + if let Some(opening) = opening { + let this = self.clone(); + self.tasks.push(this.run_subscribe_tracks(opening)); + } + Listening { + listings: self.listings.clone(), + key, + failed, + } + } + + /// Send one SUBSCRIBE_TRACKS and read its answers until it is cancelled and the peer + /// has closed it, or it fails. + async fn run_subscribe_tracks(self, opening: Opening) { + let Opening { + key, + prefix, + blockers, + live, + gone, + } = opening; + let result = self.subscribe_tracks(&prefix, blockers, &live).await; + let mut listings = self.listings.lock(); + if let Err(err) = result + && listings + .requests + .get(&key) + .is_some_and(|request| request.live.is_some()) + { + listings.fail(&prefix, err); + } + listings.requests.remove(&key); + listings.release(); + drop(listings); + // Off the wire: an overlapping request may go out. + drop(gone); + } + + async fn subscribe_tracks( + &self, + prefix: &PathOwned, + blockers: Vec>, + live: &kio::Consumer<()>, + ) -> Result<(), Error> { + // The peer refuses a prefix overlapping one it still holds, so wait for each + // overlapping request to leave the wire. + let proceed = kio::wait(|waiter| { + if live.poll_closed(waiter).is_ready() { + return Poll::Ready(false); + } + for blocker in &blockers { + if blocker.poll_closed(waiter).is_pending() { + return Poll::Pending; + } + } + Poll::Ready(true) + }) + .await; + if !proceed { + return Ok(()); + } + + let mut session = self.session.clone(); + let opened = { + let mut opening = std::pin::pin!(Stream::open(&mut session, self.version)); + kio::wait(|waiter| { + if live.poll_closed(waiter).is_ready() { + return Poll::Ready(None); + } + waiter.poll_future(opening.as_mut()).map(Some) + }) + .await + }; + let Some(stream) = opened else { + return Ok(()); + }; + let mut stream = stream?; + // No draft with SUBSCRIBE_TRACKS has MAX_REQUEST_ID, so this never waits on credit. + let request_id = kio::wait(|waiter| self.control.poll_next_request_id(waiter)).await; + stream.writer.buffer_varint(ietf::SubscribeTracks::ID)?; + stream.writer.buffer(&ietf::SubscribeTracks { + request_id, + prefix: prefix.as_path(), + forward: false, + subscriber_priority: None, + group_order: None, + filter: None, + fill: None, + properties_wanted: true, + new_group: None, + range_filters: false, + track_filter: false, + authorization_token: None, + })?; + tracing::debug!(prefix = %self.origin.absolute(prefix), id = %request_id, "subscribe_tracks started"); + + let mut messages = Messages::new(self.session.clone(), self.control.client()); + let mut established = false; + enum Event { + Closed, + Cancelled, + Message(Option), + } + loop { + let event = kio::wait(|waiter| { + let mut cx = waiter.context(); + if session.poll_closed(&mut cx).is_ready() { + return Poll::Ready(Ok(Event::Closed)); + } + if live.poll_closed(waiter).is_ready() { + return Poll::Ready(Ok(Event::Cancelled)); + } + ready!(stream.writer.poll_flush(&mut cx))?; + messages + .poll_next(&mut stream.reader, &mut cx) + .map(|next| next.map(Event::Message)) + }) + .await?; + let Framed(id, body) = match event { + Event::Closed => return Ok(()), + Event::Cancelled => break, + // The peer ended the listing, which only a cancel of ours should do. + Event::Message(None) if established => return Err(Error::Closed), + Event::Message(None) => return Err(messages.failed(Error::ProtocolViolation)), + Event::Message(Some(framed)) => framed, + }; + match id { + ietf::RequestOk::ID if !established => { + body.message::(self.version) + .map_err(|err| messages.failed(err.into()))?; + established = true; + } + ietf::RequestError::ID if !established => { + let refused = body + .message::(self.version) + .map_err(|err| messages.failed(err.into()))?; + tracing::debug!(prefix = %prefix, code = refused.error_code, reason = %refused.reason_phrase, "subscribe_tracks refused"); + return Err(request::from_code( + refused.error_code, + request::Kind::SubscribeNamespace, + self.version, + )); + } + ietf::PublishSkipped::ID if established => { + let skipped = body + .message::(self.version) + .map_err(|err| messages.failed(err.into()))?; + let namespace = prefix.join(&skipped.suffix); + self.skipped(namespace, skipped.track_name.as_ref().into()); + } + _ => return Err(messages.failed(Error::UnexpectedMessage)), + } + } + + // Cancelled: close our half (FIN on draft-18, RESET_STREAM from draft-19, where a + // FIN is not a cancel), then read until the peer closes its own. The PUBLISHes it + // made stay ours. + tracing::debug!(prefix = %self.origin.absolute(prefix), "subscribe_tracks cancelled"); + let Stream { mut writer, mut reader } = stream; + match request_stream::fin_cancels(self.version) { + true => { + let _ = writer.finish(); + } + false => writer.abort(&Error::Cancel), + } + kio::wait(|waiter| { + let mut cx = waiter.context(); + if session.poll_closed(&mut cx).is_ready() { + return Poll::Ready(()); + } + loop { + match ready!(messages.poll_next(&mut reader, &mut cx)) { + Ok(Some(_)) => continue, + Ok(None) | Err(_) => return Poll::Ready(()), + } + } + }) + .await; + Ok(()) + } + + /// A fresh subscription of ours to `name` in `namespace`, and its info once accepted. + fn subscribed(&self, namespace: &PathOwned, name: &str) -> Option<(RequestId, Option)> { + let state = self.state.lock(); + let aliases = state.aliases.read(); + // A paused one is on its way out with the entry it held. + let paused = |id: &RequestId, track: &TrackState| { + track + .alias + .is_some_and(|alias| aliases.map.get(&alias) == Some(&Alias::Paused(*id))) + }; + state + .subscribes + .iter() + .find(|(id, track)| track.broadcast == *namespace && track.name == name && !paused(id, track)) + .map(|(id, track)| (*id, track.producer.as_ref().map(|producer| producer.info().clone()))) + } + + /// The peer skipped a listed track: list it through a subscription of ours, opening + /// one paused if we have none. + fn skipped(&self, namespace: PathOwned, name: Arc) { + let key = (namespace, name); + let mut listings = self.listings.lock(); + if listings.entries.contains_key(&key) || listings.covering(&key.0).is_none() { + return; + } + let slot = match self.announces.acquire() { + Ok(slot) => slot, + Err(err) => return listings.fail(&key.0, err), + }; + if let Some((request_id, info)) = self.subscribed(&key.0, &key.1) { + let entry = Entry { + info, + request_id: Some(request_id), + handoff: None, + _slot: slot, + }; + return listings.insert(key, entry); + } + let handoff = kio::Shared::>::default(); + let entry = Entry { + info: None, + request_id: None, + handoff: Some(handoff.clone()), + _slot: slot, + }; + listings.insert(key.clone(), entry); + drop(listings); + let this = self.clone(); + self.tasks.push(async move { + match this.open_paused(&key, &handoff).await { + Ok(Some(upstream)) => this.watch(key, upstream, handoff).await, + Ok(None) => {} + Err(err) => { + tracing::debug!(broadcast = %key.0, track = %key.1, %err, "paused subscribe failed"); + let mut listings = this.listings.lock(); + if listings.watched_by(&key, &handoff).is_some() { + listings.remove(&key); + listings.fail(&key.0, err); + } + } + } + }); + } + + /// Open a paused SUBSCRIBE for a skipped track and list it once its SUBSCRIBE_OK + /// arrives. `None` once its entry was let go. + async fn open_paused( + &self, + key: &TrackKey, + handoff: &kio::Shared>, + ) -> Result>, Error> { + let gone = |waiter: &kio::Waiter| { + handoff + .poll(waiter, |handoff| match handoff.gone { + true => Poll::Ready(()), + false => Poll::Pending, + }) + .is_ready() + }; + let mut session = self.session.clone(); + let opened = { + let mut opening = std::pin::pin!(Stream::open(&mut session, self.version)); + kio::wait(|waiter| { + if gone(waiter) { + return Poll::Ready(None); + } + waiter.poll_future(opening.as_mut()).map(Some) + }) + .await + }; + let Some(stream) = opened else { + return Ok(None); + }; + let mut stream = stream?; + let request_id = kio::wait(|waiter| self.control.poll_next_request_id(waiter)).await; + self.state.lock().subscribes.insert( + request_id, + TrackState { + epoch: self.epoch.clone(), + ..TrackState::pending(key.1.to_string(), key.0.clone(), kio::Producer::new(Fill::Done)) + }, + ); + let mut messages = Messages::new(self.session.clone(), self.control.client()); + let accepted = async { + stream.writer.varint(ietf::Subscribe::ID).await?; + stream + .writer + .encode(&ietf::Subscribe { + max_age: None, + new_group: None, + request_id, + track_namespace: key.0.as_path(), + track_name: key.1.as_ref().into(), + subscriber_priority: super::super::priority::ABSENT_WIRE, + // No update can change it, so it takes the order a reader gets by default. + group_order: track::Order::default().into(), + filter: Filter::NextObject, + fill: None, + properties_wanted: true, + forward: false, + rendezvous: false, + range_filters: false, + authorization_token: None, + epoch: self.epoch.clone(), + }) + .await?; + let mut response = std::pin::pin!(self.read_subscribe_response(&mut stream, &mut messages)); + let answered = kio::wait(|waiter| { + if gone(waiter) { + return Poll::Ready(None); + } + waiter.poll_future(response.as_mut()).map(Some) + }) + .await; + match answered { + Some(Ok(Some(accepted))) => Ok(Some(accepted)), + Some(Ok(None)) => Err(Error::UnexpectedMessage), + Some(Err(err)) => Err(err), + None => Ok(None), + } + } + .await; + let accepted = match accepted { + Ok(Some(accepted)) => accepted, + Ok(None) => { + self.remove_subscribe(request_id); + self.cancel_subscribe(stream, request_id).await; + return Ok(None); + } + Err(err) => { + self.remove_subscribe(request_id); + return Err(err); + } + }; + if let Some(err) = refused(&accepted.properties, self.version, self.peer_setup.get().await.flate) { + self.remove_subscribe(request_id); + self.cancel_subscribe(stream, request_id).await; + return Err(err); + } + if let Err(err) = self.bind_alias(request_id, accepted.alias) { + self.remove_subscribe(request_id); + self.cancel_subscribe(stream, request_id).await; + return Err(err); + } + let info = accepted_info(&accepted.properties, self.version); + let listed = { + let mut listings = self.listings.lock(); + match listings.watched_by(key, handoff) { + Some(entry) => { + entry.request_id = Some(request_id); + entry.info = Some(info.clone()); + for lister in listings.listers(&key.0) { + let _ = lister.add(key.1.clone(), info.clone()); + } + true + } + None => false, + } + }; + if !listed { + self.remove_subscribe(request_id); + self.cancel_subscribe(stream, request_id).await; + return Ok(None); + } + Ok(Some(Upstream { + stream, + messages, + request_id, + alias: accepted.alias, + properties: accepted.properties, + owed: 0, + copy: None, + })) + } + + /// Bind the alias a held subscription's PUBLISH or SUBSCRIBE_OK chose, paused, closing + /// the session if it names another track. + fn bind_alias(&self, request_id: RequestId, alias: u64) -> Result<(), Error> { + let err = match self.register_alias(request_id, alias) { + Ok(()) => { + self.rebind_alias(request_id, Alias::Paused(request_id)); + return Ok(()); + } + Err(err) => err, + }; + if matches!(err, Error::Duplicate) { + tracing::warn!(track_alias = %alias, "publisher reused a live track alias for another track"); + self.session.clone().close( + super::super::error::to_session_code(&SessionError::from(&err)), + err.to_string().as_ref(), + ); + } + Err(err) + } + + /// Serve a PUBLISH: hold one answering our SUBSCRIBE_TRACKS paused as its track's entry, + /// refuse a redundant one, and decline one no listing asked for. + pub(super) async fn serve_publish( + &mut self, + mut stream: Stream, + msg: ietf::Publish<'_>, + ) -> Result<(), Error> { + let key: TrackKey = (msg.track_namespace.to_owned(), msg.track_name.as_ref().into()); + let info = accepted_info(&msg.properties, self.version); + let flate = self.peer_setup.get().await.flate; + let offer = { + let mut listings = self.listings.lock(); + // Draft-18 allows one subscription per track (section 5.1); later drafts allow + // more, but the one we hold already lists the track and carries its data. + let duplicate = match self.version { + Version::Draft18 => request::DUPLICATE_SUBSCRIPTION, + _ => request::to_code(&Error::Unroutable, request::Kind::Publish, self.version), + }; + if listings.covering(&key.0).is_none() { + match listings + .requests + .values() + .any(|request| key.0.has_prefix(&request.prefix)) + { + true => Offer::Refuse( + request::to_code(&Error::Unroutable, request::Kind::Publish, self.version), + "listing cancelled", + ), + false => Offer::Unsolicited, + } + } else if listings.entries.contains_key(&key) { + Offer::Refuse(duplicate, "already subscribed") + } else if msg.forward && !matches!(self.version, Version::Draft18 | Version::Draft19) { + // From draft-20 the PUBLISH sets its own Forward State, and PUBLISH_OK has no + // FORWARD to pause it: its objects would be refused unseen behind a healthy + // listing. + listings.fail(&key.0, Error::Unsupported); + Offer::Refuse( + request::to_code(&Error::Unsupported, request::Kind::Publish, self.version), + "PUBLISH forwards for a paused listing", + ) + } else if let Some(err) = refused(&msg.properties, self.version, flate) { + // The peer sends nothing else for the track, so a listing left standing would + // silently miss it, as with a refused paused SUBSCRIBE. + let code = request::to_code(&err, request::Kind::Publish, self.version); + listings.fail(&key.0, err); + Offer::Refuse(code, "track properties not supported") + } else { + match self.announces.acquire() { + Err(err) => { + listings.fail(&key.0, err); + Offer::Refuse(request::EXCESSIVE_LOAD, "too many listed tracks") + } + Ok(slot) => match self.subscribed(&key.0, &key.1) { + // Our own SUBSCRIBE holds the track, so it is the entry. + Some((request_id, _)) => { + let entry = Entry { + info: Some(info), + request_id: Some(request_id), + handoff: None, + _slot: slot, + }; + listings.insert(key.clone(), entry); + Offer::Refuse(duplicate, "already subscribed") + } + None => { + let handoff = kio::Shared::>::default(); + let entry = Entry { + info: Some(info), + request_id: Some(msg.request_id), + handoff: Some(handoff.clone()), + _slot: slot, + }; + listings.insert(key.clone(), entry); + Offer::Hold(handoff) + } + }, + } + } + }; + let handoff = match offer { + Offer::Unsolicited => return self.run_publish_stream(stream, msg).await, + Offer::Refuse(code, reason) => { + tracing::debug!(broadcast = %key.0, track = %key.1, reason, "refusing publish"); + let error = ietf::RequestError { + request_id: None, + error_code: code, + reason_phrase: reason.into(), + retry_interval: 0, + }; + return request_stream::reject(stream, error).await; + } + Offer::Hold(handoff) => handoff, + }; + + let request_id = msg.request_id; + self.state.lock().subscribes.insert( + request_id, + TrackState { + epoch: self.epoch.clone(), + ..TrackState::pending(key.1.to_string(), key.0.clone(), kio::Producer::new(Fill::Done)) + }, + ); + let ok = async { + self.bind_alias(request_id, msg.track_alias)?; + // PUBLISH_OK is a REQUEST_OK from draft-19. FORWARD=0 holds it paused through + // draft-19; from draft-20 the PUBLISH our FORWARD=0 asked for already is. + let id = match self.version { + Version::Draft18 => ietf::PublishOk::ID, + _ => ietf::RequestOk::ID, + }; + stream.writer.varint(id).await?; + stream + .writer + .encode(&ietf::PublishOk { + request_id: None, + forward: false, + subscriber_priority: None, + group_order: None, + filter: None, + new_group: None, + }) + .await + } + .await; + if let Err(err) = ok { + tracing::debug!(broadcast = %key.0, track = %key.1, %err, "failed to hold publish"); + self.remove_subscribe(request_id); + let mut listings = self.listings.lock(); + if listings.watched_by(&key, &handoff).is_some() { + listings.remove(&key); + listings.fail(&key.0, err); + } + return Ok(()); + } + tracing::debug!(broadcast = %self.origin.absolute(&key.0), track = %key.1, id = %request_id, "holding publish"); + let upstream = Upstream { + stream, + messages: Messages::new(self.session.clone(), self.control.client()), + request_id, + alias: msg.track_alias, + properties: msg.properties, + owed: 0, + copy: None, + }; + self.watch(key, upstream, handoff).await; + Ok(()) + } + + /// Watch a paused subscription until it ends, its entry is let go, or a subscription + /// takes it to resume. + async fn watch(&self, key: TrackKey, mut upstream: Upstream, handoff: kio::Shared>) { + let mut session = self.session.clone(); + enum Step { + Closed, + Gone, + Wanted, + Message(Result, Error>), + } + let end = loop { + let step = kio::wait(|waiter| { + let mut cx = waiter.context(); + if session.poll_closed(&mut cx).is_ready() { + return Poll::Ready(Step::Closed); + } + if let Poll::Ready(handoff) = handoff.poll(waiter, |handoff| match handoff.gone || handoff.wanted { + true => Poll::Ready(()), + false => Poll::Pending, + }) { + return Poll::Ready(match handoff.gone { + true => Step::Gone, + false => Step::Wanted, + }); + } + upstream + .messages + .poll_next(&mut upstream.stream.reader, &mut cx) + .map(Step::Message) + }) + .await; + match step { + Step::Closed => return, + Step::Wanted => { + let upstream = { + let mut held = handoff.lock(); + match (held.gone, held.wanted) { + (true, _) => upstream, + // The subscription gave up before it was handed over. + (false, false) => continue, + (false, true) => { + held.upstream = Some(upstream); + return; + } + } + }; + self.remove_subscribe(upstream.request_id); + self.cancel_subscribe(upstream.stream, upstream.request_id).await; + return; + } + Step::Gone => { + self.remove_subscribe(upstream.request_id); + self.cancel_subscribe(upstream.stream, upstream.request_id).await; + return; + } + Step::Message(Ok(Some(Framed(id, body)))) => match id { + // The answer to a pause, or to a resume that paused again before it landed. + ietf::RequestOk::ID | ietf::RequestError::ID if upstream.owed > 0 => { + if let Err(err) = self.owed_answer(id, &body) { + break Err(upstream.messages.failed(err)); + } + upstream.owed -= 1; + } + ietf::PublishDone::ID => { + break body + .message::(self.version) + .map_err(|err| upstream.messages.failed(err.into())) + .and_then(|done| listing_end(&done, self.version)); + } + _ => break Err(upstream.messages.failed(Error::UnexpectedMessage)), + }, + // PUBLISH_DONE must come before the FIN (draft-19 section 3.3.2). + Step::Message(Ok(None)) => break Err(Error::ProtocolViolation), + Step::Message(Err(err)) => break Err(err), + } + }; + tracing::debug!(broadcast = %key.0, track = %key.1, ?end, "held subscription ended"); + self.remove_subscribe(upstream.request_id); + let _ = upstream.stream.writer.finish(); + // A failed upstream fails the copy, as it would while forwarding. TRACK_ENDED leaves it + // idle: the end is past groups it never saw, so a returning reader's SUBSCRIBE learns + // where, as for a copy whose subscription was cancelled. + if let (Err(err), Some(copy)) = (&end, upstream.copy.take()) { + let _ = copy.abort(err.clone()); + } + let mut listings = self.listings.lock(); + if listings.watched_by(&key, &handoff).is_some() { + match end { + Ok(()) => listings.remove(&key), + Err(err) => { + listings.remove(&key); + listings.fail(&key.0, err); + } + } + } + } + + /// Ask for the paused subscription a listing holds for this track, to resume it. + pub(super) fn want(&self, key: &TrackKey) -> Option>> { + let listings = self.listings.lock(); + let handoff = listings.entries.get(key)?.handoff.clone()?; + handoff.lock().wanted = true; + Some(handoff) + } + + /// Ready with the subscription `handoff` hands over, or `None` once it ended instead. + pub(super) fn poll_handoff(handoff: &kio::Shared>, waiter: &kio::Waiter) -> Poll>> { + let mut handoff = ready!( + handoff.poll(waiter, |handoff| match handoff.gone || handoff.upstream.is_some() { + true => Poll::Ready(()), + false => Poll::Pending, + }) + ); + Poll::Ready(handoff.upstream.take()) + } + + /// Give up wanting `handoff`, holding again what it already handed over. + pub(super) fn unwant(&self, key: TrackKey, handoff: &kio::Shared>) { + let upstream = { + let mut held = handoff.lock(); + held.wanted = false; + held.upstream.take() + }; + if let Some(upstream) = upstream { + self.hold(key, upstream); + } + } + + /// The subscription with `request_id` took over the entry it resumes. + pub(super) fn adopted(&self, key: &TrackKey, request_id: RequestId) { + if let Some(entry) = self.listings.lock().held_by(key, request_id) { + entry.handoff = None; + } + } + + /// Whether the subscription with `request_id` holds this track's listing entry, so + /// it pauses rather than ends once nobody reads it. + pub(super) fn is_entry(&self, key: &TrackKey, request_id: RequestId) -> bool { + self.listings + .lock() + .held_by(key, request_id) + .is_some_and(|entry| entry.handoff.is_none()) + } + + /// The subscription with `request_id` learned the info of the track it holds, which + /// lists it if a skip made it the entry before its SUBSCRIBE_OK. + pub(super) fn entry_info(&self, key: &TrackKey, request_id: RequestId, info: &track::Info) { + let mut listings = self.listings.lock(); + let Some(entry) = listings.held_by(key, request_id) else { + return; + }; + if entry.info.is_some() { + return; + } + entry.info = Some(info.clone()); + for lister in listings.listers(&key.0) { + let _ = lister.add(key.1.clone(), info.clone()); + } + } + + /// The subscription with `request_id` ended: so does the entry it held. + pub(super) fn entry_ended(&self, key: &TrackKey, request_id: RequestId, end: Result<(), Error>) { + self.listings.lock().ended(key, request_id, end); + } + + /// Hold a paused subscription again as its track's entry, watched until a reader + /// resumes it, or cancel it if the entry is gone. + pub(super) fn hold(&self, key: TrackKey, upstream: Upstream) { + let handoff = kio::Shared::>::default(); + let held = match self.listings.lock().held_by(&key, upstream.request_id) { + Some(entry) => { + entry.handoff = Some(handoff.clone()); + true + } + None => false, + }; + let this = self.clone(); + self.tasks.push(async move { + match held { + true => this.watch(key, upstream, handoff).await, + false => { + this.remove_subscribe(upstream.request_id); + this.cancel_subscribe(upstream.stream, upstream.request_id).await; + } + } + }); + } + + /// Pause a subscription nobody reads that is its track's entry, and hold it again. + pub(super) async fn pause(&self, key: TrackKey, mut upstream: Upstream) { + self.park_subscribe(upstream.request_id); + let pause = Forward { + forward: false, + ..Default::default() + }; + match self.write_forward(&mut upstream.stream.writer, &pause).await { + Ok(()) => { + upstream.owed += 1; + tracing::debug!(broadcast = %key.0, track = %key.1, "subscription paused"); + self.hold(key, upstream); + } + Err(err) => { + tracing::debug!(%err, "failed to pause the subscription"); + self.remove_subscribe(upstream.request_id); + self.entry_ended(&key, upstream.request_id, Err(err)); + } + } + } + + /// Reset a subscription's state to paused, keeping the alias it is bound to: objects + /// still arriving for it are refused rather than buffered. + fn park_subscribe(&self, request_id: RequestId) { + let mut state = self.state.lock(); + let Some(held) = state.subscribes.get_mut(&request_id) else { + return; + }; + if let Ok(mut fill) = held.fill.write() { + fill.cancel(); + } + let parked = TrackState { + alias: held.alias, + epoch: held.epoch.clone(), + tail: std::mem::take(&mut held.tail), + ..TrackState::pending( + std::mem::take(&mut held.name), + held.broadcast.clone(), + kio::Producer::new(Fill::Done), + ) + }; + let fetch_id = std::mem::replace(held, parked).fetch_id; + if let Some(fetch_id) = fetch_id { + state.fetches.remove(&fetch_id); + } + if let Some(alias) = state.subscribes.get(&request_id).and_then(|track| track.alias) { + rebind_track_alias(&state.aliases, alias, request_id, Alias::Paused(request_id)); + } + } + + /// Set a held subscription's Forward State with REQUEST_UPDATE. + pub(super) async fn write_forward( + &self, + writer: &mut Writer, + forward: &Forward, + ) -> Result<(), Error> { + let request_id = self.control.next_request_id(&self.runtime).await?; + writer.varint(ietf::SubscribeUpdate::ID).await?; + writer + .encode(&ietf::SubscribeUpdate { + max_age: forward.max_age, + request_id, + subscription_request_id: None, + start_location: ietf::Location { group: 0, object: 0 }, + end_group: 0, + subscriber_priority: forward.priority.map(super::super::priority::to_wire), + forward: Some(forward.forward), + filter: forward.filter, + authorization_token: None, + new_group: forward.new_group, + fill: forward.fill, + }) + .await + } + + /// Check the answer to a REQUEST_UPDATE a held subscription still owes. It carries + /// nothing to act on: a refused one is followed by the PUBLISH_DONE that ends it. + fn owed_answer(&self, id: u64, body: &ietf::Body) -> Result<(), Error> { + match id { + ietf::RequestOk::ID => body.message::(self.version).map(|_| ())?, + _ => body.message::(self.version).map(|_| ())?, + } + Ok(()) + } + + /// Read the answer to a SUBSCRIBE, or to the REQUEST_UPDATE resuming `held`. + pub(super) async fn read_answer( + &self, + stream: &mut Stream, + messages: &mut Messages, + held: Option<&mut Resumed>, + ) -> Result, Error> { + let Some(held) = held else { + return self.read_subscribe_response(stream, messages).await; + }; + loop { + let Framed(id, body) = messages.message(&mut stream.reader).await?; + match id { + // The answer to a pause that went out before this resume. + ietf::RequestOk::ID | ietf::RequestError::ID if held.owed > 0 => { + self.owed_answer(id, &body)?; + held.owed -= 1; + } + ietf::RequestOk::ID => { + let ok = body.message::(self.version)?; + tracing::debug!(message = ?ok, "subscription resumed"); + return Ok(Some(Accepted { + alias: held.alias, + properties: held.properties.clone(), + largest: ok.largest, + })); + } + ietf::RequestError::ID => { + let refused = body.message::(self.version)?; + tracing::debug!(message = ?refused, "resume refused"); + return Err(request::from_code( + refused.error_code, + request::Kind::Subscribe, + self.version, + )); + } + ietf::PublishDone::ID => { + let done = body.message::(self.version)?; + let end = listing_end(&done, self.version); + held.ended = Some(end.clone()); + return Err(end.err().unwrap_or(Error::NotFound)); + } + _ => return Err(Error::UnexpectedMessage), + } + } + } +} + +/// A REQUEST_UPDATE setting a held subscription's Forward State. +#[derive(Default)] +pub(super) struct Forward { + pub(super) forward: bool, + /// The Location Filter it resumes with. + pub(super) filter: Option, + /// FILL_PARAMETERS (draft-20+), the backfill it resumes with. + pub(super) fill: Option, + /// The aggregate priority, in the model's higher-first terms. + pub(super) priority: Option, + pub(super) max_age: Option, + pub(super) new_group: Option, +} + +/// What a subscription resuming a held one keeps of it. +pub(super) struct Resumed { + pub(super) alias: u64, + pub(super) properties: ietf::Properties, + /// REQUEST_UPDATE answers still owed. + pub(super) owed: u64, + /// How a PUBLISH_DONE ended it before the resume was answered. + pub(super) ended: Option>, +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::model::ProduceTest as _; + use crate::transport::memory; + + const TIMEOUT: Duration = Duration::from_secs(1); + + type PeerStream = Stream; + + /// A subscriber listing `broadcast` over a raw peer that plays the publisher. + struct Harness { + subscriber: Subscriber, + peer: memory::Session, + tracks: crate::broadcast::Tracks, + listening: Listening, + version: Version, + _broadcast: crate::broadcast::Producer, + _driver: moq_clock::sim::JoinHandle<()>, + } + + async fn settle() { + moq_clock::sleep(Duration::from_millis(1)).await; + } + + fn harness(version: Version) -> Harness { + let (session, peer) = memory::pair(memory::Config::default()); + let (tasks, mut task_set) = TaskSet::new(); + let driver = moq_clock::sim::spawn(async move { kio::wait(|waiter| task_set.poll(waiter)).await }); + let subscriber = Subscriber::new( + crate::time::sim(), + session, + crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + Control::new(None, false), + None, + peer::PeerSetup::declared(peer::Peer::default()), + crate::Hop::new(1).unwrap(), + None, + version, + tasks, + Default::default(), + ); + let broadcast = crate::broadcast::Info::default().produce(); + let lister = Arc::new(broadcast.dynamic().lister().unwrap()); + let tracks = broadcast.consume().tracks().unwrap(); + let listening = subscriber.listen(PathOwned::from("bcast"), lister); + Harness { + subscriber, + peer, + tracks, + listening, + version, + _broadcast: broadcast, + _driver: driver, + } + } + + async fn read(stream: &mut PeerStream) -> (u64, ietf::Body) { + let read = async { + let id = stream.reader.varint().await.unwrap(); + (id, stream.reader.decode::().await.unwrap()) + }; + moq_clock::timeout(TIMEOUT, read) + .await + .expect("the subscriber sent nothing") + } + + async fn write(stream: &mut PeerStream, id: u64, msg: &M) { + stream.writer.varint(id).await.unwrap(); + stream.writer.encode(msg).await.unwrap(); + settle().await; + } + + /// The next listing event as `+name`, `-name`, or `synced`; `None` while pending. + fn event(tracks: &mut crate::broadcast::Tracks) -> Option { + match tracks.poll_next(&kio::Waiter::noop()) { + Poll::Ready(Ok(Some(crate::broadcast::TracksEvent::Added { name, .. }))) => Some(format!("+{name}")), + Poll::Ready(Ok(Some(crate::broadcast::TracksEvent::Removed { name }))) => Some(format!("-{name}")), + Poll::Ready(Ok(Some(crate::broadcast::TracksEvent::Synced))) => Some("synced".into()), + Poll::Ready(other) => Some(format!("{other:?}")), + Poll::Pending => None, + } + } + + impl Harness { + /// Accept the SUBSCRIBE_TRACKS and establish it. + async fn establish(&mut self) -> PeerStream { + let mut stream = moq_clock::timeout(TIMEOUT, Stream::accept(&mut self.peer, self.version)) + .await + .expect("no SUBSCRIBE_TRACKS") + .unwrap(); + let (id, body) = read(&mut stream).await; + assert_eq!(id, ietf::SubscribeTracks::ID); + let msg: ietf::SubscribeTracks = body.message(self.version).unwrap(); + assert_eq!(msg.prefix.as_str(), "bcast"); + assert!(!msg.forward, "the listing asks for every track's objects"); + let ok = ietf::RequestOk { + request_id: None, + active: None, + largest: None, + }; + write(&mut stream, ietf::RequestOk::ID, &ok).await; + assert_eq!(event(&mut self.tracks).as_deref(), Some("synced")); + stream + } + + /// PUBLISH `name` paused, returning the stream once the subscriber holds it. + async fn publish(&mut self, name: &str, request_id: u64) -> PeerStream { + let (stream, id, _) = self.offer(offered("bcast", name, request_id)).await; + assert!( + [ietf::RequestOk::ID, ietf::PublishOk::ID].contains(&id), + "PUBLISH refused: {id:#x}" + ); + stream + } + + /// A reader of `name`, served by the subscriber as a broadcast's request would be. + async fn read_track( + &mut self, + name: &str, + ) -> ( + crate::track::Consumer, + kio::Pending, + moq_clock::sim::JoinHandle<()>, + ) { + let mut dynamic = self._broadcast.dynamic(); + let track = self._broadcast.consume().track(name).unwrap(); + let reader = track.subscribe(None); + let request = dynamic.requested_track().await.expect("no track requested"); + let mut subscriber = self.subscriber.clone(); + let serving = moq_clock::sim::spawn(async move { + subscriber + .run_subscribe(Path::new("bcast"), dynamic, None, request) + .await; + }); + (track, reader, serving) + } + + /// Resume the held `video` for a reader, returning it once accepted. + async fn resume( + &mut self, + video: &mut PeerStream, + ) -> ( + crate::track::Consumer, + crate::track::Subscriber, + moq_clock::sim::JoinHandle<()>, + ) { + let (track, reader, serving) = self.read_track("video").await; + let (id, body) = read(video).await; + assert_eq!(id, ietf::SubscribeUpdate::ID, "not resumed"); + let resume: ietf::SubscribeUpdate = body.message(self.version).unwrap(); + assert_eq!(resume.forward, Some(true)); + let ok = ietf::RequestOk { + request_id: None, + active: None, + largest: None, + }; + write(video, ietf::RequestOk::ID, &ok).await; + let reader = moq_clock::timeout(TIMEOUT, reader) + .await + .expect("never accepted") + .unwrap(); + (track, reader, serving) + } + + /// Resume the held `video` for a reader, then let it go so the subscription pauses. + async fn resume_and_pause( + &mut self, + video: &mut PeerStream, + ) -> (crate::track::Consumer, moq_clock::sim::JoinHandle<()>) { + let (track, reader, serving) = self.resume(video).await; + drop(reader); + let (id, body) = read(video).await; + assert_eq!(id, ietf::SubscribeUpdate::ID, "not paused"); + let pause: ietf::SubscribeUpdate = body.message(self.version).unwrap(); + assert_eq!(pause.forward, Some(false)); + settle().await; + (track, serving) + } + + /// Send `publish`, returning the answer. + async fn offer(&mut self, publish: ietf::Publish<'_>) -> (PeerStream, u64, ietf::Body) { + let mut stream = Stream::open(&mut self.peer, self.version).await.unwrap(); + stream.writer.varint(ietf::Publish::ID).await.unwrap(); + stream.writer.encode(&publish).await.unwrap(); + + let mut ours = Stream::accept(&mut self.subscriber.session.clone(), self.version) + .await + .unwrap(); + let id = ours.reader.varint().await.unwrap(); + assert_eq!(id, ietf::Publish::ID); + let body: ietf::Body = ours.reader.decode().await.unwrap(); + let mut subscriber = self.subscriber.clone(); + let version = self.version; + moq_clock::sim::spawn(async move { + let msg: ietf::Publish = body.message(version).unwrap(); + let _ = subscriber.serve_publish(ours, msg).await; + }); + let (id, body) = read(&mut stream).await; + (stream, id, body) + } + } + + /// A paused PUBLISH of `name` in `namespace`, aliased by its request ID. + fn offered<'a>(namespace: &'a str, name: &'a str, request_id: u64) -> ietf::Publish<'a> { + ietf::Publish { + request_id: RequestId(request_id), + track_namespace: Path::new(namespace), + track_name: name.into(), + track_alias: request_id, + largest_location: None, + forward: false, + properties: ietf::Properties::default(), + subscriber_priority: None, + group_order: None, + filter: None, + } + } + + /// The error code a refused PUBLISH answered with. + fn refusal(id: u64, body: &ietf::Body, version: Version) -> u64 { + assert_eq!(id, ietf::RequestError::ID, "accepted"); + body.message::(version).unwrap().error_code + } + + /// A PUBLISH no listing asked for stays refused, and one for a track already held is + /// redundant: DUPLICATE_SUBSCRIPTION on draft-18, which allows one subscription per + /// track, and UNINTERESTED after. + #[moq_clock::test] + async fn an_unasked_or_redundant_publish_is_refused() { + for (version, duplicate) in [(Version::Draft18, 0x19), (Version::Draft19, 0x20)] { + let mut h = harness(version); + let _listing = h.establish().await; + let (_, id, body) = h.offer(offered("other", "video", 1)).await; + assert_eq!(refusal(id, &body, version), 0x3, "{version}: unsolicited"); + let _video = h.publish("video", 3).await; + let (_, id, body) = h.offer(offered("bcast", "video", 5)).await; + assert_eq!(refusal(id, &body, version), duplicate, "{version}: redundant"); + } + } + + /// A PUBLISH_DONE with TRACK_ENDED removes the track, and the listing stands. + #[moq_clock::test] + async fn a_track_ended_publish_removes_the_track() { + let version = Version::Draft22; + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + assert_eq!(event(&mut h.tracks).as_deref(), Some("+video")); + + let done = ietf::PublishDone { + request_id: None, + status_code: ietf::PublishDoneStatus::TrackEnded.code(version), + stream_count: 0, + reason_phrase: "".into(), + }; + write(&mut video, ietf::PublishDone::ID, &done).await; + assert_eq!(event(&mut h.tracks).as_deref(), Some("-video")); + assert!(h.listening.poll_failed(&kio::Waiter::noop()).is_pending()); + } + + /// Any other PUBLISH_DONE, INTERNAL_ERROR included, fails the listing rather than hide a + /// track that may be live. + #[moq_clock::test] + async fn another_publish_done_fails_the_listing() { + let version = Version::Draft22; + for (status, expected) in [ + (ietf::PublishDoneStatus::Unauthorized, Error::Unauthorized), + (ietf::PublishDoneStatus::InternalError, Error::Remote(0)), + ] { + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + assert_eq!(event(&mut h.tracks).as_deref(), Some("+video")); + + let done = ietf::PublishDone { + request_id: None, + status_code: status.code(version), + stream_count: 0, + reason_phrase: "".into(), + }; + write(&mut video, ietf::PublishDone::ID, &done).await; + match h.listening.poll_failed(&kio::Waiter::noop()) { + Poll::Ready(err) => assert_eq!(err.to_string(), expected.to_string(), "{status:?}"), + Poll::Pending => panic!("{status:?}: the listing stood"), + } + } + } + + /// A resumed listed track ending any way but TRACK_ENDED fails the listing, even a + /// clean SUBSCRIPTION_ENDED (drafts 18-19), which says nothing of the track itself. + #[moq_clock::test] + async fn a_resumed_track_ending_otherwise_fails_the_listing() { + let version = Version::Draft19; + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + assert_eq!(event(&mut h.tracks).as_deref(), Some("+video")); + + let (_track, _reader, _serving) = h.resume(&mut video).await; + assert!(h.listening.poll_failed(&kio::Waiter::noop()).is_pending()); + + // SUBSCRIPTION_ENDED, which drafts 18 and 19 register. + let done = ietf::PublishDone { + request_id: None, + status_code: 0x3, + stream_count: 0, + reason_phrase: "".into(), + }; + write(&mut video, ietf::PublishDone::ID, &done).await; + // The subscription waits out its data streams before it ends. + moq_clock::sleep(Duration::from_secs(5)).await; + assert!(h.listening.poll_failed(&kio::Waiter::noop()).is_ready()); + } + + /// A skipped track is listed through a paused SUBSCRIBE of ours, once it answers. + #[moq_clock::test] + async fn a_skipped_track_lists_once_its_paused_subscribe_answers() { + for version in [Version::Draft18, Version::Draft22] { + let mut h = harness(version); + let mut listing = h.establish().await; + let skipped = ietf::PublishSkipped { + suffix: Path::new(""), + track_name: "audio".into(), + }; + write(&mut listing, ietf::PublishSkipped::ID, &skipped).await; + assert_eq!(event(&mut h.tracks), None, "{version}: listed before it answered"); + + let mut stream = moq_clock::timeout(TIMEOUT, Stream::accept(&mut h.peer, version)) + .await + .expect("no paused SUBSCRIBE") + .unwrap(); + let (id, body) = read(&mut stream).await; + assert_eq!(id, ietf::Subscribe::ID, "{version}"); + let msg: ietf::Subscribe = body.message(version).unwrap(); + assert_eq!(msg.track_name, "audio", "{version}"); + assert_eq!( + msg.group_order, + crate::track::Order::default().into(), + "{version}: the order a reader gets by default" + ); + assert!(!msg.forward, "{version}: the SUBSCRIBE forwards"); + + let ok = ietf::SubscribeOk { + request_id: None, + track_alias: 3, + largest: None, + properties: ietf::Properties { + timescale: Some(crate::Timescale::MILLI), + ..Default::default() + }, + }; + write(&mut stream, ietf::SubscribeOk::ID, &ok).await; + assert_eq!(event(&mut h.tracks).as_deref(), Some("+audio"), "{version}"); + } + } + + /// A refused paused SUBSCRIBE fails the listing. + #[moq_clock::test] + async fn a_refused_paused_subscribe_fails_the_listing() { + let version = Version::Draft22; + let mut h = harness(version); + let mut listing = h.establish().await; + let skipped = ietf::PublishSkipped { + suffix: Path::new(""), + track_name: "audio".into(), + }; + write(&mut listing, ietf::PublishSkipped::ID, &skipped).await; + let mut stream = moq_clock::timeout(TIMEOUT, Stream::accept(&mut h.peer, version)) + .await + .expect("no paused SUBSCRIBE") + .unwrap(); + let _ = read(&mut stream).await; + let refused = ietf::RequestError { + request_id: None, + error_code: 0x3, + reason_phrase: "".into(), + retry_interval: 0, + }; + write(&mut stream, ietf::RequestError::ID, &refused).await; + assert!(matches!( + h.listening.poll_failed(&kio::Waiter::noop()), + Poll::Ready(Error::Unsupported) + )); + } + + /// A listed PUBLISH whose properties we cannot take fails the listing: the peer sends + /// nothing else for that track, so a listing left standing would silently miss it. + #[moq_clock::test] + async fn an_unsupported_publish_fails_the_listing() { + let version = Version::Draft22; + let mut h = harness(version); + let _listing = h.establish().await; + let compressed = ietf::Publish { + properties: ietf::Properties { + compress: true, + ..Default::default() + }, + ..offered("bcast", "video", 1) + }; + let (_, id, _) = h.offer(compressed).await; + assert_eq!(id, ietf::RequestError::ID, "accepted"); + assert!(matches!( + h.listening.poll_failed(&kio::Waiter::noop()), + Poll::Ready(Error::UnsupportedExtension) + )); + } + + /// From draft-20 a PUBLISH that forwards contradicts the paused listing it answers, and + /// nothing we send can pause it: it is refused and the listing fails, rather than have its + /// objects refused unseen. Through draft-19 our PUBLISH_OK pauses it. + #[moq_clock::test] + async fn a_forwarding_publish_fails_the_listing_from_draft_20() { + for version in [Version::Draft19, Version::Draft20] { + let mut h = harness(version); + let _listing = h.establish().await; + let forwarding = ietf::Publish { + forward: true, + ..offered("bcast", "video", 1) + }; + let (_, id, _) = h.offer(forwarding).await; + let failed = h.listening.poll_failed(&kio::Waiter::noop()); + match version { + Version::Draft19 => { + assert_ne!(id, ietf::RequestError::ID, "{version}: refused"); + assert!(failed.is_pending(), "{version}: {failed:?}"); + } + _ => { + assert_eq!(id, ietf::RequestError::ID, "{version}: accepted"); + assert!( + matches!(failed, Poll::Ready(Error::Unsupported)), + "{version}: {failed:?}" + ); + } + } + } + } + + /// A listed track that finishes before its resume is answered goes back to lingering, and + /// its waiting reader SUBSCRIBEs: the idle copy cannot place the end, which the SUBSCRIBE + /// learns, rather than abort a clean finish. + #[moq_clock::test] + async fn a_track_ending_before_its_resume_resubscribes() { + let version = Version::Draft22; + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + let (track, _serving) = h.resume_and_pause(&mut video).await; + + let _reader = track.subscribe(None); + let (id, body) = read(&mut video).await; + assert_eq!(id, ietf::SubscribeUpdate::ID, "not resumed"); + assert_eq!( + body.message::(version).unwrap().forward, + Some(true) + ); + let done = ietf::PublishDone { + request_id: None, + status_code: ietf::PublishDoneStatus::TrackEnded.code(version), + stream_count: 0, + reason_phrase: "".into(), + }; + write(&mut video, ietf::PublishDone::ID, &done).await; + assert!( + h.listening.poll_failed(&kio::Waiter::noop()).is_pending(), + "TRACK_ENDED failed the listing" + ); + + let mut stream = moq_clock::timeout(TIMEOUT, Stream::accept(&mut h.peer, version)) + .await + .expect("the copy did not SUBSCRIBE") + .unwrap(); + let (id, _) = read(&mut stream).await; + assert_eq!(id, ietf::Subscribe::ID); + } + + /// A paused track's upstream failing aborts the copy a reader left lingering, rather + /// than leave it open with nothing upstream. + #[moq_clock::test] + async fn a_paused_track_failing_aborts_its_lingering_copy() { + let version = Version::Draft22; + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + let (track, serving) = h.resume_and_pause(&mut video).await; + assert!(!serving.is_finished(), "the copy did not linger"); + + let done = ietf::PublishDone { + request_id: None, + status_code: ietf::PublishDoneStatus::InternalError.code(version), + stream_count: 0, + reason_phrase: "".into(), + }; + write(&mut video, ietf::PublishDone::ID, &done).await; + assert!(serving.is_finished(), "the copy outlived its upstream"); + drop(track); + } + + /// The answer a pause owes is decoded like any other, so a malformed one closes the + /// session rather than count as an answer. + #[moq_clock::test] + async fn a_malformed_pause_answer_closes_the_session() { + let version = Version::Draft22; + let mut h = harness(version); + let _listing = h.establish().await; + let mut video = h.publish("video", 1).await; + let (_track, _serving) = h.resume_and_pause(&mut video).await; + + // A REQUEST_OK with no parameters, then a trailing byte. + video.writer.varint(ietf::RequestOk::ID).await.unwrap(); + video + .writer + .write_all(&mut &[0x00, 0x02, 0x00, 0xff][..]) + .await + .unwrap(); + let mut peer = h.peer.clone(); + let closed = + kio::wait(move |waiter| crate::transport::poll::Session::poll_closed(&mut peer, &mut waiter.context())); + moq_clock::timeout(TIMEOUT, closed) + .await + .expect("the session stayed up"); + } + + /// A peer that refuses SUBSCRIBE_TRACKS, resets it, or never answers it fails at most + /// that listing: a plain SUBSCRIBE still goes out and is accepted on the session. + #[moq_clock::test] + async fn a_peer_not_answering_the_listing_still_serves_subscribe() { + let version = Version::Draft22; + for case in ["refused", "reset", "silent"] { + let mut h = harness(version); + let mut listing = moq_clock::timeout(TIMEOUT, Stream::accept(&mut h.peer, version)) + .await + .expect("no SUBSCRIBE_TRACKS") + .unwrap(); + let (id, _) = read(&mut listing).await; + assert_eq!(id, ietf::SubscribeTracks::ID); + let _held = match case { + "refused" => { + let refused = ietf::RequestError { + request_id: None, + error_code: 0x3, + reason_phrase: "".into(), + retry_interval: 0, + }; + write(&mut listing, ietf::RequestError::ID, &refused).await; + None + } + "reset" => { + let Stream { writer, reader } = listing; + writer.abort(&Error::Cancel); + settle().await; + Some(reader) + } + _ => { + settle().await; + Some(listing.reader) + } + }; + let failed = h.listening.poll_failed(&kio::Waiter::noop()); + match case { + "refused" => assert!(matches!(failed, Poll::Ready(Error::Unsupported)), "{case}: {failed:?}"), + "reset" => assert!(failed.is_ready(), "{case}: the listing stood"), + _ => assert!(failed.is_pending(), "{case}: the listing failed"), + } + + let (_track, reader, _serving) = h.read_track("video").await; + let mut stream = moq_clock::timeout(TIMEOUT, Stream::accept(&mut h.peer, version)) + .await + .expect("no SUBSCRIBE") + .unwrap(); + let (id, body) = read(&mut stream).await; + assert_eq!(id, ietf::Subscribe::ID, "{case}"); + let msg: ietf::Subscribe = body.message(version).unwrap(); + assert!(msg.forward, "{case}: a paused SUBSCRIBE"); + let ok = ietf::SubscribeOk { + request_id: None, + track_alias: 7, + largest: None, + properties: ietf::Properties::default(), + }; + write(&mut stream, ietf::SubscribeOk::ID, &ok).await; + moq_clock::timeout(TIMEOUT, reader) + .await + .expect("never accepted") + .unwrap_or_else(|err| panic!("{case}: {err}")); + } + } + + /// Dropping the listing cancels its SUBSCRIBE_TRACKS: FIN on draft-18, RESET_STREAM from + /// draft-19, where a FIN is no cancel. The held PUBLISHes are let go with it. + #[moq_clock::test] + async fn dropping_the_listing_cancels_it() { + for version in [Version::Draft18, Version::Draft19] { + let mut h = harness(version); + let mut listing = h.establish().await; + let mut video = h.publish("video", 1).await; + drop(h.listening); + settle().await; + let ended = moq_clock::timeout(TIMEOUT, listing.reader.varint_maybe()) + .await + .expect("the listing stayed open"); + match version { + Version::Draft18 => assert!(matches!(ended, Ok(None)), "{version}: {ended:?}"), + _ => assert!(ended.is_err(), "{version}: {ended:?}"), + } + let ended = moq_clock::timeout(TIMEOUT, video.reader.varint_maybe()) + .await + .expect("the PUBLISH stayed held"); + assert!(!matches!(ended, Ok(Some(_))), "{version}: {ended:?}"); + } + } +} diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index 1001d50ea54..e9b9d79d8e5 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -63,6 +63,7 @@ mod track_info_cancel; mod track_stream_demand; mod track_tail; mod tracks; +mod tracks_ietf; mod unannounce_release; mod untimed; mod wide_sequence; diff --git a/rs/moq-net/tests/integration/tracks_ietf.rs b/rs/moq-net/tests/integration/tracks_ietf.rs new file mode 100644 index 00000000000..ac3472acf67 --- /dev/null +++ b/rs/moq-net/tests/integration/tracks_ietf.rs @@ -0,0 +1,519 @@ +#![cfg(feature = "async")] + +//! A TRACKS listing over a moq-transport session (draft-18+): the subscriber sends +//! SUBSCRIBE_TRACKS with FORWARD=0 and holds each PUBLISH paused as its track's entry, which +//! a reader resumes for data instead of subscribing again. +//! +//! Deterministic: paused time and a single-threaded runtime over the mock transport. + +use crate::support; + +use std::time::Duration; + +use moq_net::broadcast::TracksEvent; +use moq_net::{Hop, Version}; +use support::harness::{MockConnectOptions, MockPair, connect_mock}; + +const TIMEOUT: Duration = Duration::from_secs(10); + +/// Every draft that has SUBSCRIBE_TRACKS. +const DRAFTS: [&str; 5] = [ + "moq-transport-18", + "moq-transport-19", + "moq-transport-20", + "moq-transport-21", + "moq-transport-22", +]; + +/// SUBSCRIBE (0x03), as the first byte of a request stream. +const SUBSCRIBE: u8 = 0x03; + +/// SUBSCRIBE_TRACKS (0x51), as the first byte of a request stream. +const SUBSCRIBE_TRACKS: u8 = 0x51; + +fn produce_origin(hop: u64) -> moq_net::origin::Producer { + let (producer, driver) = moq_net::origin::Producer::new(moq_net::origin::Config::new(Hop::new(hop).unwrap())); + support::harness::spawn(driver); + producer +} + +/// The next event as `+name`, `-name`, `synced`, `end`, or `error: ..`. +async fn next(tracks: &mut moq_net::broadcast::Tracks) -> String { + match moq_clock::timeout(TIMEOUT, tracks.next()) + .await + .expect("listing stalled") + { + Ok(Some(TracksEvent::Added { name, .. })) => format!("+{name}"), + Ok(Some(TracksEvent::Removed { name })) => format!("-{name}"), + Ok(Some(TracksEvent::Synced)) => "synced".into(), + Ok(None) => "end".into(), + Err(err) => format!("error: {err}"), + } +} + +/// Whether the listing has nothing more to report for a while. +async fn quiet(tracks: &mut moq_net::broadcast::Tracks) -> bool { + moq_clock::timeout(Duration::from_millis(500), tracks.next()) + .await + .is_err() +} + +/// `publisher` served to a fresh origin over one session; returns that origin's copy. +async fn connect(publisher: &moq_net::origin::Producer, version: &str) -> (moq_net::origin::Producer, MockPair) { + let subscriber = produce_origin(2); + let mut options = MockConnectOptions::new(version.parse::().unwrap()); + options.server_publish = Some(publisher.consume()); + options.client_subscribe = Some(subscriber.clone()); + let pair = connect_mock(options).await; + (subscriber, pair) +} + +async fn resolve(origin: &moq_net::origin::Producer, path: &str) -> moq_net::broadcast::Consumer { + moq_clock::timeout(TIMEOUT, origin.consume().routed_broadcast(path)) + .await + .expect("announce timeout") + .expect("routed") +} + +/// How many request streams of `kind` the client has opened. +fn opened(pair: &MockPair, kind: u8) -> usize { + pair.client_transport + .bidi_types() + .iter() + .filter(|first| **first == kind) + .count() +} + +/// How many SUBSCRIBE request streams the client has opened. +fn subscribes(pair: &MockPair) -> usize { + opened(pair, SUBSCRIBE) +} + +/// Read one frame of the next group, or `None` once the subscription ends. +async fn read(sub: &mut moq_net::track::Subscriber) -> Option<(u64, Vec)> { + let mut group = moq_clock::timeout(TIMEOUT, sub.recv_group()) + .await + .expect("group timeout") + .ok()??; + let frame = moq_clock::timeout(TIMEOUT, group.read_frame()) + .await + .expect("frame timeout") + .ok()??; + Some((group.sequence, frame.payload.to_vec())) +} + +/// The listing syncs at once, then lists the peer's tracks as they appear. +#[moq_clock::test] +async fn an_ietf_session_lists_its_peers_tracks() { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let _a = broadcast.create_track("a", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, _pair) = connect(&publisher, version).await; + let remote = resolve(&subscriber, "bcast").await; + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + assert_eq!(next(&mut tracks).await, "+a", "{version}"); + + let _b = broadcast.create_track("b", None).unwrap(); + assert_eq!(next(&mut tracks).await, "+b", "{version}"); + assert!(quiet(&mut tracks).await, "{version}"); + } +} + +/// SUBSCRIBE_TRACKS goes out only for a listing, since many peers do not answer it yet: +/// connecting, an announce, and a reader's SUBSCRIBE send none. +#[moq_clock::test] +async fn only_a_listing_sends_subscribe_tracks() { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let video = broadcast.create_track("video", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, pair) = connect(&publisher, version).await; + let remote = resolve(&subscriber, "bcast").await; + let mut sub = moq_clock::timeout(TIMEOUT, remote.track("video").unwrap().subscribe(None)) + .await + .expect("subscribe timeout") + .expect("subscribe"); + moq_clock::timeout(TIMEOUT, support::wanted(video.demand())) + .await + .expect("never subscribed") + .unwrap(); + let mut group = video.append_group().unwrap(); + group.write_frame(None, &b"frame"[..]).unwrap(); + group.finish().unwrap(); + assert_eq!(read(&mut sub).await, Some((0, b"frame".to_vec())), "{version}"); + assert_eq!(subscribes(&pair), 1, "{version}"); + assert_eq!(opened(&pair, SUBSCRIBE_TRACKS), 0, "{version}: listed unasked"); + + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + assert_eq!(next(&mut tracks).await, "+video", "{version}"); + assert_eq!(opened(&pair, SUBSCRIBE_TRACKS), 1, "{version}"); + } +} + +/// A listed track carries the info its PUBLISH declared. +#[moq_clock::test] +async fn a_listing_carries_track_info() { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let info = moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_priority(9); + let _a = broadcast.create_track("a", info).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, _pair) = connect(&publisher, "moq-transport-22").await; + let mut tracks = resolve(&subscriber, "bcast").await.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced"); + let event = moq_clock::timeout(TIMEOUT, tracks.next()) + .await + .expect("listing stalled") + .unwrap(); + let Some(TracksEvent::Added { name, info }) = event else { + panic!("expected an add, got {event:?}"); + }; + assert_eq!(&*name, "a"); + assert_eq!(info.timescale, Some(moq_net::Timescale::MILLI)); + assert_eq!(info.priority, 9); +} + +/// Before draft-18 there is no SUBSCRIBE_TRACKS, so the listing is refused rather than +/// answered empty, and a reader still subscribes. +#[moq_clock::test] +async fn before_draft_18_the_listing_is_refused() { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let a = broadcast.create_track("a", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, _pair) = connect(&publisher, "moq-transport-17").await; + let remote = resolve(&subscriber, "bcast").await; + let mut tracks = remote.tracks().unwrap(); + assert_eq!( + next(&mut tracks).await, + format!("error: {}", moq_net::Error::Unsupported) + ); + + let mut sub = moq_clock::timeout(TIMEOUT, remote.track("a").unwrap().subscribe(None)) + .await + .expect("subscribe timeout") + .expect("subscribe"); + moq_clock::timeout(TIMEOUT, support::wanted(a.demand())) + .await + .expect("never subscribed") + .unwrap(); + let mut group = a.append_group().unwrap(); + group.write_frame(None, &b"frame"[..]).unwrap(); + group.finish().unwrap(); + assert_eq!(read(&mut sub).await, Some((0, b"frame".to_vec()))); +} + +/// A reader of a listed track resumes its held PUBLISH, so its data arrives with no +/// SUBSCRIBE at all; draft-18 would refuse one as a second subscription to the track. +/// Once the reader leaves, the PUBLISH pauses and stays listed, and the next reader +/// resumes it again. +#[moq_clock::test] +async fn a_reader_resumes_the_held_publish() { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let video = broadcast.create_track("video", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, pair) = connect(&publisher, version).await; + let remote = resolve(&subscriber, "bcast").await; + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + assert_eq!(next(&mut tracks).await, "+video", "{version}"); + + let mut sub = moq_clock::timeout(TIMEOUT, remote.track("video").unwrap().subscribe(None)) + .await + .expect("subscribe timeout") + .expect("subscribe"); + moq_clock::timeout(TIMEOUT, support::wanted(video.demand())) + .await + .expect("never resumed") + .unwrap(); + let mut group = video.append_group().unwrap(); + group.write_frame(None, &b"first"[..]).unwrap(); + group.finish().unwrap(); + assert_eq!(read(&mut sub).await, Some((0, b"first".to_vec())), "{version}"); + assert_eq!(subscribes(&pair), 0, "{version}: subscribed beside the held PUBLISH"); + + // The last reader leaving pauses the PUBLISH upstream, and the track stays listed. + drop(sub); + moq_clock::timeout(TIMEOUT, support::unwanted(video.demand())) + .await + .expect("never paused") + .unwrap(); + assert!(quiet(&mut tracks).await, "{version}"); + + let mut sub = moq_clock::timeout(TIMEOUT, remote.track("video").unwrap().subscribe(None)) + .await + .expect("subscribe timeout") + .expect("subscribe"); + moq_clock::timeout(TIMEOUT, support::wanted(video.demand())) + .await + .expect("never resumed again") + .unwrap(); + let mut group = video.append_group().unwrap(); + group.write_frame(None, &b"second"[..]).unwrap(); + group.finish().unwrap(); + let got = loop { + match read(&mut sub).await { + Some((sequence, _)) if sequence < 1 => continue, + got => break got, + } + }; + assert_eq!(got, Some((1, b"second".to_vec())), "{version}"); + assert_eq!(subscribes(&pair), 0, "{version}"); + } +} + +/// A reader joining a listed track mid-group gets the objects already published in it: on +/// drafts 18 and 19, whose filters deliver nothing already published, through a Joining +/// FETCH on the held PUBLISH's Request ID, and from draft-20 through the resume's fill. +#[moq_clock::test] +async fn a_join_gets_the_current_groups_head() { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let video = broadcast.create_track("video", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, pair) = connect(&publisher, version).await; + let remote = resolve(&subscriber, "bcast").await; + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + assert_eq!(next(&mut tracks).await, "+video", "{version}"); + + let mut group = video.create_group(moq_net::group::Info { sequence: 5 }).unwrap(); + group.write_frame(None, &b"head"[..]).unwrap(); + + let mut sub = moq_clock::timeout(TIMEOUT, remote.track("video").unwrap().subscribe(None)) + .await + .expect("subscribe timeout") + .expect("subscribe"); + moq_clock::timeout(TIMEOUT, support::wanted(video.demand())) + .await + .expect("never resumed") + .unwrap(); + moq_clock::sleep(Duration::from_millis(10)).await; + group.write_frame(None, &b"tail"[..]).unwrap(); + group.finish().unwrap(); + + let mut joined = moq_clock::timeout(TIMEOUT, sub.recv_group()) + .await + .expect("group timeout") + .unwrap() + .expect("the joined group"); + assert_eq!(joined.sequence, 5, "{version}"); + let mut frames = Vec::new(); + while let Some(frame) = moq_clock::timeout(TIMEOUT, joined.read_frame()) + .await + .expect("frame timeout") + .unwrap() + { + frames.push(frame.payload.to_vec()); + } + assert_eq!(frames, [b"head".to_vec(), b"tail".to_vec()], "{version}"); + assert_eq!(subscribes(&pair), 0, "{version}"); + } +} + +/// A nested listing reuses the broader SUBSCRIBE_TRACKS and filters locally: the peer +/// would refuse an overlapping prefix. +#[moq_clock::test] +async fn a_nested_listing_reuses_the_broader_one() { + for version in DRAFTS { + let publisher = produce_origin(1); + let outer = publisher.create_broadcast("a").unwrap(); + let _x = outer.create_track("x", None).unwrap(); + outer.announce(Default::default()).unwrap(); + let inner = publisher.create_broadcast("a/b").unwrap(); + let _y = inner.create_track("y", None).unwrap(); + inner.announce(Default::default()).unwrap(); + + let (subscriber, _pair) = connect(&publisher, version).await; + let mut outer_tracks = resolve(&subscriber, "a").await.tracks().unwrap(); + assert_eq!(next(&mut outer_tracks).await, "synced", "{version}"); + assert_eq!(next(&mut outer_tracks).await, "+x", "{version}"); + // The broader request holds `a/b`'s tracks already, so they list before syncing. + let mut inner_tracks = resolve(&subscriber, "a/b").await.tracks().unwrap(); + assert_eq!(next(&mut inner_tracks).await, "+y", "{version}"); + assert_eq!(next(&mut inner_tracks).await, "synced", "{version}"); + + let _z = inner.create_track("z", None).unwrap(); + assert_eq!(next(&mut inner_tracks).await, "+z", "{version}"); + assert!( + quiet(&mut outer_tracks).await, + "{version}: a nested track listed in its parent" + ); + } +} + +/// A broader listing replaces the nested requests only once the peer has closed them, so it +/// is never refused as overlapping, and the nested listings keep what they listed. +#[moq_clock::test] +async fn a_broader_listing_replaces_the_nested_ones() { + for version in DRAFTS { + let publisher = produce_origin(1); + let mut held = Vec::new(); + let mut broadcasts = Vec::new(); + for path in ["a/b", "a/c", "a"] { + let broadcast = publisher.create_broadcast(path).unwrap(); + held.push(broadcast.create_track("t", None).unwrap()); + broadcast.announce(Default::default()).unwrap(); + broadcasts.push(broadcast); + } + + let (subscriber, _pair) = connect(&publisher, version).await; + let mut nested = Vec::new(); + for path in ["a/b", "a/c"] { + let mut tracks = resolve(&subscriber, path).await.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + assert_eq!(next(&mut tracks).await, "+t", "{version}: {path}"); + nested.push(tracks); + } + + let mut outer = resolve(&subscriber, "a").await.tracks().unwrap(); + assert_eq!(next(&mut outer).await, "synced", "{version}"); + assert_eq!(next(&mut outer).await, "+t", "{version}"); + for tracks in &mut nested { + assert!(quiet(tracks).await, "{version}: a nested listing changed"); + } + + // The broader request lists what follows in the nested broadcasts too. + held.push(broadcasts[0].create_track("u", None).unwrap()); + assert_eq!(next(&mut nested[0]).await, "+u", "{version}"); + } +} + +/// A PUBLISH for a track we already SUBSCRIBEd is redundant: the SUBSCRIBE lists the track +/// and keeps carrying its data. Draft-18 skips it instead, which lists it the same way. +#[moq_clock::test] +async fn a_subscribed_track_is_listed_through_its_subscribe() { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let video = broadcast.create_track("video", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, pair) = connect(&publisher, version).await; + let remote = resolve(&subscriber, "bcast").await; + let mut sub = moq_clock::timeout(TIMEOUT, remote.track("video").unwrap().subscribe(None)) + .await + .expect("subscribe timeout") + .expect("subscribe"); + moq_clock::timeout(TIMEOUT, support::wanted(video.demand())) + .await + .expect("never subscribed") + .unwrap(); + assert_eq!(subscribes(&pair), 1, "{version}"); + + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + assert_eq!(next(&mut tracks).await, "+video", "{version}"); + + let mut group = video.append_group().unwrap(); + group.write_frame(None, &b"live"[..]).unwrap(); + group.finish().unwrap(); + assert_eq!(read(&mut sub).await, Some((0, b"live".to_vec())), "{version}"); + assert!(quiet(&mut tracks).await, "{version}"); + assert_eq!(subscribes(&pair), 1, "{version}"); + } +} + +/// Each held PUBLISH counts against the session's `announces` cap, as a lite listed track +/// does: past it, the PUBLISH is refused and the listing reset rather than left short, and +/// the session stays. +#[moq_clock::test] +async fn a_listing_past_the_announces_cap_is_reset() { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + const CAP: usize = 10; + let _tracks: Vec<_> = (0..CAP) + .map(|i| broadcast.create_track(format!("t{i}"), None).unwrap()) + .collect(); + broadcast.announce(Default::default()).unwrap(); + + let mut limits = moq_net::session::Limits::default(); + limits.announces = CAP; + let subscriber = produce_origin(2); + let mut options = MockConnectOptions::new(version.parse::().unwrap()); + options.client_publish = Some(publisher.consume()); + options.server_subscribe = Some(subscriber.clone()); + options.server_limits = Some(limits); + let pair = connect_mock(options).await; + + let remote = resolve(&subscriber, "bcast").await; + let mut listing = remote.tracks().unwrap(); + assert_eq!(next(&mut listing).await, "synced", "{version}"); + // The announcement holds a slot too, so not every track fits. + let mut added = 0; + let end = loop { + match next(&mut listing).await { + event if event.starts_with('+') => added += 1, + event => break event, + } + }; + assert!(added < CAP, "{version}: listed {added} tracks under a cap of {CAP}"); + assert_eq!(end, format!("error: {}", moq_net::Error::TooManyRequests), "{version}"); + + assert!( + moq_clock::timeout(Duration::from_millis(100), pair.server.closed()) + .await + .is_err(), + "{version}: the session closed" + ); + } +} + +/// Only TRACK_ENDED removes a listed track. Our answerer cannot tell a track that finished +/// from one that left the listing and may go on elsewhere, so it ends either's PUBLISH in +/// error: the listing fails loudly instead of removing the track quietly, and a reader +/// listing again sees what is still listed. +#[moq_clock::test] +async fn an_unlisted_track_fails_the_listing() { + for finish in [false, true] { + for version in DRAFTS { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let a = broadcast.create_track("a", None).unwrap(); + let _b = broadcast.create_track("b", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (subscriber, _pair) = connect(&publisher, version).await; + let remote = resolve(&subscriber, "bcast").await; + let mut tracks = remote.tracks().unwrap(); + assert_eq!(next(&mut tracks).await, "synced", "{version}"); + let mut listed = vec![next(&mut tracks).await, next(&mut tracks).await]; + listed.sort(); + assert_eq!(listed, ["+a", "+b"], "{version}"); + + match finish { + true => { + a.finish().unwrap(); + drop(a); + } + false => { + let _ = a.abort(moq_net::Error::Cancel); + } + } + let failed = next(&mut tracks).await; + assert!(failed.starts_with("error:"), "{version} finish={finish}: {failed}"); + + let mut again = remote.tracks().unwrap(); + assert_eq!(next(&mut again).await, "synced", "{version}"); + assert_eq!(next(&mut again).await, "+b", "{version}"); + assert!(quiet(&mut again).await, "{version}"); + } + } +}