diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index 00ff7db554b..fa858b553a7 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +Resolving a rendition's `broadcast` reference, through `BroadcastConsumer::resolve` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, bound the call yourself: cancel it. + ### Priorities are signed (#6142) `TrackInfo::priority`, `Subscription::priority`, and `FetchGroupOptions::priority` are `int8_t`, and `GroupRequest::priority()` returns one. diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index 2b49aeef8cc..f170fd62c88 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +Resolving a rendition's `broadcast` reference in the rendition-based subscribes and fetches now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, bound the call yourself: add a `.timeout` to the future. + ### JSON snapshot `deltaRatio` is `deltas` `SnapshotConfig.deltaRatio` is replaced by `bool deltas` (default `true`). diff --git a/dart/moq_ffi/MIGRATE.md b/dart/moq_ffi/MIGRATE.md index 8df537cb61c..81942441036 100644 --- a/dart/moq_ffi/MIGRATE.md +++ b/dart/moq_ffi/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +Resolving a rendition's `broadcast` reference, through `MoqBroadcastConsumer.resolve` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, bound the call yourself: add a `.timeout` to the future. +Regenerate the bindings for the changed `resolve` checksum. + ### Priorities are signed (#6142) `MoqTrackInfo.priority`, `MoqSubscription.priority`, `MoqFetchGroupOptions.priority`, and `MoqGroupRequest.priority()` take `-128..=127`, higher first, and 0 is the unset midpoint. diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index f530ade4eea..a7f3a9a6bf6 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -19374,7 +19374,7 @@ void _checkApiChecksums() { 18633) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_resolve() != 33982) { + if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_resolve() != 42208) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_subscribe_track() != diff --git a/doc/bin/gstreamer.md b/doc/bin/gstreamer.md index 311da6ba08a..3b053b30a2d 100644 --- a/doc/bin/gstreamer.md +++ b/doc/bin/gstreamer.md @@ -124,7 +124,7 @@ rewound timestamps forward. Pads are named by kind and appear as the catalog announces renditions: `video_0`, `video_1`, `audio_0`. A rendition referencing another broadcast reads -that broadcast on the same connection. Link the pad you want by name; the terse +that broadcast on the same connection, waiting for it to be announced. Link the pad you want by name; the terse `moqsrc ! decodebin3` form links only the first pad offered, which may be audio. `moqsrc` follows the broadcast's announcements: when the publisher restarts, it switches to the new broadcast on the same pads, kept by rendition diff --git a/doc/concept/hang.md b/doc/concept/hang.md index 35a5cab213d..714ce485f61 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -63,7 +63,7 @@ decoder once per track. A few things the catalog can express beyond decoder config: - **Labels.** Any rendition may carry a human-readable `label` for a track picker. The map key stays the rendition's ID, so labels need not be unique and renaming one doesn't rename the track. -- **Renditions in another broadcast.** A rendition may point at a relative broadcast path, so a transcoder can publish a ladder that adds low rungs and references the source's original rendition without re-publishing its bytes. The path resolves against where the consumer found the catalog, so a reference that escapes above the root names nothing and the catalog is rejected. A consumer reads each referenced path from the first broadcast it resolves there. An optional `epoch` beside the path names the [publisher instance](/concept/moq-lite#publisher-epochs) it expects: a route proving another instance fails the rendition instead of falling back to it, while a route without an epoch (an older version) cannot prove one, so there it is best effort. +- **Renditions in another broadcast.** A rendition may point at a relative broadcast path, so a transcoder can publish a ladder that adds low rungs and references the source's original rendition without re-publishing its bytes. The path resolves against where the consumer found the catalog, so a reference that escapes above the root names nothing and the catalog is rejected. `@moq/watch` follows a referenced path's announcements like its own, restarting the rendition on each instance that serves it; every other reader, such as `moqsrc`, `moq play`, the exporters, and the bindings, waits for the first one announced and keeps it, and an exporter ends the rendition with it. An optional `epoch` beside the path names the [publisher instance](/concept/moq-lite#publisher-epochs) it expects: a route proving another instance ends the rendition instead of falling back to it, while a route without an epoch (an older version) cannot prove one, so there it is best effort. - **Track names.** The map key is a rendition's ID and, by default, its track name. A rendition sets `track` only when the two must differ, such as two renditions of same-named tracks in different broadcasts, or a rendition whose media changed and so needs a new name; readers subscribe to `track` when present. An ID can't name both a video and an audio rendition. - **Jitter.** A rendition can say how far its frames fell behind the media clock before the publisher flushed them, in whole milliseconds rounded up. Encoders report the spread of lateness above each rendition's own recent minimum, so a constant encoder delay is not jitter; container imports estimate batch spans without counting ingest delay. It describes the publisher, never the network, only grows over the life of a stream, and a player sizes its buffer to at least this much. A `0` is read as absent. - **Delay.** A rendition can also say how far its frames reach the transport behind the broadcast's earliest rendition, measured the same way from each rendition's minimum lateness, so a video encoder running 200 ms behind audio advertises `delay: 200` on video. It follows the same rules as jitter. A player holds the largest `delay + jitter` among the renditions it subscribes to, and never subtracts one rendition's `delay` from another's. diff --git a/go/ffi/MIGRATE.md b/go/ffi/MIGRATE.md index 5319a4adb04..8b8121ffdd1 100644 --- a/go/ffi/MIGRATE.md +++ b/go/ffi/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +Resolving a rendition's `broadcast` reference, through `MoqBroadcastConsumer.Resolve` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, bound the call yourself: pass a `ctx` with a deadline. +Regenerate the bindings for the changed `resolve` checksum. + ### Priorities are signed (#6142) `MoqTrackInfo.Priority`, `MoqSubscription.Priority`, `MoqFetchGroupOptions.Priority`, and `MoqGroupRequest.Priority()` are `int8`, higher first, and 0 is the unset midpoint. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index 68287cb9129..4fdd857f835 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +Resolving a rendition's `broadcast` reference, through `BroadcastConsumer.Resolve` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, bound the call yourself: pass a `ctx` with a deadline. + ### JSON snapshot `DeltaRatio` is `Deltas` `json.SnapshotOptions.DeltaRatio *uint32` and `json.DefaultDeltaRatio` are replaced by `Deltas *bool` (nil enables deltas). diff --git a/js/watch/src/broadcast.test.ts b/js/watch/src/broadcast.test.ts index 7d847986fd6..6e1d34cdf19 100644 --- a/js/watch/src/broadcast.test.ts +++ b/js/watch/src/broadcast.test.ts @@ -410,6 +410,37 @@ describe("relativeBroadcast", () => { } }); + it("drops a rendition from the catalog while its broadcast proves another epoch", async () => { + const owner = new Origin.Producer(); + const main = publish(owner, Path.from("a/b")); + const [oldEpoch, newEpoch] = [Moq.Epoch.mint(), Moq.Epoch.mint()]; + const old = owner.createBroadcast(Path.from("a/source")); + old.announce({ epoch: oldEpoch }); + const named = { ...video("avc1.64001f", "./source"), epoch: oldEpoch } as Catalog.VideoConfig; + const source = new Broadcast({ + origin: owner, + name: Path.from("a/b"), + enabled: true, + catalogFormat: "manual", + catalog: { video: { renditions: { plain: video("avc1.64001f", "./source"), named } } } as Catalog.Root, + }); + try { + await settle(); + expect(videoRenditions(source)).toEqual(["named", "plain"]); + + const replacement = owner.createBroadcast(Path.from("a/source")); + replacement.announce({ epoch: newEpoch }); + await withoutWarnings(settle); + expect(videoRenditions(source)).toEqual(["plain"]); + replacement.close(); + } finally { + source.close(); + old.close(); + main.close(); + owner.close(); + } + }); + it("uses the catalog's own broadcast when the reference is absent, empty, or self", async () => { const { source, owner } = broadcast("a/b"); const effect = new Effect(); diff --git a/js/watch/src/broadcast.ts b/js/watch/src/broadcast.ts index 490115abd07..6c3178ce2bb 100644 --- a/js/watch/src/broadcast.ts +++ b/js/watch/src/broadcast.ts @@ -9,16 +9,28 @@ import { toHang } from "./msf"; type ReferencedRendition = { broadcast?: Path.Relative; + epoch?: Catalog.ReferenceEpoch; }; +// Whether a rendition's reference names something this consumer can play. +type Usable = (rel: Path.Relative | undefined, epoch: Moq.Epoch.Valid | undefined) => boolean; + // Either the catalog's own broadcast, or a sibling to consume by path. type RelativeTarget = { local: true } | { local: false; path: Moq.Path.Valid }; function filterRenditions( renditions: Record, - usable: (rel: Path.Relative | undefined) => boolean, + usable: Usable, ): Record { - return Object.fromEntries(Object.entries(renditions).filter(([, config]) => usable(config.broadcast))); + return Object.fromEntries( + Object.entries(renditions).filter(([, config]) => usable(config.broadcast, config.epoch)), + ); +} + +// Whether `active` is proven to be another instance than `epoch` names. An epochless route cannot +// prove its instance, so only a known mismatch counts. +function provesOther(active: Moq.Broadcast.Consumer | undefined, epoch: Moq.Epoch.Valid | undefined): boolean { + return epoch !== undefined && active?.epoch !== undefined && active.epoch !== epoch; } // Whether an announced route covers `path`, until closed. Hidden routes count: a service claim @@ -47,7 +59,7 @@ function watchCovered(origin: Moq.Origin.Table, path: Moq.Path.Valid): { covered // Every section carrying a `broadcast` reference must be listed here, same as `Catalog.checkResolvable`; // one left out silently exempts its tracks from the reachability filter. -function filterCatalog(catalog: Catalog.Root, usable: (rel: Path.Relative | undefined) => boolean): Catalog.Root { +function filterCatalog(catalog: Catalog.Root, usable: Usable): Catalog.Root { return { ...catalog, video: catalog.video @@ -182,12 +194,16 @@ export class Broadcast { } // Publish the catalog minus every rendition this consumer cannot use: one naming a - // broadcast that isn't announced to us. Selecting one of those would render nothing, - // since `relativeBroadcast` resolves it to no broadcast at all. Reruns as announcements - // arrive, so a rendition appears once its broadcast does. + // broadcast that isn't announced to us, or one whose broadcast proves another epoch than it + // names. Selecting one of those would render nothing, since `relativeBroadcast` resolves it to + // no broadcast at all. Reruns as announcements arrive, so a rendition appears once its + // broadcast does. Only a rendition naming an epoch resolves its broadcast here, sharing the + // request playback uses. #runFiltered(effect: Effect): void { const raw = effect.get(this.#raw); - const usable = (rel: Path.Relative | undefined) => this.#relativeTarget(effect, rel) !== undefined; + const usable: Usable = (rel, epoch) => + this.#relativeTarget(effect, rel) !== undefined && + (epoch === undefined || !provesOther(this.#relativeActive(effect, rel), epoch)); effect.set(this.#out.catalog, raw ? filterCatalog(raw, usable) : undefined); } @@ -448,7 +464,7 @@ export class Broadcast { epoch?: Moq.Epoch.Valid, ): Moq.Broadcast.Consumer | undefined { const active = this.#relativeActive(effect, rel); - if (!active || epoch === undefined || active.epoch === undefined || active.epoch === epoch) return active; + if (!active || !provesOther(active, epoch)) return active; console.warn("ignoring rendition: its broadcast serves another epoch", active.path, active.epoch, epoch); return undefined; } diff --git a/kt/moq-ffi/MIGRATE.md b/kt/moq-ffi/MIGRATE.md index a87e06daea2..26889124bb9 100644 --- a/kt/moq-ffi/MIGRATE.md +++ b/kt/moq-ffi/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +Resolving a rendition's `broadcast` reference, through `MoqBroadcastConsumer.resolve` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, bound the call yourself: cancel the coroutine or wrap it in `withTimeout`. +Regenerate the bindings for the changed `resolve` checksum. + ### A client asks only about what it watches (#6165) On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announcedBroadcast()`, instead of under its whole scope at connect. diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 214011b3f42..3b5ed2c1193 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +Resolving a rendition's `broadcast` reference in the rendition-based subscribes and fetches now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, bound the call yourself: cancel the coroutine or wrap it in `withTimeout`. + ### JSON snapshot `deltaRatio` is `deltas` `SnapshotConfig.deltaRatio: UInt` is replaced by `deltas: Boolean` (default `true`). diff --git a/py/moq-ffi/MIGRATE.md b/py/moq-ffi/MIGRATE.md index 3390d71fffd..44d3a96c07a 100644 --- a/py/moq-ffi/MIGRATE.md +++ b/py/moq-ffi/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +Resolving a rendition's `broadcast` reference, through `MoqBroadcastConsumer.resolve()` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, bound the call yourself: cancel the task or wrap it in `asyncio.wait_for`. +Regenerate the bindings for the changed `resolve` checksum. + ### A client asks only about what it watches (#6165) On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announced_broadcast()`, instead of under its whole scope at connect. diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index 81a829b3690..ce184747fd4 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +Resolving a rendition's `broadcast` reference, through `BroadcastConsumer.resolve()` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, bound the call yourself: cancel the task or wrap it in `asyncio.wait_for`. + ### JSON snapshot `delta_ratio` is `deltas` `SnapshotProducer(delta_ratio=...)` is replaced by `deltas: bool = True`. diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index defd571a6d6..e3e052afc07 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -72,9 +72,8 @@ Decided: for the catalog instance's lifetime. Optional reference epochs constrain resolution on epoch-aware transports and remain best effort on epochless transports. Following never turns a replacement into seamless resume. The - schemas, shared resolution, and compatibility documentation landed; - [reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md) - owns the native readers that follow announcements. + schemas, shared resolution, compatibility documentation, and `moq_mux::follow` + landed; `moqsrc` following siblings with it remains. - Every first-party publisher that can restart mints its own: the apps, moq-boy, the ingest gateways, moqsink, OBS, and the bindings. Players (`moq play`, `@moq/watch`, demo/web) follow the announce `Restart`. moq-stats mints one per @@ -126,4 +125,4 @@ End+Start. The child quests own their focused regressions. ## Required -- [Reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md) - native readers restart a replaced referenced sibling on its announcements, never past a named epoch +- [moqsrc sibling follow](/quest/m0/broadcast-epoch/moqsrc-sibling-follow.md) - moqsrc restarts a referenced sibling's rendition on each instance its announcements hand out, never past a named epoch diff --git a/quest/m0/broadcast-epoch/moqsrc-sibling-follow.md b/quest/m0/broadcast-epoch/moqsrc-sibling-follow.md new file mode 100644 index 00000000000..f14cd2dd940 --- /dev/null +++ b/quest/m0/broadcast-epoch/moqsrc-sibling-follow.md @@ -0,0 +1,41 @@ +# [M] moqsrc follows referenced broadcasts' announcements + +## Goal + +`moqsrc` follows a catalog-referenced sibling's announcements the way +`@moq/watch` does: each rendition reads the instance `moq_mux::Source::follow` +hands out, idles its pad (no EOS) while the sibling is offline, and restarts on +the same pad when another instance serves it. A reference that names an +`epoch` never plays another instance. Until this lands, `moqsrc` waits for a +sibling's first announcement and keeps that instance, like every other +non-following reader. + +## Plan + +Split from the reference announcements work (maintainer, 2026-10-22), which +landed `moq_mux::follow` and the waiting `Source::bind`. The moqsrc half drew a +new state-machine finding every review round, so it gets its own design pass. + +- Start binds the rendition; End idles its pad; another instance restarts the + stream on the same pad with a fresh stream-start, caps, and a segment. +- Renditions reading one sibling instance share that instance's timeline, + whenever each starts on it, including one still subscribing when a + replacement takes over. +- A sibling track that finishes while its instance stays up idles the pad and + keeps following; a finished record names the instance that served it, so a + reshape (disable and enable, an epoch handoff) still plays the next one. +- A rendition the catalog delists drains the instance it reads, then ends its + pad and follows no later instance. +- A pump that has returned but is still in `active` must not swallow a relist: + a relist arriving before the pump is joined matches its shape and starts + nothing, for an idle delisted sibling and for a delisted catalog rendition + whose track ends just before the relist. Cover both cases. + +Weigh a simpler state model (one task per sibling instance owning its +renditions, or reconciling after each pump exits) before patching each case. + +Public API: none (moqsrc behavior). Wire: none. + +## Related + +- [Sink restart follow](/quest/m1/sink-restart-follow.md) - moves moqsrc's own broadcast follow onto `follow::Instances` diff --git a/quest/m0/broadcast-epoch/reference-announcements.md b/quest/m0/broadcast-epoch/reference-announcements.md deleted file mode 100644 index f5b82e19b2f..00000000000 --- a/quest/m0/broadcast-epoch/reference-announcements.md +++ /dev/null @@ -1,52 +0,0 @@ -# [L] Rust readers follow referenced broadcasts' announcements - -## Goal - -Native readers follow a catalog-referenced sibling's announcements the way -`@moq/watch` already does, since announcement is the online/offline signal. -A reference that names an `epoch` never follows onto another instance. - -## Plan - -Split from the catalog references work (#5500's Codex review, decided by the -maintainer 2026-10-14). That work landed the optional reference `epoch`, its -shared resolution in `moq_mux::Source` and `@moq/watch`, and the Hang draft -text; this quest owns the following behavior it left out. - -- Share it in `moq_mux` (a `Source::follow`-style API; the shape is open) - rather than per reader, built on `origin::Consumer::announced_broadcast` - rather than another hand-rolled loop. Follow unpinned and check each - handed-out instance's epoch, as `Source::bind` does: a pinned - `announced_broadcast` waits out an epochless route, which would break the - best effort the reference epoch promises there. `Source::bind` binds once - today, as `failed_binding_does_not_retry_a_later_publisher` asserts; that - changes. The "no retarget" rule applies only to readers that follow no - announcement. - Decided 2026-10-20 (maintainer): this quest owns `Source::follow` and - [sink restart follow](/quest/m1/sink-restart-follow.md) reuses it, so - no reader hand-rolls its own follow loop. -- `moqsrc`: Start binds the rendition, End idles its pad, and Restart - restarts its pump. -- Exporters: a late first announcement starts the rendition and End ends - it. Restart behavior belongs to - [sink restart follow](/quest/m1/sink-restart-follow.md). -- A replacement is a Restart for an announcement follower, never a seamless - same-epoch resume. A proven Takeover preserves the same instance. -- A reference with an `epoch` follows only its own instance: following never - substitutes a different epoch, so a Restart onto another one ends that - rendition, matching `relativeBroadcast` in - `@moq/watch` (`follows a replaced sibling only for a reference that names - no epoch`). -- `@moq/watch` returns nothing for a rendition whose followed broadcast proves - another epoch, but still lists it in `out.catalog`, so selection can pick a - rendition that never plays. Drop it from the effective catalog too. - -Test late first announcements, End then Start, Restart with and without an -epoch, and concurrent old/new consumers, in the moq-mux unit tests and the -`moqsrc` and exporter suites. - -## Related - -- [Sink restart follow](/quest/m1/sink-restart-follow.md) - exporters and sinks that follow an epochless Restart of their own broadcast -- [Export rendition rebind](/quest/m1/export-rendition-rebind.md) - exporters rebuild a rendition whose reference changes -- [Hang contribution references](/quest/m2/contribution-ref.md) - builds its lazy contribution entries on these reference rules diff --git a/quest/m1/announce-takeover.md b/quest/m1/announce-takeover.md index 593b11e5366..3ff73d8184c 100644 --- a/quest/m1/announce-takeover.md +++ b/quest/m1/announce-takeover.md @@ -94,6 +94,5 @@ ANNOUNCE_TAKEOVER; published versions retain their framing. - [Claim answer epochs](https://github.com/moq-dev/moq/pull/5678) - `Request::prepare` then `publish` answers a claim at the exact path under a fresh epoch, the operation TAKEOVER continues - [IETF takeover](/quest/m1/ietf-takeover.md) - negotiated IETF counterpart -- [Reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md) - a proven continuation keeps a followed reference on its instance - [Retired requests](https://github.com/moq-dev/moq/pull/5294) - replacements never substitute content into held handles - [Identity and recovery guide](/quest/m1/identity-guide.md) - explains takeover alongside restart and legacy behavior diff --git a/quest/m1/api-audit/resolve.md b/quest/m1/api-audit/resolve.md index 9bf6fc9f706..c6008115d96 100644 --- a/quest/m1/api-audit/resolve.md +++ b/quest/m1/api-audit/resolve.md @@ -53,7 +53,7 @@ and the bindings promote it as a top-level convenience. `Subscriber::new` (production), `rs/moq-cli/src/subscribe.rs` and `report.rs`, `rs/moq-transcode/examples/transcode.rs`, `rs/moq-bench/src/connection.rs`, the hand-rolled resolvers in - `rs/moq-mux/src/source.rs`, `rs/moq-hls/src/server/mod.rs` (wall-clock + `rs/moq-mux/src/source.rs` (with `moq_mux::follow` on `announced_broadcast`), `rs/moq-hls/src/server/mod.rs` (wall-clock `RESOLVE_TIMEOUT`) and `rs/moq-stats/src/aggregate.rs`, the `rs/moq-relay/src/web.rs` fetch deadline, the `rs/moq-e2ee/MIGRATE.md` advice to read the epoch via `routed()`, and @@ -73,5 +73,4 @@ Wire: none. ## Related - [Readers follow restarts](/quest/m1/sink-restart-follow.md) - moves readers to `follow`; whichever lands second adopts the other's names -- [Reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md) - `moq_mux::Source::follow` builds on the follow operation - [Origin fronts park](/quest/m2/origin-front-parks.md) - touches the same retry diff --git a/quest/m1/identity-guide.md b/quest/m1/identity-guide.md index 27d5b876af0..4e9c3978aed 100644 --- a/quest/m1/identity-guide.md +++ b/quest/m1/identity-guide.md @@ -40,5 +40,4 @@ Public API and wire: none; this is a user guide for existing feature owners. ## Required -- [Reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md) - settles how readers pin and follow catalog references - [Announcement takeover](/quest/m1/announce-takeover.md) - establishes the continuity operation the guide demonstrates diff --git a/quest/m1/sink-restart-follow.md b/quest/m1/sink-restart-follow.md index 7c7dc82213b..5ff849bc074 100644 --- a/quest/m1/sink-restart-follow.md +++ b/quest/m1/sink-restart-follow.md @@ -16,8 +16,10 @@ route dies, since its subscriptions then end with an error. Decided with the maintainer on 2026-10-20: widened from the server and push sinks to every moq-cli and moq-gst reader. Following a catalog's references -to other broadcasts stays with -[reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md). +to other broadcasts is [moqsrc sibling follow](/quest/m0/broadcast-epoch/moqsrc-sibling-follow.md) +for `moqsrc`, through `moq_mux::Source::follow`; +`moq play` resolves a reference once with `Source::resolve`, which waits for +a sibling's first announcement and keeps it. Readers with their own follow loop today move onto `announced_broadcast`: @@ -47,14 +49,13 @@ Audit and fix the rest the same way: - `transcode`: its source broadcast; following means restarting the ladder on the new instance. -Reuse `moq_mux::Source::follow` from -[reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md), -built on `announced_broadcast`, rather than one rule per reader (decided -2026-10-20, maintainer). Each fix lands with a test that replaces the -publisher while the reader runs. +Share `moq_mux::follow::Instances::new(origin, path, None)` (decided 2026-10-20, +maintainer: no reader hand-rolls its own follow loop) rather than one rule per +reader: it yields `follow::Event::Start` for each instance serving the path and +`follow::Event::End` once the one handed out stops serving. Build a +`moq_mux::Source` from each started instance, so its siblings follow through +`Source::follow` and its exporters pin through `Source::bind`, which waits for +a sibling's first announcement. Each fix lands +with a test that replaces the publisher while the reader runs. Public API: none. Wire: none. - -## Required - -- [Reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md) - owns `Source::follow`, built on moq-net's announced request diff --git a/quest/m2/contribution-ref.md b/quest/m2/contribution-ref.md index 40c074065a2..1a5b4b26785 100644 --- a/quest/m2/contribution-ref.md +++ b/quest/m2/contribution-ref.md @@ -35,9 +35,8 @@ references") and its decision notes rather than starting over: until the contribution resolves. A reader that follows announcements follows the contribution's Start, End, and Restart; one that follows none pins the first resolution for its parent catalog instance. Reuse - `moq_mux::Source`'s pinning and the `Source::follow` from - [reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md); - do not add a second one. + `moq_mux::Source`'s pinning and `Source::follow`; do not add a second + one. - #5722 was stacked on #5699's reference `epoch`, which has landed; rebuild it on `main`. @@ -50,7 +49,3 @@ contributor restart. Public API: a catalog `contributions` section in `hang` and `@moq/hang`, and `Broadcast.contribution` in `@moq/watch`. Wire: a new optional catalog field. - -## Required - -- [Reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md) - owns `Source::follow`, which a contribution's announcement followers reuse diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index f064ca2f464..939c139c71c 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +`moq_consume_video` and `moq_consume_audio` on a rendition whose catalog `broadcast` field names a sibling now wait for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, give up on it yourself with `moq_consume_video_cancel` or `moq_consume_audio_cancel`. + ### JSON snapshot `delta_ratio` is `deltas` `moq_json_snapshot_config.delta_ratio` is replaced by `bool deltas`. diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 11ad49bbd94..3886794cf3c 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,6 +5,11 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +Resolving a rendition's `broadcast` reference, through `MoqBroadcastConsumer::resolve` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, bound the call yourself: cancel it or race it against a timeout. + ### JSON snapshot `delta_ratio` is `deltas` `MoqJsonSnapshotConfig::delta_ratio` is replaced by `deltas: bool` (default `true`). diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index 11e0c469509..9300d72effb 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -269,9 +269,8 @@ impl MoqBroadcastConsumer { /// `MoqVideoConsumer::subscribe`, `MoqAudioConsumer::subscribe`) resolve both themselves. /// /// Errors if this broadcast came from a local producer rather than an origin, since a - /// standalone broadcast has no sibling to name, and reports a sibling that exists but is not - /// announced yet as unroutable rather than waiting for it (see - /// [`MoqOriginConsumer::request_broadcast`](crate::origin::MoqOriginConsumer::request_broadcast)). + /// standalone broadcast has no sibling to name. A sibling nothing announces yet is waited for, + /// so a late one resolves once it is announced; cancel the call to give up on it. pub async fn resolve( &self, reference: Option, diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index 342bf97bced..25ccda4f2d3 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -3867,8 +3867,8 @@ mod tests { drop((track, catalog, live)); } - // A sibling not yet announced when the rendition binds it fails that first lookup. The - // catalog's rows are still listed, and the bind is issued again until the sibling resolves. + // A sibling not yet announced when the rendition binds it is waited for. The catalog's rows + // are still listed, and the binding resolves on the sibling's first announcement. #[tokio::test] async fn a_sibling_announced_after_export_start_is_bound() { tokio::time::pause(); diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 72b4146188f..baed6031b62 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -115,9 +115,8 @@ enum Config { struct Media { handle: Mutex, track: String, - /// The source, reference, and epoch a sibling is bound through, to re-issue a bind that - /// failed before it ever resolved. - sibling: Option<(moq_mux::Source, moq_net::path::RelativeOwned, Option)>, + /// The rendition reads another broadcast than the catalog's. + sibling: bool, } struct Handle { @@ -154,7 +153,8 @@ impl Media { Ok(Self { handle: Mutex::new(handle), track: track.to_string(), - sibling: sibling(source, rel).map(|rel| (source.clone(), rel, reference.epoch().cloned())), + // `bind` already rejected an escaping reference, so both sides name a path. + sibling: source.resolve_reference(rel) != source.resolve_reference(None), }) } @@ -172,33 +172,16 @@ impl Media { /// Register the bound broadcast's close and retain its track before new lookups are refused. fn poll_sync(&self, waiter: &kio::Waiter, window: &segments::Producer) -> Arc { let mut handle = self.handle.lock().expect("media lock poisoned"); - let mut reissued = false; - loop { - match handle.binding.poll_broadcast(waiter) { - Poll::Ready(Ok(broadcast)) => { - handle.capture(&broadcast, &self.track); - if self.sibling.is_some() && !handle.ended && broadcast.poll_closed(waiter).is_ready() { - // End and Restart both drain only the pinned instance. Looking its path - // up again could serve a replacement under the old timeline's rows. - handle.ended = true; - window.end(); - } - } - // Only a binding that never resolved may be reissued. The source pins every - // successful result, so a replacement can never answer these old rows. - Poll::Ready(Err(_)) if !reissued => { - reissued = true; - if let Some((source, rel, epoch)) = &self.sibling - && let Ok(next) = source.bind(Some(rel), epoch.as_ref()) - { - handle.binding = Arc::new(next); - continue; - } - } - _ => {} + if let Poll::Ready(Ok(broadcast)) = handle.binding.poll_broadcast(waiter) { + handle.capture(&broadcast, &self.track); + if self.sibling && !handle.ended && broadcast.poll_closed(waiter).is_ready() { + // End and Restart both drain only the pinned instance. Looking its path up again + // could serve a replacement under the old timeline's rows. + handle.ended = true; + window.end(); } - return handle.binding.clone(); } + handle.binding.clone() } fn poll_track( @@ -215,18 +198,6 @@ impl Media { } } -/// A catalog `broadcast` reference that names a different path than the catalog itself. -fn sibling( - source: &moq_mux::Source, - rel: Option<&moq_net::path::RelativeOwned>, -) -> Option { - let target = source.resolve_reference(rel)?; - if source.resolve_reference(None).as_ref() == Some(&target) { - return None; - } - Some(rel.cloned().unwrap_or_else(moq_net::path::Relative::empty)) -} - /// Clear the video fields that don't change how the rendition decodes or is muxed, so a config /// the publisher only re-measured or re-labelled compares equal to the one already being served. /// diff --git a/rs/moq-hls/src/server/routes.rs b/rs/moq-hls/src/server/routes.rs index 08b28075ccd..19ac4c6e9d7 100644 --- a/rs/moq-hls/src/server/routes.rs +++ b/rs/moq-hls/src/server/routes.rs @@ -1127,7 +1127,7 @@ mod tests { moq_mux::catalog::Producer::new(&mut catalog_broadcast, moq_mux::catalog::Config::default()).unwrap(); let reserved = catalog.reserve(); let mut config = video_config(); - config.broadcast = Some(moq_net::path::Relative::new("../source").to_owned()); + config.broadcast = Some(moq_net::path::Relative::new("./source").to_owned()); let track = media_broadcast.create_track("video0", timed()).unwrap(); let mut media = reserved .video( diff --git a/rs/moq-mux/MIGRATE.md b/rs/moq-mux/MIGRATE.md index a3ff4833685..aa4f2b40339 100644 --- a/rs/moq-mux/MIGRATE.md +++ b/rs/moq-mux/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### `Source` waits for a sibling's first announcement (#6254) + +`Source::bind`, `resolve`, and `subscribe_track` now wait for a sibling nothing announces yet instead of failing with `Unroutable`, and keep the first instance they resolve: once it goes, they answer that ended broadcast rather than waiting for the next. +Where you skipped a rendition on that error, bound the call yourself (`tokio::time::timeout`, or drop it), or follow the sibling's instances with `Source::follow`. + ### JSON `delta_ratio` is `deltas` `json::Config::delta_ratio` and `with_delta_ratio` are replaced by `deltas: bool` and `with_deltas` (default `true`). diff --git a/rs/moq-mux/src/container/source.rs b/rs/moq-mux/src/container/source.rs index aaa1158ea8b..eb6d0f3d274 100644 --- a/rs/moq-mux/src/container/source.rs +++ b/rs/moq-mux/src/container/source.rs @@ -62,6 +62,8 @@ enum SourceState { /// The resolved consumer, reading frames. Boxed because it's much larger than /// the `Subscribing` variant (clippy `large_enum_variant`). Active(Box>), + /// The sibling instance it read went, and its rendition with it. + Ended, } /// A per-rendition source that normalizes frame shape (Annex-B → @@ -97,6 +99,8 @@ pub(crate) struct ExportSource { ends: Option<(u64, u64)>, /// The counters the export source reports for this rendition, as received, before any transform. received: std::sync::Arc, + /// The sibling broadcast the rendition reads, once resolved: its end ends the rendition. + instance: Option, } impl ExportSource { @@ -184,6 +188,7 @@ impl ExportSource { cuts: 0, ends: None, received: source.received(name), + instance: None, }; source.resolve_video_dimensions(&[])?; Ok(Some(source)) @@ -222,6 +227,7 @@ impl ExportSource { cuts: 0, ends: None, received: source.received(name), + instance: None, })) } @@ -253,6 +259,7 @@ impl ExportSource { cuts: 0, ends: None, received: source.received(name), + instance: None, }) } @@ -364,19 +371,31 @@ impl ExportSource { /// Read normalized media or a clean group boundary. pub fn poll_event(&mut self, waiter: &kio::Waiter) -> Poll>> { + if matches!(self.state, SourceState::Ended) { + return Poll::Ready(Ok(None)); + } + // Resolve a cross-broadcast reference into a broadcast before subscribing. if matches!(self.state, SourceState::Requesting(..)) { - let (broadcast, name) = { + let (broadcast, name, sibling) = { let SourceState::Requesting(pending, name) = &self.state else { unreachable!("just matched Requesting"); }; - (ready!(pending.poll_broadcast(waiter))?, name.clone()) + (ready!(pending.poll_broadcast(waiter))?, name.clone(), pending.sibling()) }; + if sibling { + self.instance = Some(broadcast.clone()); + } let mut subscription = moq_net::track::Subscription::default().with_max_delay(self.max_delay); if let Some(start) = self.start { subscription = subscription.with_groups(start..); } - self.state = SourceState::Subscribing(broadcast.track(&name)?.subscribe(subscription)); + let track = match broadcast.track(&name) { + Ok(track) => track, + Err(_) if self.instance_ended(waiter) => return self.end(), + Err(err) => return Poll::Ready(Err(err.into())), + }; + self.state = SourceState::Subscribing(track.subscribe(subscription)); } // Resolve the subscription before reading any frames. @@ -386,7 +405,12 @@ impl ExportSource { let SourceState::Subscribing(pending) = &self.state else { unreachable!("just matched Subscribing"); }; - ready!(pending.poll_ok(waiter))? + match pending.poll_ok(waiter) { + Poll::Ready(Ok(track)) => track, + Poll::Ready(Err(_)) | Poll::Pending if self.instance_ended(waiter) => return self.end(), + Poll::Ready(Err(err)) => return Poll::Ready(Err(err.into())), + Poll::Pending => return Poll::Pending, + } }; let media = self .media @@ -407,7 +431,30 @@ impl ExportSource { let SourceState::Active(consumer) = &mut self.state else { unreachable!("subscription resolved into an Active consumer"); }; - match ready!(consumer.poll_item(waiter))? { + let item = match consumer.poll_item(waiter) { + Poll::Ready(Ok(item)) => item, + // Only an orderly shutdown of the instance is its end: malformed media or a + // failed transport still fails the export. The field, not `instance_ended`, so + // the borrow stays off the consumer. + Poll::Ready(Err(crate::Error::Moq( + moq_net::Error::Cancel + | moq_net::Error::Closed + | moq_net::Error::GoingAway + | moq_net::Error::SessionClosed + | moq_net::Error::Session(moq_net::SessionError::Cancel), + ))) + | Poll::Pending + if self + .instance + .as_ref() + .is_some_and(|instance| instance.poll_closed(waiter).is_ready()) => + { + return self.end(); + } + Poll::Ready(Err(err)) => return Poll::Ready(Err(err)), + Poll::Pending => return Poll::Pending, + }; + match item { Some(Item::Frame { group, frame, arrived }) => { if self.ends.is_some_and(|(end_group, _)| end_group != group) { self.finish_ends(); @@ -486,6 +533,23 @@ impl ExportSource { } } + /// Whether the sibling broadcast this rendition reads has stopped serving, registering + /// `waiter` for when it does. Its track stalling or failing then is that instance's end, + /// which ends the rendition rather than the export once what it delivered is read; following + /// the instance that replaces it is the export's own call. + fn instance_ended(&self, waiter: &kio::Waiter) -> bool { + self.instance + .as_ref() + .is_some_and(|instance| instance.poll_closed(waiter).is_ready()) + } + + /// End the rendition with its instance. + fn end(&mut self) -> Poll>> { + self.finish_ends(); + self.state = SourceState::Ended; + Poll::Ready(Ok(None)) + } + fn finish_ends(&mut self) { if let Some((_, count)) = self.ends.take() { self.skips += count; @@ -666,6 +730,158 @@ mod tests { } } + /// A sibling rendition's first announcement starts it, a replacement is never read, and its + /// instance going ends the rendition instead of failing the export, both mid-stream and + /// before the subscription resolves. + #[tokio::test(start_paused = true)] + async fn a_sibling_rendition_starts_late_and_ends_with_its_instance() { + use std::time::Duration; + + use crate::container::test_util::raw_frame; + + let origin = crate::source::produce_origin(); + let _catalog = origin.publish("a/pub", Default::default()).unwrap(); + tokio::task::yield_now().await; + let source = crate::source::resolved(&origin, "a/pub").await; + let config = audio(Some("./source")); + let mut export = ExportSource::for_audio(&source, "audio", &config, Duration::from_secs(10)) + .unwrap() + .unwrap(); + let mut read = async || { + tokio::time::timeout(Duration::from_millis(100), kio::wait(|waiter| export.poll_read(waiter))) + .await + .ok() + .map(|frame| frame.unwrap().map(|frame| frame.timestamp.as_micros())) + }; + let wire = || HangContainer::Legacy(crate::container::Kind::Audio); + let info = || hang::container::track_info(hang::catalog::PRIORITY.audio); + + assert_eq!(read().await, None, "nothing announces the sibling yet"); + let old = origin.publish("a/source", Default::default()).unwrap(); + let mut track = crate::container::Producer::new(old.create_track("audio", info()).unwrap(), wire()); + track.write(raw_frame(0, b"old", true)).unwrap(); + assert_eq!(read().await, Some(Some(0)), "the late announcement starts it"); + + let new = origin.publish("a/source", Default::default()).unwrap(); + let mut replacement = crate::container::Producer::new(new.create_track("audio", info()).unwrap(), wire()); + replacement.write(raw_frame(1_000_000, b"new", true)).unwrap(); + track.write(raw_frame(24_000, b"old", true)).unwrap(); + assert_eq!(read().await, Some(Some(24_000)), "the replacement is never read"); + + drop(old); + assert_eq!(read().await, Some(None), "its end ends the rendition"); + + // A rendition still subscribing when its instance goes ends too. + let mut late = ExportSource::for_audio(&source, "late", &config, Duration::from_secs(10)) + .unwrap() + .unwrap(); + let ended = tokio::time::timeout(Duration::from_secs(1), kio::wait(|waiter| late.poll_read(waiter))).await; + assert!( + matches!(ended, Ok(Ok(None))), + "{:?}", + ended.map(|read| read.map(|_| ())) + ); + drop((track, replacement, new)); + } + + /// A sibling's failure still fails the export when its instance goes, whether its media is + /// malformed, its track is aborted with a protocol error, or its producers went away + /// unfinished: only an orderly shutdown of the instance is the rendition's end. + #[tokio::test(start_paused = true)] + async fn a_sibling_failure_outlives_its_instance() { + use std::time::Duration; + + for failure in ["malformed", "violation", "dropped"] { + let origin = crate::source::produce_origin(); + let _catalog = origin.publish("a/pub", Default::default()).unwrap(); + tokio::task::yield_now().await; + let source = crate::source::resolved(&origin, "a/pub").await; + let config = audio(Some("./source")); + let mut export = ExportSource::for_audio(&source, "audio", &config, Duration::from_secs(10)) + .unwrap() + .unwrap(); + + let sibling = origin.publish("a/source", Default::default()).unwrap(); + let track = sibling + .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(); + // Subscribe before anything is written, so the failure and the instance's end arrive + // together. + let settle = tokio::time::timeout(Duration::from_millis(100), kio::wait(|waiter| export.poll_read(waiter))); + assert!(settle.await.is_err(), "nothing is written yet"); + let mut group = track.append_group().unwrap(); + let held = match failure { + "malformed" => { + // An empty Legacy audio frame is malformed. + group + .write_frame(moq_net::Timestamp::from_micros(0).unwrap(), bytes::Bytes::new()) + .unwrap(); + Some((group, track)) + } + "violation" => { + track.clone().abort(moq_net::Error::ProtocolViolation).unwrap(); + Some((group, track)) + } + _ => { + drop((group, track)); + None + } + }; + drop(sibling); + tokio::time::sleep(Duration::from_millis(10)).await; + assert!(export.instance_ended(&kio::Waiter::noop()), "the instance has gone"); + + let read = tokio::time::timeout(Duration::from_secs(1), kio::wait(|waiter| export.poll_read(waiter))) + .await + .expect("the read settles"); + assert!( + read.is_err(), + "{failure}: {:?}", + read.map(|frame| frame.map(|frame| frame.timestamp)) + ); + drop(held); + } + } + + /// A sibling served over a session ends the rendition cleanly when its publisher goes, which + /// the session reports as its own cancellation. + #[tokio::test(start_paused = true)] + async fn a_remote_sibling_ends_with_its_instance() { + use std::time::Duration; + + use crate::container::test_util::{Link, raw_frame}; + + let remote = crate::source::produce_origin(); + let origin = crate::source::produce_origin(); + let _catalog = origin.publish("a/pub", Default::default()).unwrap(); + tokio::task::yield_now().await; + let source = crate::source::resolved(&origin, "a/pub").await; + let _link = Link::new(&remote, &origin).await; + let sibling = remote.publish("a/source", Default::default()).unwrap(); + let mut track = crate::container::Producer::new( + sibling + .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(), + HangContainer::Legacy(crate::container::Kind::Audio), + ); + track.write(raw_frame(0, b"x", true)).unwrap(); + let mut export = ExportSource::for_audio(&source, "audio", &audio(Some("./source")), Duration::from_secs(10)) + .unwrap() + .unwrap(); + let mut read = async || { + tokio::time::timeout(Duration::from_secs(1), kio::wait(|waiter| export.poll_read(waiter))) + .await + .expect("the read settles") + .unwrap() + .map(|frame| frame.timestamp.as_micros()) + }; + assert_eq!(read().await, Some(0)); + + drop(sibling); + assert_eq!(read().await, None, "its end ends the rendition"); + drop(track); + } + /// The requested budget must be present on the first SUBSCRIBE, a live start's too. Updating /// it after SUBSCRIBE_OK cannot recover backlog the publisher already skipped, nor the groups a /// zero budget drops as superseded before the update lands. diff --git a/rs/moq-mux/src/follow.rs b/rs/moq-mux/src/follow.rs new file mode 100644 index 00000000000..9823777dd5d --- /dev/null +++ b/rs/moq-mux/src/follow.rs @@ -0,0 +1,237 @@ +//! Following a broadcast across the publisher instances that serve it. +//! +//! An announcement is the online and offline signal, so a reader that restarts on each instance +//! follows [`Instances`] rather than pinning one broadcast as a [`Binding`](crate::Binding) does. + +use std::task::Poll; + +/// The publisher instances serving a broadcast, as each comes online, takes over, and goes. +/// +/// Built on [`announced_broadcast`](moq_net::origin::Consumer::announced_broadcast). Create one +/// with [`Source::follow`](crate::Source::follow) for a catalog reference, or [`Instances::new`] +/// for a path. +pub struct Instances { + feed: Feed, + /// The instance a reference named, if any. + epoch: Option, + /// The instance handed out last, until it stops serving. + current: Option, +} + +enum Feed { + /// Every instance announced at a path. + Announced(Box), + /// One instance, handed out once. + Fixed(Option), +} + +/// A change to the instance [`Instances`] serves. +pub enum Event { + /// Start on this instance, dropping whatever was read from the one before. + Start(moq_net::broadcast::Consumer), + /// The instance handed out last stopped serving: idle until the next start. + End, +} + +impl Instances { + /// Follow the broadcast at `path` through `origin`, handing out only `epoch` when given. + /// + /// Unlike [`Source::follow`](crate::Source::follow), this needs no catalog broadcast, so a + /// reader can follow the broadcast whose catalog it reads and build a + /// [`Source`](crate::Source) for each instance. + pub fn new( + origin: &moq_net::origin::Consumer, + path: impl moq_net::AsPath, + epoch: Option<&moq_net::Epoch>, + ) -> crate::Result { + let announced = origin.announced_broadcast(path, None)?; + Ok(Self::with(Feed::Announced(Box::new(announced)), epoch)) + } + + /// Hand out `broadcast` once and never report its end, which its owner follows. + pub(crate) fn fixed(broadcast: moq_net::broadcast::Consumer) -> Self { + Self::with(Feed::Fixed(Some(broadcast)), None) + } + + fn with(feed: Feed, epoch: Option<&moq_net::Epoch>) -> Self { + Self { + feed, + epoch: epoch.cloned(), + current: None, + } + } + + /// Poll for the next change, registering `waiter` when there is none yet. + /// + /// Each announcement that brings an instance hands it out, so the same one returns after an + /// end. Fails once the origin closes, and with any resolution failure, such as a handler + /// refusing the path. + pub fn poll_next(&mut self, waiter: &kio::Waiter) -> Poll> { + loop { + let next = match &mut self.feed { + // Followed unpinned and checked here: a pinned follow waits out an epochless route, + // which an epoch reads best effort. + Feed::Announced(announced) => announced.poll_available(waiter).map_err(crate::Error::from), + Feed::Fixed(broadcast) => match broadcast.take() { + Some(broadcast) => Poll::Ready(Ok(broadcast)), + None => Poll::Pending, + }, + }; + if let Poll::Ready(next) = next { + let broadcast = next?; + if crate::source::check_epoch(self.epoch.as_ref(), &broadcast).is_err() { + tracing::debug!(path = %broadcast.info().path, "skipping an instance of another epoch"); + match self.current.take() { + Some(_) => return Poll::Ready(Ok(Event::End)), + None => continue, + } + } + // A fixed instance ends with its owner, which follows that itself. + if let Feed::Announced(_) = self.feed { + self.current = Some(broadcast.clone()); + } + return Poll::Ready(Ok(Event::Start(broadcast))); + } + + if let Some(current) = &self.current + && current.poll_closed(waiter).is_ready() + { + self.current = None; + return Poll::Ready(Ok(Event::End)); + } + return Poll::Pending; + } + } + + /// The next change; see [`Self::poll_next`]. + pub async fn next(&mut self) -> crate::Result { + kio::wait(|waiter| self.poll_next(waiter)).await + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::source::{produce_origin, resolved}; + use moq_net::path::Relative; + + /// Let the origin's driver run the fronts that announcements started. + async fn settle() { + for _ in 0..10 { + tokio::task::yield_now().await; + } + } + + fn route(epoch: &moq_net::Epoch) -> moq_net::origin::Route { + moq_net::origin::Route::default().with_epoch(epoch.clone()) + } + + /// The next change a follower reports, which must arrive within the origin's update hold. + async fn followed(follow: &mut Instances) -> Option { + let next = tokio::time::timeout(std::time::Duration::from_secs(1), follow.next()) + .await + .expect("no change") + .expect("the follow failed"); + match next { + Event::Start(broadcast) => Some(broadcast), + Event::End => None, + } + } + + /// The follower stays quiet past the origin's update hold. + async fn quiet(follow: &mut Instances) { + if tokio::time::timeout(std::time::Duration::from_secs(1), follow.next()) + .await + .is_ok() + { + panic!("expected no change"); + } + } + + /// A sibling announced after the follow starts it, its end idles it, and its return starts + /// it again. + #[tokio::test(start_paused = true)] + async fn a_follow_starts_late_and_survives_an_end() { + let origin = produce_origin(); + let _catalog = origin.publish("a/pub", Default::default()).unwrap(); + settle().await; + let source = resolved(&origin, "a/pub").await; + let mut follow = source.follow(Some(&Relative::new("./source")), None).unwrap(); + quiet(&mut follow).await; + + let first = origin.publish("a/source", Default::default()).unwrap(); + let started = followed(&mut follow).await.expect("a start"); + assert_eq!(started.info().path.as_str(), "a/source"); + + drop(first); + assert!(followed(&mut follow).await.is_none(), "an end"); + quiet(&mut follow).await; + + let _second = origin.publish("a/source", Default::default()).unwrap(); + let restarted = followed(&mut follow).await.expect("a start"); + assert!(!restarted.is_clone(&started)); + } + + /// A replacement restarts a reference that names no epoch, and ends one that names the old + /// instance until that instance serves again. + #[tokio::test(start_paused = true)] + async fn a_follow_restarts_only_without_an_epoch() { + let origin = produce_origin(); + let (old_epoch, new_epoch) = (moq_net::Epoch::mint(), moq_net::Epoch::mint()); + let _catalog = origin.publish("a/pub", Default::default()).unwrap(); + let _old = origin.publish("a/source", route(&old_epoch)).unwrap(); + settle().await; + let source = resolved(&origin, "a/pub").await; + let rel = Relative::new("./source"); + let mut any = source.follow(Some(&rel), None).unwrap(); + let mut named = source.follow(Some(&rel), Some(&old_epoch)).unwrap(); + let old = followed(&mut any).await.unwrap(); + assert!(followed(&mut named).await.unwrap().is_clone(&old)); + + let new = origin.publish("a/source", route(&new_epoch)).unwrap(); + let replaced = followed(&mut any).await.unwrap(); + assert_eq!(replaced.info().epoch.as_ref(), Some(&new_epoch)); + assert!(followed(&mut named).await.is_none(), "another epoch ends it"); + quiet(&mut named).await; + // The old instance still serves the subscriptions already on it. + assert!(!old.is_closed()); + + // The replacement goes and the old instance wins again. + drop(new); + let back = followed(&mut named).await.unwrap(); + assert_eq!(back.info().epoch.as_ref(), Some(&old_epoch)); + let back = followed(&mut any).await.unwrap(); + assert_eq!(back.info().epoch.as_ref(), Some(&old_epoch)); + } + + /// An epoch is best effort over an epochless route, which cannot prove another instance. + #[tokio::test(start_paused = true)] + async fn a_follow_reads_an_epochless_route_with_an_epoch() { + let origin = produce_origin(); + let _catalog = origin.publish("a/pub", Default::default()).unwrap(); + settle().await; + let source = resolved(&origin, "a/pub").await; + let mut named = source + .follow(Some(&Relative::new("./source")), Some(&moq_net::Epoch::mint())) + .unwrap(); + let _sibling = origin.publish("a/source", Default::default()).unwrap(); + assert!(followed(&mut named).await.is_some()); + } + + /// A self-reference reads only the catalog instance, whatever replaces it at the path. + #[tokio::test(start_paused = true)] + async fn a_follow_of_the_catalog_keeps_its_instance() { + let origin = produce_origin(); + let old = origin.publish("a/pub", Default::default()).unwrap(); + settle().await; + let source = resolved(&origin, "a/pub").await; + let mut follow = source.follow(Some(&Relative::new("./pub")), None).unwrap(); + assert!(followed(&mut follow).await.unwrap().is_clone(&source.broadcast())); + + let _new = origin.publish("a/pub", Default::default()).unwrap(); + quiet(&mut follow).await; + // Its end is the catalog's, which the catalog's reader sees. + drop(old); + quiet(&mut follow).await; + } +} diff --git a/rs/moq-mux/src/lib.rs b/rs/moq-mux/src/lib.rs index 879e436fbec..e76649e1859 100644 --- a/rs/moq-mux/src/lib.rs +++ b/rs/moq-mux/src/lib.rs @@ -28,6 +28,8 @@ //! record per aligned segment, mapping a span of content time to the group //! ranges that carry it on each track, so consumers can seek or build //! HLS/DASH playlists without downloading media. +//! - [`follow`] follows a broadcast across the publisher instances that +//! serve it, for a reader that restarts on each one. pub mod binary; pub mod catalog; @@ -35,6 +37,7 @@ mod clock; pub mod codec; pub mod container; mod error; +pub mod follow; pub mod import; mod jitter; pub mod json; diff --git a/rs/moq-mux/src/source.rs b/rs/moq-mux/src/source.rs index c64a28c44d0..2a760037abf 100644 --- a/rs/moq-mux/src/source.rs +++ b/rs/moq-mux/src/source.rs @@ -23,12 +23,16 @@ type Pins = Arc> /// reference. Build one with [`Source::new`]. /// /// A source serves its own path from the broadcast it was built from, and keeps the first -/// broadcast it resolves for each sibling. Every later request for a path is served from that -/// handle ([`broadcast`](Self::broadcast), [`catalog`](Self::catalog), -/// [`resolve`](Self::resolve), [`bind`](Self::bind), [`subscribe_track`](Self::subscribe_track), -/// and an export's track requests). A route replaced after that is never resolved, epoch or -/// not, so two publishers never splice into one export; a request on a held broadcast that has -/// ended fails instead. Clones share the held broadcasts. +/// broadcast it resolves for each sibling, waiting for the sibling's first announcement if +/// nothing serves it yet. Every later request for a path is served from that handle +/// ([`broadcast`](Self::broadcast), [`catalog`](Self::catalog), [`resolve`](Self::resolve), +/// [`bind`](Self::bind), [`subscribe_track`](Self::subscribe_track), and an export's track +/// requests). A route replaced after that is never resolved, epoch or not, so two publishers +/// never splice into one export; a request on a held broadcast that has ended fails instead of +/// waiting for the next one. Clones share the held broadcasts. +/// +/// A reader that follows a sibling's announcements instead, restarting on each new instance, +/// uses [`follow`](Self::follow), which holds nothing. /// /// A reference may name the instance it expects with an epoch (the catalog's optional `epoch` /// beside `broadcast`). A held or resolved broadcast serving another epoch fails that reference @@ -133,22 +137,28 @@ impl Source { Binding::new(self.broadcast()) } - /// The broadcast `path` is pinned to, or a lookup that pins its answer, either checked - /// against `epoch` on every read. + /// The broadcast `path` is pinned to, or a lookup that waits for the path's first + /// announcement and pins its answer, either checked against `epoch` on every read. fn request_path(&self, path: &moq_net::PathOwned, epoch: Option<&moq_net::Epoch>) -> Binding { let bound = match self.pins.lock().expect("pins poisoned").get(path) { Some(pinned) => Bound::Ready(pinned.clone()), // Unpinned even with an epoch: an epochless route still answers, best effort, and // the read refuses a route that proves another instance. - None => Bound::Requested { - lookup: Box::new(Mutex::new(Lookup::new(&self.origin, path))), - pins: self.pins.clone(), - path: path.clone(), - }, + None => { + let mut routing = self.origin.routed_broadcast(path).into_inner(); + // Issue the request now: a handler answers it whether or not anyone reads yet. + let _ = kio::Task::poll(&mut routing, &kio::Waiter::noop()); + Bound::Requested { + routing: Box::new(Mutex::new(routing)), + pins: self.pins.clone(), + path: path.clone(), + } + } }; Binding { bound, epoch: epoch.cloned(), + sibling: *path != self.path, } } @@ -230,9 +240,10 @@ impl Source { /// /// `rel` is a rendition's catalog `broadcast` field: `None` (or an empty reference) /// resolves the catalog broadcast itself; anything else fetches the referenced - /// broadcast from the origin. `epoch` is the rendition's `epoch` field, the instance the - /// broadcast must be (see [`Source`]). Use it when you need the broadcast handle itself - /// (e.g. to FETCH individual groups) rather than a subscription. + /// broadcast from the origin, waiting for its first announcement if nothing serves it yet. + /// `epoch` is the rendition's `epoch` field, the instance the broadcast must be (see + /// [`Source`]). Use it when you need the broadcast handle itself (e.g. to FETCH individual + /// groups) rather than a subscription. /// /// A reference that escapes above the origin root is /// [`Error::EscapingBroadcast`](crate::Error::EscapingBroadcast): the rendition names @@ -248,10 +259,10 @@ impl Source { /// Start one broadcast request now and retain its result for repeated reads. /// /// Unlike [`resolve`](Self::resolve), this issues the request without awaiting or polling. - /// A remote or dynamic handler may answer later. A client session that only discovers - /// what is watched is asked about the path first, and the request goes out once it - /// answers. The binding never retries a failed request - /// or resolves the path again after a publisher is replaced. + /// A path nothing announces yet resolves once something does, and a remote or dynamic + /// handler may answer later. A client session that only discovers what is watched is asked + /// about the path while the binding waits. Once answered, the binding never resolves the path again, even + /// after its publisher is replaced or goes; [`follow`](Self::follow) does. /// /// A path this source already resolved binds to that broadcast; otherwise the origin is /// asked, deduplicating repeat requests for one path so the catalog and every rendition share @@ -272,8 +283,9 @@ impl Source { /// awaiting SUBSCRIBE_OK. /// /// `rel` is a rendition's catalog `broadcast` field: `None` (or an empty reference) - /// subscribes on the catalog broadcast; anything else fetches the referenced broadcast - /// from the origin first, checked against `epoch` as in [`resolve`](Self::resolve). A + /// subscribes on the catalog broadcast; anything else is resolved as in + /// [`resolve`](Self::resolve), waiting for its first announcement and checked against + /// `epoch`. A /// reference that escapes above the origin root is /// [`Error::EscapingBroadcast`](crate::Error::EscapingBroadcast). /// @@ -289,28 +301,79 @@ impl Source { let broadcast = self.bind(rel, epoch)?.broadcast().await?; Ok(broadcast.track(name)?.subscribe(None).await?) } + + /// Follow the broadcast a rendition's reference names across its announcements. + /// + /// Holds nothing: each instance serving a sibling is handed out as it comes online or takes + /// over, and its end is reported, so a reader restarts the rendition on each one. A + /// reference to the catalog broadcast itself hands out only the instance this source was + /// built from and never reports its end, since a reader follows its catalog's own end and + /// restarts by building a new source. + /// + /// With an `epoch`, only that instance (or an epochless route, which cannot prove another + /// one) is handed out: another taking over ends the rendition rather than substituting for + /// it. A self-reference whose epoch the catalog instance contradicts fails with + /// [`Error::EpochMismatch`](crate::Error::EpochMismatch), since no other instance can come. + /// Rejects an escaping reference exactly as [`resolve`](Self::resolve) does. + pub fn follow( + &self, + rel: Option<&moq_net::path::Relative<'_>>, + epoch: Option<&moq_net::Epoch>, + ) -> crate::Result { + let path = self.target(rel)?; + Ok(match path == self.path { + true => { + let broadcast = self.broadcast(); + check_epoch(epoch, &broadcast)?; + crate::follow::Instances::fixed(broadcast) + } + false => crate::follow::Instances::new(&self.origin, &path, epoch)?, + }) + } +} + +/// Fail with [`Error::EpochMismatch`](crate::Error::EpochMismatch) when `broadcast` is proven to +/// be another instance than `epoch` names. An epochless route cannot prove its instance, so only +/// a known mismatch fails. +pub(crate) fn check_epoch( + epoch: Option<&moq_net::Epoch>, + broadcast: &moq_net::broadcast::Consumer, +) -> crate::Result<()> { + let info = broadcast.info(); + match (epoch, &info.epoch) { + (Some(expected), Some(actual)) if expected != actual => Err(crate::Error::EpochMismatch { + path: info.path.to_string(), + expected: expected.clone(), + actual: actual.clone(), + }), + _ => Ok(()), + } } /// A held broadcast or the retained result of one eagerly issued broadcast request. /// -/// Reading the binding never looks up its path again, even after a failure or publisher -/// replacement. Pending requests follow the origin's routing semantics; issuing a request -/// does not establish an epoch relationship with a separate catalog broadcast. A binding made -/// with an epoch refuses a broadcast proven to serve another one. +/// A pending request waits for a path nothing announces yet and rides out route churn until it +/// resolves (see [`routed_broadcast`](moq_net::origin::Consumer::routed_broadcast)). Once the +/// path is pinned, reading the binding answers that pin and never looks the path up again, even +/// after its publisher is replaced or goes. Issuing a request does not establish an epoch +/// relationship with a separate catalog broadcast. A binding made with an epoch refuses a +/// broadcast proven to serve another one. /// /// Build one with [`Source::bind`], or with [`Binding::new`] for a broadcast already in hand. pub struct Binding { bound: Bound, /// The instance the reference named, if any. epoch: Option, + /// The reference names another broadcast than the catalog's. + sibling: bool, } enum Bound { /// A broadcast the caller already holds. Ready(moq_net::broadcast::Consumer), - /// A lookup started when the binding was made. + /// A request issued when the binding was made, resolved once something announces the path. Requested { - lookup: Box>, + routing: Box>, /// Where the answer is pinned, the first for its path winning. pins: Pins, path: moq_net::PathOwned, @@ -323,36 +386,40 @@ impl Binding { Self { bound: Bound::Ready(broadcast), epoch: None, + sibling: false, } } + /// Whether the reference names another broadcast than the catalog's. + pub(crate) fn sibling(&self) -> bool { + self.sibling + } + /// Poll for the bound broadcast without blocking. /// /// Concurrent polls and cancelled waits retain the same request and result. pub fn poll_broadcast(&self, waiter: &kio::Waiter) -> Poll> { let broadcast = match &self.bound { Bound::Ready(broadcast) => broadcast.clone(), - Bound::Requested { lookup, pins, path } => { - let broadcast = ready!(lookup.lock().expect("lookup poisoned").poll(waiter))?; - // A request that raced another for the path takes the one pinned first. The path's - // first answer is pinned even when it fails this binding's epoch, so no later - // reference resolves the path independently. - let mut pins = pins.lock().expect("pins poisoned"); - pins.entry(path.clone()).or_insert(broadcast).clone() + Bound::Requested { routing, pins, path } => { + // Once a path is pinned, its pin is the answer: a request that raced another for + // the path takes the one pinned first, and the routing is never polled again, since + // it would wait out the gap after the pinned instance goes. + if let Some(pinned) = pins.lock().expect("pins poisoned").get(path) { + pinned.clone() + } else { + let broadcast = { + let mut routing = routing.lock().expect("routing poisoned"); + ready!(kio::Task::poll(&mut *routing, waiter))? + }; + // The path's first answer is pinned even when it fails this binding's epoch, so + // no later reference resolves the path independently. + let mut pins = pins.lock().expect("pins poisoned"); + pins.entry(path.clone()).or_insert(broadcast).clone() + } } }; - // An epochless route cannot prove its instance, so only a known mismatch fails. - let info = broadcast.info(); - if let (Some(expected), Some(actual)) = (&self.epoch, &info.epoch) - && expected != actual - { - return Poll::Ready(Err(crate::Error::EpochMismatch { - path: info.path.to_string(), - expected: expected.clone(), - actual: actual.clone(), - })); - } - Poll::Ready(Ok(broadcast)) + Poll::Ready(check_epoch(self.epoch.as_ref(), &broadcast).map(|()| broadcast)) } /// The bound broadcast, awaiting the origin's answer when it hasn't arrived yet. @@ -363,76 +430,6 @@ impl Binding { } } -/// One request for a path, made once the origin has heard whether anything serves it. -/// -/// A client session only asks its peer about paths something watches, so a sibling no -/// listing covers would be unroutable when asked at once. Following the path first and -/// asking once a route serves it, or once every session has synced without one, answers -/// from what the peers announce. An origin that already knows its routes answers at once, -/// so the request still goes out on binding. -struct Lookup { - origin: moq_net::origin::Consumer, - path: moq_net::PathOwned, - /// Dropped once the request settles: a broadcast resolved through a discovered route - /// keeps its own path watched. - watch: Option, - request: Option, -} - -impl Lookup { - fn new(origin: &moq_net::origin::Consumer, path: &moq_net::PathOwned) -> Self { - // A path no pattern can spell, or one outside the scope, fails on the request instead. - let watch = origin.follow(path).ok(); - let mut lookup = Self { - origin: origin.clone(), - path: path.clone(), - watch, - request: None, - }; - // Ask now when the origin already knows, so a dynamic handler hears it on binding. - let _ = lookup.poll(&kio::Waiter::noop()); - lookup - } - - fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { - loop { - if self.request.is_none() { - if let Some(watch) = &mut self.watch { - // The follower reduces the covering routes to the one serving the path, so its - // latest event is whether a route serves it now. Ask as soon as one does: - // waiting for every session to sync would let one that never answers hold the - // lookup up. Without a route, only sync concludes that none will. - let mut routed = false; - loop { - match watch.poll_next(waiter) { - Poll::Ready(Some(moq_net::announce::Event::End(_))) => routed = false, - Poll::Ready(Some(_)) => routed = true, - Poll::Ready(None) | Poll::Pending => break, - } - } - if !routed { - ready!(watch.poll_synced(waiter)); - } - } - self.request = Some(self.origin.request_broadcast(&self.path, None).into_inner()); - } - let result = ready!(self.request.as_ref().expect("requested above").poll_ok(waiter)); - // The route can retract between the follower reporting it and the request reading - // the table. Until every session has synced, keep following for another. - let unsynced = self - .watch - .as_ref() - .is_some_and(|watch| watch.poll_synced(&kio::Waiter::noop()).is_pending()); - if matches!(result, Err(moq_net::Error::Unroutable)) && unsynced { - self.request = None; - continue; - } - self.watch = None; - return Poll::Ready(result); - } - } -} - /// Test helper: build an origin producer, spawning its driver on the ambient runtime. #[cfg(test)] pub(crate) fn produce_origin() -> moq_net::origin::Producer { @@ -524,20 +521,41 @@ mod tests { assert!(first.is_clone(&binding.broadcast().await.unwrap())); } - /// A failed lookup pins nothing: the guarantee starts at a path's first resolution. - #[tokio::test] - async fn failed_binding_does_not_retry_a_later_publisher() { + /// A binding made before anything announces its sibling resolves on the first announcement + /// and keeps that instance: past its replacement, and once it goes, answering the ended + /// instance at once rather than waiting for the next one. + #[tokio::test(start_paused = true)] + async fn a_binding_waits_for_the_first_announcement_and_keeps_it() { let origin = produce_origin(); let _catalog = origin.publish("pub", Default::default()).unwrap(); settle().await; let source = resolved(&origin, "pub").await; let media = Relative::new("media"); let binding = source.bind(Some(&media), None).unwrap(); - assert!(binding.broadcast().await.is_err()); - let _publisher = origin.publish("media", Default::default()).unwrap(); settle().await; - assert!(!source.resolve(Some(&media), None).await.unwrap().is_closed()); - assert!(binding.broadcast().await.is_err()); + assert!(binding.poll_broadcast(&kio::Waiter::noop()).is_pending()); + + let first_publisher = origin.publish("media", Default::default()).unwrap(); + let first = binding.broadcast().await.unwrap(); + assert!(!first.is_closed()); + + let _second = origin.publish("media", Default::default()).unwrap(); + settle().await; + assert!(binding.broadcast().await.unwrap().is_clone(&first)); + assert!(source.resolve(Some(&media), None).await.unwrap().is_clone(&first)); + + drop(first_publisher); + first.closed().await; + assert!(binding.broadcast().await.unwrap().is_clone(&first)); + let late = source.bind(Some(&media), None).unwrap(); + assert!( + late.broadcast().await.unwrap().is_clone(&first), + "a later binding reads the pin" + ); + + // A new catalog instance starts fresh pins, which resolve the replacement. + let fresh = source.switched(&source.broadcast()); + assert!(!fresh.resolve(Some(&media), None).await.unwrap().is_closed()); } /// A source serves its path from the broadcast it was built from, even when a replacement @@ -729,6 +747,11 @@ mod tests { let own = source.resolve(rel.as_ref(), Some(&catalog)).await.unwrap(); assert!(own.is_clone(&source.broadcast()), "{reference:?}"); assert!(is_mismatch(source.resolve(rel.as_ref(), Some(&other)).await, &other)); + assert!(source.follow(rel.as_ref(), Some(&catalog)).is_ok()); + assert!(matches!( + source.follow(rel.as_ref(), Some(&other)), + Err(crate::Error::EpochMismatch { .. }) + )); } } diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 8c55896b050..7ec001fad12 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +Resolving a rendition's `broadcast` reference, through `BroadcastConsumer.resolve(_:epoch:)` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, bound the call yourself: cancel the task. + ### JSON snapshot `deltaRatio` is `deltas` `Json.SnapshotProducer(deltaRatio:)` and `MoqJsonSnapshotConfig.deltaRatio` are replaced by `deltas: Bool` (default `true`). diff --git a/swift/ffi/MIGRATE.md b/swift/ffi/MIGRATE.md index e50bf21fcd7..f27cf7ce292 100644 --- a/swift/ffi/MIGRATE.md +++ b/swift/ffi/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A broadcast reference waits for its sibling's announcement (#6254) + +Resolving a rendition's `broadcast` reference, through `MoqBroadcastConsumer.resolve(reference:epoch:)` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced. +Where you skipped such a rendition on that error, bound the call yourself: cancel the task. +Regenerate the bindings for the changed `resolve` checksum. + ### A client asks only about what it watches (#6165) On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announcedBroadcast()`, instead of under its whole scope at connect.