From 6543828e660a617ee0296a92213acbb9424e5f50 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 4 Oct 2026 20:41:24 -0700 Subject: [PATCH 1/5] quest: claim broadcast-epoch/origin Co-Authored-By: Claude Opus 5.5 From 1cc9c1ef42a7464e7b4e8e3d29b3fa3a99ba7c68 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 4 Oct 2026 21:33:38 -0700 Subject: [PATCH 2/5] feat(net): bare names follow their newest epoch A request for a bare name no route covers resolves to the greatest name/@ a route serves, in Rust and JS. The Rust front follows that one epoch and resets its tracks with Unroutable once the name resolves elsewhere; JS swaps the request's active broadcast. A grant admitting a name also admits its epochs. Publishing mints no epoch by default; Path::mint_epoch / Path.mintEpoch make it one call. Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/auth.md | 6 +- doc/concept/moq-lite.md | 31 +- doc/lib/js/net.md | 5 +- doc/lib/rs/moq-net.md | 2 +- drafts/draft-lcurley-moq-lite.md | 11 + js/net/src/origin.test.ts | 104 ++++++ js/net/src/origin.ts | 100 ++++- js/net/src/path.test.ts | 17 +- js/net/src/path.ts | 5 + quest/m0/broadcast-epoch/README.md | 43 ++- quest/m0/broadcast-epoch/apps.md | 15 +- quest/m0/broadcast-epoch/bindings.md | 9 +- quest/m0/broadcast-epoch/gateways.md | 6 +- quest/m0/broadcast-epoch/gst.md | 9 +- quest/m0/broadcast-epoch/hop-removal.md | 9 +- quest/m0/broadcast-epoch/origin.md | 53 --- quest/m0/broadcast-epoch/ts-restart.md | 8 +- quest/m1/obs-epoch.md | 6 +- rs/moq-net/benches/origin.rs | 38 ++ rs/moq-net/src/model/origin.rs | 465 +++++++++++++++++++++--- rs/moq-net/src/path/mod.rs | 5 + rs/moq-relay/tests/auth_embedder.rs | 46 +++ 22 files changed, 803 insertions(+), 190 deletions(-) delete mode 100644 quest/m0/broadcast-epoch/origin.md diff --git a/doc/bin/relay/auth.md b/doc/bin/relay/auth.md index 5b624bc8743..58d1cab9f36 100644 --- a/doc/bin/relay/auth.md +++ b/doc/bin/relay/auth.md @@ -122,8 +122,10 @@ only. There is no shared secret. **Patterns.** A grant is any pattern union and means exactly what it says: `foo/**` is a subtree, a bare `foo` is that one broadcast, `live/*` is every broadcast one segment under `live`, and `room/*/chat` is each room's chat and -nothing beside it. The relay announces, publishes, and resolves only the paths -inside the grant. Announcements travel by literal head on the wire, so a +nothing beside it. A pattern that admits a name also admits its +[epochs](/concept/moq-lite#publisher-epochs) (`foo/@`), while a grant +on one epoch reaches only that epoch. The relay announces, publishes, and +resolves only the paths inside the grant. Announcements travel by literal head on the wire, so a non-prefix grant is filtered locally on each side while the announced route stays a prefix on every protocol version. diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 6f906db54f9..58aeffc5fce 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -138,7 +138,10 @@ An application can identify each publisher instance with a shared `Epoch` from `moq-net` or `@moq/net`. It is a lowercase hyphenated UUIDv7, ordered newest last, with its wall-clock creation time available as `Epoch::time()` in Rust or `Epoch.time(epoch)` in TypeScript. Minting is explicit; publishing does not -add an epoch automatically. +add an epoch automatically. A publisher that may restart publishes each run +under a fresh one, so a restart is a new broadcast rather than a reused name: +`path.mint_epoch()` in Rust and `Path.mintEpoch(path)` in TypeScript append a +freshly minted epoch. The epoch segment counts toward the 32-part path limit. `Path::join_epoch(Some(&epoch))` and `Path.joinEpoch(name, epoch)` append an `@` segment. `Path::split_epoch()` and `Path.splitEpoch(path)` return @@ -147,9 +150,29 @@ count: `@alice`, bare UUIDs, uppercase UUIDs, and other UUID versions remain ordinary path segments. Existing path normalization still applies. The segment travels as part of the ordinary broadcast path on every supported -wire version. Pattern grants still match the full path: `room/**` covers an -epoch-qualified instance, while `room/camera` is an exact name. Epochs do not -hide a broadcast; a leading `.` in a name segment still does. +wire version. Epochs do not hide a broadcast; a leading `.` in a name segment +still does. + +A request for a bare name that no route covers resolves to its newest epoch: +the greatest `name/@` with a live route. The broadcast is still named +`name`, so a catalog's relative references resolve against the name. When the +name resolves elsewhere (a newer epoch, an older one once the newest is +retracted, or a route covering the name itself), a Rust origin ends the +broadcast and resets its tracks with `Unroutable`, and the next request lands +on the new resolution; it never splices one epoch into another. In TypeScript +the request's `active` broadcast swaps to the new one. A path naming an epoch +pins it and never moves. A relay resolves bare requests this way for every +client and protocol version, so an older client subscribing by name keeps +working, provided it resubscribes after an `Unroutable` reset. A relay without this support routes +`name/@` but never resolves bare `name`, since a route covers its +descendants, not its parent: a bare-name viewer behind one needs a publisher +that publishes the bare name itself. + +A grant that admits a name also admits its epochs: an exact `room/camera` +grant reaches `room/camera/@` for publishing and subscribing, and +`room/**` covers both. A grant on one epoch reaches only that epoch, never the +bare name or a sibling. The widening is a `room/camera/@*` pattern, so any +single `@`-prefixed segment below the name is admitted, not only UUIDv7 text. ### Hidden broadcasts diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index aae825f85f4..1b71d41c503 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -9,8 +9,9 @@ description: The pub/sub layer in TypeScript The TypeScript twin of [`moq-net`](/lib/rs/moq-net): connections, origins, broadcasts, tracks, groups, and frames, negotiating moq-lite or moq-transport -at setup. `Epoch` provides the shared publisher identity, and `Path.splitEpoch` -and `Path.joinEpoch` carry it in the broadcast path; see +at setup. `Epoch` provides the shared publisher identity, and `Path.mintEpoch`, +`Path.splitEpoch`, and `Path.joinEpoch` carry it in the broadcast path; a +request for the bare name follows the newest epoch. See [publisher epochs](/concept/moq-lite#publisher-epochs). ```ts diff --git a/doc/lib/rs/moq-net.md b/doc/lib/rs/moq-net.md index 5fa5089f8b7..2d237dc0d0e 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -17,7 +17,7 @@ above ([hang](/lib/rs/hang)); relays and CDNs implement only this. - **Origins** scope what a session can see, and merge duplicate subscriptions so a broadcast is pulled upstream once no matter how many local readers. - **Broadcasts** are created unannounced and invisible to everyone, then announced as an exact route, or served below a prefix with `dynamic`. A consumer of the same origin sees exactly what a peer sees. Discovery accepts pattern unions; events carry the advertised prefix and captures for a complete match. -- **Epochs** identify publisher instances with a canonical UUIDv7 and explicit path helpers; see [publisher epochs](/concept/moq-lite#publisher-epochs). +- **Epochs** identify publisher instances with a canonical UUIDv7 and explicit path helpers (`Path::mint_epoch`), and a request for the bare name follows the newest one; see [publisher epochs](/concept/moq-lite#publisher-epochs). - **Patterns** (`Pattern`, `Patterns`) are re-exported from [`moq-pattern`](https://docs.rs/moq-pattern). Literal `Path` stays a coordinate. - **Tracks** carry groups with a priority, an optional publisher retention window (`Info::max_age`), and a timescale. Subscribers set their own priority and max age and can change them live. - **Groups** are written frame by frame and delivered on independent streams. Old groups are cached for fetch-by-sequence; stale groups are skipped per the subscriber's budget. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 4b6b6ff6876..99192d82ea1 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -453,6 +453,16 @@ A receiver that has spent its re-resolution, or has nothing to spend it on, MUST Every other code, and any unrecognized one, is terminal and propagates without re-resolution, so probing unserved paths costs one round trip per path. A receiver SHOULD NOT cache refusals; rate limiting is the advertiser's concern. +#### Epochs {#epochs} +A path whose final segment is `@` followed by a lowercase hyphenated UUIDv7 names one epoch of the path before it, its name. +A publisher that may restart SHOULD publish each run under a fresh epoch, so a restart is a new Broadcast rather than a reused path. +The segment is ordinary path text on the wire. + +A request for a path naming no epoch that no route covers resolves to the greatest epoch one segment below it that a route covers; UUIDv7 text orders by creation time. +When the path later resolves elsewhere (a newer epoch, an older one once the newest is retracted, or a route covering the path), the receiver MUST reset the request with UNROUTABLE rather than move it to a different Broadcast, and a repeated request resolves afresh. +A request naming an epoch never moves. +This is receiver behavior on every version: a receiver without it finds no route covering the path, and the request is unroutable. + ### Subscribe A subscriber opens Subscribe Streams to request a Track. @@ -1372,6 +1382,7 @@ The `Message Length` describes the payload size on the wire. - Added announce compression: ANNOUNCE_START gains `Path Base` and `Path Keep` to copy the head of a live advertisement's suffix, and ANNOUNCE_START and ANNOUNCE_UPDATE gain `Hop Base` and `Hop Keep` to copy the tail of a live advertisement's Hop ID list. - Capped the SETUP Message Length at 65,536 bytes. - A relay puts a random Hop ID, picked per session, in front of an announcement whose reconstructed path starts with 0, and writes that stamp followed by 0 for an empty path. +- Specified epochs: a final `@` segment names one run of a path, a request for an uncovered name resolves to its newest covered epoch, and a request that would move to another epoch is reset with UNROUTABLE. ## moq-lite-06 diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index 7f29e489693..233f6c180c5 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -1796,3 +1796,107 @@ test("broadcast handles carry the path they were created or requested at", async broadcast.close(); origin.close(); }); + +/** Two epochs of `room/alice` in mint order, older first. */ +const OLD = Path.from("room/alice/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f"); +const NEW = Path.from("room/alice/@0199b7f4-3c2b-7d1e-9f0b-2b6c1a9d8e7f"); + +test("a bare name follows its newest epoch and falls back to an older one", async () => { + const origin = new Producer(); + const consumer = origin.consume(); + const bare = Path.from("room/alice"); + expect(wireOf(consumer).routes(bare)).toBe(false); + + const old = publish(origin, OLD); + expect(wireOf(consumer).routes(bare)).toBe(true); + const request = consumer.request(bare, { announced: true }); + const pinned = consumer.request(OLD); + const first = request.active.peek(); + expect(first).toBeDefined(); + // Named as asked, so a catalog's relative references resolve against the name. + expect(first?.path).toBe(bare); + + // A newer epoch is a new broadcast to the follower; the pinned request stays. + const next = publish(origin, NEW); + const second = request.active.peek(); + expect(second).toBeDefined(); + expect(second).not.toBe(first); + expect(second?.path).toBe(bare); + expect(pinned.active.peek()?.closed.peek()).toBeUndefined(); + + // Retracting the newest falls back to the older epoch still live. + next.close(); + await settle(); + const third = request.active.peek(); + expect(third).toBeDefined(); + expect(third).not.toBe(second); + + old.close(); + await settle(); + expect(request.active.peek()).toBeUndefined(); + + request.close(); + pinned.close(); + origin.close(); +}); + +test("a received epoch serves a bare request through its session", async () => { + const origin = new Producer(); + const consumer = origin.consume(); + const upstream = new BroadcastProducer(); + const asked: Path.Valid[] = []; + const handle = wireOf(origin).receive(NEW, Route.default); + void (async () => { + for await (const request of handle.requested()) { + asked.push(request.path); + request.accept(upstream.consume()); + } + })(); + + const request = consumer.request(Path.from("room/alice")); + await settle(); + expect(request.active.peek()).toBeDefined(); + // The session is asked for the epoch, never the bare name. + expect(asked).toEqual([NEW]); + + request.close(); + handle.close(); + upstream.close(); + origin.close(); +}); + +test("a route covering the name beats its epochs", async () => { + const origin = new Producer(); + const consumer = origin.consume(); + const epoch = publish(origin, NEW); + const raw = publish(origin, Path.from("room/alice")); + + const request = consumer.request(Path.from("room/alice")); + const active = request.active.peek(); + const own = consumer.request(Path.from("room/alice")); + expect(active?.path).toBe(Path.from("room/alice")); + raw.close(); + await settle(); + expect(request.active.peek()).not.toBe(active); + expect(request.active.peek()).toBeDefined(); + + own.close(); + request.close(); + epoch.close(); + origin.close(); +}); + +test("a grant on a name admits its epochs and a grant on an epoch only that one", () => { + const origin = new Producer(); + const exact = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.literal("room/alice")])); + const broadcast = publish(exact, OLD); + expect(() => exact.createBroadcast(Path.from("room/alice/cam"))).toThrow(); + + const one = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.literal(OLD)])); + expect(() => one.consume().request(OLD).close()).not.toThrow(); + expect(() => one.consume().request(Path.from("room/alice"))).toThrow(); + expect(() => one.consume().request(NEW)).toThrow(); + + broadcast.close(); + origin.close(); +}); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index 5a54a34eca7..5803ea2f0dd 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -34,9 +34,10 @@ class Scope { this.allowed = allowed; } + /** A pattern that admits a name also admits its epochs (`name/@`). */ narrow(root: Path.Valid, patterns: Path.Patterns): Scope { const joined = Path.encode(Path.join(this.root, root)); - const rooted = patterns.rooted(joined); + const rooted = withEpochs(patterns.rooted(joined)); const allowed = this.allowed?.intersect(rooted) ?? rooted; if (allowed.size === 0) throw new Error("origin scopes do not overlap"); return new Scope(joined, allowed); @@ -122,6 +123,27 @@ class Scope { } } +const EPOCH_SEGMENT: Path.Segment = { kind: "partial", prefix: "@", suffix: "" }; + +/** + * `patterns` with each name they admit also admitting its epochs: a member not ending in + * `**` gains a `/@*` sibling. A grant on one epoch names that epoch, so it never widens to + * the bare name or its siblings. Mirrors Rust's `with_epochs`. + */ +function withEpochs(patterns: Path.Patterns): Path.Patterns { + const widened = new Path.Patterns(patterns); + for (const member of patterns) { + const last = member.segments.at(-1); + if (last?.kind === "globstar" || (last?.kind === "partial" && last.prefix === "@" && last.suffix === "")) { + continue; + } + // A member at the depth limit names nothing with room for an epoch. + if (member.segments.length >= Path.Pattern.MAX_SEGMENTS) continue; + widened.insert(Path.Pattern.from([...member.segments, EPOCH_SEGMENT])); + } + return widened; +} + /** Whether the route advertised at `prefix` may serve any path `pattern` admits. */ function advertOverlaps(advert: Advertised, prefix: Path.Valid, pattern: Path.Pattern): boolean { return advert.claim ? advert.claim.overlaps(pattern) : scopeOverlaps(pattern, prefix); @@ -473,6 +495,13 @@ class OriginState { * the answer for a single path. */ refresh(path: Path.Valid): void { + this.#refreshSlot(path); + // A bare name follows the epochs below it. + const { name, epoch } = Path.splitEpoch(path); + if (epoch !== undefined) this.#refreshSlot(name); + } + + #refreshSlot(path: Path.Valid): void { const slot = this.requests.peek()?.get(path); if (!slot) return; slot.route.set(this.route(path, slot)); @@ -483,10 +512,17 @@ class OriginState { * refuser; one with nothing serving ends with `err`. */ refuse(path: Path.Valid, entry: RouteEntry, err: Error): void { + this.#refuseSlot(path, path, entry, err); + // A bare name following this epoch was asking through the same route. + const { name, epoch } = Path.splitEpoch(path); + if (epoch !== undefined && this.target(name) === path) this.#refuseSlot(name, path, entry, err); + } + + #refuseSlot(path: Path.Valid, target: Path.Valid, entry: RouteEntry, err: Error): void { const slot = this.requests.peek()?.get(path); if (!slot) return; // Only the route the request is waiting on speaks for it; a superseded one's answer is moot. - if (this.bestEntry(path, (candidate) => slot.refused.has(candidate)) !== entry) return; + if (this.bestEntry(target, (candidate) => slot.refused.has(candidate)) !== entry) return; const serving = slot.route.peek(); if (serving && serving.closed.peek() === undefined) { @@ -513,8 +549,12 @@ class OriginState { * releases a retracted route's session subscription even when nothing reads it again. */ refreshPrefix(prefix: Path.Valid): void { + // A route at an epoch also moves the bare name above it. + const { name, epoch } = Path.splitEpoch(prefix); for (const [path, slot] of this.requests.peek() ?? []) { - if (Path.hasPrefix(prefix, path)) slot.route.set(this.route(path, slot)); + if (Path.hasPrefix(prefix, path) || (epoch !== undefined && path === name)) { + slot.route.set(this.route(path, slot)); + } } } @@ -575,7 +615,8 @@ class OriginState { /** * What `path` resolves to: an announced local publish, a broadcast materialized from - * the best covering route, or the blind answer. + * the best covering route, or the blind answer. A bare name resolves through its + * {@link target} epoch, so a newer epoch swaps in a different broadcast. * * Materialization is lazy and cached per path: the first request under a route opens * the providing session's subscription and repeats share it. A better route is made @@ -583,9 +624,11 @@ class OriginState { * answers (then swaps) or refuses (then is skipped). A retracted route swaps at once. */ route(path: Path.Valid, slot: Pick): broadcast.Consumer | undefined { - const entry = this.bestEntry(path, (candidate) => slot.refused.has(candidate)); - const local = this.local.peek()?.get(path); - if (local && this.localWins(path, entry)) { + // Everything below is served from the target; the slot and its cache stay keyed by `path`. + const target = this.target(path); + const entry = this.bestEntry(target, (candidate) => slot.refused.has(candidate)); + const local = this.local.peek()?.get(target); + if (local && this.localWins(target, entry)) { // Nothing reads a remote front the local broadcast replaced, so close its session subscription. this.releaseMaterialized(path); return local; @@ -602,16 +645,42 @@ class OriginState { return slot.answer; } - const served = entry.server.served.get(path); + const served = entry.server.served.get(target); if (served && served.closed.peek() === undefined) { cached?.front.close(); - this.materialized.set(path, { entry, front: served }); - return served; + // A bare name shares its epoch's broadcast with the epoch's own requests, so it + // caches a handle of its own: releasing one must not close the other. + const front = target === path ? served : served.clone(); + this.materialized.set(path, { entry, front }); + return front; } - entry.server.enqueue(path); + entry.server.enqueue(target); return cached?.front; } + + /** + * The path a request for `path` is served from: `path` itself when anything routes it, + * otherwise the newest epoch below it that something routes. A path naming an epoch + * pins it. Mirrors Rust's resolution, so a bare name follows its newest live epoch and + * falls back to an older one when the newest goes away. + */ + target(path: Path.Valid): Path.Valid { + if (this.local.peek()?.has(path) || this.bestEntry(path)) return path; + if (Path.splitEpoch(path).epoch !== undefined) return path; + let newest: Path.Valid | undefined; + const consider = (candidate: Path.Valid) => { + const { name, epoch } = Path.splitEpoch(candidate); + // Same name, so the text orders by epoch, which orders by mint time. + if (epoch !== undefined && name === path && (newest === undefined || candidate > newest)) + newest = candidate; + }; + for (const candidate of this.local.peek()?.keys() ?? []) consider(candidate); + for (const [prefix, entries] of this.routes.peek() ?? []) { + if (entries.some((entry) => entry.scope.matches(prefix))) consider(prefix); + } + return newest ?? path; + } } /** @@ -1082,7 +1151,9 @@ export class Requesting { * The resolved broadcast, or undefined while nothing provides the path. * * The table's route when it has one: a local publish (no round trip) or an announced - * broadcast, swapping when a republish takes the path. Otherwise a session's blind + * broadcast, swapping when a republish takes the path. A bare name nothing routes + * follows its newest epoch (`name/@`), swapping to a new broadcast when a newer + * epoch appears or falling back when the newest goes away. Otherwise a session's blind * answer, which is assumed present rather than known live: a missing broadcast * surfaces as a reset on the first track subscription, not here. Drops back to * undefined when the providing route dies and resolves again when another appears. @@ -1214,8 +1285,9 @@ export class Consumer { * @internal */ #routes(path: Path.Valid): boolean { - if (this.#state.local.peek()?.has(path)) return true; - return this.#state.bestEntry(path) !== undefined; + const target = this.#state.target(path); + if (this.#state.local.peek()?.has(target)) return true; + return this.#state.bestEntry(target) !== undefined; } /** diff --git a/js/net/src/path.test.ts b/js/net/src/path.test.ts index 51d3e8a000a..4f814023521 100644 --- a/js/net/src/path.test.ts +++ b/js/net/src/path.test.ts @@ -1,4 +1,4 @@ -import { expect, test } from "bun:test"; +import { expect, spyOn, test } from "bun:test"; import * as Epoch from "./epoch.ts"; import * as Path from "./path.ts"; @@ -365,3 +365,18 @@ test("epoch segments are literal pattern components", () => { expect(Path.Pattern.parse("demo/video").matches(path)).toBe(false); expect(Path.Pattern.parse(path).matches(path)).toBe(true); }); + +test("mintEpoch appends a fresh epoch", () => { + // UUIDv7 minting stays monotonic across a process, so a real clock here would push + // every later fixed-clock mint (epoch.test.ts) forward. Pin one earlier than theirs. + const now = spyOn(Date, "now").mockReturnValue(1_600_000_000_000); + try { + const minted = Path.mintEpoch(Path.from("room/alice")); + const { name, epoch } = Path.splitEpoch(minted); + expect(name).toBe(Path.from("room/alice")); + expect(epoch).toBeDefined(); + expect(Path.mintEpoch(Path.from("room/alice"))).not.toBe(minted); + } finally { + now.mockRestore(); + } +}); diff --git a/js/net/src/path.ts b/js/net/src/path.ts index 6c92478b763..e6d9543d710 100644 --- a/js/net/src/path.ts +++ b/js/net/src/path.ts @@ -360,3 +360,8 @@ export function splitEpoch(path: Valid): { name: Valid; epoch?: Epoch.Valid } { export function joinEpoch(name: Valid, epoch?: Epoch.Valid): Valid { return epoch === undefined ? name : join(name, from(`@${epoch}`)); } + +/** Append a freshly minted epoch, naming a new instance of this broadcast. */ +export function mintEpoch(name: Valid): Valid { + return joinEpoch(name, Epoch.mint()); +} diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 141a6f8ff53..87806d7bad8 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -10,7 +10,7 @@ restarts its group numbering at 0 under an un-epoched name, while its old route lingers, is resumed into the old broadcast and stalls viewers until its sequence catches up. -By default, each publish of `demo/BBB.hang` goes out as +Each first-party publish of `demo/BBB.hang` goes out as `demo/BBB.hang/@`, so a restart is a new broadcast. A viewer of the bare name follows the newest live epoch as soon as it is announced. Moving to a new epoch is a clean boundary (a fresh catalog and tracks, never resumed @@ -36,22 +36,26 @@ Decided: - The marker is a child segment `@`, parsed into `Option` by [the shared primitive](/doc/concept/moq-lite.md#publisher-epochs). Not a lite-07 flag: the path is the only carrier. -- The broadcast-publish path mints an epoch unless the path already carries - one. A caller who passes an explicit epoch, such as a redundant publisher, - keeps it. The prefix-route `announce(prefix, route)` stays raw, and that is - the opt-out. So prefix vs broadcast is an API distinction, not a wire flag. +- Publishing does not mint an epoch by default; the path is published as + given (decided 2026-10-04 by the maintainer, replacing "mint unless the path + already carries one"). Minting is one call: `Path::mint_epoch` in Rust and + `Path.mintEpoch` in TypeScript append a fresh `@`. Each first-party + publisher calls it once per run; a redundant pair passes a shared epoch. - Viewers follow the greatest epoch with a live route. When it goes away and an older one is still live, they fall back to it. -- A bare request with no route of its own resolves to that same epoch on every - version, so lite-06 and IETF clients keep working through an epoch-aware - relay. When a newer epoch appears, the bare subscription ends with a typed - reset, and the client's normal resubscribe lands on the new one. +- A bare request with no route covering the name resolves to that same epoch + on every version, so lite-06 and IETF clients keep working through an + epoch-aware relay. When the name resolves elsewhere, the bare subscription + ends with an `Unroutable` reset, and the client's normal resubscribe lands on + the new one. A route covering the name wins over its epochs. +- A grant that admits a name admits its epochs (a `name/@*` sibling); a grant + on one epoch reaches only that epoch. - An unmodified third-party relay routes `foo/@` but never resolves a bare `foo`, since a route covers its descendants, not its parent. A - bare-name viewer behind one needs a publisher that opts out with the raw - prefix route. Document this rather than promise it works. -- Publishers on the default publish path, such as moq-boy and moq-room, - inherit the epoch from Origin. moq-stats mints its own through + bare-name viewer behind one needs a publisher that publishes the bare name. + Document this rather than promise it works. +- Publishers such as moq-boy and moq-room mint their epoch at publish. + moq-stats mints its own through [Stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md), which also gates the release (decided 2026-10-04): a restarted stats node under a reused name stalls its viewers the same way. @@ -76,16 +80,23 @@ This README owns: Killing the newest epoch falls back to a still-live older one. - A `doc/concept` page on broadcast naming: what an epoch is, publish and consume behavior, takeover and fallback, bare-path resolution, and the - prefix-route opt-out. + bare-name opt-out. + +Open: + +- Does a catalog `broadcast` reference by bare name pin the epoch its catalog + came from, or follow the newest? Settle it with + [Catalog track alias](/quest/m1/catalog-track-alias.md). Today a bare + request's broadcast is named by the bare name, so relative references + resolve against it and follow; a pinned request's are named under its epoch. ## Required - [Retracted demand release](/quest/m0/broadcast-epoch/unannounce-demand-release.md) - a retracted broadcast's track demand is released when its last subscriber leaves, as before #4741 -- [Origin](/quest/m0/broadcast-epoch/origin.md) - moq-net publish mints an epoch, consumers follow the newest live one, and bare requests resolve to it on every version - [Apps](/quest/m0/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web publish under epochs and play bare names - [Gateways](/quest/m0/broadcast-epoch/gateways.md) - RTMP, SRT, and WHIP ingest mint an epoch per incoming connection, so an encoder reconnect is a clean takeover - [TS restart](/quest/m0/broadcast-epoch/ts-restart.md) - a signalled backward TS discontinuity finishes the broadcast and continues the same input under a fresh epoch -- [Bindings](/quest/m0/broadcast-epoch/bindings.md) - moq-ffi and every wrapper expose the epoch and inherit the default +- [Bindings](/quest/m0/broadcast-epoch/bindings.md) - moq-ffi and every wrapper expose the epoch and a one-call mint - [GStreamer](/quest/m0/broadcast-epoch/gst.md) - moqsink publishes each run under a fresh epoch - [Remove `--hop`](/quest/m0/broadcast-epoch/hop-removal.md) - `moq` takes an optional `--epoch` instead of `--hop`, a plain publisher declares a random Hop ID, and the per-session hop stamp is gone - [Bounded stats aggregate](/quest/m0/broadcast-epoch/stats-aggregate-bound.md) - the stats aggregator folds departed nodes into a retired total, so epoch churn stops growing its memory diff --git a/quest/m0/broadcast-epoch/apps.md b/quest/m0/broadcast-epoch/apps.md index cfbbdf28c21..adf3ef287bf 100644 --- a/quest/m0/broadcast-epoch/apps.md +++ b/quest/m0/broadcast-epoch/apps.md @@ -2,8 +2,9 @@ ## Goal -`moq-cli` publish and play, `@moq/publish`, `@moq/watch`, and `demo/web` use -the origin default. Each publish run is a new epoch, so a restart while the +`moq-cli` publish and play, `@moq/publish`, `@moq/watch`, and `demo/web` +publish each run under a fresh epoch (`Path::mint_epoch`, `Path.mintEpoch`; +publishing does not mint one by default). Each publish run is a new epoch, so a restart while the old route lingers is a new broadcast rather than a resume into the old one, which stalls viewers until the new run's group sequence catches up. Watching a bare name switches to a republish within an RTT. The UI and logs show the @@ -11,13 +12,11 @@ full epoch path, and a watch link can pin one. ## Plan -- Publish sides need little beyond passing bare names. Check that nothing - caches the announced path across a restart. +- Publish sides mint the epoch once per run where they create the broadcast. + Check that nothing caches the announced path across a restart. +- Watch sides on the old JS path wait for an announcement covering the bare + name; `@moq/net` now treats an epoch below it as routing the name. - Watch sides handle "the broadcast changed" as a fresh catalog and decoder reset. Test a republish mid-playback in the browser and native players. - Update `doc/bin/cli.md` and every example invocation that shows a published path. - -## Required - -- [Origin](/quest/m0/broadcast-epoch/origin.md) - the publish default and follow logic diff --git a/quest/m0/broadcast-epoch/bindings.md b/quest/m0/broadcast-epoch/bindings.md index 4ee0c1b2a7e..15fe36bd9e3 100644 --- a/quest/m0/broadcast-epoch/bindings.md +++ b/quest/m0/broadcast-epoch/bindings.md @@ -2,8 +2,9 @@ ## Goal -`moq-ffi` and the py, swift, kt, go, and dart wrappers publish under the -default epoch and follow bare names like Rust. The generated C and C++ +`moq-ffi` and the py, swift, kt, go, and dart wrappers make minting an epoch +one call (publishing does not mint one by default) and follow bare names like +Rust. The generated C and C++ bindings pick it up from moq-ffi; libmoq gets no new API. The epoch of a published or consumed broadcast is readable, and a caller can pass an explicit one. The reconnect counter `session.epoch()` is renamed so "epoch" has one meaning. @@ -23,7 +24,3 @@ Decided in the 2026-10-05 audit: this lands before the [FFI shape](/quest/m1/ffi-shape/README.md) line (#4519), which reshapes the same wrappers and keeps `epoch()` today. It rebases onto this quest and adopts the epoch surface and the rename, so the wrappers break once each. - -## Required - -- [Origin](/quest/m0/broadcast-epoch/origin.md) - the behavior the bindings surface diff --git a/quest/m0/broadcast-epoch/gateways.md b/quest/m0/broadcast-epoch/gateways.md index 2124764d1fc..f0b8f9ec1e2 100644 --- a/quest/m0/broadcast-epoch/gateways.md +++ b/quest/m0/broadcast-epoch/gateways.md @@ -10,15 +10,11 @@ up. ## Plan -Use the origin default where the gateways create broadcasts (`moq-rtmp`, +Mint the epoch (`Path::mint_epoch`) where the gateways create broadcasts (`moq-rtmp`, `moq-srt`, `moq-rtc`, and the relay wiring). Test a reconnect under the same key with the stale connection still open. Update `doc/bin/relay/` where it describes ingest paths. -## Required - -- [Origin](/quest/m0/broadcast-epoch/origin.md) - the publish default - ## Related - [TS restart](/quest/m0/broadcast-epoch/ts-restart.md) - a signalled restart inside one connection, which this quest's per-connection epoch does not cover diff --git a/quest/m0/broadcast-epoch/gst.md b/quest/m0/broadcast-epoch/gst.md index f4ec65fd191..ed47763d230 100644 --- a/quest/m0/broadcast-epoch/gst.md +++ b/quest/m0/broadcast-epoch/gst.md @@ -7,7 +7,7 @@ a clean takeover for viewers. ## Plan -`moqsink` takes the origin default per session. When +`moqsink` mints an epoch per session. When [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) lands, each of its publication generations is a new epoch. Update `doc/bin/gstreamer.md` if it shows paths. @@ -15,12 +15,7 @@ lands, each of its publication generations is a new epoch. Update Decided in the 2026-10-05 audit: the OBS half moved to [OBS publishes under epochs](/quest/m1/obs-epoch.md), so the release gate no longer waits on the C++ line. `moqsink` is Rust on moq-net and needs nothing -from it. moq-c announces through `broadcast::Producer::announce`, so it only -inherits an epoch if Origin mints one there; the OBS quest checks that. - -## Required - -- [Origin](/quest/m0/broadcast-epoch/origin.md) - the publish default moqsink takes +from it. ## Related diff --git a/quest/m0/broadcast-epoch/hop-removal.md b/quest/m0/broadcast-epoch/hop-removal.md index 2e98108b4f9..244ac1045ef 100644 --- a/quest/m0/broadcast-epoch/hop-removal.md +++ b/quest/m0/broadcast-epoch/hop-removal.md @@ -4,8 +4,9 @@ Nothing names a publisher's identity outside its path. `moq` loses `--hop`, `MOQ_HOP`, and the hidden `--origin` alias; an optional `--epoch` takes their -place for publishing. Omitted, each run gets a fresh epoch (the origin -default); a redundant pair passes the same value. A plain publisher declares +place for publishing. Omitted, each run mints a fresh epoch +(`Path::mint_epoch`, since publishing does not mint one); a redundant pair +passes the same value. A plain publisher declares a random Hop ID per process with no flag, as the bindings and js already do, so a multi-homed publisher still catches its own loops. `--cluster-id` names a node and no longer falls back to `--hop`. Relays stop stamping an unnamed @@ -47,7 +48,3 @@ to the relay). Neither is required to land this. Public API: removes `--hop`, `MOQ_HOP`, and `--origin`, adds `--epoch`, and `--cluster-id` stops reading `--hop`. Wire: relays stop stamping. - -## Required - -- [Origin](/quest/m0/broadcast-epoch/origin.md) - the default mint `--epoch` falls back to diff --git a/quest/m0/broadcast-epoch/origin.md b/quest/m0/broadcast-epoch/origin.md deleted file mode 100644 index 9906345af6f..00000000000 --- a/quest/m0/broadcast-epoch/origin.md +++ /dev/null @@ -1,53 +0,0 @@ -# [L] Origin: mint, follow, and resolve epochs - -## Goal - -In `moq-net` (Rust and JS), publishing a broadcast at a bare path announces it -under a fresh epoch. A consumer of a bare name follows the newest epoch with -a live route and falls back to an older live one. A bare request resolves the -same way on every protocol version, so the relay serves old clients without -any wire change. - -## Plan - -- Publish: the broadcast create-and-announce path appends `Epoch::mint()` - unless the path already has an epoch. `announce(prefix, route)` stays raw. - A bare path already at the 32-part limit has no room for the epoch segment: - refuse it at publish, pointing at the raw route, rather than fail at encode. -- Auth: a grant that admits bare `foo` admits `foo/@` for both publish - and subscribe, and a grant on one epoch never widens to the bare name or its - siblings. Check how exact grants and patterns match today, and test both - sides in moq-relay's auth tests. -- Consume: `routed` and `request_broadcast` on a bare name watch the routes - one `@` segment below it. They pick the greatest live epoch, and on a table - change, re-select: move up at once, or fall back when the current one is - retracted. A path that names an epoch pins it and never moves. Each move is - a new broadcast to the caller, never a splice. Within one epoch path, any - route resumes a subscription, whoever serves it. -- Bare resolution: a bare request with no route of its own resolves to that - epoch. A takeover ends the bare subscription with a typed reset, never a - silent switch. Choose the code so existing clients resubscribe rather than - give up. -- A nested epoch (`name/@e/derived/@f`) resolves per level. Split-horizon - exclusion and the per-path fronts from #3312 stay intact. -- Benchmark resolution swept over epochs per name and names per origin, so - following does not scan the table. -- Settle here, in this m0 quest, whether a catalog `broadcast` reference by - bare name pins the epoch its catalog came from or follows the newest - (decided in the 2026-10-05 audit: it is not handed to - [Catalog track alias](/quest/m1/catalog-track-alias.md), an m1 quest that - never mentions epochs). Record the answer in the line README. -- Update `doc/concept` and `drafts/draft-lcurley-moq-lite.md` wherever they - describe resolution or takeover. The rule is a relay behavior, so state it - in the draft even though no field changes. - -Public API: behavior change on publish (the announced path gains an epoch, -and a 32-part bare path is refused), on bare-name consume, and on what an -exact grant admits. -Wire: none. - -## Related - -- [Catalog track alias](/quest/m1/catalog-track-alias.md) - cross-broadcast catalog references, which must pick an epoch - -- [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - a new epoch starts each track at sequence 0 diff --git a/quest/m0/broadcast-epoch/ts-restart.md b/quest/m0/broadcast-epoch/ts-restart.md index f302c717bf9..95e1f9874c9 100644 --- a/quest/m0/broadcast-epoch/ts-restart.md +++ b/quest/m0/broadcast-epoch/ts-restart.md @@ -20,8 +20,8 @@ and a flagged forward jump publishes break markers and carries on. Decided (maintainer, 2026-09-30): - A rewind is new content, so it is always a new broadcast at a new epoch - path, never a continuation of the old name. Viewers of the bare name follow - it through [Origin](/quest/m0/broadcast-epoch/origin.md). + path (`Path::mint_epoch`), never a continuation of the old name. Viewers of + the bare name follow it through the origin's newest-epoch resolution. - `decode` stops at the flagged rewind and reports it. The caller finishes the old broadcast (a clean end, not an abort, so its viewers read to its end), publishes a new broadcast at a fresh epoch path, and calls @@ -43,10 +43,6 @@ connection carries both epochs. Update `doc/bin/cli.md` and `doc/bin/srt.md`. Public API: breaking in moq-mux, `ts::Import::decode` reports a restart and `restart` is new. Wire: none. -## Required - -- [Origin](/quest/m0/broadcast-epoch/origin.md) - the fresh epoch path the rest of the feed publishes under - ## Closes - [#4582](https://github.com/moq-dev/moq/issues/4582) - a signalled backward TS discontinuity ends the import diff --git a/quest/m1/obs-epoch.md b/quest/m1/obs-epoch.md index 0866b9fac08..af40fff046a 100644 --- a/quest/m1/obs-epoch.md +++ b/quest/m1/obs-epoch.md @@ -15,10 +15,8 @@ release gate waits only on `moqsink`. - OBS gets the epoch through the generated C++ bindings from moq-ffi, which the C++ line moves the plugin onto (decided in the 2026-09-30 audit: libmoq, now moq-c, gets no new API). -- First check whether the plugin already inherits it: today it announces - through moq-c's `moq_publish_announce`, which calls - `broadcast::Producer::announce`. If Origin mints the epoch on that path, - the plugin needs no code, only a test. +- Origin publishes the path as given, so the plugin mints its own epoch per + Start Streaming. - Show the full epoch path in the dock, and update `doc/bin/obs.md` if it shows paths. diff --git a/rs/moq-net/benches/origin.rs b/rs/moq-net/benches/origin.rs index a6cceec63b6..50ea6fbfefd 100644 --- a/rs/moq-net/benches/origin.rs +++ b/rs/moq-net/benches/origin.rs @@ -421,6 +421,43 @@ fn bench_request(c: &mut Criterion) { group.finish(); } +/// Resolving a bare name to its newest epoch, with `names` names in the table +/// each published under `epochs` live epochs: the walk reads only the epochs +/// one segment below the requested name, so `names` must not show. +fn bench_follow(c: &mut Criterion) { + let mut group = c.benchmark_group("origin/follow"); + for names in [100, 1_000] { + for epochs in [1, 8, 64] { + let (producer, mut driver) = origin::Producer::new(origin::Config::default()); + let consumer = producer.consume(); + let _publishers: Vec = (0..names) + .flat_map(|i| { + let name = format!("room/{i}"); + (0..epochs) + .map(|_| { + let path = moq_net::Path::new(&name).mint_epoch(); + producer.publish(path, origin::Route::default()).unwrap() + }) + .collect::>() + }) + .collect(); + let waiter = kio::Waiter::noop(); + group.bench_function(BenchmarkId::from_parameter(format!("{names}n_{epochs}e")), |b| { + b.iter(|| { + let pending = consumer.request_broadcast("room/0"); + // The front's driver resolves the first request; later ones join it. + driver.poll(moq_net::time::Instant::now(), &waiter).unwrap(); + pending + .now_or_never() + .expect("resolves once driven") + .expect("newest epoch"); + }); + }); + } + } + group.finish(); +} + /// Publisher handoff at one path: a subscriber is reading from one local /// source when a second announces at the same path and takes over (newest /// wins). Measured from the standby's attach to the subscriber receiving its @@ -601,6 +638,7 @@ criterion_group!( bench_serve_idle, bench_subscribe, bench_request, + bench_follow, bench_handoff, bench_relay, bench_parked diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 00cd050446c..29b8dadd210 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -997,6 +997,9 @@ struct RemoteFront { /// The front's broadcast, weak: dead once the front ends, so a /// later request re-creates the front instead of joining a corpse. broadcast: broadcast::WeakConsumer, + /// The absolute path it is served from: its own, or the epoch a bare name + /// resolved to when the front was made. + target: PathOwned, } /// The last route a cursor observed: entry id, metadata, servability, and captures. @@ -1282,6 +1285,28 @@ impl Default for OriginScope { } } +/// `patterns` with each name they admit also admitting its epochs: a member not +/// ending in `**` gains a `/@*` sibling. A grant on one epoch names that epoch, so +/// it never widens to the bare name or its siblings. +fn with_epochs(patterns: Patterns) -> Patterns { + let epoch = Segment::Partial { + prefix: "@".to_string(), + suffix: String::new(), + }; + let mut widened = patterns.clone(); + for member in patterns.iter() { + // `**` already reaches every epoch, and a member that is one is already widened. + if matches!(member.segments().last(), Some(last) if *last == Segment::Globstar || *last == epoch) { + continue; + } + // A member at the depth limit names nothing with room for an epoch. + if let Ok(member) = Pattern::new(member.segments().iter().cloned().chain([epoch.clone()])) { + widened.insert(member); + } + } + widened +} + /// The announce-interest prefixes that cover a pattern scope on a prefix-only /// wire: each member's literal head, minus heads another already covers. pub(crate) fn interest_prefixes(allowed: &Patterns) -> Vec { @@ -1537,11 +1562,17 @@ impl Producer { /// End the broadcast with [`broadcast::Producer::close`] or by dropping it; /// either way the path closes once it was the last source. /// + /// The path is published as given. A publisher that may restart publishes + /// each run under a fresh epoch ([`Path::mint_epoch`]), so a restart is a new + /// broadcast that bare-name consumers follow (see + /// [`Consumer::request_broadcast`]) rather than a reused name resumed into + /// the old run. + /// /// Fails with [`Error::Unauthorized`] if `path` is outside the prefixes this /// producer may publish under (after [`scope`](Self::scope)) or beneath a /// [`mount`](Self::mount), - /// [`Error::BoundsExceeded`] if the full rooted path exceeds - /// [`Path::MAX_PARTS`], [`Error::InvalidPath`] if it holds a segment no + /// [`Error::BoundsExceeded`] if the full rooted path (an epoch segment + /// included) exceeds [`Path::MAX_PARTS`], [`Error::InvalidPath`] if it holds a segment no /// pattern can spell (`*` or `**`), or [`Error::Closed`] once the origin's /// [`Driver`] has been dropped. pub fn create_broadcast(&self, path: impl AsPath) -> Result { @@ -1716,12 +1747,13 @@ impl Producer { /// Returns a producer rooted at `root` and restricted to matching `patterns`. /// /// `root` is relative to this producer's root, and `patterns` are relative to - /// the new root. Returns [`Error::Unauthorized`] when the requested scope has + /// the new root. A pattern that admits a name also admits its epochs + /// (`name/@`). Returns [`Error::Unauthorized`] when the requested scope has /// no overlap with this producer's scope, or [`Error::BoundsExceeded`] when /// rooting the patterns would exceed the path limit. pub fn scope(&self, root: impl AsPath, patterns: &Patterns) -> Result { let root = self.root.join(root).to_owned(); - let rooted = patterns.rooted(root.as_str()).map_err(|_| BoundsExceeded)?; + let rooted = with_epochs(patterns.rooted(root.as_str()).map_err(|_| BoundsExceeded)?); let scope = self.scope.narrow(&rooted).ok_or(Error::Unauthorized)?; Ok(Producer { hop: self.hop, @@ -2217,11 +2249,15 @@ struct FrontTask { shared: kio::Shared, /// The broadcast the front serves. broadcast: broadcast::Producer, - /// Absolute path of the front. + /// Absolute path the front selects routes for and requests through. path: PathOwned, + /// The bare name the front was requested at, when `path` is the epoch it + /// resolved to. The front ends once the name resolves elsewhere. + follows: Option, /// The requesters' horizon, applied to every (re)selection. horizon: Horizon, - /// Wakes the front when a route covering its path changes. + /// Wakes the front when a route covering its path, or an epoch below the + /// name it follows, changes. watch: Watch, /// Resolves the requesters parked on the front's channel. request: kio::Producer, @@ -2308,6 +2344,7 @@ async fn run_front(task: FrontTask) { shared, broadcast, path, + follows, horizon, watch, request, @@ -2339,31 +2376,48 @@ async fn run_front(task: FrontTask) { // The watch generation the last selection saw. let mut seen = 0; let mut events: VecDeque = VecDeque::new(); + // The followed name resolved to another epoch (or its own route): the front + // ends, and its tracks with it, so readers ask again and land there. + let mut moved = false; // Read the table for the machine: the best route and whether // the serving source is on its way out. Also what the watch wakes for. - let select = |front: &mut Front, sources: &HashMap, seen: &mut u64| -> Event { - let table = shared.read(); - if table.closed { - return Event::Closed; - } - // Read alongside the decision, under the lock a poke takes first. - *seen = watch.seen(); - front.retain_routes(|route| table.routes.covers(&path.as_path(), route)); - let best = table - .best_route(&path.as_path(), horizon, front.refused_routes()) - .map(|entry| Candidate { - route: entry.id, - local: entry.local, - }); - let serving_closing = front - .serving() - .and_then(|id| sources.get(&id)) - .is_some_and(|source| source.is_closing()); - Event::Selected { best, serving_closing } - }; + let select = + |front: &mut Front, sources: &HashMap, seen: &mut u64, moved: &mut bool| -> Event { + let table = shared.read(); + if table.closed { + return Event::Closed; + } + // Read alongside the decision, under the lock a poke takes first. + *seen = watch.seen(); + // Moving to another epoch is a new broadcast, never a splice. A name with + // nothing left to resolve to ends like any retraction instead. + if let Some(name) = &follows + && table + .resolve(&name.as_path(), horizon) + .is_some_and(|resolved| resolved != path) + { + *moved = true; + return Event::Selected { + best: None, + serving_closing: false, + }; + } + front.retain_routes(|route| table.routes.covers(&path.as_path(), route)); + let best = table + .best_route(&path.as_path(), horizon, front.refused_routes()) + .map(|entry| Candidate { + route: entry.id, + local: entry.local, + }); + let serving_closing = front + .serving() + .and_then(|id| sources.get(&id)) + .is_some_and(|source| source.is_closing()); + Event::Selected { best, serving_closing } + }; - events.push_back(select(&mut front, &sources, &mut seen)); + events.push_back(select(&mut front, &sources, &mut seen, &mut moved)); loop { while let Some(event) = events.pop_front() { @@ -2373,7 +2427,7 @@ async fn run_front(task: FrontTask) { }; for action in front.step(event) { match action { - Action::Reselect => events.push_back(select(&mut front, &sources, &mut seen)), + Action::Reselect => events.push_back(select(&mut front, &sources, &mut seen, &mut moved)), Action::Request { route } => { // The entry and what it serves. let found = { @@ -2567,6 +2621,14 @@ async fn run_front(task: FrontTask) { // subscriptions already in flight): their readers follow the copy // they read to its end, since no front is left to replace it. broadcast.close(); + // A followed name moved: nothing carries on, so each reader is + // reset and its next request lands on what the name resolves to now. + if moved { + for (_, mut io) in tracks.drain() { + io.end(Err(Error::Unroutable)); + } + return; + } for (_, mut io) in tracks.drain() { let used = io.weak.is_used(); // A reader still waiting on its source's answer is in flight @@ -2782,7 +2844,7 @@ async fn run_front(task: FrontTask) { deadline.set(None); Event::Deadline { now: timers.now() } } - Step::Table => select(&mut front, &sources, &mut seen), + Step::Table => select(&mut front, &sources, &mut seen, &mut moved), }; events.push_back(event); } @@ -3077,6 +3139,13 @@ impl RouteTable { } } + /// Wake the watches at exactly `path`. + fn poke_at(&self, path: &Path) { + if let (_, Some(node)) = self.split(path) { + node.poke(); + } + } + /// Wake every watch: the origin is tearing down. fn poke_all(&self) { self.root.walk(&mut |node| node.poke()); @@ -3270,6 +3339,10 @@ impl OriginState { } // The fronts and requesters under the prefix re-select from the table. routes.poke_below(prefix); + // So do those following the bare name an epoch route sits under. + if let (name, Some(_)) = prefix.split_epoch() { + routes.poke_at(&name); + } } /// Register a [`Watch`] on the routes covering `path`. @@ -3388,6 +3461,36 @@ impl OriginState { } best } + + /// The path a request for the absolute `path` is served from, for a requester + /// seeing `horizon`: `path` itself when a route covers it, otherwise the newest + /// epoch below it that a route serves. `None` when nothing serves it. + fn resolve(&self, path: &Path, horizon: Horizon) -> Option { + let none: HashSet = HashSet::new(); + if self.best_route(path, horizon, &none).is_some() { + return Some(path.to_owned()); + } + // A path naming an epoch pins it: there is nothing newer to follow. + if path.split_epoch().1.is_some() { + return None; + } + let (_, Some(node)) = self.routes.split(path) else { + return None; + }; + // Canonical UUIDv7 text orders by mint time, so the greatest is the newest. + // Sorted as text and parsed lazily: the newest is usually the one served. + let mut segments: Vec<&str> = node + .children + .keys() + .filter_map(|segment| segment.strip_prefix('@')) + .collect(); + segments.sort_unstable_by(|a, b| b.cmp(a)); + segments + .into_iter() + .filter_map(|text| text.parse::().ok()) + .map(|epoch| path.join_epoch(Some(&epoch))) + .find(|epoch| self.best_route(epoch, horizon, &none).is_some()) + } } /// A remote announce source still replaying its initial set, from @@ -4094,8 +4197,9 @@ impl Consumer { /// Block until an announced route covers `path`, and return it. /// /// Covering means the route's prefix is a (segment-wise) prefix of `path`, - /// including the exact path itself. Returns `None` if the path is outside this - /// consumer's scope or the consumer is closed first. + /// including the exact path itself. A bare `path` is also routed by an epoch + /// one segment below it (`path/@`). Returns `None` if the path is + /// outside this consumer's scope or the consumer is closed first. /// /// To resolve a broadcast rather than inspect the route, use /// [`Self::routed_broadcast`]: pairing this with [`Self::request_broadcast`] @@ -4124,9 +4228,12 @@ impl Consumer { // forwarding, so it must not drive the announce guards. Hiding narrows // discovery, not lookup, so a hidden path resolves like any other. let mut announced = consumer.untagged().with_hidden(true).announced(); + // A bare name is also routed by an epoch one segment below it. + let bare = path.split_epoch().1.is_none(); loop { if let AnnounceEvent::Start(announce) | AnnounceEvent::Update(announce) = announced.next().await? - && path.has_prefix(&announce.prefix) + && (path.has_prefix(&announce.prefix) + || bare && matches!(announce.prefix.split_epoch(), (name, Some(_)) if name == path)) { return Some(announce.route); } @@ -4134,7 +4241,9 @@ impl Consumer { } /// Block until `path` resolves to a broadcast: [`Self::request_broadcast`], - /// retried whenever the routes covering the path change. + /// retried whenever the routes covering the path, or the epochs below a bare + /// name, change. To follow a bare name across epochs, call it again once the + /// broadcast it returned ends. /// /// A request answers for the routes as they stand, so it can miss an /// announcement that has not arrived yet, lose its covering route to @@ -4190,12 +4299,13 @@ impl Consumer { /// Returns a consumer rooted at `root` and restricted to matching `patterns`. /// /// `root` is relative to this consumer's root, and `patterns` are relative to - /// the new root. Returns [`Error::Unauthorized`] when the requested scope has + /// the new root. A pattern that admits a name also admits its epochs + /// (`name/@`). Returns [`Error::Unauthorized`] when the requested scope has /// no overlap with this consumer's scope, or [`Error::BoundsExceeded`] when /// rooting the patterns would exceed the path limit. pub fn scope(&self, root: impl AsPath, patterns: &Patterns) -> Result { let root = self.root.join(root).to_owned(); - let rooted = patterns.rooted(root.as_str()).map_err(|_| BoundsExceeded)?; + let rooted = with_epochs(patterns.rooted(root.as_str()).map_err(|_| BoundsExceeded)?); let scope = self.scope.narrow(&rooted).ok_or(Error::Unauthorized)?; Ok(Consumer { scope, @@ -4219,6 +4329,13 @@ impl Consumer { /// retracting with no replacement ends the broadcast, and the next request /// re-serves the path. Tracks already in flight carry on to their own end. /// + /// A bare name no route covers resolves to its newest epoch: the greatest + /// `path/@` a route serves. The broadcast is still named `path`, and + /// follows that one epoch: once the name resolves elsewhere (a newer epoch, an + /// older one after the newest is retracted, or a route covering the name), it + /// ends and so do its tracks, with [`Error::Unroutable`], so the next request + /// lands on the new resolution. A path naming an epoch pins it. + /// /// The returned future fails with [`Error::Unroutable`] at once when no /// announced route covers the path, including a broadcast created on this /// origin but not announced. @@ -4256,15 +4373,12 @@ impl Consumer { return kio::Pending::new(Requesting::failed(Error::Closed)); } - // Nothing serves the path: no announced broadcast and no served route. - // Checked before joining a front, so a front still draining after its - // route retracted takes no newcomers. - if state - .best_route(&absolute.as_path(), self.horizon, &HashSet::new()) - .is_none() - { + // Nothing serves the path: no announced broadcast, no served route, and + // no epoch below a bare name. Checked before joining a front, so a front + // still draining after its route retracted takes no newcomers. + let Some(target) = state.resolve(&absolute.as_path(), self.horizon) else { return kio::Pending::new(Requesting::failed(Error::Unroutable)); - } + }; // Join the live front for this path and exclusion, if any: its watcher // resolves (or already resolved) the request channel with the front's @@ -4272,10 +4386,15 @@ impl Consumer { // route serves the path, it is the same broadcast. let key = (absolute.clone(), self.horizon); if let Some(front) = state.fronts.get(&key) { - let pending = Requesting::queued(front.request.consume()) - .with_path(requested) - .with_stats(scope); - return kio::Pending::new(pending); + if front.target == target { + let pending = Requesting::queued(front.request.consume()) + .with_path(requested) + .with_stats(scope); + return kio::Pending::new(pending); + } + // The front follows an epoch the name has since moved off, and ends + // on its next selection: serve the newcomer from a fresh one. + state.fronts.remove(&key); } // A route covers the path: mint the front and hand its watcher the @@ -4295,6 +4414,7 @@ impl Consumer { RemoteFront { request: request.clone(), broadcast: broadcast.consume().weak(), + target: target.clone(), }, ); // Released before the push: a set whose handles are gone drops the task, @@ -4303,7 +4423,8 @@ impl Consumer { self.tasks.push(run_front(FrontTask { shared: self.shared.clone(), broadcast, - path: absolute, + follows: (target != absolute).then_some(absolute), + path: target, horizon: self.horizon, watch, request, @@ -8213,19 +8334,25 @@ mod tests { let consumer = producer.consume().scope("", &scopes(&["room"])).unwrap(); assert_eq!(consumer.allowed(), scopes(&["room"])); + // A member naming a broadcast also reaches its epochs. for text in ["room", "", "*room", "room/*", "*", "**/room", "room/**/chat", "*.hang"] { let union = Patterns::from(text.parse::().unwrap()); - assert_eq!(producer.scope("", &union).expect(text).allowed(), union, "{text}"); + let reached = with_epochs(union.clone()); + assert_eq!(producer.scope("", &union).expect(text).allowed(), reached, "{text}"); assert_eq!( producer.consume().scope("", &union).expect(text).allowed(), - union, + reached, "{text}" ); } - let mixed: Patterns = ["room/**".parse().unwrap(), "other".parse().unwrap()] - .into_iter() - .collect(); + let mixed: Patterns = [ + "room/**".parse().unwrap(), + "other".parse().unwrap(), + "other/@*".parse().unwrap(), + ] + .into_iter() + .collect(); assert_eq!(producer.scope("", &mixed).unwrap().allowed(), mixed); } @@ -8415,13 +8542,19 @@ mod tests { let chats = rooms .scope("", &Patterns::from("*/chat".parse::().unwrap())) .unwrap(); - assert_eq!(chats.allowed(), Patterns::from("room/chat".parse::().unwrap())); + assert_eq!( + chats.allowed(), + with_epochs(Patterns::from("room/chat".parse::().unwrap())) + ); let exact = producer .scope("", &Patterns::from("room/alice".parse::().unwrap())) .unwrap(); let rooted = exact.scope("room", &Patterns::from(Pattern::all())).unwrap(); - assert_eq!(rooted.allowed(), Patterns::from("alice".parse::().unwrap())); + assert_eq!( + rooted.allowed(), + with_epochs(Patterns::from("alice".parse::().unwrap())) + ); assert!(matches!( exact.scope("room/bob", &Patterns::from(Pattern::all())), Err(Error::Unauthorized) @@ -8583,4 +8716,226 @@ mod tests { .encode(&mut buf, crate::lite::Version::Lite06) .expect("a draining route is still forwarded, so its cost must encode"); } + + /// Two epochs in mint order, older first. + const OLD: &str = "0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f"; + const NEW: &str = "0199b7f4-3c2b-7d1e-9f0b-2b6c1a9d8e7f"; + + fn epoch(name: &str, epoch: &str) -> PathOwned { + Path::new(name).join_epoch(Some(&epoch.parse().unwrap())) + } + + /// Publish one epoch of `room/alice` with a `video` track holding one group. + fn publish_epoch(producer: &Producer, at: &str, payload: &'static [u8]) -> (broadcast::Producer, track::Producer) { + let broadcast = producer.publish(epoch("room/alice", at), Route::default()).unwrap(); + let track = broadcast.create_track("video", None).unwrap(); + let mut group = track.append_group().unwrap(); + group.write_frame(crate::Timestamp::ZERO, payload).unwrap(); + group.finish().unwrap(); + (broadcast, track) + } + + async fn read_video(broadcast: &broadcast::Consumer) -> (crate::track::Subscriber, Vec) { + let mut subscription = broadcast.track("video").unwrap().subscribe(None).await.unwrap(); + let mut group = next_group(&mut subscription).await.unwrap().unwrap(); + let payload = group.read_frame().await.unwrap().unwrap().payload.to_vec(); + (subscription, payload) + } + + #[test] + fn mint_epoch_appends_a_fresh_epoch() { + let minted = Path::new("room/alice").mint_epoch(); + let (name, epoch) = minted.split_epoch(); + assert_eq!(name, Path::new("room/alice")); + assert!(epoch.is_some()); + assert_ne!(Path::new("room/alice").mint_epoch(), minted); + } + + #[tokio::test] + async fn a_bare_name_resolves_to_its_newest_epoch() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let _old = publish_epoch(&producer, OLD, b"old"); + let _new = publish_epoch(&producer, NEW, b"new"); + + let resolved = consumer.request_broadcast("room/alice").await.unwrap(); + // Named as asked, so a catalog's relative references resolve against the name. + assert_eq!(resolved.info().path, Path::new("room/alice")); + assert_eq!(read_video(&resolved).await.1, b"new"); + + // A path naming an epoch pins it. + let pinned = consumer.request_broadcast(epoch("room/alice", OLD)).await.unwrap(); + assert_eq!(read_video(&pinned).await.1, b"old"); + } + + #[tokio::test] + async fn a_newer_epoch_resets_bare_readers() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let _old = publish_epoch(&producer, OLD, b"old"); + + let bare = consumer.request_broadcast("room/alice").await.unwrap(); + let pinned = consumer.request_broadcast(epoch("room/alice", OLD)).await.unwrap(); + let (mut following, payload) = read_video(&bare).await; + assert_eq!(payload, b"old"); + let (mut staying, _) = read_video(&pinned).await; + + let _new = publish_epoch(&producer, NEW, b"new"); + // The takeover is a typed reset, never a splice into the new epoch. + assert!(matches!(next_group(&mut following).await, Err(Error::Unroutable))); + settle(|| bare.is_closed()).await; + assert!(!pinned.is_closed(), "a pinned epoch never moves"); + assert!(staying.poll_recv_group(&kio::Waiter::noop()).is_pending()); + + // Asking again lands on the new epoch. + let bare = consumer.request_broadcast("room/alice").await.unwrap(); + assert_eq!(read_video(&bare).await.1, b"new"); + } + + #[tokio::test] + async fn retracting_the_newest_epoch_falls_back_to_an_older_one() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let _old = publish_epoch(&producer, OLD, b"old"); + let (new, _track) = publish_epoch(&producer, NEW, b"new"); + + let bare = consumer.request_broadcast("room/alice").await.unwrap(); + let (mut following, payload) = read_video(&bare).await; + assert_eq!(payload, b"new"); + + new.close(); + assert!(matches!(next_group(&mut following).await, Err(Error::Unroutable))); + let bare = consumer.request_broadcast("room/alice").await.unwrap(); + assert_eq!(read_video(&bare).await.1, b"old"); + } + + #[tokio::test] + async fn the_last_epoch_retracting_ends_like_any_route() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let (old, _track) = publish_epoch(&producer, OLD, b"old"); + + let bare = consumer.request_broadcast("room/alice").await.unwrap(); + read_video(&bare).await; + old.unannounce(); + settle(|| bare.is_closed()).await; + assert!(matches!( + consumer.request_broadcast("room/alice").await, + Err(Error::Unroutable) + )); + } + + #[tokio::test] + async fn a_route_covering_the_name_beats_its_epochs() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let _new = publish_epoch(&producer, NEW, b"new"); + let raw = producer.publish("room/alice", Route::default()).unwrap(); + let track = raw.create_track("video", None).unwrap(); + let mut group = track.append_group().unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"raw".as_ref()).unwrap(); + group.finish().unwrap(); + + let bare = consumer.request_broadcast("room/alice").await.unwrap(); + assert_eq!(read_video(&bare).await.1, b"raw"); + } + + #[tokio::test] + async fn a_bare_follower_moves_to_a_route_covering_the_name() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let _new = publish_epoch(&producer, NEW, b"new"); + + let bare = consumer.request_broadcast("room/alice").await.unwrap(); + let (mut following, _) = read_video(&bare).await; + let _raw = producer.publish("room/alice", Route::default()).unwrap(); + assert!(matches!(next_group(&mut following).await, Err(Error::Unroutable))); + } + + #[tokio::test] + async fn routed_broadcast_follows_an_epoch_announced_later() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + + let routed = tokio::spawn({ + let consumer = consumer.clone(); + async move { consumer.routed_broadcast("room/alice").await } + }); + tokio::task::yield_now().await; + let _old = publish_epoch(&producer, OLD, b"old"); + let resolved = routed.await.unwrap().unwrap(); + assert_eq!(read_video(&resolved).await.1, b"old"); + + let route = consumer.routed("room/alice").await.unwrap(); + assert!(route.hops.is_empty()); + } + + #[tokio::test] + async fn an_epoch_through_the_requester_is_not_followed() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let _route = producer + .dynamic(epoch("room/alice", NEW), Route::default().with_hops(hops(&[10]))) + .unwrap(); + + assert!(matches!( + consumer + .clone() + .excluding(origin(10)) + .request_broadcast("room/alice") + .await, + Err(Error::Unroutable) + )); + let pending = consumer.request_broadcast("room/alice"); + assert!(pending.is_queued()); + } + + #[tokio::test] + async fn a_derived_name_follows_its_own_epochs() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let derived = epoch("room/alice", OLD).join("transcode"); + let _broadcast = producer + .publish(derived.join_epoch(Some(&NEW.parse().unwrap())), Route::default()) + .unwrap(); + + consumer.request_broadcast(&derived).await.unwrap(); + assert!(matches!( + consumer.request_broadcast("room/alice").await, + Err(Error::Unroutable) + )); + } + + #[tokio::test] + async fn a_grant_on_a_name_admits_its_epochs() { + let producer = origin(1).produce(); + let exact = Patterns::from(Pattern::literal("room/alice").unwrap()); + + // Publish: an exact grant admits the name's epochs, not its other children. + let publisher = producer.scope("", &exact).unwrap(); + let _broadcast = publisher.publish(epoch("room/alice", OLD), Route::default()).unwrap(); + assert!(matches!( + publisher.publish("room/alice/other", Route::default()), + Err(Error::Unauthorized) + )); + + // Subscribe: the same grant reaches the bare name, a pinned epoch, and sees it announced. + let viewer = producer.consume().scope("", &exact).unwrap(); + viewer.request_broadcast("room/alice").await.unwrap(); + viewer.request_broadcast(epoch("room/alice", OLD)).await.unwrap(); + viewer.announced().assert_next_active(epoch("room/alice", OLD)); + + // A grant on one epoch never widens to the bare name or a sibling epoch. + let one = Patterns::from(Pattern::literal(epoch("room/alice", OLD).as_str()).unwrap()); + let viewer = producer.consume().scope("", &one).unwrap(); + viewer.request_broadcast(epoch("room/alice", OLD)).await.unwrap(); + assert!(matches!( + viewer.request_broadcast("room/alice").await, + Err(Error::Unauthorized) + )); + assert!(matches!( + viewer.request_broadcast(epoch("room/alice", NEW)).await, + Err(Error::Unauthorized) + )); + } } diff --git a/rs/moq-net/src/path/mod.rs b/rs/moq-net/src/path/mod.rs index 7d06ea414f3..008388024f6 100644 --- a/rs/moq-net/src/path/mod.rs +++ b/rs/moq-net/src/path/mod.rs @@ -372,6 +372,11 @@ impl<'a> Path<'a> { } } + /// Append a freshly minted epoch, naming a new instance of this broadcast. + pub fn mint_epoch(&self) -> PathOwned { + self.join_epoch(Some(&crate::Epoch::mint())) + } + /// Resolve a [`Relative`] against this path. /// /// A non-empty reference replaces the last segment of the base, matching relative URL diff --git a/rs/moq-relay/tests/auth_embedder.rs b/rs/moq-relay/tests/auth_embedder.rs index 6c295340a93..471be2bae42 100644 --- a/rs/moq-relay/tests/auth_embedder.rs +++ b/rs/moq-relay/tests/auth_embedder.rs @@ -147,3 +147,49 @@ async fn a_moved_gateway_tier_retags_its_stats() { assert_eq!(active("gateway"), 0); work.abort(); } + +/// Admit one session holding `grant` for both roles. +async fn admit_both(cluster: &cluster::Cluster, grant: Grant) -> cluster::Admitted { + let (auth, mut admissions) = auth::Auth::embedded("edge"); + tokio::spawn(async move { + let admission = admissions.next().await.unwrap(); + admission.grant(lease::Consumer::fixed(grant)); + }); + cluster + .admit(&auth, auth.request(Transport::Rtmp, "/room")) + .await + .unwrap() +} + +#[tokio::test] +async fn an_exact_grant_admits_the_names_epochs_and_no_further() { + const OLD: &str = "room/alice/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f"; + const NEW: &str = "room/alice/@0199b7f4-3c2b-7d1e-9f0b-2b6c1a9d8e7f"; + let cluster = cluster::Cluster::new(cluster::Options::default()).unwrap(); + + let name = admit_both( + &cluster, + Grant::new(patterns(&["room/alice"]), patterns(&["room/alice"])), + ) + .await; + let publisher = name.publisher.as_ref().unwrap(); + let _old = publisher.publish(OLD, moq_net::origin::Route::default()).unwrap(); + assert!(matches!( + publisher.publish("room/alice/cam", moq_net::origin::Route::default()), + Err(moq_net::Error::Unauthorized) + )); + let subscriber = name.subscriber.as_ref().unwrap(); + subscriber.request_broadcast("room/alice").await.unwrap(); + subscriber.request_broadcast(OLD).await.unwrap(); + + // A grant on one epoch reaches that epoch only. + let one = admit_both(&cluster, Grant::new(Patterns::new(), patterns(&[OLD]))).await; + let subscriber = one.subscriber.as_ref().unwrap(); + subscriber.request_broadcast(OLD).await.unwrap(); + for path in ["room/alice", NEW] { + assert!(matches!( + subscriber.request_broadcast(path).await, + Err(moq_net::Error::Unauthorized) + )); + } +} From 63b2ea39c6b0799739860099eca6cc6beb862324 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 14:22:47 -0700 Subject: [PATCH 3/5] feat(net): settle epoch naming: with_epoch, epoch-free catalog base, end-only epochs - Rename Path::join_epoch / Path.joinEpoch to with_epoch / withEpoch, which set the final epoch (replacing any) and remove it for None. - An epoch only ends a path: publishing or serving a prefix with an epoch before its last segment fails with Error::MisplacedEpoch. - Relative references resolve against a base's name past its final epoch, so a catalog means the same whether fetched by name or by epoch; a reference follows its target's newest epoch unless it spells one. - Specify both in the hang and lite drafts and record the decisions in the broadcast-epoch line README. Co-Authored-By: Claude Opus 5.5 --- doc/concept/hang.md | 2 +- doc/concept/moq-lite.md | 19 +++++-- doc/lib/js/net.md | 2 +- doc/lib/rs/moq-net.md | 2 +- drafts/draft-lcurley-moq-hang.md | 4 ++ drafts/draft-lcurley-moq-lite.md | 3 +- js/net/src/origin.test.ts | 11 ++++ js/net/src/origin.ts | 11 ++++ js/net/src/path.test.ts | 37 +++++++++++- js/net/src/path.ts | 24 +++++--- quest/m0/broadcast-epoch/README.md | 23 +++++--- rs/moq-e2ee/README.md | 2 +- rs/moq-e2ee/src/tests.rs | 2 +- rs/moq-e2ee/tests/transport.rs | 2 +- rs/moq-net/src/error.rs | 15 +++-- rs/moq-net/src/model/origin.rs | 45 ++++++++++----- rs/moq-net/src/path/epoch.json | 6 +- rs/moq-net/src/path/mod.rs | 90 +++++++++++++++++++++++++----- 18 files changed, 233 insertions(+), 67 deletions(-) diff --git a/doc/concept/hang.md b/doc/concept/hang.md index 1a7bfb40f6a..a020361b534 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -53,7 +53,7 @@ every video rendition (display size, rotation, flip) sit at the section root. 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 track name used to subscribe, 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. +- **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, past any final `@` epoch, so a reference that escapes above the root names nothing and the catalog is rejected. A reference follows its target's newest [epoch](/concept/moq-lite#publisher-epochs) unless it spells one, which a transcoder does to pin the source run it read. - **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. - **Stalled renditions.** A publisher can flag a rendition as temporarily bad so players prefer another one without the track disappearing. First-party video publishers set this flag after more than three frame intervals of source silence or encoding lag while subscribed, and clear it after three on-time completed frames or when idle. Browser and native capture poll while waiting; FLV and MPEG-TS importers observe video silence as container data arrives. The shared detector is `hang::catalog::stalled::Detector` in Rust and `Catalog.Stalled.Detector` in JavaScript. It is a playback diagnostic, not an authorization or routing signal. diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 58aeffc5fce..5a5789f8df0 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -143,11 +143,15 @@ under a fresh one, so a restart is a new broadcast rather than a reused name: `path.mint_epoch()` in Rust and `Path.mintEpoch(path)` in TypeScript append a freshly minted epoch. The epoch segment counts toward the 32-part path limit. -`Path::join_epoch(Some(&epoch))` and `Path.joinEpoch(name, epoch)` append an -`@` segment. `Path::split_epoch()` and `Path.splitEpoch(path)` return -the name and optional epoch. Only the final segment and canonical UUIDv7 text -count: `@alice`, bare UUIDs, uppercase UUIDs, and other UUID versions remain -ordinary path segments. Existing path normalization still applies. +`Path::with_epoch(&epoch)` and `Path.withEpoch(path, epoch)` set the final +`@` segment, replacing any epoch already there, and +`with_epoch(None)` / `Path.withEpoch(path)` remove it. `Path::split_epoch()` and +`Path.splitEpoch(path)` return the name and optional epoch. Only the final +segment and canonical UUIDv7 text count: `@alice`, bare UUIDs, uppercase UUIDs, +and other UUID versions remain ordinary path segments. An epoch only ever ends +a path, so publishing `name/@/more` fails (`Error::MisplacedEpoch` in +Rust); a derived broadcast carries its source's epoch at its own end instead. +Existing path normalization still applies. The segment travels as part of the ordinary broadcast path on every supported wire version. Epochs do not hide a broadcast; a leading `.` in a name segment @@ -155,7 +159,10 @@ still does. A request for a bare name that no route covers resolves to its newest epoch: the greatest `name/@` with a live route. The broadcast is still named -`name`, so a catalog's relative references resolve against the name. When the +`name`. A catalog's relative references resolve against its name past any final +epoch, so they mean the same whether the catalog was requested by name or by +epoch, and a reference follows its target's newest epoch unless it spells one +(`./source/@`). When the name resolves elsewhere (a newer epoch, an older one once the newest is retracted, or a route covering the name itself), a Rust origin ends the broadcast and resets its tracks with `Unroutable`, and the next request lands diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 1b71d41c503..d0ee6170d85 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -10,7 +10,7 @@ description: The pub/sub layer in TypeScript The TypeScript twin of [`moq-net`](/lib/rs/moq-net): connections, origins, broadcasts, tracks, groups, and frames, negotiating moq-lite or moq-transport at setup. `Epoch` provides the shared publisher identity, and `Path.mintEpoch`, -`Path.splitEpoch`, and `Path.joinEpoch` carry it in the broadcast path; a +`Path.splitEpoch`, and `Path.withEpoch` carry it in the broadcast path; a request for the bare name follows the newest epoch. See [publisher epochs](/concept/moq-lite#publisher-epochs). diff --git a/doc/lib/rs/moq-net.md b/doc/lib/rs/moq-net.md index 2d237dc0d0e..45d34da777b 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -17,7 +17,7 @@ above ([hang](/lib/rs/hang)); relays and CDNs implement only this. - **Origins** scope what a session can see, and merge duplicate subscriptions so a broadcast is pulled upstream once no matter how many local readers. - **Broadcasts** are created unannounced and invisible to everyone, then announced as an exact route, or served below a prefix with `dynamic`. A consumer of the same origin sees exactly what a peer sees. Discovery accepts pattern unions; events carry the advertised prefix and captures for a complete match. -- **Epochs** identify publisher instances with a canonical UUIDv7 and explicit path helpers (`Path::mint_epoch`), and a request for the bare name follows the newest one; see [publisher epochs](/concept/moq-lite#publisher-epochs). +- **Epochs** identify publisher instances with a canonical UUIDv7 and explicit path helpers (`Path::mint_epoch`, `Path::with_epoch`), and a request for the bare name follows the newest one; see [publisher epochs](/concept/moq-lite#publisher-epochs). - **Patterns** (`Pattern`, `Patterns`) are re-exported from [`moq-pattern`](https://docs.rs/moq-pattern). Literal `Path` stays a coordinate. - **Tracks** carry groups with a priority, an optional publisher retention window (`Info::max_age`), and a timescale. Subscribers set their own priority and max age and can change them live. - **Groups** are written frame by frame and delivered on independent streams. Old groups are cached for fetch-by-sequence; stale groups are skipped per the subscriber's budget. diff --git a/drafts/draft-lcurley-moq-hang.md b/drafts/draft-lcurley-moq-hang.md index 52d5060e68b..9bb11fed52f 100644 --- a/drafts/draft-lcurley-moq-hang.md +++ b/drafts/draft-lcurley-moq-hang.md @@ -499,7 +499,10 @@ The `broadcast` field overrides that, naming a different broadcast that publishe The value is a relative path, resolved against the path of the broadcast that served the catalog. It uses relative reference resolution ({{!RFC3986, Section 5.2}}): a non-empty reference replaces the catalog broadcast's last path segment before applying `.` and `..` segments. For example, `./source` in a catalog served by `room/transcode` resolves to `room/source`, while `.` resolves to `room`. +A final epoch segment (see Epochs in {{moql}}) is not part of the base: a catalog served by `room/transcode/@` resolves `./source` to `room/source` too, so a reference means the same whether the catalog was requested by name or by epoch. An empty reference resolves to the catalog broadcast itself. +A reference names an epoch only when it spells one: `./source` follows the newest epoch of `room/source`, while `./source/@` pins that epoch. +A publisher whose renditions must come from one run, such as a transcoder referencing its source, SHOULD spell the epoch. A publisher MUST NOT use an absolute path, nor a reference that escapes above the root. The root is the consumer's authorized subtree, so such a reference names content the consumer cannot reach. A consumer MUST reject a catalog containing one, rather than resolving the reference against a different broadcast or ignoring the rendition. @@ -1091,6 +1094,7 @@ This document has no IANA actions. ## moq-hang-03 {:numbered="false"} +- A `broadcast` reference resolves against the catalog broadcast's name, past a final epoch segment, and follows the newest epoch of its target unless it spells one. - Defined encoder `jitter` as flush lateness above the rendition's own recent minimum, replacing fixed frame-duration hints; container batches retain media-span estimates. - Clarified that CMAF audio samples are sync samples independently of publisher group boundaries. - Clarified that container importers can estimate jitter from batch media spans without measuring input wait time. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 99192d82ea1..f3b728a2e9a 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -456,6 +456,7 @@ A receiver SHOULD NOT cache refusals; rate limiting is the advertiser's concern. #### Epochs {#epochs} A path whose final segment is `@` followed by a lowercase hyphenated UUIDv7 names one epoch of the path before it, its name. A publisher that may restart SHOULD publish each run under a fresh epoch, so a restart is a new Broadcast rather than a reused path. +An epoch only ever ends a path: a publisher MUST NOT announce a path with an epoch segment before its last, and a receiver MAY refuse such an announcement. The segment is ordinary path text on the wire. A request for a path naming no epoch that no route covers resolves to the greatest epoch one segment below it that a route covers; UUIDv7 text orders by creation time. @@ -1382,7 +1383,7 @@ The `Message Length` describes the payload size on the wire. - Added announce compression: ANNOUNCE_START gains `Path Base` and `Path Keep` to copy the head of a live advertisement's suffix, and ANNOUNCE_START and ANNOUNCE_UPDATE gain `Hop Base` and `Hop Keep` to copy the tail of a live advertisement's Hop ID list. - Capped the SETUP Message Length at 65,536 bytes. - A relay puts a random Hop ID, picked per session, in front of an announcement whose reconstructed path starts with 0, and writes that stamp followed by 0 for an empty path. -- Specified epochs: a final `@` segment names one run of a path, a request for an uncovered name resolves to its newest covered epoch, and a request that would move to another epoch is reset with UNROUTABLE. +- Specified epochs: a final `@` segment names one run of a path and never appears earlier, a request for an uncovered name resolves to its newest covered epoch, and a request that would move to another epoch is reset with UNROUTABLE. ## moq-lite-06 diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index 233f6c180c5..130f668801f 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -1900,3 +1900,14 @@ test("a grant on a name admits its epochs and a grant on an epoch only that one" broadcast.close(); origin.close(); }); + +test("an epoch only ends a path", () => { + const origin = new Producer(); + for (const path of [Path.join(OLD, Path.from("transcode")), Path.join(OLD, NEW.split("/").at(-1) as Path.Valid)]) { + expect(() => origin.createBroadcast(path)).toThrow("misplaced epoch"); + expect(() => origin.dynamic(path)).toThrow("misplaced epoch"); + } + // A derived broadcast carries the source's epoch at its own end instead. + origin.createBroadcast(Path.withEpoch(Path.from("room/alice/transcode"), Path.splitEpoch(OLD).epoch)).close(); + origin.close(); +}); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index 5803ea2f0dd..39eda47a0e6 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -125,6 +125,14 @@ class Scope { const EPOCH_SEGMENT: Path.Segment = { kind: "partial", prefix: "@", suffix: "" }; +/** Throw when an epoch (`@`) sits anywhere but the end of `path`; an epoch only ever ends a path. */ +function refuseMisplacedEpoch(path: Path.Valid) { + const parts = path === "" ? [] : path.split("/"); + if (parts.slice(0, -1).some((part) => Path.splitEpoch(part as Path.Valid).epoch !== undefined)) { + throw new Error(`misplaced epoch: an epoch must be the last path segment: ${path}`); + } +} + /** * `patterns` with each name they admit also admitting its epochs: a member not ending in * `**` gains a `/@*` sibling. A grant on one epoch names that epoch, so it never widens to @@ -803,6 +811,7 @@ export class Producer implements Table { */ createBroadcast(path: Path.Valid): broadcast.Producer { path = this.#scope.path(path); + refuseMisplacedEpoch(path); const created = this.#state.created; if (!created) throw new Error("origin is closed"); @@ -891,6 +900,8 @@ export class Producer implements Table { #insertRoute(prefix: Path.Valid, route: Route, originated: boolean): Dynamic { prefix = this.#scope.prefix(prefix); + // A peer's announcements are its own; only refuse what this origin originates. + if (originated) refuseMisplacedEpoch(prefix); const server = new ServeState(this.#scope.root); server.onChange = (path) => this.#state.refresh(path); const entry: RouteEntry = { diff --git a/js/net/src/path.test.ts b/js/net/src/path.test.ts index 4f814023521..5b88a5b78cc 100644 --- a/js/net/src/path.test.ts +++ b/js/net/src/path.test.ts @@ -333,7 +333,7 @@ const epochs = (await Bun.file(new URL("../../../rs/moq-net/src/path/epoch.json" valid: Array<{ text: string; unix_ms: number }>; invalid: string[]; ordered: string[]; - paths: Array<{ path: string; name: string; epoch: string | null }>; + paths: Array<{ path: string; name: string; epoch: string | null; misplaced?: boolean }>; }; test("shared epoch parse, reject, order and time vectors", () => { @@ -353,13 +353,44 @@ test("shared epoch path vectors", () => { const { name, epoch } = Path.splitEpoch(path); expect(name).toBe(row.name as Path.Valid); expect(epoch ?? null).toBe(row.epoch as Epoch.Valid | null); - expect(Path.joinEpoch(name, epoch)).toBe(path); + if (!row.misplaced) expect(Path.withEpoch(name, epoch)).toBe(path); + } +}); + +test("withEpoch sets the final epoch", () => { + const [old, next] = epochs.ordered.map(Epoch.parse); + const name = Path.from("room/alice"); + const pinned = Path.withEpoch(name, old); + expect(pinned).toBe(`room/alice/@${old}` as Path.Valid); + // Never stacks: an existing epoch is replaced, and `undefined` removes it. + expect(Path.withEpoch(pinned, next)).toBe(Path.withEpoch(name, next)); + expect(Path.withEpoch(pinned)).toBe(name); + expect(Path.withEpoch(name)).toBe(name); +}); + +test("references resolve against the name past its epoch", () => { + const [epoch, other] = epochs.ordered.map(Epoch.parse); + const name = Path.from("room/transcode"); + const pinned = Path.withEpoch(name, epoch); + for (const text of ["./source", ".", "../other", "transcode/sub"]) { + const rel = Path.normalizeRelative(text); + expect(Path.resolve(pinned, rel)).toBe(Path.resolve(name, rel)); + expect(Path.tryResolve(pinned, rel)).toBe(Path.tryResolve(name, rel)); + } + // The empty reference still names the catalog broadcast itself. + expect(Path.resolve(pinned, "" as Path.Relative)).toBe(pinned); + // And `relative` stays its inverse. + for (const text of ["room/source", `room/source/@${other}`, "room", "other"]) { + const target = Path.from(text); + const rel = Path.relative(target, pinned); + expect(rel).toBeDefined(); + expect(Path.resolve(pinned, rel as Path.Relative)).toBe(target); } }); test("epoch segments are literal pattern components", () => { const epoch = Epoch.parse(epochs.valid[1].text); - const path = Path.joinEpoch(Path.from("demo/video"), epoch); + const path = Path.withEpoch(Path.from("demo/video"), epoch); expect(Path.Pattern.parse("demo/**").matches(path)).toBe(true); expect(Path.Pattern.parse("demo/video/@*").matches(path)).toBe(true); expect(Path.Pattern.parse("demo/video").matches(path)).toBe(false); diff --git a/js/net/src/path.ts b/js/net/src/path.ts index e6d9543d710..28313a74b3b 100644 --- a/js/net/src/path.ts +++ b/js/net/src/path.ts @@ -217,6 +217,8 @@ export function normalizeRelative(rel: string): Relative { * resolution. `..` segments then pop another segment; other segments are appended. * `.` and empty segments are no-ops. Excess `..` once the base is empty is also a no-op * (subsequent named segments still append). An empty `rel` returns the base unchanged. + * A base's final epoch is not a segment here: `a/b/@` resolves like `a/b`, so a + * catalog's references mean the same whether it was requested by name or by epoch. * * Mirrors the Rust `Path::resolve`, used by hang catalogs to express * cross-broadcast track references (a rendition's `broadcast` field). @@ -231,7 +233,8 @@ export function normalizeRelative(rel: string): Relative { export function resolve(base: Valid, rel: Relative): Valid { if (rel === "") return base; - const segments = base === "" ? [] : base.split("/"); + const { name } = splitEpoch(base); + const segments = name === "" ? [] : name.split("/"); segments.pop(); for (const seg of rel.split("/")) { @@ -258,7 +261,8 @@ export function resolve(base: Valid, rel: Relative): Valid { export function tryResolve(base: Valid, rel: Relative): Valid | undefined { if (rel === "") return base; - const segments = base === "" ? [] : base.split("/"); + const { name } = splitEpoch(base); + const segments = name === "" ? [] : name.split("/"); segments.pop(); for (const seg of rel.split("/")) { @@ -308,8 +312,9 @@ export function relative(target: Valid, base: Valid): Relative | undefined { // since resolution replaces that segment rather than emitting it. if (target === base) return "" as Relative; - // Resolution replaces the base's last segment, so walk from its parent. - const dir = base === "" ? [] : base.split("/"); + // Resolution replaces the base's last segment, past any epoch, so walk from its parent. + const { name } = splitEpoch(base); + const dir = name === "" ? [] : name.split("/"); dir.pop(); const parts = target === "" ? [] : target.split("/"); @@ -356,12 +361,13 @@ export function splitEpoch(path: Valid): { name: Valid; epoch?: Epoch.Valid } { return { name: path }; } -/** Append an optional epoch as a final `@` segment. */ -export function joinEpoch(name: Valid, epoch?: Epoch.Valid): Valid { +/** `path` with its final epoch set to `epoch`, replacing any it has, or removed for `undefined`. */ +export function withEpoch(path: Valid, epoch?: Epoch.Valid): Valid { + const { name } = splitEpoch(path); return epoch === undefined ? name : join(name, from(`@${epoch}`)); } -/** Append a freshly minted epoch, naming a new instance of this broadcast. */ -export function mintEpoch(name: Valid): Valid { - return joinEpoch(name, Epoch.mint()); +/** `path` under a freshly minted epoch, naming a new instance of the broadcast. */ +export function mintEpoch(path: Valid): Valid { + return withEpoch(path, Epoch.mint()); } diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 87806d7bad8..11ed2da6c48 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -49,7 +49,20 @@ Decided: ends with an `Unroutable` reset, and the client's normal resubscribe lands on the new one. A route covering the name wins over its epochs. - A grant that admits a name admits its epochs (a `name/@*` sibling); a grant - on one epoch reaches only that epoch. + on one epoch reaches only that epoch. The sibling admits any single `@` + segment, not only UUIDv7 text, since a pattern cannot spell one (decided + 2026-10-05: accepted and documented). +- An epoch only ever ends a path (decided 2026-10-05). Publishing + `name/@e/more` fails with `MisplacedEpoch`, and `with_epoch` + (`Path.withEpoch` in TypeScript) replaces a final epoch rather than stacking + one, with `None` removing it. +- A catalog `broadcast` reference follows by default (decided 2026-10-05 in + #4817): it resolves against the catalog's name past its final epoch, so a + bare and a pinned fetch agree, and follows the target's newest epoch unless + it spells one. A transcoder pins its source by writing `./source/@`. +- Precedence and the move reset stay as built (decided 2026-10-05): any route + covering the name, an ancestor prefix included, wins over its epochs, and a + bare subscription that moves ends with `Unroutable` (0x36). - An unmodified third-party relay routes `foo/@` but never resolves a bare `foo`, since a route covers its descendants, not its parent. A bare-name viewer behind one needs a publisher that publishes the bare name. @@ -82,14 +95,6 @@ This README owns: consume behavior, takeover and fallback, bare-path resolution, and the bare-name opt-out. -Open: - -- Does a catalog `broadcast` reference by bare name pin the epoch its catalog - came from, or follow the newest? Settle it with - [Catalog track alias](/quest/m1/catalog-track-alias.md). Today a bare - request's broadcast is named by the bare name, so relative references - resolve against it and follow; a pinned request's are named under its epoch. - ## Required - [Retracted demand release](/quest/m0/broadcast-epoch/unannounce-demand-release.md) - a retracted broadcast's track demand is released when its last subscriber leaves, as before #4741 diff --git a/rs/moq-e2ee/README.md b/rs/moq-e2ee/README.md index c2cf2fa5b8c..448b1e137fc 100644 --- a/rs/moq-e2ee/README.md +++ b/rs/moq-e2ee/README.md @@ -23,7 +23,7 @@ authenticated channel. Every publisher instance mints a shared `moq_net::Epoch` ```rust let credential = Credential::new(credential::Config { context, kid, secret })?; let generation = credential.generation(moq_net::Epoch::mint()); -let path = credential.path("meeting.hang")?.join_epoch(Some(generation.epoch())); +let path = credential.path("meeting.hang")?.with_epoch(generation.epoch()); let name = generation.name("video")?; let producer = generation.produce(broadcast.create_track(name.as_str(), None)?)?; ``` diff --git a/rs/moq-e2ee/src/tests.rs b/rs/moq-e2ee/src/tests.rs index 072c6f573ad..e23ae704c54 100644 --- a/rs/moq-e2ee/src/tests.rs +++ b/rs/moq-e2ee/src/tests.rs @@ -344,7 +344,7 @@ fn path_joins_epoch() { let epoch = Epoch::mint(); let path = cred.path("meeting.hang").unwrap(); assert_eq!(path.as_str().len(), 22); - let full = path.join_epoch(Some(&epoch)); + let full = path.with_epoch(&epoch); let (opaque, parsed) = full.split_epoch(); assert_eq!(opaque, path); assert_eq!(parsed.unwrap(), epoch); diff --git a/rs/moq-e2ee/tests/transport.rs b/rs/moq-e2ee/tests/transport.rs index 42fb1f08869..8917201ade3 100644 --- a/rs/moq-e2ee/tests/transport.rs +++ b/rs/moq-e2ee/tests/transport.rs @@ -33,7 +33,7 @@ async fn connect_protected(version: Version, track: &str) -> Fixture { }) .unwrap(); let generation = cred.generation(Epoch::mint()); - let path = cred.path("meeting.hang").unwrap().join_epoch(Some(generation.epoch())); + let path = cred.path("meeting.hang").unwrap().with_epoch(generation.epoch()); let name = generation.name(track).unwrap(); let publisher = produce_origin(1); diff --git a/rs/moq-net/src/error.rs b/rs/moq-net/src/error.rs index eae8cb053b8..0ff1d8926ee 100644 --- a/rs/moq-net/src/error.rs +++ b/rs/moq-net/src/error.rs @@ -291,6 +291,10 @@ pub enum Error { #[error("invalid path: {0}")] InvalidPath(#[from] crate::InvalidPattern), + /// A path holds an epoch (`@`) before its last segment; an epoch only ever ends a path. + #[error("misplaced epoch: an epoch must be the last path segment")] + MisplacedEpoch, + /// A duplicate ID was used // The broadcast/track is a duplicate #[error("duplicate")] @@ -538,7 +542,8 @@ impl From<&Error> for SessionError { | Error::Encode(_) | Error::WrongSize | Error::BoundsExceeded(_) - | Error::InvalidPath(_) => Self::ProtocolViolation, + | Error::InvalidPath(_) + | Error::MisplacedEpoch => Self::ProtocolViolation, Error::App(app) => Self::App(*app), // A code we did not recognize, so we cannot say which space it came from. // Forwarding it into this one risks landing on a value that IS registered here @@ -576,9 +581,11 @@ impl From<&Error> for StreamError { Error::Timeout => Self::DeliveryTimeout, Error::GoingAway => Self::GoingAway, // Our own parse failure is, from the peer's side, a malformed track. - Error::Decode(_) | Error::BoundsExceeded(_) | Error::InvalidPath(_) | Error::MalformedTrack => { - Self::MalformedTrack - } + Error::Decode(_) + | Error::BoundsExceeded(_) + | Error::InvalidPath(_) + | Error::MisplacedEpoch + | Error::MalformedTrack => Self::MalformedTrack, Error::App(app) => Self::App(*app), // See the SessionError impl: an unregistered code carries no registry, so // re-sending the number could mistranslate it. diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 29b8dadd210..763c0ca8352 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -1573,7 +1573,8 @@ impl Producer { /// [`mount`](Self::mount), /// [`Error::BoundsExceeded`] if the full rooted path (an epoch segment /// included) exceeds [`Path::MAX_PARTS`], [`Error::InvalidPath`] if it holds a segment no - /// pattern can spell (`*` or `**`), or [`Error::Closed`] once the origin's + /// pattern can spell (`*` or `**`), [`Error::MisplacedEpoch`] if an epoch + /// segment comes before its last, or [`Error::Closed`] once the origin's /// [`Driver`] has been dropped. pub fn create_broadcast(&self, path: impl AsPath) -> Result { let path = path.as_path(); @@ -1588,6 +1589,9 @@ impl Producer { if full.parts().count() > Path::MAX_PARTS { return Err(BoundsExceeded.into()); } + if full.has_misplaced_epoch() { + return Err(Error::MisplacedEpoch); + } // A path only a pattern could spell (a `*` segment) advertises nowhere, so // refuse it here rather than publish a broadcast no cursor can see. let claim = prefix_claim(&full)?; @@ -1887,6 +1891,9 @@ impl Announcing { if requested.parts().count() > Path::MAX_PARTS { return Err(BoundsExceeded.into()); } + if requested.has_misplaced_epoch() { + return Err(Error::MisplacedEpoch); + } let claim = prefix_claim(&requested)?; if !producer.scope.allowed.overlaps(&claim) || !producer.scope.publishes(&requested) { return Err(Error::Unauthorized); @@ -3488,7 +3495,7 @@ impl OriginState { segments .into_iter() .filter_map(|text| text.parse::().ok()) - .map(|epoch| path.join_epoch(Some(&epoch))) + .map(|epoch| path.with_epoch(&epoch)) .find(|epoch| self.best_route(epoch, horizon, &none).is_some()) } } @@ -8722,7 +8729,7 @@ mod tests { const NEW: &str = "0199b7f4-3c2b-7d1e-9f0b-2b6c1a9d8e7f"; fn epoch(name: &str, epoch: &str) -> PathOwned { - Path::new(name).join_epoch(Some(&epoch.parse().unwrap())) + Path::new(name).with_epoch(&epoch.parse::().unwrap()) } /// Publish one epoch of `room/alice` with a `video` track holding one group. @@ -8891,19 +8898,29 @@ mod tests { } #[tokio::test] - async fn a_derived_name_follows_its_own_epochs() { + async fn an_epoch_only_ends_a_path() { let producer = origin(1).produce(); - let consumer = producer.consume(); - let derived = epoch("room/alice", OLD).join("transcode"); - let _broadcast = producer - .publish(derived.join_epoch(Some(&NEW.parse().unwrap())), Route::default()) + let source = epoch("room/alice", OLD); + for path in [ + source.join("transcode"), + source.with_epoch(&NEW.parse::().unwrap()).join("x"), + ] { + assert!(matches!( + producer.publish(&path, Route::default()), + Err(Error::MisplacedEpoch) + )); + assert!(matches!( + producer.dynamic(&path, Route::default()), + Err(Error::MisplacedEpoch) + )); + } + // A derived broadcast carries the source's epoch at its own end instead. + producer + .publish( + Path::new("room/alice/transcode").with_epoch(&OLD.parse::().unwrap()), + Route::default(), + ) .unwrap(); - - consumer.request_broadcast(&derived).await.unwrap(); - assert!(matches!( - consumer.request_broadcast("room/alice").await, - Err(Error::Unroutable) - )); } #[tokio::test] diff --git a/rs/moq-net/src/path/epoch.json b/rs/moq-net/src/path/epoch.json index fe51a8e82bc..c8965139438 100644 --- a/rs/moq-net/src/path/epoch.json +++ b/rs/moq-net/src/path/epoch.json @@ -84,7 +84,8 @@ { "path": "demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f/track", "name": "demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f/track", - "epoch": null + "epoch": null, + "misplaced": true }, { "path": "demo/@0199B7F4-3C2A-7D1E-9F0B-2B6C1A9D8E7F", @@ -99,7 +100,8 @@ { "path": "demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f/@0199b7f4-9e10-7f42-8a3c-5d7e2b1c0f9a", "name": "demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f", - "epoch": "0199b7f4-9e10-7f42-8a3c-5d7e2b1c0f9a" + "epoch": "0199b7f4-9e10-7f42-8a3c-5d7e2b1c0f9a", + "misplaced": true }, { "path": "demo/@0199b7f4-3c2a-4d1e-9f0b-2b6c1a9d8e7f", diff --git a/rs/moq-net/src/path/mod.rs b/rs/moq-net/src/path/mod.rs index 008388024f6..ecc0c6c56ae 100644 --- a/rs/moq-net/src/path/mod.rs +++ b/rs/moq-net/src/path/mod.rs @@ -364,23 +364,41 @@ impl<'a> Path<'a> { } } - /// Append an optional epoch as a final `@` segment. - pub fn join_epoch(&self, epoch: Option<&crate::Epoch>) -> PathOwned { - match epoch { - Some(epoch) => self.join(format!("@{epoch}")), - None => self.to_owned(), + /// This path with its final epoch set to `epoch`, replacing any it has, or removed for `None`. + pub fn with_epoch<'e>(&self, epoch: impl Into>) -> PathOwned { + let (name, _) = self.split_epoch(); + match epoch.into() { + Some(epoch) => name.join(format!("@{epoch}")), + None => name.to_owned(), } } - /// Append a freshly minted epoch, naming a new instance of this broadcast. + /// This path under a freshly minted epoch, naming a new instance of the broadcast. pub fn mint_epoch(&self) -> PathOwned { - self.join_epoch(Some(&crate::Epoch::mint())) + self.with_epoch(&crate::Epoch::mint()) + } + + /// Whether an epoch segment sits anywhere but the end, which no broadcast may publish. + pub(crate) fn has_misplaced_epoch(&self) -> bool { + let mut parts = self.parts().peekable(); + while let Some(part) = parts.next() { + if parts.peek().is_some() + && part + .strip_prefix('@') + .is_some_and(|text| text.parse::().is_ok()) + { + return true; + } + } + false } /// Resolve a [`Relative`] against this path. /// /// A non-empty reference replaces the last segment of the base, matching relative URL /// resolution. `..` segments then pop another segment; other segments are appended. + /// A base's final epoch is not a segment here: `a/b/@` resolves like `a/b`, so a + /// catalog's references mean the same whether it was requested by name or by epoch. /// Excess `..` is a no-op once the base is empty (subsequent named segments still append). /// An empty `rel` returns this path as an owned copy. /// @@ -401,7 +419,8 @@ impl<'a> Path<'a> { return self.to_owned(); } - let mut segments: Vec<&str> = self.parts().collect(); + let (name, _) = self.split_epoch(); + let mut segments: Vec<&str> = name.parts().collect(); segments.pop(); for seg in rel.as_str().split('/') { @@ -435,7 +454,8 @@ impl<'a> Path<'a> { return Some(self.to_owned()); } - let mut segments: Vec<&str> = self.parts().collect(); + let (name, _) = self.split_epoch(); + let mut segments: Vec<&str> = name.parts().collect(); segments.pop(); for seg in rel.as_str().split('/') { @@ -501,8 +521,9 @@ impl<'a> Path<'a> { return Some(Relative::empty()); } - // Resolution replaces the base's last segment, so walk from its parent. - let mut dir: Vec<&str> = base.parts().collect(); + // Resolution replaces the base's last segment, past any epoch, so walk from its parent. + let (name, _) = base.split_epoch(); + let mut dir: Vec<&str> = name.parts().collect(); dir.pop(); let target: Vec<&str> = self.parts().collect(); @@ -819,15 +840,58 @@ mod tests { let (name, epoch) = path.split_epoch(); assert_eq!(name.as_str(), row["name"].as_str().unwrap()); assert_eq!(epoch.as_ref().map(|epoch| epoch.as_str()), row["epoch"].as_str()); - assert_eq!(name.join_epoch(epoch.as_ref()), path); + let misplaced = row["misplaced"].as_bool().unwrap_or(false); + assert_eq!(path.has_misplaced_epoch(), misplaced, "{path}"); + if !misplaced { + assert_eq!(name.with_epoch(epoch.as_ref()), path); + } assert_eq!(path.is_hidden(), name.is_hidden()); } } + #[test] + fn with_epoch_sets_the_final_epoch() { + let old: crate::Epoch = "0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f".parse().unwrap(); + let new: crate::Epoch = "0199b7f4-3c2b-7d1e-9f0b-2b6c1a9d8e7f".parse().unwrap(); + let name = Path::new("room/alice"); + let pinned = name.with_epoch(&old); + assert_eq!(pinned.as_str(), format!("room/alice/@{old}")); + // Never stacks: an existing epoch is replaced, and `None` removes it. + assert_eq!(pinned.with_epoch(&new), name.with_epoch(&new)); + assert_eq!(pinned.with_epoch(None), name); + assert_eq!(name.with_epoch(None), name); + assert_eq!(pinned.mint_epoch().split_epoch().0, name); + } + + #[test] + fn references_resolve_against_the_name_past_its_epoch() { + let epoch: crate::Epoch = "0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f".parse().unwrap(); + let name = Path::new("room/transcode"); + let pinned = name.with_epoch(&epoch); + for rel in ["./source", ".", "../other", "transcode/sub"] { + let rel = Relative::new(rel); + assert_eq!(pinned.resolve(&rel), name.resolve(&rel), "{rel}"); + assert_eq!(pinned.try_resolve(&rel), name.try_resolve(&rel), "{rel}"); + } + // The empty reference still names the catalog broadcast itself. + assert_eq!(pinned.resolve(&Relative::empty()), pinned); + // And `relative` stays its inverse. + for target in [ + "room/source", + "room/source/@0199b7f4-3c2b-7d1e-9f0b-2b6c1a9d8e7f", + "room", + "other", + ] { + let target = Path::new(target); + let rel = target.relative(&pinned).unwrap(); + assert_eq!(pinned.resolve(&rel), target, "{target}"); + } + } + #[test] fn epoch_segments_are_literal_pattern_components() { let epoch: crate::Epoch = "0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f".parse().unwrap(); - let path = Path::new("demo/video").join_epoch(Some(&epoch)); + let path = Path::new("demo/video").with_epoch(&epoch); assert!("demo/**".parse::().unwrap().matches(path.as_str())); assert!("demo/video/@*".parse::().unwrap().matches(path.as_str())); assert!(!"demo/video".parse::().unwrap().matches(path.as_str())); From ffa7e285c00bb00fc5cbcc3de6f5404375ba4ab1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 6 Oct 2026 00:56:40 -0700 Subject: [PATCH 4/5] feat(net)!: bare names bind once and stay sticky; only epochs resume across routes - A bare request binds once, at request time, to its newest announced epoch, ahead of any route covering the name, and otherwise to the covering route. It never moves: a newer epoch is a different broadcast. Drops the follow and reset-on-move logic. - A path without an epoch is pinned to the route that first served it and ends when that route goes, so unrelated content is never stitched. Epoch paths keep resuming across routes. - JS gives epochs the same precedence; a swap of `active` is already a new broadcast, never a splice. - Moves the failover tests and the handoff bench onto epoch paths, adds pinning tests, renames the follow bench to bind, and specifies the rules in the lite draft, concept docs, and the line README. Co-Authored-By: Claude Opus 5.5 --- doc/concept/hang.md | 2 +- doc/concept/moq-lite.md | 46 +-- drafts/draft-lcurley-moq-hang.md | 4 +- drafts/draft-lcurley-moq-lite.md | 16 +- js/net/src/origin.test.ts | 19 +- js/net/src/origin.ts | 9 +- quest/m0/broadcast-epoch/README.md | 53 ++-- quest/m0/broadcast-epoch/bindings.md | 2 +- quest/m0/broadcast-epoch/ts-restart.md | 5 +- rs/moq-mux/src/container/consumer.rs | 8 +- rs/moq-net/benches/origin.rs | 19 +- rs/moq-net/src/model/front.rs | 19 +- rs/moq-net/src/model/origin.rs | 378 +++++++++++++++---------- rs/moq-net/tests/route_change.rs | 19 +- rs/moq-relay/tests/goaway_cluster.rs | 12 +- rs/moq-tokio/tests/broadcast.rs | 14 +- 16 files changed, 377 insertions(+), 248 deletions(-) diff --git a/doc/concept/hang.md b/doc/concept/hang.md index a020361b534..8c6fdaaf639 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -53,7 +53,7 @@ every video rendition (display size, rotation, flip) sit at the section root. 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 track name used to subscribe, 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, past any final `@` epoch, so a reference that escapes above the root names nothing and the catalog is rejected. A reference follows its target's newest [epoch](/concept/moq-lite#publisher-epochs) unless it spells one, which a transcoder does to pin the source run it read. +- **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, past any final `@` epoch, so a reference that escapes above the root names nothing and the catalog is rejected. A reference binds to its target's newest [epoch](/concept/moq-lite#publisher-epochs) when requested unless it spells one, which a transcoder does to pin the source run it read. - **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. - **Stalled renditions.** A publisher can flag a rendition as temporarily bad so players prefer another one without the track disappearing. First-party video publishers set this flag after more than three frame intervals of source silence or encoding lag while subscribed, and clear it after three on-time completed frames or when idle. Browser and native capture poll while waiting; FLV and MPEG-TS importers observe video silence as container data arrives. The shared detector is `hang::catalog::stalled::Detector` in Rust and `Catalog.Stalled.Detector` in JavaScript. It is a playback diagnostic, not an authorization or routing signal. diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 5a5789f8df0..014fc7a4de1 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -96,9 +96,12 @@ always a prefix, on every wire version and on moq-transport alike; a service that serves only some of the paths beneath its prefix refuses the rest as they are requested. Each route carries the chain of relay identities it passed through, which is how forwarding loops are caught, and a cost, which is how a -subscriber picks among several routes to the same broadcast. A path names one -broadcast whoever publishes it, so a subscription moves between routes without -a seam; a publisher must not reuse a path for different content. A hop of 0 is +subscriber picks among several routes to the same broadcast. A path naming an +[epoch](#publisher-epochs) is one broadcast from one publisher, so a subscription +to it moves between routes without a seam; a publisher must not reuse an epoch +for different content. A path without an epoch carries no such promise (two +transcoder claimants may serve different bytes), so its subscription stays on +the route that first served it and ends when that route goes. A hop of 0 is the anonymous mark and travels the chain unchanged; when it is the first hop, a relay puts a random ID, fresh per connection, in front of it. A route that passed through an anonymous hop at any depth ranks below every fully identified route, whatever @@ -157,23 +160,28 @@ The segment travels as part of the ordinary broadcast path on every supported wire version. Epochs do not hide a broadcast; a leading `.` in a name segment still does. -A request for a bare name that no route covers resolves to its newest epoch: -the greatest `name/@` with a live route. The broadcast is still named -`name`. A catalog's relative references resolve against its name past any final +A request for a bare name binds once, when made, to its newest epoch: the +greatest `name/@` with a live route, ahead of any route covering the +name. With no epoch it goes through a route covering the name, such as a +transcoder's claim, and stays on that route. The broadcast is still named +`name`, and it never moves to a newer epoch, which is a different broadcast: in +Rust it ends with the epoch it was bound to, and the next request binds to the +newest. In TypeScript a request is long-lived, so its `active` broadcast swaps +to the newer epoch as a new broadcast, and js/watch restarts its decoders on it. +A path naming an epoch pins it and never moves. A smart subscriber watches the +announcements below a name and requests each epoch by its full path, treating +a new one as a discontinuity. + +A catalog's relative references resolve against its name past any final epoch, so they mean the same whether the catalog was requested by name or by -epoch, and a reference follows its target's newest epoch unless it spells one -(`./source/@`). When the -name resolves elsewhere (a newer epoch, an older one once the newest is -retracted, or a route covering the name itself), a Rust origin ends the -broadcast and resets its tracks with `Unroutable`, and the next request lands -on the new resolution; it never splices one epoch into another. In TypeScript -the request's `active` broadcast swaps to the new one. A path naming an epoch -pins it and never moves. A relay resolves bare requests this way for every -client and protocol version, so an older client subscribing by name keeps -working, provided it resubscribes after an `Unroutable` reset. A relay without this support routes -`name/@` but never resolves bare `name`, since a route covers its -descendants, not its parent: a bare-name viewer behind one needs a publisher -that publishes the bare name itself. +epoch, and a reference binds to its target's newest epoch when requested unless it spells one +(`./source/@`). + +A relay resolves bare requests this way for every client and protocol +version, so an older client subscribing by name keeps working. A relay without +this support routes `name/@` but never resolves bare `name`, since a +route covers its descendants, not its parent: a bare-name viewer behind one +needs a publisher that publishes the bare name itself. A grant that admits a name also admits its epochs: an exact `room/camera` grant reaches `room/camera/@` for publishing and subscribing, and diff --git a/drafts/draft-lcurley-moq-hang.md b/drafts/draft-lcurley-moq-hang.md index 9bb11fed52f..47729b0e14c 100644 --- a/drafts/draft-lcurley-moq-hang.md +++ b/drafts/draft-lcurley-moq-hang.md @@ -501,7 +501,7 @@ It uses relative reference resolution ({{!RFC3986, Section 5.2}}): a non-empty r For example, `./source` in a catalog served by `room/transcode` resolves to `room/source`, while `.` resolves to `room`. A final epoch segment (see Epochs in {{moql}}) is not part of the base: a catalog served by `room/transcode/@` resolves `./source` to `room/source` too, so a reference means the same whether the catalog was requested by name or by epoch. An empty reference resolves to the catalog broadcast itself. -A reference names an epoch only when it spells one: `./source` follows the newest epoch of `room/source`, while `./source/@` pins that epoch. +A reference names an epoch only when it spells one: `./source` is a bare request, bound to the newest epoch of `room/source` when the consumer makes it, while `./source/@` pins that epoch. A publisher whose renditions must come from one run, such as a transcoder referencing its source, SHOULD spell the epoch. A publisher MUST NOT use an absolute path, nor a reference that escapes above the root. The root is the consumer's authorized subtree, so such a reference names content the consumer cannot reach. @@ -1094,7 +1094,7 @@ This document has no IANA actions. ## moq-hang-03 {:numbered="false"} -- A `broadcast` reference resolves against the catalog broadcast's name, past a final epoch segment, and follows the newest epoch of its target unless it spells one. +- A `broadcast` reference resolves against the catalog broadcast's name, past a final epoch segment, and is requested by bare name, binding to its target's newest epoch, unless it spells one. - Defined encoder `jitter` as flush lateness above the rendition's own recent minimum, replacing fixed frame-duration hints; container batches retain media-span estimates. - Clarified that CMAF audio samples are sync samples independently of publisher group boundaries. - Clarified that container importers can estimate jitter from batch media spans without measuring input wait time. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index f3b728a2e9a..423f447c05f 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -118,7 +118,8 @@ Any broadcasts and subscriptions are transparently proxied by the CDN behind the ## Broadcast A Broadcast is a collection of Tracks named by a path. This corresponds to a MoqTransport's "track namespace". -A path names one Broadcast whichever publisher serves it: a publisher MUST NOT reuse a path for different content, and publishes a new instance under a new path instead. +A path naming an epoch (see [Epochs](#epochs)) names one Broadcast from one publisher, whichever relay serves it: a publisher MUST NOT reuse an epoch for different content, and publishes a new instance under a new epoch instead. +A path without an epoch makes no such promise: two publishers of one such path, such as two claimants of a transcoder's prefix, may serve different content. A publisher advertises what it can serve via ANNOUNCE_START messages, each carrying a path prefix: a route covering every broadcast path beneath it. A route is the only shape an advertisement takes: a publisher that serves only some of the paths beneath a prefix, such as a transcoder for any broadcast's derivative, advertises the covering prefix and refuses the requests it will not serve (see [Resolution](#resolution)); no message narrows a route. @@ -425,7 +426,8 @@ Applying one rule to both advertisement and dispatch keeps advertised paths trut When resolving a path covered by several routes (across any number of streams), the subscriber SHOULD prefer the most specific covering route (see [Resolution](#resolution)), then a path that contains no 0 Hop ID over one that does, then the lowest Warm Route Cost after adding each arriving link's cost (see [Cost Parameter](#cost-parameter)), breaking ties toward the lowest Cold Route Cost, then toward the shortest path, and then toward the most recently received, so a reconnecting publisher is not outranked by the stale session it replaced. -Every route covering a path serves the same Broadcast, so a relay MAY move a live subscription between them, continuing from the first frame the subscriber lacks, and a route change (a reconnect, a cheaper path, a draining session) is invisible to the subscriber. +Every route serving a path that names an epoch serves the same Broadcast, so a relay MAY move a live subscription between them, continuing from the first frame the subscriber lacks, and a route change (a reconnect, a cheaper path, a draining session) is invisible to the subscriber. +For any other path, a relay MUST NOT move a live subscription to another route, whose content may differ: the subscription stays on the route that first served it and ends when that route goes, and a repeated request resolves afresh. #### Resolution {#resolution} A SUBSCRIBE, FETCH, or TRACK request names a path, and the receiver resolves it against the routes covering that path, after the per-subscriber exclusion above. @@ -459,9 +461,11 @@ A publisher that may restart SHOULD publish each run under a fresh epoch, so a r An epoch only ever ends a path: a publisher MUST NOT announce a path with an epoch segment before its last, and a receiver MAY refuse such an announcement. The segment is ordinary path text on the wire. -A request for a path naming no epoch that no route covers resolves to the greatest epoch one segment below it that a route covers; UUIDv7 text orders by creation time. -When the path later resolves elsewhere (a newer epoch, an older one once the newest is retracted, or a route covering the path), the receiver MUST reset the request with UNROUTABLE rather than move it to a different Broadcast, and a repeated request resolves afresh. +A request for a path naming no epoch resolves to the greatest epoch one segment below it that a route covers, ahead of any route covering the path itself; UUIDv7 text orders by creation time. +With no such epoch, it resolves through a route covering the path, as any other path does. +The request is bound once, when it is received: a newer epoch is a different Broadcast, and the receiver MUST NOT move the request to it, so the request ends with the epoch it was bound to and a repeated request resolves afresh. A request naming an epoch never moves. +A subscriber that wants each new epoch as it appears watches the announcements below the name and requests each epoch by its full path, treating the switch as a discontinuity. This is receiver behavior on every version: a receiver without it finds no route covering the path, and the request is unroutable. ### Subscribe @@ -1372,7 +1376,7 @@ The `Message Length` describes the payload size on the wire. - The subscriber FINs its Subscribe Stream after settling its tail; graceful session close waits for that FIN or reset. - Made TRACK_INFO Publisher Max Age optional, encoded as milliseconds plus one with zero meaning no limit. - Added `Largest Group` and `Largest Frame` to SUBSCRIBE_OK: the publisher's largest position when it answers, which a subscriber takes as where the live feed is. A publisher MUST answer at once when the requested start is past it. Earlier versions carry no such position, so a subscriber takes the first frame instead. -- A path names one Broadcast whichever publisher serves it, and a publisher MUST NOT reuse a path for different content. A relay MAY move a subscription between any routes covering the path, continuing from the first frame the subscriber lacks instead of at a group boundary. Replaces the first-hop identity. +- A path naming an epoch names one Broadcast whichever relay serves it, and a publisher MUST NOT reuse an epoch for different content. A relay MAY move a subscription between routes serving an epoch path, continuing from the first frame the subscriber lacks instead of at a group boundary, and MUST NOT move one for a path without an epoch. Replaces the first-hop identity. - Assigned `moq-lite-07-wip` as this draft's protocol identifier until it is finalized as `moq-lite-07`. - Switched every variable-length integer, including SETUP parameter values, from QUIC's two-bit length prefix to moq-transport's leading-ones encoding, widening the range to 64 bits. @@ -1383,7 +1387,7 @@ The `Message Length` describes the payload size on the wire. - Added announce compression: ANNOUNCE_START gains `Path Base` and `Path Keep` to copy the head of a live advertisement's suffix, and ANNOUNCE_START and ANNOUNCE_UPDATE gain `Hop Base` and `Hop Keep` to copy the tail of a live advertisement's Hop ID list. - Capped the SETUP Message Length at 65,536 bytes. - A relay puts a random Hop ID, picked per session, in front of an announcement whose reconstructed path starts with 0, and writes that stamp followed by 0 for an empty path. -- Specified epochs: a final `@` segment names one run of a path and never appears earlier, a request for an uncovered name resolves to its newest covered epoch, and a request that would move to another epoch is reset with UNROUTABLE. +- Specified epochs: a final `@` segment names one run of a path and never appears earlier, a request for a bare name binds once to its newest covered epoch ahead of a route covering the name, and never moves to a newer one. ## moq-lite-06 diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index 130f668801f..b4a85135d3e 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -1865,24 +1865,25 @@ test("a received epoch serves a bare request through its session", async () => { origin.close(); }); -test("a route covering the name beats its epochs", async () => { +test("an epoch beats a route covering the name", async () => { const origin = new Producer(); const consumer = origin.consume(); const epoch = publish(origin, NEW); const raw = publish(origin, Path.from("room/alice")); const request = consumer.request(Path.from("room/alice")); - const active = request.active.peek(); - const own = consumer.request(Path.from("room/alice")); - expect(active?.path).toBe(Path.from("room/alice")); - raw.close(); + const fromEpoch = request.active.peek(); + expect(fromEpoch).toBeDefined(); + // Served from the epoch: once it goes, the bare name falls through to its own route, + // as a new broadcast. Had the route won, nothing would change here. + epoch.close(); await settle(); - expect(request.active.peek()).not.toBe(active); - expect(request.active.peek()).toBeDefined(); + const fromRoute = request.active.peek(); + expect(fromRoute).toBeDefined(); + expect(fromRoute).not.toBe(fromEpoch); - own.close(); request.close(); - epoch.close(); + raw.close(); origin.close(); }); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index 39eda47a0e6..d2a0e83cd0e 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -668,13 +668,12 @@ class OriginState { } /** - * The path a request for `path` is served from: `path` itself when anything routes it, - * otherwise the newest epoch below it that something routes. A path naming an epoch - * pins it. Mirrors Rust's resolution, so a bare name follows its newest live epoch and - * falls back to an older one when the newest goes away. + * The path a request for `path` is served from: the newest epoch below a bare `path` + * that something routes, ahead of any route covering the name, otherwise `path` itself. + * A path naming an epoch pins it. Mirrors Rust's resolution; a request re-reads it, so + * a bare name's `active` swaps to a newer epoch as a new broadcast, never a continuation. */ target(path: Path.Valid): Path.Valid { - if (this.local.peek()?.has(path) || this.bestEntry(path)) return path; if (Path.splitEpoch(path).epoch !== undefined) return path; let newest: Path.Valid | undefined; const consider = (candidate: Path.Valid) => { diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 11ed2da6c48..ddca5b049e2 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -11,8 +11,9 @@ route lingers, is resumed into the old broadcast and stalls viewers until its sequence catches up. Each first-party publish of `demo/BBB.hang` goes out as -`demo/BBB.hang/@`, so a restart is a new broadcast. A viewer of the -bare name follows the newest live epoch as soon as it is announced. Moving to +`demo/BBB.hang/@`, so a restart is a new broadcast. A smart viewer +switches to the newest epoch as soon as it is announced, and a bare-name viewer +binds to the newest when it subscribes. Moving to a new epoch is a clean boundary (a fresh catalog and tracks, never resumed across), and each run stays addressable by its full path. @@ -41,13 +42,21 @@ Decided: already carries one"). Minting is one call: `Path::mint_epoch` in Rust and `Path.mintEpoch` in TypeScript append a fresh `@`. Each first-party publisher calls it once per run; a redundant pair passes a shared epoch. -- Viewers follow the greatest epoch with a live route. When it goes away and an - older one is still live, they fall back to it. -- A bare request with no route covering the name resolves to that same epoch - on every version, so lite-06 and IETF clients keep working through an - epoch-aware relay. When the name resolves elsewhere, the bare subscription - ends with an `Unroutable` reset, and the client's normal resubscribe lands on - the new one. A route covering the name wins over its epochs. +- Smart subscribers use epochs natively (decided 2026-10-05 in #4817): they + watch the announcements below a name, request each epoch by its full path, + and treat a new epoch as a discontinuity (a fresh decoder). Dumb subscribers + use bare names and are sticky. +- A bare request binds once, when made, to the newest epoch with a live route, + ahead of any route covering the name (a fully qualified epoch wins). With no + epoch it goes through the covering route, such as an on-demand transcode + claim, which never announces its output. The binding never moves: a newer + epoch is a different broadcast, and the request ends with the epoch it bound + to. In TypeScript the long-lived request's `active` swaps to the newer epoch + as a new broadcast. +- Only an epoch names one origin, so only an epoch path resumes across routes. + A path without an epoch stays on the route that first served it and ends + when that route goes; it is never stitched (decided 2026-10-05). Two + unrelated epochs are never stitched either. - A grant that admits a name admits its epochs (a `name/@*` sibling); a grant on one epoch reaches only that epoch. The sibling admits any single `@` segment, not only UUIDv7 text, since a pattern cannot spell one (decided @@ -56,13 +65,10 @@ Decided: `name/@e/more` fails with `MisplacedEpoch`, and `with_epoch` (`Path.withEpoch` in TypeScript) replaces a final epoch rather than stacking one, with `None` removing it. -- A catalog `broadcast` reference follows by default (decided 2026-10-05 in +- A catalog `broadcast` reference is bare by default (decided 2026-10-05 in #4817): it resolves against the catalog's name past its final epoch, so a - bare and a pinned fetch agree, and follows the target's newest epoch unless - it spells one. A transcoder pins its source by writing `./source/@`. -- Precedence and the move reset stay as built (decided 2026-10-05): any route - covering the name, an ancestor prefix included, wins over its epochs, and a - bare subscription that moves ends with `Unroutable` (0x36). + bare and a pinned fetch agree, and binds to the target's newest epoch when + requested unless it spells one. A transcoder pins its source by writing `./source/@`. - An unmodified third-party relay routes `foo/@` but never resolves a bare `foo`, since a route covers its descendants, not its parent. A bare-name viewer behind one needs a publisher that publishes the bare name. @@ -80,19 +86,20 @@ Decided: release) moved under it, and the OBS half of GStreamer and OBS moved to m1 as [OBS publishes under epochs](/quest/m1/obs-epoch.md), so the release gate no longer waits on m1 work. -- Derived output mirrors the epoch it came from - (`.pro/transcode//foo.hang/@e`, per the - [wildcard](/quest/m0/wildcard/README.md) line's derived-output layout), so - the service's prefix claim still covers it. +- Derived output served on demand through a claim stays bare and sticky per + relay (decided 2026-10-05): a worker dying costs its subscribers one reset + and a cold start on the next claimant, never a splice. Whether that removes + the [wildcard](/quest/m0/wildcard/README.md) line's mirrored-epoch and + group-start requirements is the wildcard line's call. This README owns: - An end-to-end relay test: republish a name while the old publisher's session - stays open. A new-API viewer and a lite-06 or IETF bare-path viewer both - reach the new epoch within one RTT-scale bound rather than the idle timeout. - Killing the newest epoch falls back to a still-live older one. + stays open. A new-API viewer following announcements reaches the new epoch + within one RTT-scale bound rather than the idle timeout, and a lite-06 or + IETF bare-path viewer that resubscribes binds to it. - A `doc/concept` page on broadcast naming: what an epoch is, publish and - consume behavior, takeover and fallback, bare-path resolution, and the + consume behavior, smart and sticky subscribers, bare-path binding, and the bare-name opt-out. ## Required diff --git a/quest/m0/broadcast-epoch/bindings.md b/quest/m0/broadcast-epoch/bindings.md index 15fe36bd9e3..c8dcaf07635 100644 --- a/quest/m0/broadcast-epoch/bindings.md +++ b/quest/m0/broadcast-epoch/bindings.md @@ -3,7 +3,7 @@ ## Goal `moq-ffi` and the py, swift, kt, go, and dart wrappers make minting an epoch -one call (publishing does not mint one by default) and follow bare names like +one call (publishing does not mint one by default) and bind bare names like Rust. The generated C and C++ bindings pick it up from moq-ffi; libmoq gets no new API. The epoch of a published or consumed broadcast is readable, and a caller can pass an explicit one. The diff --git a/quest/m0/broadcast-epoch/ts-restart.md b/quest/m0/broadcast-epoch/ts-restart.md index 95e1f9874c9..76bd24dc460 100644 --- a/quest/m0/broadcast-epoch/ts-restart.md +++ b/quest/m0/broadcast-epoch/ts-restart.md @@ -20,8 +20,9 @@ and a flagged forward jump publishes break markers and carries on. Decided (maintainer, 2026-09-30): - A rewind is new content, so it is always a new broadcast at a new epoch - path (`Path::mint_epoch`), never a continuation of the old name. Viewers of - the bare name follow it through the origin's newest-epoch resolution. + path (`Path::mint_epoch`), never a continuation of the old name. Smart viewers + switch to it from its announcement; a bare-name viewer binds to it on its + next subscribe. - `decode` stops at the flagged rewind and reports it. The caller finishes the old broadcast (a clean end, not an abort, so its viewers read to its end), publishes a new broadcast at a fresh epoch path, and calls diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 9d99686ce9b..0c3fa226a18 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -1646,14 +1646,16 @@ mod tests { #[tokio::test(start_paused = true)] async fn truncated_resumed_group_skips_to_the_next_clean_group() { let origin = crate::source::produce_origin(); + // Only an epoch path resumes across routes. + let live = moq_net::Path::new("live").mint_epoch(); let hops = moq_net::Hops::try_from(vec![moq_net::Hop::new(10).unwrap()]).unwrap(); let first_route = origin .dynamic( - "live", + &live, moq_net::origin::Route::default().with_hops(hops.clone()).with_cost(5), ) .unwrap(); - let pending = origin.consume().request_broadcast("live"); + let pending = origin.consume().request_broadcast(&live); let first = moq_net::broadcast::Info::new().produce(); let info = hang::container::track_info(hang::catalog::PRIORITY.video); let first_track = first.create_track("video", info.clone()).unwrap(); @@ -1690,7 +1692,7 @@ mod tests { for sequence in 1..=4 { let route = origin .dynamic( - "live", + &live, moq_net::origin::Route::default() .with_hops(hops.clone()) .with_cost(5 - sequence), diff --git a/rs/moq-net/benches/origin.rs b/rs/moq-net/benches/origin.rs index 50ea6fbfefd..fa61591a7d1 100644 --- a/rs/moq-net/benches/origin.rs +++ b/rs/moq-net/benches/origin.rs @@ -421,11 +421,11 @@ fn bench_request(c: &mut Criterion) { group.finish(); } -/// Resolving a bare name to its newest epoch, with `names` names in the table +/// Binding a bare name to its newest epoch, with `names` names in the table /// each published under `epochs` live epochs: the walk reads only the epochs /// one segment below the requested name, so `names` must not show. -fn bench_follow(c: &mut Criterion) { - let mut group = c.benchmark_group("origin/follow"); +fn bench_bind(c: &mut Criterion) { + let mut group = c.benchmark_group("origin/bind"); for names in [100, 1_000] { for epochs in [1, 8, 64] { let (producer, mut driver) = origin::Producer::new(origin::Config::default()); @@ -458,13 +458,14 @@ fn bench_follow(c: &mut Criterion) { group.finish(); } -/// Publisher handoff at one path: a subscriber is reading from one local +/// Publisher handoff at one epoch path: a subscriber is reading from one local /// source when a second announces at the same path and takes over (newest -/// wins). Measured from the standby's attach to the subscriber receiving its +/// wins). Only an epoch path resumes across sources. Measured from the standby's attach to the subscriber receiving its /// first group, with `publishers` unrelated broadcasts in the table. fn bench_handoff(c: &mut Criterion) { let mut group = c.benchmark_group("origin/handoff"); group.measurement_time(Duration::from_secs(5)); + let live = moq_net::Path::new("room/live").mint_epoch(); for publishers in [1, 1_000] { group.bench_function(BenchmarkId::from_parameter(format!("{publishers}p")), |b| { let runtime = tokio::runtime::Builder::new_current_thread() @@ -483,18 +484,18 @@ fn bench_handoff(c: &mut Criterion) { runtime.block_on(async { let mut total = Duration::ZERO; for _ in 0..iterations { - let incumbent = producer.publish("room/live", origin::Route::default()).unwrap(); + let incumbent = producer.publish(&live, origin::Route::default()).unwrap(); let track = incumbent.create_track("video", None).unwrap(); let mut first = track.append_group().unwrap(); first.write_frame(Timestamp::ZERO, b"one".as_ref()).unwrap(); first.finish().unwrap(); - let resolved = consumer.request_broadcast("room/live").await.unwrap(); + let resolved = consumer.request_broadcast(&live).await.unwrap(); let mut subscription = resolved.track("video").unwrap().subscribe(None).await.unwrap(); subscription.recv_group().await.unwrap().expect("first group"); let started = std::time::Instant::now(); - let standby = producer.create_broadcast("room/live").unwrap(); + let standby = producer.create_broadcast(&live).unwrap(); let track = standby.create_track("video", None).unwrap(); let mut second = track.create_group(moq_net::group::Info { sequence: 1 }).unwrap(); second.write_frame(Timestamp::ZERO, b"two".as_ref()).unwrap(); @@ -638,7 +639,7 @@ criterion_group!( bench_serve_idle, bench_subscribe, bench_request, - bench_follow, + bench_bind, bench_handoff, bench_relay, bench_parked diff --git a/rs/moq-net/src/model/front.rs b/rs/moq-net/src/model/front.rs index b7b00c19bdb..49795d1a506 100644 --- a/rs/moq-net/src/model/front.rs +++ b/rs/moq-net/src/model/front.rs @@ -9,10 +9,11 @@ //! sources, the tracks, the clock) and executes the actions; see //! `origin::run_front`. //! -//! A path names one broadcast, whoever serves it, so any route covering the path -//! may take over from another and its tracks resume where they stopped. A -//! publisher reusing a name for different content is a bug; it publishes under a -//! new name (an epoch) instead. +//! A path naming an epoch names one origin's broadcast, whoever relays it, so any +//! route serving it may take over from another and its tracks resume where they +//! stopped. A path without an epoch carries no such promise: the driver keeps it +//! on the route that first served it (see `origin::run_front`), and the machine +//! never sees another. //! //! Sources and tracks are named by ids and names, never handles, so a //! transition can be checked in a unit test by comparing the actions it emits. @@ -224,6 +225,16 @@ impl Front { self.serving.map(|(source, _)| source) } + /// The route the attached source came through, if any. + pub(super) fn serving_route(&self) -> Option { + self.serving.map(|(_, candidate)| candidate) + } + + /// Whether a source ever attached: the front has served bytes. + pub(super) fn has_served(&self) -> bool { + self.resolved + } + /// Whether the front is over. #[cfg(test)] fn ended(&self) -> bool { diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 763c0ca8352..f61264e2341 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -2256,15 +2256,12 @@ struct FrontTask { shared: kio::Shared, /// The broadcast the front serves. broadcast: broadcast::Producer, - /// Absolute path the front selects routes for and requests through. + /// Absolute path the front selects routes for and requests through: its own, + /// or the epoch a bare name was bound to. path: PathOwned, - /// The bare name the front was requested at, when `path` is the epoch it - /// resolved to. The front ends once the name resolves elsewhere. - follows: Option, /// The requesters' horizon, applied to every (re)selection. horizon: Horizon, - /// Wakes the front when a route covering its path, or an epoch below the - /// name it follows, changes. + /// Wakes the front when a route covering its path changes. watch: Watch, /// Resolves the requesters parked on the front's channel. request: kio::Producer, @@ -2351,7 +2348,6 @@ async fn run_front(task: FrontTask) { shared, broadcast, path, - follows, horizon, watch, request, @@ -2383,48 +2379,41 @@ async fn run_front(task: FrontTask) { // The watch generation the last selection saw. let mut seen = 0; let mut events: VecDeque = VecDeque::new(); - // The followed name resolved to another epoch (or its own route): the front - // ends, and its tracks with it, so readers ask again and land there. - let mut moved = false; + // Only an epoch names one origin, so only its routes are interchangeable. A + // path without one stays on the route that first served it: it never resumes + // through another, whose bytes may differ, and ends once that route is gone. + let pinned = path.split_epoch().1.is_none(); // Read the table for the machine: the best route and whether // the serving source is on its way out. Also what the watch wakes for. - let select = - |front: &mut Front, sources: &HashMap, seen: &mut u64, moved: &mut bool| -> Event { - let table = shared.read(); - if table.closed { - return Event::Closed; - } - // Read alongside the decision, under the lock a poke takes first. - *seen = watch.seen(); - // Moving to another epoch is a new broadcast, never a splice. A name with - // nothing left to resolve to ends like any retraction instead. - if let Some(name) = &follows - && table - .resolve(&name.as_path(), horizon) - .is_some_and(|resolved| resolved != path) - { - *moved = true; - return Event::Selected { - best: None, - serving_closing: false, - }; - } - front.retain_routes(|route| table.routes.covers(&path.as_path(), route)); - let best = table - .best_route(&path.as_path(), horizon, front.refused_routes()) - .map(|entry| Candidate { - route: entry.id, - local: entry.local, - }); - let serving_closing = front - .serving() - .and_then(|id| sources.get(&id)) - .is_some_and(|source| source.is_closing()); - Event::Selected { best, serving_closing } - }; + let select = |front: &mut Front, sources: &HashMap, seen: &mut u64| -> Event { + let table = shared.read(); + if table.closed { + return Event::Closed; + } + // Read alongside the decision, under the lock a poke takes first. + *seen = watch.seen(); + front.retain_routes(|route| table.routes.covers(&path.as_path(), route)); + let serving_closing = front + .serving() + .and_then(|id| sources.get(&id)) + .is_some_and(|source| source.is_closing()); + if pinned && front.has_served() { + let best = front + .serving_route() + .filter(|serving| table.routes.covers(&path.as_path(), serving.route)); + return Event::Selected { best, serving_closing }; + } + let best = table + .best_route(&path.as_path(), horizon, front.refused_routes()) + .map(|entry| Candidate { + route: entry.id, + local: entry.local, + }); + Event::Selected { best, serving_closing } + }; - events.push_back(select(&mut front, &sources, &mut seen, &mut moved)); + events.push_back(select(&mut front, &sources, &mut seen)); loop { while let Some(event) = events.pop_front() { @@ -2434,7 +2423,7 @@ async fn run_front(task: FrontTask) { }; for action in front.step(event) { match action { - Action::Reselect => events.push_back(select(&mut front, &sources, &mut seen, &mut moved)), + Action::Reselect => events.push_back(select(&mut front, &sources, &mut seen)), Action::Request { route } => { // The entry and what it serves. let found = { @@ -2628,14 +2617,6 @@ async fn run_front(task: FrontTask) { // subscriptions already in flight): their readers follow the copy // they read to its end, since no front is left to replace it. broadcast.close(); - // A followed name moved: nothing carries on, so each reader is - // reset and its next request lands on what the name resolves to now. - if moved { - for (_, mut io) in tracks.drain() { - io.end(Err(Error::Unroutable)); - } - return; - } for (_, mut io) in tracks.drain() { let used = io.weak.is_used(); // A reader still waiting on its source's answer is in flight @@ -2851,7 +2832,7 @@ async fn run_front(task: FrontTask) { deadline.set(None); Event::Deadline { now: timers.now() } } - Step::Table => select(&mut front, &sources, &mut seen, &mut moved), + Step::Table => select(&mut front, &sources, &mut seen), }; events.push_back(event); } @@ -3470,33 +3451,33 @@ impl OriginState { } /// The path a request for the absolute `path` is served from, for a requester - /// seeing `horizon`: `path` itself when a route covers it, otherwise the newest - /// epoch below it that a route serves. `None` when nothing serves it. + /// seeing `horizon`: the newest epoch below a bare `path` that a route serves, + /// otherwise `path` itself when a route covers it. `None` when nothing serves it. fn resolve(&self, path: &Path, horizon: Horizon) -> Option { let none: HashSet = HashSet::new(); - if self.best_route(path, horizon, &none).is_some() { - return Some(path.to_owned()); - } - // A path naming an epoch pins it: there is nothing newer to follow. - if path.split_epoch().1.is_some() { - return None; + // A fully qualified epoch wins over a route covering the bare name. A path + // naming an epoch pins it: there is nothing newer to bind to. + if path.split_epoch().1.is_none() + && let (_, Some(node)) = self.routes.split(path) + { + // Canonical UUIDv7 text orders by mint time, so the greatest is the newest. + // Sorted as text and parsed lazily: the newest is usually the one served. + let mut segments: Vec<&str> = node + .children + .keys() + .filter_map(|segment| segment.strip_prefix('@')) + .collect(); + segments.sort_unstable_by(|a, b| b.cmp(a)); + let newest = segments + .into_iter() + .filter_map(|text| text.parse::().ok()) + .map(|epoch| path.with_epoch(&epoch)) + .find(|epoch| self.best_route(epoch, horizon, &none).is_some()); + if newest.is_some() { + return newest; + } } - let (_, Some(node)) = self.routes.split(path) else { - return None; - }; - // Canonical UUIDv7 text orders by mint time, so the greatest is the newest. - // Sorted as text and parsed lazily: the newest is usually the one served. - let mut segments: Vec<&str> = node - .children - .keys() - .filter_map(|segment| segment.strip_prefix('@')) - .collect(); - segments.sort_unstable_by(|a, b| b.cmp(a)); - segments - .into_iter() - .filter_map(|text| text.parse::().ok()) - .map(|epoch| path.with_epoch(&epoch)) - .find(|epoch| self.best_route(epoch, horizon, &none).is_some()) + self.best_route(path, horizon, &none).map(|_| path.to_owned()) } } @@ -4249,8 +4230,8 @@ impl Consumer { /// Block until `path` resolves to a broadcast: [`Self::request_broadcast`], /// retried whenever the routes covering the path, or the epochs below a bare - /// name, change. To follow a bare name across epochs, call it again once the - /// broadcast it returned ends. + /// name, change. To switch to a newer epoch as soon as it appears, watch + /// [`Self::announced`] and request it by its full path. /// /// A request answers for the routes as they stand, so it can miss an /// announcement that has not arrived yet, lose its covering route to @@ -4330,18 +4311,20 @@ impl Consumer { /// the best announced route covering it (the most specific prefix, then the /// cheapest, a broadcast published on this origin winning ties) and /// materializes it, from the broadcast itself or from the peer that - /// announced the route. When its serving source dies or a better route - /// appears, the front switches to the best remaining route, invisibly to - /// subscribers: a path names one broadcast, whoever serves it. Its route - /// retracting with no replacement ends the broadcast, and the next request - /// re-serves the path. Tracks already in flight carry on to their own end. + /// announced the route. For a path naming an epoch, which names one origin, + /// the front switches to the best remaining route when its serving source dies + /// or a better route appears, invisibly to subscribers. A path without an epoch + /// stays on the route that first served it, since another route's bytes may + /// differ, and ends once that route goes. Either way, the broadcast ends when + /// nothing it may use is left, and the next request re-serves the path. + /// Tracks already in flight carry on to their own end. /// - /// A bare name no route covers resolves to its newest epoch: the greatest - /// `path/@` a route serves. The broadcast is still named `path`, and - /// follows that one epoch: once the name resolves elsewhere (a newer epoch, an - /// older one after the newest is retracted, or a route covering the name), it - /// ends and so do its tracks, with [`Error::Unroutable`], so the next request - /// lands on the new resolution. A path naming an epoch pins it. + /// A bare name binds once, at request time, to its newest epoch: the greatest + /// `path/@` a route serves, ahead of any route covering the name. With + /// no epoch it binds to a route covering the name itself. The broadcast is + /// still named `path` and never moves: a newer epoch is a different broadcast, + /// served to later requests, and the bound one ends with its epoch. A path + /// naming an epoch pins it. /// /// The returned future fails with [`Error::Unroutable`] at once when no /// announced route covers the path, including a broadcast created on this @@ -4399,8 +4382,8 @@ impl Consumer { .with_stats(scope); return kio::Pending::new(pending); } - // The front follows an epoch the name has since moved off, and ends - // on its next selection: serve the newcomer from a fresh one. + // The front stays bound to an older epoch for its own readers, and a + // newcomer binds to the newest: a fresh front, never the old one moved. state.fronts.remove(&key); } @@ -4415,7 +4398,7 @@ impl Consumer { }); let request = kio::Producer::::default(); let consumer = request.consume(); - let watch = state.watch(&self.shared, &absolute); + let watch = state.watch(&self.shared, &target); state.fronts.insert( key, RemoteFront { @@ -4430,7 +4413,6 @@ impl Consumer { self.tasks.push(run_front(FrontTask { shared: self.shared.clone(), broadcast, - follows: (target != absolute).then_some(absolute), path: target, horizon: self.horizon, watch, @@ -5807,20 +5789,28 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); - let _local = producer.publish("room/alice", Route::default().with_cost(5)).unwrap(); + let _local = producer + .publish(epoch("room/alice", OLD), Route::default().with_cost(5)) + .unwrap(); let first = consumer - .request_broadcast("room/alice") + .request_broadcast(epoch("room/alice", OLD)) .await .expect("resolves locally"); let server = producer - .dynamic("room/alice", Route::default().with_hops(hops(&[10])).with_cost(1)) + .dynamic( + epoch("room/alice", OLD), + Route::default().with_hops(hops(&[10])).with_cost(1), + ) .unwrap(); let request = queued(&server).await; let upstream = broadcast::Info::new().produce(); request.accept(&upstream); - let second = consumer.request_broadcast("room/alice").await.expect("resolves"); + let second = consumer + .request_broadcast(epoch("room/alice", OLD)) + .await + .expect("resolves"); assert!(first.is_clone(&second), "the newcomer joins the front"); } @@ -6050,9 +6040,12 @@ mod tests { async fn takeover_keeps_the_open_group_head(dies_first: bool) { let producer = origin(1).produce(); let first_server = producer - .dynamic("room/alice", Route::default().with_hops(hops(&[10])).with_cost(5)) + .dynamic( + epoch("room/alice", OLD), + Route::default().with_hops(hops(&[10])).with_cost(5), + ) .unwrap(); - let pending = producer.consume().request_broadcast("room/alice"); + let pending = producer.consume().request_broadcast(epoch("room/alice", OLD)); let upstream = broadcast::Info::new().produce(); let mut dynamic = upstream.dynamic(); queued(&first_server).await.accept(&upstream); @@ -6097,7 +6090,10 @@ mod tests { } let cost = if dies_first { 5 } else { 0 }; let replacement_server = producer - .dynamic("room/alice", Route::default().with_hops(hops(&[10])).with_cost(cost)) + .dynamic( + epoch("room/alice", OLD), + Route::default().with_hops(hops(&[10])).with_cost(cost), + ) .unwrap(); let replacement = broadcast::Info::new().produce(); let mut replacement_dynamic = replacement.dynamic(); @@ -7267,7 +7263,7 @@ mod tests { impl ResumeRig { /// Announce a served route with `first` as its first hop, materialize - /// "room/alice" through it with a one-group "before" track, and subscribe. + /// epoch("room/alice", OLD) through it with a one-group "before" track, and subscribe. async fn new(first: &[u64]) -> (Self, Dynamic, broadcast::Producer) { let producer = origin(1).produce(); let consumer = producer.consume(); @@ -7276,7 +7272,7 @@ mod tests { .dynamic("room", Route::default().with_hops(hops(first))) .unwrap(); - let pending = consumer.request_broadcast("room/alice"); + let pending = consumer.request_broadcast(epoch("room/alice", OLD)); let request = queued(&server).await; let source = broadcast::Info::new().produce(); let track = source.create_track("video", None).unwrap(); @@ -7445,7 +7441,12 @@ mod tests { let frame = group.read_frame().await.expect("read frame").expect("frame"); assert_eq!(&frame.payload[..], b"after", "first hop {first:?}"); - let resolved = rig.producer.consume().request_broadcast("room/alice").await.unwrap(); + let resolved = rig + .producer + .consume() + .request_broadcast(epoch("room/alice", OLD)) + .await + .unwrap(); assert!(resolved.is_clone(&rig.resolved), "first hop {first:?} left the front"); assert!( standby.poll_requested_broadcast(&kio::Waiter::noop()).is_pending(), @@ -7473,7 +7474,7 @@ mod tests { .dynamic("room", Route::default().with_hops(hops(&[10, 7]))) .unwrap(); - let pending = consumer.request_broadcast("room/alice"); + let pending = consumer.request_broadcast(epoch("room/alice", OLD)); let request = queued(&incumbent).await; let source = broadcast::Info::new().produce(); let track = source.create_track("video", None).unwrap(); @@ -8046,9 +8047,12 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); - let first = producer.publish("room/alice", Route::default()).unwrap(); + let first = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); let track = first.create_track("video", None).unwrap(); - let resolved = consumer.request_broadcast("room/alice").await.expect("resolves"); + let resolved = consumer + .request_broadcast(epoch("room/alice", OLD)) + .await + .expect("resolves"); let mut subscription = resolved .track("video") .unwrap() @@ -8062,7 +8066,7 @@ mod tests { assert_eq!(&group.read_frame().await.unwrap().unwrap().payload[..], b"before"); // The newest source is dispatched the track, and refused for its metadata. - let second = producer.publish("room/alice", Route::default()).unwrap(); + let second = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); let _incompatible = second .create_track("video", track::Info::default().with_timescale(crate::Timescale::MICRO)) .unwrap(); @@ -8096,7 +8100,7 @@ mod tests { let server = producer .dynamic("room", Route::default().with_hops(hops(&[10]))) .unwrap(); - let pending = producer.consume().request_broadcast("room/alice"); + let pending = producer.consume().request_broadcast(epoch("room/alice", OLD)); let upstream = broadcast::Info::new().produce(); let old = upstream.create_track("video", None).unwrap(); queued(&server).await.accept(&upstream); @@ -8117,7 +8121,7 @@ mod tests { async fn an_unread_draining_track_releases_the_old_source() { let (producer, _server, _upstream, old, subscription) = remote_front().await; - let newcomer = producer.create_broadcast("room/alice").unwrap(); + let newcomer = producer.create_broadcast(epoch("room/alice", OLD)).unwrap(); let mut handler = newcomer.dynamic(); newcomer.announce(Route::default()).unwrap(); let _unanswered = tokio::time::timeout(Duration::from_secs(1), handler.requested_track()) @@ -8139,10 +8143,14 @@ mod tests { #[tokio::test(start_paused = true)] async fn a_returning_reader_is_not_stranded_on_a_dropped_copy() { let (producer, _server, upstream, old, mut subscription) = remote_front().await; - let resolved = producer.consume().request_broadcast("room/alice").await.unwrap(); + let resolved = producer + .consume() + .request_broadcast(epoch("room/alice", OLD)) + .await + .unwrap(); // No handler and no track: refuses "video" with NotFound. - let _second = producer.publish("room/alice", Route::default()).unwrap(); + let _second = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); for _ in 0..10 { tokio::task::yield_now().await; } @@ -8159,7 +8167,7 @@ mod tests { .expect("parked") .expect("open"); - let _third = producer.publish("room/alice", Route::default()).unwrap(); + let _third = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); for _ in 0..10 { tokio::task::yield_now().await; } @@ -8192,9 +8200,12 @@ mod tests { async fn a_refused_copy_is_not_kept_subscribed() { let producer = origin(1).produce(); let consumer = producer.consume(); - let first = producer.publish("room/alice", Route::default()).unwrap(); + let first = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); let track = first.create_track("video", None).unwrap(); - let resolved = consumer.request_broadcast("room/alice").await.expect("resolves"); + let resolved = consumer + .request_broadcast(epoch("room/alice", OLD)) + .await + .expect("resolves"); let mut subscription = resolved.track("video").unwrap().subscribe(None).await.unwrap(); let mut group = track.append_group().unwrap(); group.write_frame(crate::Timestamp::ZERO, b"before".as_ref()).unwrap(); @@ -8202,7 +8213,7 @@ mod tests { let mut group = subscription.recv_group().await.unwrap().unwrap(); assert_eq!(&group.read_frame().await.unwrap().unwrap().payload[..], b"before"); - let second = producer.publish("room/alice", Route::default()).unwrap(); + let second = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); let incompatible = second .create_track("video", track::Info::default().with_timescale(crate::Timescale::MICRO)) .unwrap(); @@ -8275,9 +8286,12 @@ mod tests { async fn the_end_keeps_the_copy_still_serving() { let producer = origin(1).produce(); let consumer = producer.consume(); - let first = producer.publish("room/alice", Route::default()).unwrap(); + let first = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); let track = first.create_track("video", None).unwrap(); - let resolved = consumer.request_broadcast("room/alice").await.expect("resolves"); + let resolved = consumer + .request_broadcast(epoch("room/alice", OLD)) + .await + .expect("resolves"); let mut subscription = resolved.track("video").unwrap().subscribe(None).await.unwrap(); let mut group = track.append_group().unwrap(); group.write_frame(crate::Timestamp::ZERO, b"before".as_ref()).unwrap(); @@ -8286,7 +8300,7 @@ mod tests { assert_eq!(&group.read_frame().await.unwrap().unwrap().payload[..], b"before"); drop(group); - let second = producer.create_broadcast("room/alice").unwrap(); + let second = producer.create_broadcast(epoch("room/alice", OLD)).unwrap(); let mut handler = second.dynamic(); second.announce(Route::default()).unwrap(); let request = tokio::time::timeout(Duration::from_secs(1), handler.requested_track()) @@ -8776,42 +8790,50 @@ mod tests { } #[tokio::test] - async fn a_newer_epoch_resets_bare_readers() { + async fn a_bare_request_stays_on_its_epoch() { let producer = origin(1).produce(); let consumer = producer.consume(); - let _old = publish_epoch(&producer, OLD, b"old"); + let (_old, old_track) = publish_epoch(&producer, OLD, b"old"); let bare = consumer.request_broadcast("room/alice").await.unwrap(); - let pinned = consumer.request_broadcast(epoch("room/alice", OLD)).await.unwrap(); let (mut following, payload) = read_video(&bare).await; assert_eq!(payload, b"old"); - let (mut staying, _) = read_video(&pinned).await; + // A newer epoch is a different broadcast: the bound request never moves to it. let _new = publish_epoch(&producer, NEW, b"new"); - // The takeover is a typed reset, never a splice into the new epoch. - assert!(matches!(next_group(&mut following).await, Err(Error::Unroutable))); - settle(|| bare.is_closed()).await; - assert!(!pinned.is_closed(), "a pinned epoch never moves"); - assert!(staying.poll_recv_group(&kio::Waiter::noop()).is_pending()); + let mut group = old_track.append_group().unwrap(); + group + .write_frame(crate::Timestamp::ZERO, b"still old".as_ref()) + .unwrap(); + group.finish().unwrap(); + let mut group = next_group(&mut following) + .await + .unwrap() + .expect("the old epoch carries on"); + assert_eq!(&group.read_frame().await.unwrap().unwrap().payload[..], b"still old"); + assert!(!bare.is_closed()); - // Asking again lands on the new epoch. - let bare = consumer.request_broadcast("room/alice").await.unwrap(); - assert_eq!(read_video(&bare).await.1, b"new"); + // A later request binds to the newest. + let later = consumer.request_broadcast("room/alice").await.unwrap(); + assert!(!later.is_clone(&bare)); + assert_eq!(read_video(&later).await.1, b"new"); } #[tokio::test] - async fn retracting_the_newest_epoch_falls_back_to_an_older_one() { + async fn a_bare_request_ends_with_its_epoch() { let producer = origin(1).produce(); let consumer = producer.consume(); let _old = publish_epoch(&producer, OLD, b"old"); - let (new, _track) = publish_epoch(&producer, NEW, b"new"); + let (new, track) = publish_epoch(&producer, NEW, b"new"); let bare = consumer.request_broadcast("room/alice").await.unwrap(); let (mut following, payload) = read_video(&bare).await; assert_eq!(payload, b"new"); - new.close(); - assert!(matches!(next_group(&mut following).await, Err(Error::Unroutable))); + // Never spliced into the older epoch still live: the binding ends with its epoch. + drop((new, track)); + assert!(!matches!(next_group(&mut following).await, Ok(Some(_)))); + settle(|| bare.is_closed()).await; let bare = consumer.request_broadcast("room/alice").await.unwrap(); assert_eq!(read_video(&bare).await.1, b"old"); } @@ -8833,10 +8855,11 @@ mod tests { } #[tokio::test] - async fn a_route_covering_the_name_beats_its_epochs() { + async fn an_epoch_beats_a_route_covering_the_name() { let producer = origin(1).produce(); let consumer = producer.consume(); let _new = publish_epoch(&producer, NEW, b"new"); + let _claim = producer.dynamic("room", Route::default()).unwrap(); let raw = producer.publish("room/alice", Route::default()).unwrap(); let track = raw.create_track("video", None).unwrap(); let mut group = track.append_group().unwrap(); @@ -8844,19 +8867,84 @@ mod tests { group.finish().unwrap(); let bare = consumer.request_broadcast("room/alice").await.unwrap(); - assert_eq!(read_video(&bare).await.1, b"raw"); + assert_eq!(read_video(&bare).await.1, b"new"); + } + + /// A worker's answer for bare `room/alice`: its broadcast, its `video` track, + /// and that track's open group. + type Worker = (broadcast::Producer, track::Producer, crate::group::Producer); + + /// Serve bare `room/alice` through `server` with a `video` track holding one + /// open group that has written `payload`. + async fn serve_bare(server: &Dynamic, payload: &'static [u8]) -> Worker { + let request = queued(server).await; + let source = broadcast::Info::new().produce(); + let track = source.create_track("video", None).unwrap(); + let mut group = track.append_group().unwrap(); + group.write_frame(crate::Timestamp::ZERO, payload).unwrap(); + request.accept(&source); + (source, track, group) } #[tokio::test] - async fn a_bare_follower_moves_to_a_route_covering_the_name() { + async fn a_bare_path_stays_on_its_first_route() { let producer = origin(1).produce(); let consumer = producer.consume(); - let _new = publish_epoch(&producer, NEW, b"new"); + let first = producer + .dynamic("room/alice", Route::default().with_hops(hops(&[10])).with_cost(5)) + .unwrap(); - let bare = consumer.request_broadcast("room/alice").await.unwrap(); - let (mut following, _) = read_video(&bare).await; - let _raw = producer.publish("room/alice", Route::default()).unwrap(); - assert!(matches!(next_group(&mut following).await, Err(Error::Unroutable))); + let pending = consumer.request_broadcast("room/alice"); + let (_source, _track, mut open) = serve_bare(&first, b"first").await; + let bare = pending.await.unwrap(); + let mut subscription = bare.track("video").unwrap().subscribe(None).await.unwrap(); + let mut reading = next_group(&mut subscription).await.unwrap().unwrap(); + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"first"); + + // A cheaper route serving the same bare path is never asked: its bytes may differ. + let cheaper = producer + .dynamic("room/alice", Route::default().with_hops(hops(&[11])).with_cost(1)) + .unwrap(); + for _ in 0..10 { + tokio::task::yield_now().await; + } + assert!(cheaper.poll_requested_broadcast(&kio::Waiter::noop()).is_pending()); + open.write_frame(crate::Timestamp::ZERO, b"more".as_ref()).unwrap(); + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"more"); + } + + /// Two claimants serve one bare path with different bytes. Killing the serving one + /// mid-group ends the subscription instead of resuming it on the other. + #[tokio::test] + async fn a_bare_path_never_resumes_on_another_route() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let first = producer + .dynamic("room/alice", Route::default().with_hops(hops(&[10]))) + .unwrap(); + let second = producer + .dynamic("room/alice", Route::default().with_hops(hops(&[11])).with_cost(5)) + .unwrap(); + + let pending = consumer.request_broadcast("room/alice"); + let (source, track, open) = serve_bare(&first, b"worker one").await; + let bare = pending.await.unwrap(); + let mut subscription = bare.track("video").unwrap().subscribe(None).await.unwrap(); + let mut reading = next_group(&mut subscription).await.unwrap().unwrap(); + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"worker one"); + + drop((open, track, source, first)); + // The open group and the track end; nothing from the other worker is spliced in. + assert!(!matches!(reading.read_frame().await, Ok(Some(_)))); + assert!(!matches!(next_group(&mut subscription).await, Ok(Some(_)))); + settle(|| bare.is_closed()).await; + assert!(second.poll_requested_broadcast(&kio::Waiter::noop()).is_pending()); + + // Asking again binds afresh, to the survivor. + let pending = consumer.request_broadcast("room/alice"); + let _worker = serve_bare(&second, b"worker two").await; + let again = pending.await.unwrap(); + assert!(!again.is_clone(&bare)); } #[tokio::test] diff --git a/rs/moq-net/tests/route_change.rs b/rs/moq-net/tests/route_change.rs index 417d1fc249b..5d7b19a0469 100644 --- a/rs/moq-net/tests/route_change.rs +++ b/rs/moq-net/tests/route_change.rs @@ -1,8 +1,8 @@ //! A subscription survives its route changing, end to end over real sessions. //! //! A publisher `P` is pulled by two relays `A` and `B`, both of which re-advertise -//! it to the subscribing relay `R`. A path is one broadcast whoever serves it, so `R` -//! may resume a subscription served through one onto the other. The reader on `R` +//! it to the subscribing relay `R`. A path naming an epoch is one broadcast whoever +//! relays it, so `R` may resume a subscription served through one onto the other. The reader on `R` //! must see every frame exactly once, in order, whether the route changes between //! groups or in the middle of one, and however it changes. @@ -19,6 +19,9 @@ const TEST_TIMEOUT: Duration = Duration::from_secs(30); /// Frames per group. const FRAMES: u64 = 4; +/// The broadcast, under an epoch: only an epoch path resumes across routes. +const LIVE: &str = "live/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f"; + fn produce_origin(hop: u64) -> origin::Producer { let (producer, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); tokio::spawn(support::harness::run(driver)); @@ -86,7 +89,7 @@ impl Topology { let relay_b = produce_origin(3); let subscriber = produce_origin(4); - let broadcast = publisher.create_broadcast("live").unwrap(); + let broadcast = publisher.create_broadcast(LIVE).unwrap(); let track = broadcast.create_track("video", None).unwrap(); broadcast.announce(Default::default()).unwrap(); @@ -95,8 +98,8 @@ impl Topology { let a_to_r = link(version, &relay_a, &subscriber).await; let consumer = subscriber.consume(); - consumer.routed("live").await.unwrap(); - let remote = consumer.request_broadcast("live").await.unwrap(); + consumer.routed(LIVE).await.unwrap(); + let remote = consumer.request_broadcast(LIVE).await.unwrap(); let prefs = track::Subscription::default().with_max_age(Duration::from_secs(60)); let sub = remote.track("video").unwrap().subscribe(prefs).await.unwrap(); @@ -354,8 +357,8 @@ async fn lagging_route_dies(version: Version) -> mpsc::UnboundedReceiver<(u64, m } async fn subscribe(origin: &origin::Producer) -> track::Subscriber { let consumer = origin.consume(); - consumer.routed("live").await.unwrap(); - let remote = consumer.request_broadcast("live").await.unwrap(); + consumer.routed(LIVE).await.unwrap(); + let remote = consumer.request_broadcast(LIVE).await.unwrap(); let preferences = track::Subscription::default().with_max_age(Duration::from_secs(60)); remote.track("video").unwrap().subscribe(preferences).await.unwrap() } @@ -371,7 +374,7 @@ async fn lagging_route_dies(version: Version) -> mpsc::UnboundedReceiver<(u64, m produce_origin(4), produce_origin(5), ); - let broadcast = p.create_broadcast("live").unwrap(); + let broadcast = p.create_broadcast(LIVE).unwrap(); let track = broadcast.create_track("video", None).unwrap(); broadcast.announce(Default::default()).unwrap(); let p_a = lagged(version, &p, &a, Duration::from_millis(300)).await; diff --git a/rs/moq-relay/tests/goaway_cluster.rs b/rs/moq-relay/tests/goaway_cluster.rs index 2bacd26e84c..97d0294ef02 100644 --- a/rs/moq-relay/tests/goaway_cluster.rs +++ b/rs/moq-relay/tests/goaway_cluster.rs @@ -726,13 +726,15 @@ async fn collect_group(sub: &mut moq_net::track::Subscriber, seen: &mut BTreeSet } /// An empty-URI GOAWAY ("reconnect to me") makes the cluster redial the same -/// endpoint. Both sessions' routes name the same first hop, so the subscription -/// through the drained session re-splices onto the redial and keeps delivering. +/// endpoint. The broadcast names an epoch, so the subscription through the drained +/// session re-splices onto the redial and keeps delivering. async fn cluster_reconnects_on_empty_uri_goaway_inner() { let _ = rustls::crypto::aws_lc_rs::default_provider().install_default(); let upstream_origin = moq_tokio::origin::spawn(); - let broadcast = upstream_origin.create_broadcast("cam").expect("create broadcast"); + // Only an epoch path resumes across sessions. + let cam = moq_net::Path::new("cam").mint_epoch(); + let broadcast = upstream_origin.create_broadcast(&cam).expect("create broadcast"); broadcast.announce(Default::default()).expect("create broadcast"); let track = broadcast.create_track("video", None).expect("create track"); @@ -759,8 +761,8 @@ async fn cluster_reconnects_on_empty_uri_goaway_inner() { // Downstream consumer sees group 0 through the first session. let bc = within("broadcast announced", async { let consumer = cluster.origin.consume(); - consumer.routed("cam").await?; - consumer.request_broadcast("cam").await.ok() + consumer.routed(&cam).await?; + consumer.request_broadcast(&cam).await.ok() }) .await .expect("broadcast announced"); diff --git a/rs/moq-tokio/tests/broadcast.rs b/rs/moq-tokio/tests/broadcast.rs index 70dc6ab3ca6..a6737932961 100644 --- a/rs/moq-tokio/tests/broadcast.rs +++ b/rs/moq-tokio/tests/broadcast.rs @@ -991,11 +991,13 @@ async fn read_payloads(sub: &mut moq_net::track::Subscriber, count: usize) -> Ve /// The client connects to two servers announcing the same route. The preferred /// (cheaper) route serves the track; when that session dies, the broadcast /// re-splices through the standby at a group boundary, without the path ever -/// being retracted: both routes name the same first hop, so they are the same -/// origin reached different ways and the subscription rides the failover. +/// being retracted: the path names an epoch, so both routes serve one origin +/// reached different ways and the subscription rides the failover. #[tracing_test::traced_test] #[tokio::test] async fn broadcast_route_migration() { + // Only an epoch path resumes across sessions. + let path = moq_net::Path::new("test").mint_epoch(); use moq_net::Timestamp; let publisher = Hop::new(0x42).unwrap(); @@ -1004,7 +1006,7 @@ async fn broadcast_route_migration() { let origin_a = moq_tokio::origin::spawn(); let mut hops_a = moq_net::Hops::new(); hops_a.push(publisher).unwrap(); - let broadcast_a = origin_a.create_broadcast("test").expect("create broadcast"); + let broadcast_a = origin_a.create_broadcast(&path).expect("create broadcast"); broadcast_a .announce(moq_net::origin::Route::default().with_hops(hops_a).with_cost(1)) .expect("announce"); @@ -1024,7 +1026,7 @@ async fn broadcast_route_migration() { let mut hops_b = moq_net::Hops::new(); hops_b.push(publisher).unwrap(); hops_b.push(Hop::new(0x1234).unwrap()).unwrap(); - let broadcast_b = origin_b.create_broadcast("test").expect("create broadcast"); + let broadcast_b = origin_b.create_broadcast(&path).expect("create broadcast"); broadcast_b .announce(moq_net::origin::Route::default().with_hops(hops_b).with_cost(2)) .expect("announce"); @@ -1098,14 +1100,14 @@ async fn broadcast_route_migration() { // One path, announced once even though two sessions route it (the cheaper // route wins the advertisement). let (update, active) = next_announce(&mut announcements).await; - assert_eq!(update.prefix.as_str(), "test"); + assert_eq!(update.prefix, path); assert!(active, "expected announce"); // Resolve and subscribe: the cheaper route (A) serves the track. let subscription = moq_net::track::Subscription::default() .with_start(moq_net::track::Position::group(1)) .with_max_age(Duration::from_secs(10)); - let broadcast = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + let broadcast = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast(&path)) .await .expect("request timeout") .expect("routed broadcast resolves"); From b984df66517c5bfe55fe40a4e4be40328edae921 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 6 Oct 2026 11:00:27 -0700 Subject: [PATCH 5/5] feat(net): negotiate publisher epochs as metadata Keep broadcast paths unchanged, require explicit matching identities for route resume, and pin unidentified subscriptions. Carry epochs in negotiated Lite announcements and TRACK, SUBSCRIBE, and FETCH requests. Co-Authored-By: Codex --- doc/bin/relay/auth.md | 6 +- doc/bin/relay/cluster.md | 10 + doc/concept/hang.md | 2 +- doc/concept/moq-lite.md | 99 ++- doc/lib/js/net.md | 7 +- doc/lib/rs/moq-net.md | 8 +- drafts/draft-lcurley-moq-e2ee.md | 24 +- drafts/draft-lcurley-moq-hang.md | 4 - drafts/draft-lcurley-moq-lite.md | 60 +- js/net/src/broadcast.ts | 31 +- js/net/src/connection/forward.ts | 7 +- js/net/src/consume.test.ts | 30 + js/net/src/consume.ts | 32 +- js/net/src/epoch.test.ts | 6 +- js/net/src/epoch.ts | 2 +- js/net/src/hop.ts | 12 +- js/net/src/lite/announce.ts | 26 +- js/net/src/lite/connection.test.ts | 53 ++ js/net/src/lite/connection.ts | 6 +- js/net/src/lite/epoch.test.ts | 73 +++ js/net/src/lite/epoch.ts | 17 + js/net/src/lite/fetch.ts | 11 +- js/net/src/lite/publisher.test.ts | 32 +- js/net/src/lite/publisher.ts | 45 +- js/net/src/lite/setup.test.ts | 8 + js/net/src/lite/setup.ts | 36 +- js/net/src/lite/subscribe.ts | 8 + js/net/src/lite/subscriber.test.ts | 20 +- js/net/src/lite/subscriber.ts | 73 ++- js/net/src/lite/track.ts | 18 +- js/net/src/origin.test.ts | 128 +--- js/net/src/origin.ts | 159 ++--- js/net/src/path.test.ts | 68 +-- js/net/src/path.ts | 40 +- js/net/src/wire.ts | 9 +- quest/m0/broadcast-epoch/README.md | 127 +--- quest/m0/broadcast-epoch/apps.md | 18 +- quest/m0/broadcast-epoch/bindings.md | 5 +- quest/m0/broadcast-epoch/gateways.md | 2 +- quest/m0/broadcast-epoch/gst.md | 11 +- quest/m0/broadcast-epoch/hop-removal.md | 7 +- quest/m0/broadcast-epoch/stats-epoch.md | 9 +- quest/m0/broadcast-epoch/stats-split.md | 7 +- quest/m0/broadcast-epoch/ts-restart.md | 8 +- quest/m1/obs-epoch.md | 8 +- rs/moq-e2ee/README.md | 8 +- rs/moq-e2ee/src/tests.rs | 12 - rs/moq-e2ee/tests/transport.rs | 12 +- rs/moq-mux/src/container/consumer.rs | 17 +- rs/moq-net/benches/origin.rs | 63 +- rs/moq-net/src/client.rs | 1 + rs/moq-net/src/epoch.rs | 2 +- rs/moq-net/src/error.rs | 15 +- rs/moq-net/src/fuzz.rs | 3 + rs/moq-net/src/lite/announce.rs | 33 +- rs/moq-net/src/lite/epoch.rs | 23 + rs/moq-net/src/lite/fetch.rs | 5 + rs/moq-net/src/lite/mod.rs | 1 + rs/moq-net/src/lite/publisher.rs | 152 +++-- rs/moq-net/src/lite/session.rs | 1 + rs/moq-net/src/lite/setup.rs | 16 + rs/moq-net/src/lite/subscribe.rs | 5 + rs/moq-net/src/lite/subscriber.rs | 146 ++++- rs/moq-net/src/lite/track.rs | 11 +- rs/moq-net/src/model/broadcast.rs | 35 +- rs/moq-net/src/model/front.rs | 31 +- rs/moq-net/src/model/origin.rs | 767 +++++++----------------- rs/moq-net/src/path/epoch.json | 79 --- rs/moq-net/src/path/mod.rs | 115 +--- rs/moq-net/src/server.rs | 2 + rs/moq-net/tests/epochs.rs | 166 +++++ rs/moq-net/tests/route_change.rs | 84 ++- rs/moq-relay/tests/auth_embedder.rs | 46 -- rs/moq-relay/tests/goaway_cluster.rs | 16 +- rs/moq-tokio/tests/broadcast.rs | 15 +- 75 files changed, 1584 insertions(+), 1670 deletions(-) create mode 100644 js/net/src/consume.test.ts create mode 100644 js/net/src/lite/epoch.test.ts create mode 100644 js/net/src/lite/epoch.ts create mode 100644 rs/moq-net/src/lite/epoch.rs create mode 100644 rs/moq-net/tests/epochs.rs diff --git a/doc/bin/relay/auth.md b/doc/bin/relay/auth.md index 532f2911f45..9fe0373f356 100644 --- a/doc/bin/relay/auth.md +++ b/doc/bin/relay/auth.md @@ -123,10 +123,8 @@ only. There is no shared secret. **Patterns.** A grant is any pattern union and means exactly what it says: `foo/**` is a subtree, a bare `foo` is that one broadcast, `live/*` is every broadcast one segment under `live`, and `room/*/chat` is each room's chat and -nothing beside it. A pattern that admits a name also admits its -[epochs](/concept/moq-lite#publisher-epochs) (`foo/@`), while a grant -on one epoch reaches only that epoch. The relay announces, publishes, and -resolves only the paths inside the grant. Announcements travel by literal head on the wire, so a +nothing beside it. The relay announces, publishes, and resolves only the paths +inside the grant. Announcements travel by literal head on the wire, so a non-prefix grant is filtered locally on each side while the announced route stays a prefix on every protocol version. diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index 96434b45c33..02f3b23695d 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -289,3 +289,13 @@ filters with `origin::Consumer::local()`. The `/nodes` [internal endpoint](/bin/relay/http#get-nodes) lists the peers this relay dialed and holds a session with. + +### Epoch identity and failover + +Upgraded Lite peers carry publisher epochs as announcement and request metadata. +A relay can resume a subscription through another route only when its requested +epoch matches. Plain-path subscriptions with no epoch remain pinned and end +when their serving route disappears, including GOAWAY reconnects. The client +must resubscribe. Legacy Lite and moq-transport links carry no epoch; they keep +plain paths and cannot establish cross-route content identity. See +[Publisher epochs](/concept/moq-lite#publisher-epochs) for cache compatibility. diff --git a/doc/concept/hang.md b/doc/concept/hang.md index f9b96830b49..156957142c4 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -53,7 +53,7 @@ every video rendition (display size, rotation, flip) sit at the section root. 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 track name used to subscribe, 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, past any final `@` epoch, so a reference that escapes above the root names nothing and the catalog is rejected. A reference binds to its target's newest [epoch](/concept/moq-lite#publisher-epochs) when requested unless it spells one, which a transcoder does to pin the source run it read. +- **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. - **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. - **Stalled renditions.** A publisher can flag a rendition as temporarily bad so players prefer another one without the track disappearing. First-party video publishers set this flag after more than three frame intervals of source silence or encoding lag while subscribed, and clear it after three on-time completed frames or when idle. Browser and native capture poll while waiting; FLV and MPEG-TS importers observe video silence as container data arrives. The shared detector is `hang::catalog::stalled::Detector` in Rust and `Catalog.Stalled.Detector` in JavaScript. It is a playback diagnostic, not an authorization or routing signal. diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 2531c0aa6fa..536576c6900 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -97,12 +97,9 @@ always a prefix, on every wire version and on moq-transport alike; a service that serves only some of the paths beneath its prefix refuses the rest as they are requested. Each route carries the chain of relay identities it passed through, which is how forwarding loops are caught, and a cost, which is how a -subscriber picks among several routes to the same broadcast. A path naming an -[epoch](#publisher-epochs) is one broadcast from one publisher, so a subscription -to it moves between routes without a seam; a publisher must not reuse an epoch -for different content. A path without an epoch carries no such promise (two -transcoder claimants may serve different bytes), so its subscription stays on -the route that first served it and ends when that route goes. A hop of 0 is +subscriber picks among routes to the same broadcast. A subscription with a known +epoch can resume through routes attesting that epoch; an unidentified subscription +stays on its first serving route. A publisher must not reuse an identity for different content. A hop of 0 is the anonymous mark and travels the chain unchanged; when it is the first hop, a relay puts a random ID, fresh per connection, in front of it. A route that passed through an anonymous hop at any depth ranks below every fully identified route, whatever @@ -139,57 +136,45 @@ without waiting, since it has no FIN to acknowledge. ### Publisher epochs -An application can identify each publisher instance with a shared `Epoch` from -`moq-net` or `@moq/net`. It is a lowercase hyphenated UUIDv7, ordered newest -last, with its wall-clock creation time available as `Epoch::time()` in Rust -or `Epoch.time(epoch)` in TypeScript. Minting is explicit; publishing does not -add an epoch automatically. A publisher that may restart publishes each run -under a fresh one, so a restart is a new broadcast rather than a reused name: -`path.mint_epoch()` in Rust and `Path.mintEpoch(path)` in TypeScript append a -freshly minted epoch. The epoch segment counts toward the 32-part path limit. - -`Path::with_epoch(&epoch)` and `Path.withEpoch(path, epoch)` set the final -`@` segment, replacing any epoch already there, and -`with_epoch(None)` / `Path.withEpoch(path)` remove it. `Path::split_epoch()` and -`Path.splitEpoch(path)` return the name and optional epoch. Only the final -segment and canonical UUIDv7 text count: `@alice`, bare UUIDs, uppercase UUIDs, -and other UUID versions remain ordinary path segments. An epoch only ever ends -a path, so publishing `name/@/more` fails (`Error::MisplacedEpoch` in -Rust); a derived broadcast carries its source's epoch at its own end instead. -Existing path normalization still applies. - -The segment travels as part of the ordinary broadcast path on every supported -wire version. Epochs do not hide a broadcast; a leading `.` in a name segment -still does. - -A request for a bare name binds once, when made, to its newest epoch: the -greatest `name/@` with a live route, ahead of any route covering the -name. With no epoch it goes through a route covering the name, such as a -transcoder's claim, and stays on that route. The broadcast is still named -`name`, and it never moves to a newer epoch, which is a different broadcast: in -Rust it ends with the epoch it was bound to, and the next request binds to the -newest. In TypeScript a request is long-lived, so its `active` broadcast swaps -to the newer epoch as a new broadcast, and js/watch restarts its decoders on it. -A path naming an epoch pins it and never moves. A smart subscriber watches the -announcements below a name and requests each epoch by its full path, treating -a new one as a discontinuity. - -A catalog's relative references resolve against its name past any final -epoch, so they mean the same whether the catalog was requested by name or by -epoch, and a reference binds to its target's newest epoch when requested unless it spells one -(`./source/@`). - -A relay resolves bare requests this way for every client and protocol -version, so an older client subscribing by name keeps working. A relay without -this support routes `name/@` but never resolves bare `name`, since a -route covers its descendants, not its parent: a bare-name viewer behind one -needs a publisher that publishes the bare name itself. - -A grant that admits a name also admits its epochs: an exact `room/camera` -grant reaches `room/camera/@` for publishing and subscribing, and -`room/**` covers both. A grant on one epoch reaches only that epoch, never the -bare name or a sibling. The widening is a `room/camera/@*` pattern, so any -single `@`-prefixed segment below the name is admitted, not only UUIDv7 text. +A broadcast identity is its path plus an optional publisher epoch. An epoch is +an immutable lowercase UUIDv7. Creating a local broadcast through Origin mints +one automatically; an explicit epoch lets replicas declare the same content. +Every track, group and frame position within an identity must remain immutable. +`Epoch::time()` and `Epoch.time()` expose the UUID's creation time; route selection +does not rank publishers by that clock. + +Rust accepts `broadcast::Id::from("room/camera").with_epoch(epoch)` for publication +and requests. JavaScript accepts `{ path: Path.from("room/camera"), epoch }` when +creating a broadcast, and exposes `broadcast.epoch` on consumers. Announcements +carry `route.epoch`. The path stays `room/camera`: authentication, wildcard grants, +relative references, and hidden-name rules are unchanged. There is no special +`@epoch` path syntax or implicit bare-to-epoch binding. + +Lite peers negotiate the Epoch SETUP parameter (0x6, value 1). When both support +it, announcements and TRACK, SUBSCRIBE and FETCH requests carry an optional +trailing epoch. A request with an epoch can only use a matching route; it never +falls back to a different instance. Replacing an announced epoch sends END then +START at the same path. Repricing the same epoch preserves the announcement. + +Without an epoch, a Rust subscription pins its first serving route, including +when that route has a known epoch. It ends when that route disappears, including +a cluster reconnect after GOAWAY. It never shares a front with an explicit-epoch +request. Clients follow announcement changes by requesting a fresh broadcast and +resetting their catalog and decoders. JavaScript's `request.active` delivers a +new broadcast handle when its selected source changes; it does not splice frames. +Native clients must select an announced epoch explicitly to retain seamless failover. + +Lite peers without the capability, pre-05 Lite, and moq-transport receive the same +plain paths and no epoch metadata. An incoming route from such a peer has unknown +identity, even if its name happens to resemble a UUID. Relays never invent an +epoch for it or resume it through a different route. Known identity can survive +between upgraded relays even when a downstream peer cannot represent it. + +This preserves legacy discovery and subscriptions, but does not invalidate caches +in third-party moq-transport relays. Those deployments still need immutable wire +names and object positions across publisher restarts. Applications that require +end-to-end generation identity must use an epoch-aware path through the network +or arrange unique names themselves. ### Hidden broadcasts diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 9892a0bbbb3..3bf44afffe2 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -9,10 +9,9 @@ description: The pub/sub layer in TypeScript The TypeScript twin of [`moq-net`](/lib/rs/moq-net): connections, origins, broadcasts, tracks, groups, and frames, negotiating moq-lite or moq-transport -at setup. `Epoch` provides the shared publisher identity, and `Path.mintEpoch`, -`Path.splitEpoch`, and `Path.withEpoch` carry it in the broadcast path; a -request for the bare name follows the newest epoch. See -[publisher epochs](/concept/moq-lite#publisher-epochs). +at setup. `Epoch` identifies a publisher instance separately from its path. +Origin mints it on local broadcast creation; received broadcasts expose it as +`broadcast.epoch`. See [Publisher epochs](/concept/moq-lite#publisher-epochs). ```ts import * as Moq from "@moq/net"; diff --git a/doc/lib/rs/moq-net.md b/doc/lib/rs/moq-net.md index 2088dcc1ef6..389033c0a6b 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -13,11 +13,17 @@ prioritization on top of QUIC. It negotiates [moq-lite](/concept/moq-lite) or IETF moq-transport at setup and presents one API either way. Media is a layer above ([hang](/lib/rs/hang)); relays and CDNs implement only this. +A local broadcast gets a fresh epoch by default. Use +`broadcast::Id::from(path).with_epoch(epoch)` to publish replicas or request a +specific announced instance. Plain-path requests remain pinned to their first +serving route; only explicit epochs permit seamless route failover. See +[Publisher epochs](/concept/moq-lite#publisher-epochs). + ## What it gives you - **Origins** scope what a session can see, and merge duplicate subscriptions so a broadcast is pulled upstream once no matter how many local readers. - **Broadcasts** are created unannounced and invisible to everyone, then announced as an exact route, or served below a prefix with `dynamic`. A consumer of the same origin sees exactly what a peer sees. Discovery accepts pattern unions; events carry the advertised prefix and captures for a complete match. -- **Epochs** identify publisher instances with a canonical UUIDv7 and explicit path helpers (`Path::mint_epoch`, `Path::with_epoch`), and a request for the bare name follows the newest one; see [publisher epochs](/concept/moq-lite#publisher-epochs). +- **Epochs** identify publisher instances with a canonical UUIDv7 carried as announcement and request metadata; see [publisher epochs](/concept/moq-lite#publisher-epochs). - **Patterns** (`Pattern`, `Patterns`) are re-exported from [`moq-pattern`](https://docs.rs/moq-pattern). Literal `Path` stays a coordinate. - **Tracks** carry groups with a priority, an optional publisher retention window (`Info::max_age`), and a timescale. Subscribers set their own priority and max age and can change them live. - **Groups** are written frame by frame and delivered on independent streams. Old groups are cached for fetch-by-sequence; stale groups are skipped per the subscriber's budget. diff --git a/drafts/draft-lcurley-moq-e2ee.md b/drafts/draft-lcurley-moq-e2ee.md index bdb5af13263..8448d3ac1b7 100644 --- a/drafts/draft-lcurley-moq-e2ee.md +++ b/drafts/draft-lcurley-moq-e2ee.md @@ -34,7 +34,7 @@ informative: This document specifies moq-e2ee-00, a versioned profile for end-to-end encryption of MoQ application payloads. Authorized publishers and subscribers share a 32-byte broadcast secret out of band. -Each publisher instance mints an epoch and publishes under an opaque broadcast path ending in it. +Each publisher instance mints an epoch and publishes at an opaque broadcast path with that epoch as identity metadata. HKDF-SHA-256 derives opaque physical track names and per-track AES-128-GCM keys from the secret and the epoch; grouped frames and datagrams use separate key domains. Media frames and datagrams carry only ciphertext plus a 16-byte tag. The profile binds object identity through derivation and the nonce, not an on-wire header. @@ -69,7 +69,7 @@ It differs where the models diverge: - One 32-byte broadcast secret authorizes every track. Per-track keys are derived, not supplied. - The Key ID is part of the out-of-band credential. No per-frame header or immutable property carries it. -- The salt is not derived from the key. The publisher instance's epoch is an input to every derivation and the last segment of the broadcast path ({{epoch}}), so a restarted publisher derives new keys instead of needing a new Key ID. +- The salt is not derived from the key. The publisher instance's epoch is an input to every derivation and the broadcast's identity metadata ({{epoch}}), so a restarted publisher derives new keys instead of needing a new Key ID. - The nonce is the identity counter itself, not a salt XOR. The derived key is already unique per credential, epoch, physical name, and domain. - The payload is ciphertext concatenated with the 16-byte tag, with no inner length prefix, encrypted properties, or padding. - moq-lite frame indices are implied by position in the group ({{moql}} Section "Frame"), not an on-wire object ID. This profile still uses that index as the 32-bit nonce half, because it is the only canonical end-to-end frame identity on both moq-lite and MoQ Transport. @@ -132,13 +132,13 @@ Each instance of a broadcast MUST mint an epoch that no other instance under the Two instances MUST NOT share an epoch: they would derive the same keys and collide on nonces. Its leading 48-bit timestamp makes epochs sort by creation time and its random bits make collisions negligible. -A protected broadcast is published at `/@`, where `` is the 22-character base64url segment derived from the credential and the application's semantic broadcast name according to {{derive}}, and `` is the UUID text. -The `@` marker is part of the path segment only; the HKDF `bytes(epoch)` input remains the UUID text without `@`. -The opaque derivation does not include the epoch, so every instance of the same semantic broadcast shares a discovery prefix. -The path carries no format or protection marker; for example, the semantic name `meeting.hang` appears only as an input to the opaque derivation. -A plaintext consumer that opens the protected broadcast fails because it cannot find the plaintext catalog it expects, not because of a path naming rule. -Subscribers discover instances by the `/` prefix and select the greatest epoch, where greatest is newest. -A subscriber that already knows the full path parses the epoch from its last segment after removing `@`. +A protected broadcast is published at ``, the 22-character base64url segment derived from the credential and the application's semantic broadcast name according to {{derive}}. +The publisher conveys its epoch using negotiated MoQ Lite epoch metadata, or through the application's authenticated channel when the transport cannot represent it. +The HKDF `bytes(epoch)` input is the canonical UUID text. +The opaque derivation does not include the epoch, so every instance of the same semantic broadcast shares a discovery path. +The path carries no format or protection marker; the semantic name `meeting.hang` appears only as an input to the opaque derivation. +A subscriber MUST bind the selected epoch to every track request where the transport supports it, and MUST create a new generation when the epoch changes. +Legacy intermediaries that cache solely by wire names and positions require application-assigned immutable names; epoch metadata cannot invalidate their caches. The epoch and the path are not secret and are not authenticated. A relay that presents a wrong epoch causes authentication failure; a relay that withholds a newer instance denies service. @@ -335,7 +335,7 @@ Relays, caches, recorders, and control planes are untrusted for content. Authorized endpoints that hold the broadcast secret are trusted. Sender authenticity against another endpoint that also holds the secret is not a goal of `moq-e2ee-00`. -A relay can still observe the outer broadcast path including the opaque segment and epoch, opaque physical names, group and frame structure, timestamps, sizes, and traffic patterns. +A relay can still observe the outer opaque broadcast path and any conveyed epoch metadata, opaque physical names, group and frame structure, timestamps, sizes, and traffic patterns. Padding and metadata-flow confidentiality are out of scope. The opaque segment hides the application's semantic broadcast name from a relay only while the application does not publish or otherwise expose the same name in plaintext. @@ -364,8 +364,8 @@ This document requests no registrations. ## draft-lcurley-moq-e2ee-00 {:numbered="false"} -- Require canonical UUIDv7 epochs and carry them in `@` path segments, leaving HKDF UUID inputs unchanged. -- Initial `moq-e2ee-00` profile: out-of-band credential, opaque broadcast path with a publisher-minted epoch as its last segment, HKDF physical names and keys, AES-128-GCM payloads, identity bounds, typed failures, and shared primitive vectors. +- Require canonical UUIDv7 epochs and convey them as identity metadata or through the application channel, leaving HKDF UUID inputs unchanged. +- Initial `moq-e2ee-00` profile: out-of-band credential, opaque broadcast path with a publisher-minted epoch, HKDF physical names and keys, AES-128-GCM payloads, identity bounds, typed failures, and shared primitive vectors. # Acknowledgments diff --git a/drafts/draft-lcurley-moq-hang.md b/drafts/draft-lcurley-moq-hang.md index db315a235e6..38dc8567153 100644 --- a/drafts/draft-lcurley-moq-hang.md +++ b/drafts/draft-lcurley-moq-hang.md @@ -499,10 +499,7 @@ The `broadcast` field overrides that, naming a different broadcast that publishe The value is a relative path, resolved against the path of the broadcast that served the catalog. It uses relative reference resolution ({{!RFC3986, Section 5.2}}): a non-empty reference replaces the catalog broadcast's last path segment before applying `.` and `..` segments. For example, `./source` in a catalog served by `room/transcode` resolves to `room/source`, while `.` resolves to `room`. -A final epoch segment (see Epochs in {{moql}}) is not part of the base: a catalog served by `room/transcode/@` resolves `./source` to `room/source` too, so a reference means the same whether the catalog was requested by name or by epoch. An empty reference resolves to the catalog broadcast itself. -A reference names an epoch only when it spells one: `./source` is a bare request, bound to the newest epoch of `room/source` when the consumer makes it, while `./source/@` pins that epoch. -A publisher whose renditions must come from one run, such as a transcoder referencing its source, SHOULD spell the epoch. A publisher MUST NOT use an absolute path, nor a reference that escapes above the root. The root is the consumer's authorized subtree, so such a reference names content the consumer cannot reach. A consumer MUST reject a catalog containing one, rather than resolving the reference against a different broadcast or ignoring the rendition. @@ -1075,7 +1072,6 @@ This document has no IANA actions. ## moq-hang-03 {:numbered="false"} -- A `broadcast` reference resolves against the catalog broadcast's name, past a final epoch segment, and is requested by bare name, binding to its target's newest epoch, unless it spells one. - Defined encoder `jitter` as flush lateness above the rendition's own recent minimum, replacing fixed frame-duration hints; container batches retain media-span estimates. - Clarified that CMAF audio samples are sync samples independently of publisher group boundaries. - Clarified that container importers can estimate jitter from batch media spans without measuring input wait time. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index f699ed80067..6ebb5579efa 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -118,8 +118,7 @@ Any broadcasts and subscriptions are transparently proxied by the CDN behind the ## Broadcast A Broadcast is a collection of Tracks named by a path. This corresponds to a MoqTransport's "track namespace". -A path naming an epoch (see [Epochs](#epochs)) names one Broadcast from one publisher, whichever relay serves it: a publisher MUST NOT reuse an epoch for different content, and publishes a new instance under a new epoch instead. -A path without an epoch makes no such promise: two publishers of one such path, such as two claimants of a transcoder's prefix, may serve different content. +A path with a known epoch names one Broadcast. A publisher MUST NOT reuse this identity for different content; without the Epoch extension, it MUST use immutable paths and object positions. See [Epoch Parameter](#epoch-parameter). A publisher advertises what it can serve via ANNOUNCE_START messages, each carrying a path prefix: a route covering every broadcast path beneath it. A route is the only shape an advertisement takes: a publisher that serves only some of the paths beneath a prefix, such as a transcoder for any broadcast's derivative, advertises the covering prefix and refuses the requests it will not serve (see [Resolution](#resolution)); no message narrows a route. @@ -428,8 +427,7 @@ The Spread Hash is the 64-bit FNV-1a hash, with offset basis `0x420C0DECB00B` an It is keyed on the requested path rather than the route's prefix, so equal-cost advertisers of one prefix share its paths instead of the first one taking them all, while one path resolves to the same advertiser on every relay that holds the same routes. When choosing which route to advertise for a prefix, the requested path is the prefix itself. -Every route serving a path that names an epoch serves the same Broadcast, so a relay MAY move a live subscription between them, continuing from the first frame the subscriber lacks, and a route change (a reconnect, a cheaper path, a draining session) is invisible to the subscriber. -For any other path, a relay MUST NOT move a live subscription to another route, whose content may differ: the subscription stays on the route that first served it and ends when that route goes, and a repeated request resolves afresh. +A relay MAY resume a subscription across routes attesting the same requested epoch, continuing from the first frame the subscriber lacks. An unidentified subscription stays pinned to its selected route. See [Epoch Parameter](#epoch-parameter). #### Resolution {#resolution} A SUBSCRIBE, FETCH, or TRACK request names a path, and the receiver resolves it against the routes covering that path, after the per-subscriber exclusion above. @@ -455,19 +453,6 @@ Every refusal is terminal and propagates without re-resolution, so probing unser An advertiser signals capacity through its route alone: it withdraws or re-prices the route before it runs out, leaving headroom for requests already in flight, since a withdrawal and a request for the slot it gave away can cross. A receiver SHOULD NOT cache refusals; rate limiting is the advertiser's concern. -#### Epochs {#epochs} -A path whose final segment is `@` followed by a lowercase hyphenated UUIDv7 names one epoch of the path before it, its name. -A publisher that may restart SHOULD publish each run under a fresh epoch, so a restart is a new Broadcast rather than a reused path. -An epoch only ever ends a path: a publisher MUST NOT announce a path with an epoch segment before its last, and a receiver MAY refuse such an announcement. -The segment is ordinary path text on the wire. - -A request for a path naming no epoch resolves to the greatest epoch one segment below it that a route covers, ahead of any route covering the path itself; UUIDv7 text orders by creation time. -With no such epoch, it resolves through a route covering the path, as any other path does. -The request is bound once, when it is received: a newer epoch is a different Broadcast, and the receiver MUST NOT move the request to it, so the request ends with the epoch it was bound to and a repeated request resolves afresh. -A request naming an epoch never moves. -A subscriber that wants each new epoch as it appears watches the announcements below the name and requests each epoch by its full path, treating the switch as a discontinuity. -This is receiver behavior on every version: a receiver without it finds no route covering the path, and the request is unroutable. - ### Subscribe A subscriber opens Subscribe Streams to request a Track. @@ -712,6 +697,8 @@ This length field does not include the length of the varint length itself. An implementation SHOULD close the connection with a PROTOCOL_VIOLATION if it receives a message with an unexpected length. The version and extensions should be used to support new fields, not the message length. +When the Epoch extension is negotiated, its optional trailer is delimited by Message Length as specified in [Epoch Parameter](#epoch-parameter). + ## STREAM_TYPE {#stream_type} All streams start with a short header indicating the stream type. @@ -776,6 +763,37 @@ The following Setup Parameters are defined: |------|-----------|-------------| | 0x5 | Hop | Hop ID (i) | |------|-----------|-------------| +| 0x6 | Epoch | 1 (i) | +|------|-----------|-------------| + +### Epoch Parameter {#epoch-parameter} +The Epoch parameter (0x6) advertises support for publisher identity metadata. +Its value MUST be the variable-length integer 1; other values are a protocol violation. +Absence means unsupported. Both endpoints MUST advertise support before sending an epoch. + +When negotiated, ANNOUNCE_START, TRACK, SUBSCRIBE, and FETCH MAY append an Epoch string after their otherwise version-specific fields, inside Message Length. +No trailing bytes means unknown identity; a present value MUST be a lowercase hyphenated UUIDv7 with the RFC variant. +An empty string is invalid. Epoch metadata MUST NOT be sent without negotiation. +The extension can be negotiated on Lite versions 05 and later; earlier versions retain their original encodings. +On Lite-05 the trailer follows an active ANNOUNCE_BROADCAST's hop list; on Lite-06 and later it follows ANNOUNCE_START's route costs. + +The pair (Broadcast Path, Epoch) identifies immutable content, including track metadata and every frame position. +A publisher MUST mint a new epoch when it would otherwise reuse those positions for different content. +Replicas MAY share an epoch only when they serve the same content at each position. +An epoch is metadata, never a reserved path component, and does not alter authorization or relative path resolution. +The epoch's timestamp does not establish routing priority. + +A request carrying an epoch MUST select only a route attesting that epoch and MUST be refused when no such route is available. +TRACK, SUBSCRIBE, and FETCH for one broadcast instance MUST carry the same epoch, so a restart between requests cannot mix instances. +Subscriptions MAY resume across routes only for that same known epoch. +An unidentified request MUST remain pinned to its selected route and MUST NOT be merged with an explicit-epoch request. +Changing the selected route requires a new unidentified subscription. + +An advertisement's epoch is immutable for its lifetime. A publisher replacing it MUST send ANNOUNCE_END followed by a new ANNOUNCE_START at the same prefix; ANNOUNCE_UPDATE only changes routing metadata. +Lite-05's duplicate-active update likewise MUST NOT change the epoch. +Relays MUST preserve known epochs when negotiated and MUST NOT invent identity for an unidentified incoming route. +Omitting metadata toward a legacy peer does not change the broadcast path. +These rules do not invalidate external caches that key content only by legacy names and positions; publishers using such caches still MUST preserve the identity those names promise. ### Probe Parameter {#probe-parameter} The Probe Parameter advertises the sender's capability level when acting as a publisher on a [Probe Stream](#probe). @@ -902,6 +920,7 @@ ANNOUNCE_START Message { Hops (..), Warm Route Cost (i), Cold Route Cost (i), + Epoch (s) OPTIONAL, negotiated } Hops { @@ -1022,6 +1041,7 @@ SUBSCRIBE Message { Group End (i) Frame Start (i) Frame End (i) + Epoch (s) OPTIONAL, negotiated } ~~~ @@ -1101,6 +1121,7 @@ TRACK Message { Message Length (i) Broadcast Path (s) Track Name (s) + Epoch (s) OPTIONAL, negotiated } ~~~ @@ -1231,6 +1252,7 @@ FETCH Message { Group Sequence (i) Frame Start (i) Frame End (i) + Epoch (s) OPTIONAL, negotiated } ~~~ @@ -1377,9 +1399,10 @@ The `Message Length` describes the payload size on the wire. - A refusal is not retried at another route of the same prefix either. - Made TRACK_INFO Publisher Max Age optional, encoded as milliseconds plus one with zero meaning no limit. - Added `Largest Group` and `Largest Frame` to SUBSCRIBE_OK: the publisher's largest position when it answers, which a subscriber takes as where the live feed is. A publisher MUST answer at once when the requested start is past it. Earlier versions carry no such position, so a subscriber takes the first frame instead. -- A path naming an epoch names one Broadcast whichever relay serves it, and a publisher MUST NOT reuse an epoch for different content. A relay MAY move a subscription between routes serving an epoch path, continuing from the first frame the subscriber lacks instead of at a group boundary, and MUST NOT move one for a path without an epoch. Replaces the first-hop identity. +- A path and epoch identify one Broadcast. A relay MAY resume a subscription through another route attesting the same epoch, continuing from the first frame the subscriber lacks. Unidentified subscriptions remain pinned. Replaces the first-hop identity. - Assigned `moq-lite-07-wip` as this draft's protocol identifier until it is finalized as `moq-lite-07`. +- Added the negotiated Epoch SETUP parameter (0x6) and identity trailers on announcements and track requests; unidentified subscriptions stay pinned to one route. - Switched every variable-length integer, including SETUP parameter values, from QUIC's two-bit length prefix to moq-transport's leading-ones encoding, widening the range to 64 bits. - Hid routes with a `.`-prefixed segment below the requested prefix from announce discovery, and added the ANNOUNCE_REQUEST `Hidden` field to opt in. - Added `Stream Count` to SUBSCRIBE_END: the number of Group Streams opened for the subscription. SUBSCRIBE_END is now sent once every counted Group Stream has opened, rather than as soon as the final group is known. @@ -1389,7 +1412,6 @@ The `Message Length` describes the payload size on the wire. - Added announce compression: ANNOUNCE_START gains `Path Base` and `Path Keep` to copy the head of a live advertisement's suffix, and ANNOUNCE_START and ANNOUNCE_UPDATE gain `Hop Base` and `Hop Keep` to copy the tail of a live advertisement's Hop ID list. - Capped the SETUP Message Length at 65,536 bytes. - A relay puts a random Hop ID, picked per session, in front of an announcement whose reconstructed path starts with 0, and writes that stamp followed by 0 for an empty path. -- Specified epochs: a final `@` segment names one run of a path and never appears earlier, a request for a bare name binds once to its newest covered epoch ahead of a route covering the name, and never moves to a newer one. ## moq-lite-06 diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index 99efcd09c33..ecbcf54b0ab 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -4,6 +4,7 @@ * @module */ import { type Dispose, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; +import type * as Epoch from "./epoch.ts"; import { NotFound } from "./error.ts"; import type { Consumer as GroupConsumer } from "./group.ts"; import { Route } from "./hop.ts"; @@ -13,6 +14,14 @@ import * as track from "./track.ts"; import { untilAborted } from "./util/abort.ts"; import { registerWire, trackOf, type Broadcast as Wire } from "./wire.ts"; +/** A broadcast path and its immutable publisher instance, if known. */ +export interface Id { + /** The broadcast path relative to the origin. */ + path: Path.Valid; + /** The publisher instance; absent identities cannot be resumed across routes. */ + epoch?: Epoch.Valid; +} + /** The origin callback a created broadcast uses to advertise its exact path. @internal */ export interface Announcer { /** Advertise or re-price this broadcast's path. */ @@ -234,7 +243,10 @@ export class Producer { #announcer?: Announcer; #path = Path.empty(); - constructor() { + /** The publisher instance, fixed for this broadcast. */ + readonly epoch?: Epoch.Valid; + constructor(epoch?: Epoch.Valid) { + this.epoch = epoch; registerWire(this, this.#wire(false)); } @@ -263,7 +275,7 @@ export class Producer { /** A read handle for this broadcast, named by the path the origin created it at. */ consume(): Consumer { - return makeConsumer({ state: this.#state, path: this.#path }); + return makeConsumer({ state: this.#state, path: this.#path, epoch: this.epoch }); } async #requested(): Promise { @@ -337,7 +349,10 @@ export class Producer { throw new Error("broadcast is closed"); } if (!this.#announcer) throw new Error("broadcast is not attached to an origin"); - this.#announcer.announce(Route.normalize(route)); + const normalized = Route.normalize(route); + if (normalized.epoch !== undefined && normalized.epoch !== this.epoch) + throw new Error("an announcement cannot change publisher epoch"); + this.#announcer.announce({ ...normalized, epoch: this.epoch }); } /** @@ -358,6 +373,7 @@ export class Producer { // What a new consumer handle inherits: the shared broadcast plus the path naming it. interface Shared { + epoch?: Epoch.Valid; state: BroadcastState; path: Path.Valid; } @@ -375,14 +391,17 @@ let makeConsumer: (shared: Shared) => Consumer; * @public */ export class Consumer { + /** The publisher instance selected for this broadcast, if known. */ + readonly epoch?: Epoch.Valid; #state: BroadcastState; #path: Path.Valid; // Guards against a double close() on this handle over-decrementing the consumer count. #closed = false; - protected constructor(shared?: never); - protected constructor(shared?: Shared) { + protected constructor(shared?: never, epoch?: Epoch.Valid); + protected constructor(shared?: Shared, epoch?: Epoch.Valid) { + this.epoch = shared?.epoch ?? epoch; this.#state = shared?.state ?? new BroadcastState(); this.#path = shared?.path ?? Path.empty(); this.#state.consumers++; @@ -440,7 +459,7 @@ export class Consumer { // Hand this consumer's backing state and path to a clone. Opaque (`never`) so the state type // stays unexported; a subclass passes it straight back into its own `super(...)`. protected shareState(): never { - return { state: this.#state, path: this.#path } satisfies Shared as never; + return { state: this.#state, path: this.#path, epoch: this.epoch } satisfies Shared as never; } /** Get a lazy handle for a track on this broadcast. Repeat subscriptions dedupe onto one upstream subscription. */ diff --git a/js/net/src/connection/forward.ts b/js/net/src/connection/forward.ts index 9bdbf252185..d22818eeb62 100644 --- a/js/net/src/connection/forward.ts +++ b/js/net/src/connection/forward.ts @@ -4,6 +4,7 @@ * @module */ import { type Dispose, race } from "@moq/signals"; +import type * as Epoch from "../epoch.ts"; import type { Dynamic, Producer as OriginProducer, RequestSlot } from "../origin.ts"; import * as Path from "../path.ts"; import { wireOf } from "../wire.ts"; @@ -80,7 +81,7 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi } else { const handle = originWire.receive(event.prefix, event.route); inserted.set(event.prefix, handle); - void drive(handle, conn); + void drive(handle, conn, event.route.epoch); } } else { const handle = inserted.get(event.prefix); @@ -126,11 +127,11 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi * A path the table already routes is left alone. A request resolves to the table's route over * any blind answer, so answering one would only park a handle nothing reads. */ -async function drive(handle: Dynamic, conn: Established): Promise { +async function drive(handle: Dynamic, conn: Established, epoch?: Epoch.Valid): Promise { const session = wireOf(conn); try { for await (const request of handle.requested()) { - request.accept(session.consume(request.path)); + request.accept(session.consume(request.path, epoch)); } } catch { handle.close(); diff --git a/js/net/src/consume.test.ts b/js/net/src/consume.test.ts new file mode 100644 index 00000000000..54a46c903e1 --- /dev/null +++ b/js/net/src/consume.test.ts @@ -0,0 +1,30 @@ +import { expect, test } from "bun:test"; +import { Producer } from "./broadcast.ts"; +import { BroadcastCache } from "./consume.ts"; +import * as Epoch from "./epoch.ts"; +import * as Path from "./path.ts"; + +// An unknown request must not join a known identity, regardless of arrival order. +test.each([true, false])("cache keeps known and unknown epochs separate (known first: %s)", (knownFirst) => { + const epoch = Epoch.mint(); + const path = Path.from("live"); + const cache = new BroadcastCache(); + const known = new Producer(epoch); + const unknown = new Producer(); + for (const source of knownFirst ? [known, unknown] : [unknown, known]) { + cache.insert(path, source.consume(), source.epoch); + } + const a = cache.get(path, epoch); + const b = cache.get(path); + expect(a?.epoch).toBe(epoch); + expect(b?.epoch).toBeUndefined(); + cache.evict(path, epoch); + expect(cache.get(path, epoch)).toBeUndefined(); + const remaining = cache.get(path); + expect(remaining).toBeDefined(); + a?.close(); + b?.close(); + remaining?.close(); + known.close(); + unknown.close(); +}); diff --git a/js/net/src/consume.ts b/js/net/src/consume.ts index 11bf6acec26..8799b31b3f6 100644 --- a/js/net/src/consume.ts +++ b/js/net/src/consume.ts @@ -1,26 +1,27 @@ import type * as broadcast from "./broadcast.ts"; +import type * as Epoch from "./epoch.ts"; import type * as Path from "./path.ts"; /** - * Per-path dedup cache for consumed broadcasts, shared by the moq-lite and moq-ietf + * Per-identity dedup cache for consumed broadcasts, shared by the moq-lite and moq-ietf * subscribers. * * Resolving the same path must not mint a fresh subscription per call: repeat requests * for the same path (e.g. several renditions referencing one `broadcast: "./source"`) should * share a single upstream subscription. This mirrors the Rust `origin::Consumer` weak-cache: - * a still-live path resolves to a shared {@link broadcast.Consumer.clone}, a closed one is + * a still-live identity resolves to a shared {@link broadcast.Consumer.clone}, a closed one is * re-consumed on the next request. Each handle is reference-counted, so the shared broadcast * closes once every caller has closed its handle. * * @internal */ export class BroadcastCache { - // The base handle per path; callers get reference-counted clones of it. - #cache = new Map(); + // The base handle per (path, epoch); callers get reference-counted clones of it. + #cache = new Map(); /** A shared handle to the live broadcast cached for `path`, or `undefined` on a miss. */ - get(path: Path.Valid): broadcast.Consumer | undefined { - const base = this.#cache.get(path); + get(path: Path.Valid, epoch?: Epoch.Valid): broadcast.Consumer | undefined { + const base = this.#cache.get(JSON.stringify([path, epoch])); if (base && base.closed.peek() === undefined) return base.clone(); return undefined; } @@ -29,13 +30,14 @@ export class BroadcastCache { * Cache `consumer` as the base handle for `path` (evicting it once it closes) and return it. * Call on a {@link get} miss, after wiring up the fresh consumer's subscribe loop. */ - insert(path: Path.Valid, consumer: broadcast.Consumer): broadcast.Consumer { - this.#cache.set(path, consumer); + insert(path: Path.Valid, consumer: broadcast.Consumer, epoch?: Epoch.Valid): broadcast.Consumer { + this.#cache.set(JSON.stringify([path, epoch]), consumer); // Drop the entry once the broadcast closes (every handle released), so the next request // re-consumes rather than cloning a dead handle. Guard against a newer entry for the path. void consumer.closed.then(() => { - if (this.#cache.get(path) === consumer) this.#cache.delete(path); + if (this.#cache.get(JSON.stringify([path, epoch])) === consumer) + this.#cache.delete(JSON.stringify([path, epoch])); }); return consumer; @@ -51,14 +53,10 @@ export class BroadcastCache { * Existing handles are left alone: they belong to their holders, and the wire resets * whatever they still have open. * - * Eviction is unconditional, which costs a dedup miss when two announcement streams watch - * one path: the second stream's retraction can arrive after the first has already seen the - * replacement, dropping the fresh entry so the next request subscribes again instead of - * sharing. Telling that stale retraction from a live one needs a generation id on the - * advertisement (moq-lite's `Epoch`, not yet on the wire), so until then this errs toward a - * duplicate subscription rather than risk handing out a dead one. + * An epoch's retraction evicts only that identity. Unidentified advertisements still + * evict conservatively when overlapping announcement streams retract the same path. */ - evict(path: Path.Valid): void { - this.#cache.delete(path); + evict(path: Path.Valid, epoch?: Epoch.Valid): void { + this.#cache.delete(JSON.stringify([path, epoch])); } } diff --git a/js/net/src/epoch.test.ts b/js/net/src/epoch.test.ts index e4d4cf27c66..db74ff9dd6e 100644 --- a/js/net/src/epoch.test.ts +++ b/js/net/src/epoch.test.ts @@ -2,11 +2,13 @@ import { expect, spyOn, test } from "bun:test"; import * as Epoch from "./epoch.ts"; test("mint uses UUIDv7 and orders successive identities with a fixed wall clock", () => { - const now = spyOn(Date, "now").mockReturnValue(1_700_000_000_000); + // UUIDv7 keeps monotonic process state, including mints in other test files. + const timestamp = Epoch.time(Epoch.mint()).getTime() + 1; + const now = spyOn(Date, "now").mockReturnValue(timestamp); try { const epoch = Epoch.mint(); expect(Epoch.parse(epoch)).toBe(epoch); - expect(Epoch.time(epoch).getTime()).toBe(1_700_000_000_000); + expect(Epoch.time(epoch).getTime()).toBe(timestamp); expect(Epoch.mint() > epoch).toBe(true); } finally { now.mockRestore(); diff --git a/js/net/src/epoch.ts b/js/net/src/epoch.ts index f3782d9c99b..0e25229e1bf 100644 --- a/js/net/src/epoch.ts +++ b/js/net/src/epoch.ts @@ -7,7 +7,7 @@ export type Valid = string & { readonly _brand: "epoch" }; const canonical = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/; -/** Parse UUID text without the path's `@` marker, refusing noncanonical forms. */ +/** Parse UUID text, refusing noncanonical forms. */ export function parse(text: string): Valid { if (text.length !== 36 || !canonical.test(text)) throw new RangeError("invalid epoch: expected a lowercase hyphenated UUIDv7"); diff --git a/js/net/src/hop.ts b/js/net/src/hop.ts index b5e69ebc766..2516b871cc2 100644 --- a/js/net/src/hop.ts +++ b/js/net/src/hop.ts @@ -8,6 +8,7 @@ * @module */ import * as z from "zod/mini"; +import type * as Epoch from "./epoch.ts"; /** * One relay's identity in a broadcast's hop chain, encoded as a 62-bit varint on the wire. @@ -112,6 +113,8 @@ export const Cost = { * an announce event carries it so consumers can read it back. */ export interface Route { + /** The immutable publisher instance served by this route, if known. */ + epoch?: Epoch.Valid; /** The chain of hops the route has traversed, oldest first. */ hops: Hop[]; /** What pulling content via this route costs; lower wins. */ @@ -124,12 +127,12 @@ export const Route = { default: { hops: [], cost: Cost.zero } as Route, /** Normalize a partial route, treating a bare bigint cost as both magnitudes alike. */ - normalize(route: Route | { hops?: readonly Hop[]; cost?: Cost | bigint } = {}): Route { + normalize(route: Route | { hops?: readonly Hop[]; cost?: Cost | bigint; epoch?: Epoch.Valid } = {}): Route { const hops = route.hops ? [...route.hops] : []; const cost = route.cost; - if (cost === undefined) return { hops, cost: Cost.zero }; - if (typeof cost === "bigint") return { hops, cost: { warm: cost, cold: cost } }; - return { hops, cost: { warm: cost.warm, cold: cost.cold } }; + if (cost === undefined) return { epoch: route.epoch, hops, cost: Cost.zero }; + if (typeof cost === "bigint") return { epoch: route.epoch, hops, cost: { warm: cost, cold: cost } }; + return { epoch: route.epoch, hops, cost: { warm: cost.warm, cold: cost.cold } }; }, }; @@ -148,6 +151,7 @@ export function routesEqual(a: Route | undefined, b: Route | undefined): boolean if (a === b) return true; if (!a || !b) return false; return ( + a.epoch === b.epoch && a.cost.warm === b.cost.warm && a.cost.cold === b.cost.cold && a.hops.length === b.hops.length && diff --git a/js/net/src/lite/announce.ts b/js/net/src/lite/announce.ts index 69ee0c09445..2682dcc4771 100644 --- a/js/net/src/lite/announce.ts +++ b/js/net/src/lite/announce.ts @@ -1,7 +1,9 @@ +import type * as Epoch from "../epoch.ts"; import { ProtocolViolation } from "../error.ts"; import { type Cost, type Hop, HopSchema, MAX_HOPS, UNKNOWN_HOP } from "../hop.ts"; import * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; +import * as EpochWire from "./epoch.ts"; import * as Message from "./message.ts"; import { hasAnnounceCompression, @@ -49,7 +51,15 @@ export type AnnounceBroadcast = * (lite-06+) the route cost. An absent cost encodes as zero; it decodes as * `undefined` on a wire with no room for one. On lite-07, `suffix` follows the * segments `pathBase` copies and `hops` precede the ones `hopBase` copies. */ - | { status: "active"; suffix: Path.Valid; hops: Hop[]; cost?: Cost; pathBase?: Base; hopBase?: Base } + | { + status: "active"; + epoch?: Epoch.Valid; + suffix: Path.Valid; + hops: Hop[]; + cost?: Cost; + pathBase?: Base; + hopBase?: Base; + } /** Pre-lite-06: a broadcast is no longer available, retracted by path. */ | { status: "ended"; suffix: Path.Valid } /** Lite06+: a broadcast is no longer available, retracted by announce id. @@ -199,6 +209,7 @@ async function encodeAnnounce06Body(w: Writer, msg: AnnounceBroadcast, version: await encodePath(w, version, msg.suffix, msg.pathBase); await encodeHopsBlock(w, version, msg.hops, msg.hopBase); await encodeRouteCost(w, version, msg.cost); + await EpochWire.encode(w, version, msg.epoch); break; case "endedId": await w.u62(msg.id); @@ -237,7 +248,13 @@ async function decodeAnnounce06Body(r: Reader, typ: number, version: Version): P case ANNOUNCE_START: { const path = await decodePath(r, version); const hops = await decodeHopsBlock(r, version); - return { status: "active", ...path, ...hops, cost: await decodeRouteCost(r, version) }; + return { + status: "active", + ...path, + ...hops, + cost: await decodeRouteCost(r, version), + epoch: await EpochWire.decode(r, version), + }; } case ANNOUNCE_END: return { status: "endedId", id: await r.u62() }; @@ -262,6 +279,7 @@ async function encodeLegacyBody(w: Writer, msg: AnnounceBroadcast, version: Vers await w.u8(STATUS_ACTIVE); await w.string(Path.encode(msg.suffix)); await encodeHops(w, version, msg.hops); + await EpochWire.encode(w, version, msg.epoch); break; case "ended": await w.u8(STATUS_ENDED); @@ -286,7 +304,9 @@ async function decodeLegacyBody(r: Reader, version: Version): Promise { + const pair = createMockTransportPair(alpn); + const source = new Producer(); + const destination = new Producer(); + const path = Path.from("live"); + const a = source.createBroadcast(path); + const video = a.createTrack("video"); + const group = video.appendGroup(); + group.writeString("a"); + group.close(); + a.announce(); + const url = new URL("https://localhost/test"); + const [client, server] = await Promise.all([ + connect({ url, transport: pair.client, consume: destination }), + accept({ url, transport: pair.server, publish: source.consume() }), + ]); + const announcements = destination.announced(); + const request = destination.consume().request(path); + try { + const first = await announcements.next(); + expect(first?.kind).toBe("start"); + if (first?.kind !== "start") throw new Error("expected start"); + expect(first.prefix).toBe(path); + expect(first.route.epoch).toBe(a.epoch); + while (!request.active.peek()) await Signal.race(request.active); + const remote = request.active.peek()?.clone(); + if (!remote) throw new Error("no broadcast"); + expect(remote.epoch).toBe(a.epoch); + const track = remote.track("video"); + expect(await track.info()).toBeDefined(); + const sub = track.subscribe().ordered(); + expect(await (await sub.nextGroup())?.readString()).toBe("a"); + sub.close(); + expect(await (await track.fetchGroup(0)).readString()).toBe("a"); + // A new instance reuses the plain path, but cannot satisfy A's later requests. + const b = source.createBroadcast(path); + b.createTrack("late"); + b.announce(); + expect(b.epoch).not.toBe(a.epoch); + await expect(remote.track("late").info()).rejects.toThrow(); + b.close(); + } finally { + request.close(); + announcements.close(); + client.abort(); + server.abort(); + a.close(); + source.close(); + destination.close(); + } +}); diff --git a/js/net/src/lite/connection.ts b/js/net/src/lite/connection.ts index 2dda1492d7b..df7791992b7 100644 --- a/js/net/src/lite/connection.ts +++ b/js/net/src/lite/connection.ts @@ -136,9 +136,9 @@ export class Connection implements Established { this.probe = this.#probe; this.hop = randomHop(); - this.#publisher = new Publisher(this.#quic, this.#version, this.hop, publish); + this.#publisher = new Publisher(this.#quic, this.#version, this.hop, { publish, peerSetup: this.#peerSetup }); this.#subscriber = new Subscriber(this.#quic, this.#version, this.hop, this.#probe, this.#peerSetup); - registerWire(this, { consume: (path) => this.#subscriber.consume(path), goaway: this.#goaway }); + registerWire(this, { consume: (path, epoch) => this.#subscriber.consume(path, epoch), goaway: this.#goaway }); void this.#run(); } @@ -233,7 +233,7 @@ export class Connection implements Established { try { await writer.u53(DataType.Setup); const probe = await probeLevel(this.#quic, this.#version); - await new Setup({ probe, hop: this.hop }).encode(writer, this.#version); + await new Setup({ probe, hop: this.hop, epoch: true }).encode(writer, this.#version); writer.close(); } catch (err: unknown) { writer.reset(err); diff --git a/js/net/src/lite/epoch.test.ts b/js/net/src/lite/epoch.test.ts new file mode 100644 index 00000000000..a3cb046c132 --- /dev/null +++ b/js/net/src/lite/epoch.test.ts @@ -0,0 +1,73 @@ +import { expect, test } from "bun:test"; +import * as Epoch from "../epoch.ts"; +import * as Path from "../path.ts"; +import { Reader, Writer } from "../stream.ts"; +import { decodeAnnounceBroadcast, encodeAnnounceBroadcast } from "./announce.ts"; +import { Fetch } from "./fetch.ts"; +import { Subscribe } from "./subscribe.ts"; +import { Track } from "./track.ts"; +import { Version } from "./version.ts"; + +const epoch = Epoch.parse("01900000-0000-7000-8000-000000000001"); +const path = Path.from("live"); + +async function bytes(version: Version, encode: (writer: Writer) => Promise) { + const chunks: Uint8Array[] = []; + const writer = new Writer( + new WritableStream({ + write: (chunk) => { + chunks.push(chunk.slice()); + }, + }), + version, + ); + await encode(writer); + writer.close(); + await writer.closed; + return Uint8Array.from(chunks.flatMap((chunk) => Array.from(chunk))); +} + +test.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])( + "epoch trailers preserve the path on version %s", + async (version) => { + for (const identity of [undefined, epoch]) { + const messages = [ + [new Track(path, "video", identity), Track.decode], + [new Fetch({ broadcast: path, track: "video", priority: 0, group: 3, epoch: identity }), Fetch.decode], + [ + new Subscribe({ id: 1n, broadcast: path, track: "video", priority: 0, epoch: identity }), + Subscribe.decode, + ], + ] as const; + for (const [message, decode] of messages) { + const encoded = await bytes(version, (writer) => message.encode(writer, version)); + const reader = new Reader(undefined, encoded, version); + const got = await decode(reader, version); + expect(got.broadcast).toBe(path); + expect(got.epoch).toBe(identity); + expect(await reader.done()).toBe(true); + } + const encoded = await bytes(version, (writer) => + encodeAnnounceBroadcast(writer, { status: "active", suffix: path, hops: [], epoch: identity }, version), + ); + const got = await decodeAnnounceBroadcast(new Reader(undefined, encoded, version), version); + expect(got.status).toBe("active"); + if (got.status !== "active") throw new Error("expected active"); + expect(got.suffix).toBe(path); + expect(got.epoch).toBe(identity); + } + }, +); + +test("a plain TRACK keeps its original bytes", async () => { + const encoded = await bytes(Version.DRAFT_05, (writer) => new Track(path, "v").encode(writer, Version.DRAFT_05)); + expect(encoded).toEqual(Uint8Array.from([7, 4, 108, 105, 118, 101, 1, 118])); +}); + +test("pre-SETUP versions refuse epoch trailers", async () => { + await expect( + bytes(Version.DRAFT_04, (writer) => + new Subscribe({ id: 1n, broadcast: path, track: "v", priority: 0, epoch }).encode(writer, Version.DRAFT_04), + ), + ).rejects.toThrow("epoch metadata"); +}); diff --git a/js/net/src/lite/epoch.ts b/js/net/src/lite/epoch.ts new file mode 100644 index 00000000000..0dd972264f7 --- /dev/null +++ b/js/net/src/lite/epoch.ts @@ -0,0 +1,17 @@ +import * as Epoch from "../epoch.ts"; +import type { Reader, Writer } from "../stream.ts"; +import { hasSetupStream, type Version } from "./version.ts"; + +/** Append a known epoch to a negotiated message. */ +export async function encode(w: Writer, version: Version, epoch?: Epoch.Valid): Promise { + if (epoch === undefined) return; + if (!hasSetupStream(version)) throw new Error("epoch metadata requires SETUP negotiation"); + await w.string(epoch); +} + +/** Read an optional epoch from the end of a message. */ +export async function decode(r: Reader, version: Version): Promise { + if (await r.done()) return undefined; + if (!hasSetupStream(version)) throw new Error("epoch metadata requires SETUP negotiation"); + return Epoch.parse(await r.string()); +} diff --git a/js/net/src/lite/fetch.ts b/js/net/src/lite/fetch.ts index 35fe2e17dec..a4577dfa922 100644 --- a/js/net/src/lite/fetch.ts +++ b/js/net/src/lite/fetch.ts @@ -1,5 +1,7 @@ +import type * as Epoch from "../epoch.ts"; import * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; +import * as EpochWire from "./epoch.ts"; import * as Message from "./message.ts"; import { hasFrameBounds, Version } from "./version.ts"; @@ -14,6 +16,8 @@ function guardFetch(version: Version) { } export class Fetch { + /** The selected publisher instance, when negotiated. */ + epoch?: Epoch.Valid; broadcast: Path.Valid; track: string; priority: number; @@ -29,6 +33,7 @@ export class Fetch { endFrame?: number; constructor({ + epoch, broadcast, track, priority, @@ -36,6 +41,7 @@ export class Fetch { startFrame = 0, endFrame, }: { + epoch?: Epoch.Valid; broadcast: Path.Valid; track: string; priority: number; @@ -43,6 +49,7 @@ export class Fetch { startFrame?: number; endFrame?: number; }) { + this.epoch = epoch; this.broadcast = broadcast; this.track = track; this.priority = priority; @@ -64,6 +71,7 @@ export class Fetch { // The peer would serve the whole group, including frames we excluded. throw new Error("frame bounds not supported for this version"); } + await EpochWire.encode(w, version, this.epoch); } static async #decode(r: Reader, version: Version): Promise { @@ -73,7 +81,7 @@ export class Fetch { const group = await r.u53(); if (!hasFrameBounds(version)) { - return new Fetch({ broadcast, track, priority, group }); + return new Fetch({ broadcast, track, priority, group, epoch: await EpochWire.decode(r, version) }); } const startFrame = await r.u53(); @@ -83,6 +91,7 @@ export class Fetch { } return new Fetch({ + epoch: await EpochWire.decode(r, version), broadcast, track, priority, diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 81492ed6a91..360c44080d3 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -39,7 +39,7 @@ test.each([Version.DRAFT_01, Version.DRAFT_03, Version.DRAFT_06])( async (version) => { const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, version, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("static")); await Promise.resolve(); const failure = new Error("peer stopped receiving announcements"); @@ -90,7 +90,7 @@ test.each([ ])("a re-price goes out only where the wire carries cost (version %s)", async (version, sent) => { const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, version, randomHop(), { publish: origin.consume() }); const broadcast = origin.createBroadcast(Path.from("cam")); broadcast.announce({ cost: 7n }); @@ -128,7 +128,7 @@ test.each([ async function subscribeEnd(sequences: number[], version: Version = Version.DRAFT_05): Promise { const pair = createMockTransportPair(version === Version.DRAFT_07 ? ALPN_07_WIP : ALPN_05); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, version, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); @@ -191,7 +191,7 @@ async function groupSendOrders(options: { priority: number; sequences: number[]; const groups = sequences.map((sequence) => new GroupProducer(sequence)); const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); @@ -275,7 +275,7 @@ test("lite draft-05: a subscribe update re-ranks the whole subscription", async test("lite draft-05: a subscribe update re-ranks a group already on the wire", async () => { const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); @@ -328,7 +328,7 @@ test("lite draft-05: a subscribe update re-ranks a group already on the wire", a test("lite draft-05: a subscribe update during the stream open still ranks the group", async () => { const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); @@ -388,7 +388,7 @@ test("lite draft-05: many concurrent groups share one subscription listener", as const count = 120; const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); @@ -442,7 +442,7 @@ test("lite draft-05: many concurrent groups share one subscription listener", as test("lite draft-05: the fetch response ranks the publisher's own writes", async () => { const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); @@ -541,7 +541,7 @@ async function servedSubscription( const frames = options.frames ?? ["hello"]; const pair = createMockTransportPair(version === Version.DRAFT_06 ? ALPN_06 : ALPN_05); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, version, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video", { maxAge: options.maxAge }); @@ -1043,7 +1043,7 @@ test("lite draft-07: subscribe end counts zero streams when no groups were produ test("lite draft-07: subscribe end waits for groups below a declared finish", async () => { const pair = createMockTransportPair(ALPN_07_WIP); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, Version.DRAFT_07, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, Version.DRAFT_07, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); @@ -1088,7 +1088,7 @@ test("lite draft-07: subscribe end waits for groups below a declared finish", as async function heldOpenEnd() { const pair = createMockTransportPair(ALPN_07_WIP); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, Version.DRAFT_07, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, Version.DRAFT_07, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); @@ -1174,7 +1174,7 @@ async function serve( ): Promise<{ start?: number; end?: number; served: Served[] }> { const pair = createMockTransportPair(ALPN_06); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, Version.DRAFT_06, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, Version.DRAFT_06, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); @@ -1364,7 +1364,7 @@ async function saturatedGroup() { }; const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); @@ -1444,7 +1444,7 @@ test("lite draft-05: a blocked group header is reset when the group expires", as pair.server.createUnidirectionalStream = async () => writable; const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); @@ -1574,7 +1574,7 @@ test("lite draft-05: a group that goes stale while its stream opens writes nothi const pair = createMockTransportPair(ALPN_05); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); @@ -1647,7 +1647,7 @@ test.each([0, 1])("lite draft-07 reports the cached largest position when starti const version = Version.DRAFT_07; const pair = createMockTransportPair(ALPN_07_WIP); const origin = new OriginProducer(); - const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); + const publisher = new Publisher(pair.server, version, randomHop(), { publish: origin.consume() }); const broadcast = publish(origin, Path.from("quiet")); const track = broadcast.createTrack("video"); const group = new GroupProducer(0); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index bde4aa1381b..4cf05ba0159 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -18,6 +18,7 @@ import type { Fetch } from "./fetch.ts"; import { Group as GroupMessage } from "./group.ts"; import { Priority, sendOrder } from "./priority.ts"; import { Probe } from "./probe.ts"; +import { type Setup, supportsEpoch } from "./setup.ts"; import { encodeSubscribeResponse, exclusiveGroupEnd, @@ -363,6 +364,7 @@ export class Publisher { #advertised: Getter; #publish?: OriginConsumer; + #epochs: Promise; // TRACK_INFO is immutable per track, so resolve it from the application once // (via a throwaway subscribe whose info() resolves when the app calls accept) @@ -381,7 +383,13 @@ export class Publisher { * * @internal */ - constructor(quic: WebTransport, version: Version, hop: Hop, publish?: OriginConsumer) { + constructor( + quic: WebTransport, + version: Version, + hop: Hop, + { publish, peerSetup }: { publish?: OriginConsumer; peerSetup?: Getter } = {}, + ) { + this.#epochs = supportsEpoch({ version, peer: peerSetup, closed: quic.closed }); this.#quic = quic; this.version = version; this.hop = hop; @@ -408,6 +416,7 @@ export class Publisher { } async #runAnnounce(msg: AnnounceRequest, stream: Stream) { + const epochs = await this.#epochs; if (this.#withdrawal.closing.peek()) return; console.debug(`announce: prefix=${msg.prefix}`); @@ -434,7 +443,13 @@ export class Publisher { if (hasAnnounceId(this.version)) announceIds.set(suffix, nextAnnounceId++); await encodeAnnounceBroadcast( stream.writer, - { status: "active", suffix, hops: wireHops(route), cost: route.cost }, + { + status: "active", + suffix, + hops: wireHops(route), + cost: route.cost, + epoch: epochs ? route.epoch : undefined, + }, this.version, ); }; @@ -541,11 +556,12 @@ export class Publisher { for (const [suffix, snap] of active) { const cur = updated.get(suffix); - if (!cur || cur.identity !== snap.identity) await retract(suffix); + if (!cur || cur.identity !== snap.identity || cur.route.epoch !== snap.route.epoch) + await retract(suffix); } for (const [suffix, snap] of updated) { const prev = active.get(suffix); - if (!prev || prev.identity !== snap.identity) { + if (!prev || prev.identity !== snap.identity || prev.route.epoch !== snap.route.epoch) { await announce(suffix, snap.route); } else if (!routesEqual(onWire(prev.route), onWire(snap.route))) { await restart(suffix, snap.route); @@ -572,11 +588,16 @@ export class Publisher { * @internal */ async runSubscribe(msg: Subscribe, stream: Stream) { + if (msg.epoch !== undefined && !(await this.#epochs)) { + stream.abort(new Error("epoch metadata was not negotiated")); + return; + } let front: broadcast.Consumer | undefined; try { front = this.#publish && - (wireOf(this.#publish).local(msg.broadcast) ?? (await wireOf(this.#publish).demand(msg.broadcast))); + (wireOf(this.#publish).local(msg.broadcast, msg.epoch) ?? + (await wireOf(this.#publish).demand(msg.broadcast, msg.epoch))); } catch (err: unknown) { stream.writer.reset(error(err)); return; @@ -696,11 +717,16 @@ export class Publisher { return; } + if (msg.epoch !== undefined && !(await this.#epochs)) { + stream.abort(new Error("epoch metadata was not negotiated")); + return; + } let front: broadcast.Consumer | undefined; try { front = this.#publish && - (wireOf(this.#publish).local(msg.broadcast) ?? (await wireOf(this.#publish).demand(msg.broadcast))); + (wireOf(this.#publish).local(msg.broadcast, msg.epoch) ?? + (await wireOf(this.#publish).demand(msg.broadcast, msg.epoch))); } catch (err: unknown) { stream.writer.reset(error(err)); return; @@ -967,10 +993,15 @@ export class Publisher { * @internal */ async runTrackInfo(msg: TrackMessage, stream: Stream) { + if (msg.epoch !== undefined && !(await this.#epochs)) { + stream.abort(new Error("epoch metadata was not negotiated")); + return; + } try { const front = this.#publish && - (wireOf(this.#publish).local(msg.broadcast) ?? (await wireOf(this.#publish).demand(msg.broadcast))); + (wireOf(this.#publish).local(msg.broadcast, msg.epoch) ?? + (await wireOf(this.#publish).demand(msg.broadcast, msg.epoch))); if (!front) throw new NotFound(`broadcast ${msg.broadcast}`); const info = await this.#resolveTrackInfo(front, msg.track); diff --git a/js/net/src/lite/setup.test.ts b/js/net/src/lite/setup.test.ts index 7a7b805142c..a3cf555654c 100644 --- a/js/net/src/lite/setup.test.ts +++ b/js/net/src/lite/setup.test.ts @@ -183,3 +183,11 @@ test("SETUP decode refuses an oversized length before reading the body", async ( "too large", ); }); + +test("epoch metadata is explicitly negotiated", async () => { + expect((await roundTrip(new Setup())).epoch).toBe(false); + expect((await roundTrip(new Setup({ epoch: true }))).epoch).toBe(true); + expect((await decodeParam(0x6n, Varint.encode(1))).epoch).toBe(true); + await expect(decodeParam(0x6n, Varint.encode(0))).rejects.toThrow("epoch"); + await expect(decodeParam(0x6n, Varint.encode(2))).rejects.toThrow("epoch"); +}); diff --git a/js/net/src/lite/setup.ts b/js/net/src/lite/setup.ts index 22b61b42680..cd9eca7d720 100644 --- a/js/net/src/lite/setup.ts +++ b/js/net/src/lite/setup.ts @@ -1,3 +1,4 @@ +import { type Getter, race, Signal } from "@moq/signals"; /** * The lite-05+ SETUP message: each endpoint advertises its capabilities once, as the * sole message on a unidirectional Setup Stream ({@link DataType.Setup}), then closes it. @@ -19,6 +20,7 @@ const PARAM_PATH = 0x2n; const PARAM_ROLE = 0x3n; /** Setup Parameter id for the endpoint's Hop ID. */ const PARAM_HOP = 0x5n; +const PARAM_EPOCH = 0x6n; /** Cap on the number of parameters in a bag, matching the Rust decoder. */ const MAX_PARAMS = 64; @@ -167,6 +169,8 @@ class Parameters { /** The capabilities a {@link Setup} advertises. Each defaults to the wire default, which is the absence of the parameter. */ export interface SetupProps { + /** Whether publisher epoch metadata is supported. */ + epoch?: boolean; /** See {@link Setup.probe}. Defaults to {@link ProbeLevel.None}. */ probe?: ProbeLevel; /** See {@link Setup.path}. Omitted by default. */ @@ -185,6 +189,8 @@ export interface SetupProps { * depends on a negotiated capability (e.g. PROBE) must wait for it. */ export class Setup { + /** Whether publisher epoch metadata is supported. */ + epoch: boolean; /** The probe capability this endpoint supports. {@link ProbeLevel.None} when absent. */ probe: ProbeLevel; @@ -212,7 +218,8 @@ export class Setup { */ hop?: Hop; - constructor({ probe, path, role, hop }: SetupProps = {}) { + constructor({ probe, path, role, hop, epoch }: SetupProps = {}) { + this.epoch = epoch ?? false; this.probe = probe ?? ProbeLevel.None; this.path = path; this.role = role ?? Role.Both; @@ -227,6 +234,7 @@ export class Setup { async #encode(w: Writer, version: Version) { const params = new Parameters(); + if (this.epoch) params.setVarint(PARAM_EPOCH, 1n, version); // None is the wire default, so omit it to keep the message empty when nothing is set. if (this.probe !== ProbeLevel.None) { params.setVarint(PARAM_PROBE, this.probe, version); @@ -262,7 +270,9 @@ export class Setup { const hopRaw = await params.getVarint(PARAM_HOP, version); const hop = hopRaw === undefined || hopRaw === 0n ? undefined : HopSchema.parse(hopRaw); - return new Setup({ probe, path, role, hop }); + const epoch = await params.getVarint(PARAM_EPOCH, version); + if (epoch !== undefined && epoch !== 1n) throw new Error("invalid epoch capability"); + return new Setup({ probe, path, role, hop, epoch: epoch === 1n }); } /** Encode the SETUP message with its size prefix. Throws on pre-lite-05 versions. */ @@ -277,3 +287,25 @@ export class Setup { return Message.decode(r, (r) => Setup.#decode(r, version), MAX_SETUP_SIZE); } } + +/** Resolve epoch support after SETUP, or false if the session closes first. */ +export async function supportsEpoch({ + version, + peer, + closed, +}: { + version: Version; + peer?: Getter; + closed: Promise; +}): Promise { + if (!hasSetupStream(version) || !peer) return false; + const ended = closed.then( + () => false, + () => false, + ); + for (;;) { + const setup = peer.peek(); + if (setup) return setup.epoch; + if ((await race([Signal.race(peer), ended])) === false) return false; + } +} diff --git a/js/net/src/lite/subscribe.ts b/js/net/src/lite/subscribe.ts index fecb237f40a..15932047aff 100644 --- a/js/net/src/lite/subscribe.ts +++ b/js/net/src/lite/subscribe.ts @@ -1,6 +1,8 @@ +import type * as Epoch from "../epoch.ts"; import * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; import type { Location } from "../track.ts"; +import * as EpochWire from "./epoch.ts"; import * as Message from "./message.ts"; import { hasFrameBounds, hasGroupOrder, hasLargest, hasStreamCount, resolvesStart, Version } from "./version.ts"; @@ -228,6 +230,8 @@ export class SubscribeUpdate { } export class Subscribe { + /** The selected publisher instance, when negotiated. */ + epoch?: Epoch.Valid; id: bigint; broadcast: Path.Valid; track: string; @@ -252,6 +256,7 @@ export class Subscribe { endFrame?: number; constructor(props: { + epoch?: Epoch.Valid; id: bigint; broadcast: Path.Valid; track: string; @@ -262,6 +267,7 @@ export class Subscribe { startFrame?: number; endFrame?: number; }) { + this.epoch = props.epoch; this.id = props.id; this.broadcast = props.broadcast; this.track = props.track; @@ -291,6 +297,7 @@ export class Subscribe { await encodeFrameBounds(w, version, this); break; } + await EpochWire.encode(w, version, this.epoch); } static async #decode(r: Reader, version: Version): Promise { @@ -311,6 +318,7 @@ export class Subscribe { const end = endGroup !== undefined ? endGroup - 1 : undefined; const frames = await decodeFrameBounds(r, version, startGroup, end); return new Subscribe({ + epoch: await EpochWire.decode(r, version), id, broadcast, track, diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index 7b668639bbf..623bd0340a0 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -885,7 +885,7 @@ test.each([ const subscriber = new Subscriber(quic, Version.DRAFT_05, HopSchema.parse(1n)); let settled = false; - const fetch = subscriber.fetchGroup(Path.from("room"), "video", 0).then( + const fetch = subscriber.fetchGroup({ path: Path.from("room") }, "video", 0).then( () => { settled = true; return undefined; @@ -919,7 +919,7 @@ test("a fetch started after the subscriber closes rejects without opening a stre const subscriber = new Subscriber(quic, Version.DRAFT_05, HopSchema.parse(1n)); subscriber.close(); - const err = await subscriber.fetchGroup(Path.from("room"), "video", 0).catch((err: unknown) => err); + const err = await subscriber.fetchGroup({ path: Path.from("room") }, "video", 0).catch((err: unknown) => err); expectCut(err, undefined); expect(streams.length).toBe(0); }); @@ -930,7 +930,7 @@ test("an already-aborted fetch rejects without opening a stream", async () => { const cause = new Error("gone"); const err = await subscriber - .fetchGroup(Path.from("room"), "video", 0, { signal: AbortSignal.abort(cause) }) + .fetchGroup({ path: Path.from("room") }, "video", 0, { signal: AbortSignal.abort(cause) }) .catch((err: unknown) => err); expect(err).toBe(cause); expect(streams.length).toBe(0); @@ -943,8 +943,8 @@ test("one of two fetch sharers aborting leaves the other's fetch", async () => { const subscriber = new Subscriber(quic, Version.DRAFT_05, HopSchema.parse(1n)); const controller = new AbortController(); - const a = subscriber.fetchGroup(Path.from("room"), "video", 0, { signal: controller.signal }); - const b = subscriber.fetchGroup(Path.from("room"), "video", 0); + const a = subscriber.fetchGroup({ path: Path.from("room") }, "video", 0, { signal: controller.signal }); + const b = subscriber.fetchGroup({ path: Path.from("room") }, "video", 0); await drainUntil(() => streams.length === 1); await answerTrackInfo(streams[0]); @@ -977,8 +977,8 @@ test.each([ const first = new AbortController(); const second = new AbortController(); - const a = subscriber.fetchGroup(Path.from("room"), "video", 0, { signal: first.signal }); - const b = subscriber.fetchGroup(Path.from("room"), "video", 0, { signal: second.signal }); + const a = subscriber.fetchGroup({ path: Path.from("room") }, "video", 0, { signal: first.signal }); + const b = subscriber.fetchGroup({ path: Path.from("room") }, "video", 0, { signal: second.signal }); await drainUntil(() => streams.length === 1); await streams[0].reading; @@ -1014,7 +1014,7 @@ test("a fetch after the last sharer left is never failed with the cancelled one" const subscriber = new Subscriber(quic, Version.DRAFT_05, HopSchema.parse(1n)); const controller = new AbortController(); - const a = subscriber.fetchGroup(Path.from("room"), "video", 0, { signal: controller.signal }); + const a = subscriber.fetchGroup({ path: Path.from("room") }, "video", 0, { signal: controller.signal }); void a.catch(() => undefined); await drainUntil(() => streams.length === 1); await answerTrackInfo(streams[0]); @@ -1023,7 +1023,7 @@ test("a fetch after the last sharer left is never failed with the cancelled one" controller.abort(new Error("gone")); for (let i = 0; i < depth; i++) await Promise.resolve(); - const b = subscriber.fetchGroup(Path.from("room"), "video", 0).catch((err: unknown) => err); + const b = subscriber.fetchGroup({ path: Path.from("room") }, "video", 0).catch((err: unknown) => err); for (let i = 0; i < 64; i++) await Promise.resolve(); // An empty-group FIN accepts whichever FETCH the late caller is waiting on. @@ -1051,7 +1051,7 @@ test("the last reader leaving mid-response cancels the fetch", async () => { const { quic, streams } = fakeSession(); const subscriber = new Subscriber(quic, Version.DRAFT_05, HopSchema.parse(1n)); - const fetch = subscriber.fetchGroup(Path.from("room"), "video", 0); + const fetch = subscriber.fetchGroup({ path: Path.from("room") }, "video", 0); await drainUntil(() => streams.length === 1); await answerTrackInfo(streams[0]); await drainUntil(() => streams.length === 2); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 6f59818192d..735ddf31570 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -3,6 +3,7 @@ import * as announce from "../announced.ts"; import * as broadcast from "../broadcast.ts"; import type { Probe as ProbeStats } from "../connection/stats.ts"; import { BroadcastCache } from "../consume.ts"; +import type * as Epoch from "../epoch.ts"; import { controlTimeout, error, ProtocolViolation, reason, StreamCode, StreamError, sessionCause } from "../error.ts"; import * as netGroup from "../group.ts"; import { Cost, type Hop, MAX_HOPS, type Route, randomHop, routesEqual, stampHops, UNKNOWN_HOP } from "../hop.ts"; @@ -28,7 +29,7 @@ import { Fetch as FetchMessage } from "./fetch.ts"; import { frameDecoder, type Group as GroupMessage, readFrames } from "./group.ts"; import { sendOrder } from "./priority.ts"; import { Probe } from "./probe.ts"; -import { ProbeLevel, type Setup } from "./setup.ts"; +import { ProbeLevel, type Setup, supportsEpoch } from "./setup.ts"; import { StreamId } from "./stream.ts"; import { decodeSubscribeResponse, @@ -153,6 +154,7 @@ export class Subscriber { // The peer's SETUP (lite-05+), undefined until it arrives. Gates opening the PROBE // stream on the peer having advertised Probe >= Report. #peerSetup?: Signal; + #epochs: Promise; // Distinguishes failures from streams torn down by Subscriber.close(). #closed = new AbortController(); @@ -179,6 +181,7 @@ export class Subscriber { this.#stamp = randomHop(); this.#probe = probe; this.#peerSetup = peerSetup; + this.#epochs = supportsEpoch({ version, peer: peerSetup, closed: quic.closed }); } /** @@ -331,9 +334,13 @@ export class Subscriber { // Present on active/restart; ended messages never carry hops worth checking. let hops: Hop[] | undefined; let cost: Cost | undefined; + let epoch: Epoch.Valid | undefined; switch (announce.status) { case "active": { + epoch = announce.epoch; + if (epoch !== undefined && !(await this.#epochs)) + throw new ProtocolViolation("epoch metadata was not negotiated"); const resolved = hasAnnounceId(this.version) ? history.start(announce) : announce; // The wire names the suffix beneath the interest prefix; the consumer // sees the covered path from the session root. @@ -356,6 +363,7 @@ export class Subscriber { // Resolve the id; it stays live (the replacement reuses it). const resolved = history.update(announce); path = Path.join(prefix, resolved.suffix); + epoch = advertised.get(path)?.route.epoch; active = true; hops = resolved.hops; cost = announce.cost; @@ -389,7 +397,7 @@ export class Subscriber { const previous = advertised.get(path); advertised.delete(path); if (!previous?.live) return; - this.#consumes.evict(path); + this.#consumes.evict(path, previous.route.epoch); console.debug(`announced: broadcast=${path} active=false`); announced.append({ prefix: path, @@ -443,7 +451,7 @@ export class Subscriber { }); continue; } - const route: Route = { hops: fullHops, cost: cost ?? Cost.zero }; + const route: Route = { hops: fullHops, cost: cost ?? Cost.zero, epoch }; const captures = scopeCaptures(scope, path); if (!visible(path)) { advertised.set(path, { live: false, route, captures }); @@ -455,6 +463,8 @@ export class Subscriber { // route in place, so a forwarder re-prices without retracting. const previous = advertised.get(path); if (previous?.live) { + if (previous.route.epoch !== epoch) + throw new ProtocolViolation("an announcement cannot change publisher epoch"); // Even from another publisher: the path still names the same broadcast, so // the shared consume stays. advertised.set(path, { live: true, route, captures }); @@ -501,28 +511,30 @@ export class Subscriber { * @param name - The name of the broadcast to consume * @returns A Broadcast instance */ - consume(path: Path.Valid): broadcast.Consumer { - return this.#consumes.get(path) ?? this.#consumes.insert(path, this.#createConsume(path)); + consume(path: Path.Valid, epoch?: Epoch.Valid): broadcast.Consumer { + return ( + this.#consumes.get(path, epoch) ?? this.#consumes.insert(path, this.#createConsume({ path, epoch }), epoch) + ); } - #createConsume(path: Path.Valid): broadcast.Consumer { + #createConsume(id: broadcast.Id): broadcast.Consumer { // A consumed broadcast resolves info() and fetchGroup() over the wire by reaching // back into this Subscriber (see ConsumeBroadcast below), rather than the wire // installing callbacks on the broadcast. - const consumer = new ConsumeBroadcast(this, path); + const consumer = new ConsumeBroadcast(this, id); void (async () => { for (;;) { const request = await wireOf(consumer).requested(); if (!request) break; - void this.#runSubscribe(path, request); + void this.#runSubscribe(id, request); } })(); return consumer; } - async #runSubscribe(broadcast: Path.Valid, request: track.Request) { + async #runSubscribe(broadcast: broadcast.Id, request: track.Request) { const id = this.#subscribeNext++; const subscription = request.subscription; const initialBounds = groupBounds(subscription.groups); @@ -540,7 +552,8 @@ export class Subscriber { const msg = new Subscribe({ id, - broadcast, + broadcast: broadcast.path, + epoch: broadcast.epoch, track: request.name, priority: subscription.priority ?? 0, maxAge: subscription.maxAge, @@ -602,7 +615,7 @@ export class Subscriber { const subscriptionUpdates = this.version === Version.DRAFT_01 || this.version === Version.DRAFT_02 ? undefined - : this.#runSubscriptionUpdates(id, broadcast, entry, msg, stream); + : this.#runSubscriptionUpdates(id, broadcast.path, entry, msg, stream); // Terminal conditions (stream end, track close, a failed subscription update) settle at most // once; race them into one stable promise so the demand loop doesn't re-subscribe each pass. @@ -660,7 +673,7 @@ export class Subscriber { if (supportsTrackStream(this.version)) { // Fetch the immutable properties once via the TRACK stream. - const info = await this.#trackInfo(msg.broadcast, msg.track); + const info = await this.#trackInfo({ path: msg.broadcast, epoch: msg.epoch }, msg.track); producer = request.accept(this.#toModelInfo(info)); timescale.set(info.timescale); } else { @@ -703,10 +716,12 @@ export class Subscriber { } // Opens a TRACK stream, reads the single TRACK_INFO, and FINs. Lite-05+ only. - async #trackInfo(broadcast: Path.Valid, track: string): Promise { + async #trackInfo(broadcast: broadcast.Id, track: string): Promise { + if (broadcast.epoch !== undefined && !(await this.#epochs)) + throw new Error("peer does not support epoch identity"); return this.#exchange({ version: this.version }, async (stream) => { await stream.writer.u53(StreamId.Track); - await new TrackMessage(broadcast, track).encode(stream.writer, this.version); + await new TrackMessage(broadcast.path, track, broadcast.epoch).encode(stream.writer, this.version); const info = await TrackInfo.decode(stream.reader, this.version); // The publisher FINs after TRACK_INFO; FIN our side too. stream.close(); @@ -748,7 +763,7 @@ export class Subscriber { // Resolve a track's immutable model info via a TRACK stream (lite-05+), for the // ConsumeBroadcast backing track.Consumer.query(). On older drafts there's no TRACK // stream, so this rejects rather than fabricating defaults. - async resolveTrackInfo(broadcast: Path.Valid, track: string): Promise { + async resolveTrackInfo(broadcast: broadcast.Id, track: string): Promise { if (!supportsTrackStream(this.version)) { throw new Error("track info requires moq-lite-05 or newer"); } @@ -758,7 +773,7 @@ export class Subscriber { // Open a FETCH stream for one group and stream its bare frames into a group, for the // ConsumeBroadcast backing track.Consumer.fetchGroup() (lite-05+). async fetchGroup( - broadcast: Path.Valid, + broadcast: broadcast.Id, track: string, sequence: number, options: track.FetchGroupOptions = {}, @@ -800,7 +815,7 @@ export class Subscriber { // group, evict the entry, and reject every caller waiting for acceptance. A setup every caller // has abandoned is cancelled the same way. async #runFetch( - broadcast: Path.Valid, + broadcast: broadcast.Id, track: string, sequence: number, priority: number, @@ -837,7 +852,7 @@ export class Subscriber { // Resolve the track's timescale, then open the FETCH stream and wait for it to be accepted. // Closing the group during that wait resets the stream. async #fetchSetup( - broadcast: Path.Valid, + broadcast: broadcast.Id, track: string, sequence: number, priority: number, @@ -846,7 +861,13 @@ export class Subscriber { const info = await untilClosed(group, this.#trackInfo(broadcast, track)); return this.#exchange({ sendOrder: sendOrder({ priority }), version: this.version }, async (stream) => { await stream.writer.u53(StreamId.Fetch); - await new FetchMessage({ broadcast, track, priority, group: sequence }).encode(stream.writer, this.version); + await new FetchMessage({ + broadcast: broadcast.path, + epoch: broadcast.epoch, + track, + priority, + group: sequence, + }).encode(stream.writer, this.version); // A byte or an empty-group FIN accepts the fetch; a reset rejects it. // done() buffers that byte so the response pump can decode it normally. await untilClosed(group, stream.reader.done()); @@ -1306,21 +1327,21 @@ async function untilAbandoned(group: netGroup.Producer, step: Promise): Pr */ class ConsumeBroadcast extends broadcast.Consumer { #subscriber: Subscriber; - #path: Path.Valid; + #id: broadcast.Id; - constructor(subscriber: Subscriber, path: Path.Valid, state?: never) { - super(state); + constructor(subscriber: Subscriber, id: broadcast.Id, state?: never) { + super(state, id.epoch); overrideBroadcastWire(this, { - resolveTrackInfo: (name) => subscriber.resolveTrackInfo(path, name), - fetchGroup: (name, sequence, options) => subscriber.fetchGroup(path, name, sequence, options), + resolveTrackInfo: (name) => subscriber.resolveTrackInfo(id, name), + fetchGroup: (name, sequence, options) => subscriber.fetchGroup(id, name, sequence, options), }); this.#subscriber = subscriber; - this.#path = path; + this.#id = id; } // Preserve the subclass (and its wire-backed info/fetchGroup) when the consume cache shares // this broadcast across callers. override clone(): ConsumeBroadcast { - return new ConsumeBroadcast(this.#subscriber, this.#path, this.shareState()); + return new ConsumeBroadcast(this.#subscriber, this.#id, this.shareState()); } } diff --git a/js/net/src/lite/track.ts b/js/net/src/lite/track.ts index d07db186b24..e207be2e61e 100644 --- a/js/net/src/lite/track.ts +++ b/js/net/src/lite/track.ts @@ -1,6 +1,8 @@ +import type * as Epoch from "../epoch.ts"; import * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; +import * as EpochWire from "./epoch.ts"; import * as Message from "./message.ts"; import { hasGroupOrder, Version } from "./version.ts"; @@ -22,33 +24,37 @@ function guardTrack(version: Version) { * Asks for a track's immutable publisher properties without subscribing or fetching. */ export class Track { + /** The selected publisher instance, when negotiated. */ + epoch?: Epoch.Valid; broadcast: Path.Valid; track: string; - constructor(broadcast: Path.Valid, track: string) { + constructor(broadcast: Path.Valid, track: string, epoch?: Epoch.Valid) { + this.epoch = epoch; this.broadcast = broadcast; this.track = track; } - async #encode(w: Writer) { + async #encode(w: Writer, version: Version) { await w.string(Path.encode(this.broadcast)); await w.string(this.track); + await EpochWire.encode(w, version, this.epoch); } - static async #decode(r: Reader): Promise { + static async #decode(r: Reader, version: Version): Promise { const broadcast = Path.decode(await r.string()); const track = await r.string(); - return new Track(broadcast, track); + return new Track(broadcast, track, await EpochWire.decode(r, version)); } async encode(w: Writer, version: Version): Promise { guardTrack(version); - return Message.encode(w, (w) => this.#encode(w)); + return Message.encode(w, (w) => this.#encode(w, version)); } static async decode(r: Reader, version: Version): Promise { guardTrack(version); - return Message.decode(r, (r) => Track.#decode(r)); + return Message.decode(r, (r) => Track.#decode(r, version)); } } diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index 615dfca3c16..491a8f229e6 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -85,7 +85,7 @@ test("a borrowed table exposes dynamic serving and a live scoped broadcast map", local.announce({ cost: 4n }); await settle(); - expect(live.peek().get(localPath)).toEqual(Route.normalize({ cost: 4n })); + expect(live.peek().get(localPath)).toEqual(Route.normalize({ cost: 4n, epoch: local.epoch })); expect(changes.some((value) => value.get(localPath)?.cost.warm === 4n)).toBe(true); const prefix = Path.from("room"); @@ -161,7 +161,7 @@ test("an announced local path competes with a received route on cost", async () local.announce({ cost: 9n }); expect(live.peek().get(path)).toEqual(Route.normalize({ hops: [PEER], cost: 5n })); local.announce({ cost: 5n }); - expect(live.peek().get(path)).toEqual(Route.normalize({ cost: 5n })); + expect(live.peek().get(path)).toEqual(Route.normalize({ cost: 5n, epoch: local.epoch })); local.close(); await settle(); @@ -182,7 +182,7 @@ test("a scoped route remains visible when an exact local path is outside the sco const scope = Path.Pattern.parse("room/*"); const live = origin.broadcasts(scope); - expect(origin.broadcasts().peek().get(path)).toEqual(Route.default); + expect(origin.broadcasts().peek().get(path)).toEqual({ ...Route.default, epoch: local.epoch }); expect(live.peek().get(path)).toEqual(Route.normalize({ cost: 5n })); local.close(); @@ -1359,7 +1359,9 @@ test("a peer is offered and served the cheapest originated route", async () => { local.announce({ cost: 5n }); expect(wireOf(consumer).advertised.peek()?.get(prefix)?.[0]?.route).toEqual(Route.normalize({ cost: 1n })); local.announce({ cost: 0n }); - expect(wireOf(consumer).advertised.peek()?.get(prefix)?.[0]?.route).toEqual(Route.normalize({ cost: 0n })); + expect(wireOf(consumer).advertised.peek()?.get(prefix)?.[0]?.route).toEqual( + Route.normalize({ cost: 0n, epoch: local.epoch }), + ); local.close(); upstream.close(); @@ -1927,118 +1929,12 @@ test("broadcast handles carry the path they were created or requested at", async origin.close(); }); -/** Two epochs of `room/alice` in mint order, older first. */ -const OLD = Path.from("room/alice/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f"); -const NEW = Path.from("room/alice/@0199b7f4-3c2b-7d1e-9f0b-2b6c1a9d8e7f"); - -test("a bare name follows its newest epoch and falls back to an older one", async () => { - const origin = new Producer(); - const consumer = origin.consume(); - const bare = Path.from("room/alice"); - expect(wireOf(consumer).routes(bare)).toBe(false); - - const old = publish(origin, OLD); - expect(wireOf(consumer).routes(bare)).toBe(true); - const request = consumer.request(bare, { announced: true }); - const pinned = consumer.request(OLD); - const first = request.active.peek(); - expect(first).toBeDefined(); - // Named as asked, so a catalog's relative references resolve against the name. - expect(first?.path).toBe(bare); - - // A newer epoch is a new broadcast to the follower; the pinned request stays. - const next = publish(origin, NEW); - const second = request.active.peek(); - expect(second).toBeDefined(); - expect(second).not.toBe(first); - expect(second?.path).toBe(bare); - expect(pinned.active.peek()?.closed.peek()).toBeUndefined(); - - // Retracting the newest falls back to the older epoch still live. - next.close(); - await settle(); - const third = request.active.peek(); - expect(third).toBeDefined(); - expect(third).not.toBe(second); - - old.close(); - await settle(); - expect(request.active.peek()).toBeUndefined(); - - request.close(); - pinned.close(); - origin.close(); -}); - -test("a received epoch serves a bare request through its session", async () => { - const origin = new Producer(); - const consumer = origin.consume(); - const upstream = new BroadcastProducer(); - const asked: Path.Valid[] = []; - const handle = wireOf(origin).receive(NEW, Route.default); - void (async () => { - for await (const request of handle.requested()) { - asked.push(request.path); - request.accept(upstream.consume()); - } - })(); - - const request = consumer.request(Path.from("room/alice")); - await settle(); - expect(request.active.peek()).toBeDefined(); - // The session is asked for the epoch, never the bare name. - expect(asked).toEqual([NEW]); - - request.close(); - handle.close(); - upstream.close(); - origin.close(); -}); - -test("an epoch beats a route covering the name", async () => { - const origin = new Producer(); - const consumer = origin.consume(); - const epoch = publish(origin, NEW); - const raw = publish(origin, Path.from("room/alice")); - - const request = consumer.request(Path.from("room/alice")); - const fromEpoch = request.active.peek(); - expect(fromEpoch).toBeDefined(); - // Served from the epoch: once it goes, the bare name falls through to its own route, - // as a new broadcast. Had the route won, nothing would change here. - epoch.close(); - await settle(); - const fromRoute = request.active.peek(); - expect(fromRoute).toBeDefined(); - expect(fromRoute).not.toBe(fromEpoch); - - request.close(); - raw.close(); - origin.close(); -}); - -test("a grant on a name admits its epochs and a grant on an epoch only that one", () => { - const origin = new Producer(); - const exact = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.literal("room/alice")])); - const broadcast = publish(exact, OLD); - expect(() => exact.createBroadcast(Path.from("room/alice/cam"))).toThrow(); - - const one = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.literal(OLD)])); - expect(() => one.consume().request(OLD).close()).not.toThrow(); - expect(() => one.consume().request(Path.from("room/alice"))).toThrow(); - expect(() => one.consume().request(NEW)).toThrow(); - - broadcast.close(); - origin.close(); -}); - -test("an epoch only ends a path", () => { +test("reannouncing a broadcast cannot change its epoch", () => { const origin = new Producer(); - for (const path of [Path.join(OLD, Path.from("transcode")), Path.join(OLD, NEW.split("/").at(-1) as Path.Valid)]) { - expect(() => origin.createBroadcast(path)).toThrow("misplaced epoch"); - expect(() => origin.dynamic(path)).toThrow("misplaced epoch"); - } - // A derived broadcast carries the source's epoch at its own end instead. - origin.createBroadcast(Path.withEpoch(Path.from("room/alice/transcode"), Path.splitEpoch(OLD).epoch)).close(); + const source = origin.createBroadcast(Path.from("live")); + const other = origin.createBroadcast(Path.from("other")); + expect(() => source.announce({ ...Route.default, epoch: other.epoch })).toThrow("epoch"); + source.close(); + other.close(); origin.close(); }); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index 62fefd099f8..a3276c635d8 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -13,6 +13,7 @@ import { Derived, type Dispose, type GetPromise, type Getter, getter, Once, Signal } from "@moq/signals"; import * as announce from "./announced.ts"; import * as broadcast from "./broadcast.ts"; +import * as Epoch from "./epoch.ts"; import { StreamCode, StreamError } from "./error.ts"; import { isAnonymous, Route, routesEqual } from "./hop.ts"; import { hiddenBelow, hooks, scopeCaptures, scopeHead, scopeOverlaps, spreadHash } from "./internal.ts"; @@ -34,10 +35,9 @@ class Scope { this.allowed = allowed; } - /** A pattern that admits a name also admits its epochs (`name/@`). */ narrow(root: Path.Valid, patterns: Path.Patterns): Scope { const joined = Path.encode(Path.join(this.root, root)); - const rooted = withEpochs(patterns.rooted(joined)); + const rooted = patterns.rooted(joined); const allowed = this.allowed?.intersect(rooted) ?? rooted; if (allowed.size === 0) throw new Error("origin scopes do not overlap"); return new Scope(joined, allowed); @@ -123,35 +123,6 @@ class Scope { } } -const EPOCH_SEGMENT: Path.Segment = { kind: "partial", prefix: "@", suffix: "" }; - -/** Throw when an epoch (`@`) sits anywhere but the end of `path`; an epoch only ever ends a path. */ -function refuseMisplacedEpoch(path: Path.Valid) { - const parts = path === "" ? [] : path.split("/"); - if (parts.slice(0, -1).some((part) => Path.splitEpoch(part as Path.Valid).epoch !== undefined)) { - throw new Error(`misplaced epoch: an epoch must be the last path segment: ${path}`); - } -} - -/** - * `patterns` with each name they admit also admitting its epochs: a member not ending in - * `**` gains a `/@*` sibling. A grant on one epoch names that epoch, so it never widens to - * the bare name or its siblings. Mirrors Rust's `with_epochs`. - */ -function withEpochs(patterns: Path.Patterns): Path.Patterns { - const widened = new Path.Patterns(patterns); - for (const member of patterns) { - const last = member.segments.at(-1); - if (last?.kind === "globstar" || (last?.kind === "partial" && last.prefix === "@" && last.suffix === "")) { - continue; - } - // A member at the depth limit names nothing with room for an epoch. - if (member.segments.length >= Path.Pattern.MAX_SEGMENTS) continue; - widened.insert(Path.Pattern.from([...member.segments, EPOCH_SEGMENT])); - } - return widened; -} - /** Whether the route advertised at `prefix` may serve any path `pattern` admits. */ function advertOverlaps(advert: Advertised, prefix: Path.Valid, pattern: Path.Pattern): boolean { return advert.claim ? advert.claim.overlaps(pattern) : scopeOverlaps(pattern, prefix); @@ -522,13 +493,6 @@ class OriginState { * the answer for a single path. */ refresh(path: Path.Valid): void { - this.#refreshSlot(path); - // A bare name follows the epochs below it. - const { name, epoch } = Path.splitEpoch(path); - if (epoch !== undefined) this.#refreshSlot(name); - } - - #refreshSlot(path: Path.Valid): void { const slot = this.requests.peek()?.get(path); if (!slot) return; slot.route.set(this.route(path, slot)); @@ -552,18 +516,11 @@ class OriginState { * per candidate. */ refuse(path: Path.Valid, entry: RouteEntry, err: Error): void { - this.#refuseSlot(path, path, entry, err); - // A bare name following this epoch was asking through the same route. - const { name, epoch } = Path.splitEpoch(path); - if (epoch !== undefined && this.target(name) === path) this.#refuseSlot(name, path, entry, err); - } - - #refuseSlot(path: Path.Valid, target: Path.Valid, entry: RouteEntry, err: Error): void { const slot = this.requests.peek()?.get(path); if (!slot) return; // Only the route the request is waiting on speaks for it; one superseded by another // route or a local broadcast has a moot answer. - if (this.bestEntry(target) !== entry || this.localWins(target, entry)) return; + if (this.bestEntry(path) !== entry || this.localWins(path, entry)) return; this.requests.mutate((map) => { if (map?.get(path) === slot) map.delete(path); @@ -583,12 +540,8 @@ class OriginState { * releases a retracted route's session subscription even when nothing reads it again. */ refreshPrefix(prefix: Path.Valid): void { - // A route at an epoch also moves the bare name above it. - const { name, epoch } = Path.splitEpoch(prefix); for (const [path, slot] of this.requests.peek() ?? []) { - if (Path.hasPrefix(prefix, path) || (epoch !== undefined && path === name)) { - slot.route.set(this.route(path, slot)); - } + if (Path.hasPrefix(prefix, path)) slot.route.set(this.route(path, slot)); } } @@ -615,7 +568,7 @@ class OriginState { } /** The preferred entry on the most specific route covering `path`, ignoring skipped entries, if any. */ - bestEntry(path: Path.Valid, skip?: (entry: RouteEntry) => boolean): RouteEntry | undefined { + bestEntry(path: Path.Valid, skip?: (entry: RouteEntry) => boolean, epoch?: Epoch.Valid): RouteEntry | undefined { let bestPrefix: Path.Valid | undefined; let best: RouteEntry | undefined; for (const [prefix, entries] of this.routes.peek() ?? []) { @@ -623,7 +576,10 @@ class OriginState { const entry = preferredEntry( path, entries, - (candidate) => !candidate.scope.matches(path) || (skip?.(candidate) ?? false), + (candidate) => + !candidate.scope.matches(path) || + (epoch !== undefined && candidate.route.peek().epoch !== epoch) || + (skip?.(candidate) ?? false), ); if (!entry) continue; if (bestPrefix === undefined || prefix.length > bestPrefix.length) { @@ -650,8 +606,7 @@ class OriginState { /** * What `path` resolves to: an announced local publish, a broadcast materialized from - * the best covering route, or the blind answer. A bare name resolves through its - * {@link target} epoch, so a newer epoch swaps in a different broadcast. + * the best covering route, or the blind answer. * * Materialization is lazy and cached per path: the first request under a route opens * the providing session's subscription and repeats share it. A better route is made @@ -659,10 +614,9 @@ class OriginState { * answers (then swaps) or refuses (then the request ends). A retracted route swaps at once. */ route(path: Path.Valid, slot: Pick): broadcast.Consumer | undefined { - const target = this.target(path); - const entry = this.bestEntry(target); - const local = this.local.peek()?.get(target); - if (local && this.localWins(target, entry)) { + const entry = this.bestEntry(path); + const local = this.local.peek()?.get(path); + if (local && this.localWins(path, entry)) { // Nothing reads a remote front the local broadcast replaced, so close its session subscription. this.releaseMaterialized(path); return local; @@ -679,41 +633,16 @@ class OriginState { return slot.answer; } - const served = entry.server.served.get(target); + const served = entry.server.served.get(path); if (served && served.closed.peek() === undefined) { cached?.front.close(); - // A bare name shares its epoch's broadcast with the epoch's own requests, so it - // caches a handle of its own: releasing one must not close the other. - const front = target === path ? served : served.clone(); - this.materialized.set(path, { entry, front }); - return front; + this.materialized.set(path, { entry, front: served }); + return served; } - entry.server.enqueue(target); + entry.server.enqueue(path); return cached?.front; } - - /** - * The path a request for `path` is served from: the newest epoch below a bare `path` - * that something routes, ahead of any route covering the name, otherwise `path` itself. - * A path naming an epoch pins it. Mirrors Rust's resolution; a request re-reads it, so - * a bare name's `active` swaps to a newer epoch as a new broadcast, never a continuation. - */ - target(path: Path.Valid): Path.Valid { - if (Path.splitEpoch(path).epoch !== undefined) return path; - let newest: Path.Valid | undefined; - const consider = (candidate: Path.Valid) => { - const { name, epoch } = Path.splitEpoch(candidate); - // Same name, so the text orders by epoch, which orders by mint time. - if (epoch !== undefined && name === path && (newest === undefined || candidate > newest)) - newest = candidate; - }; - for (const candidate of this.local.peek()?.keys() ?? []) consider(candidate); - for (const [prefix, entries] of this.routes.peek() ?? []) { - if (entries.some((entry) => entry.scope.matches(prefix))) consider(prefix); - } - return newest ?? path; - } } /** @@ -733,7 +662,7 @@ export interface Table { readonly discovery: Getter; /** Create an unannounced broadcast at `path`; see {@link Producer.createBroadcast}. */ - createBroadcast(path: Path.Valid): broadcast.Producer; + createBroadcast(id: Path.Valid | broadcast.Id): broadcast.Producer; /** Resolve `path`, optionally waiting for an announcement; see {@link Consumer.request}. */ request(path: Path.Valid, options?: RequestOptions): Requesting; @@ -745,7 +674,10 @@ export interface Table { announced(scope?: Path.Pattern, options?: announce.Options): announce.Consumer; /** Advertise a prefix and serve requests under it; see {@link Producer.dynamic}. */ - dynamic(prefix: Path.Valid, route?: Route | { hops?: Route["hops"]; cost?: Route["cost"] | bigint }): Dynamic; + dynamic( + prefix: Path.Valid, + route?: Route | { hops?: Route["hops"]; cost?: Route["cost"] | bigint; epoch?: Epoch.Valid }, + ): Dynamic; } /** Options for resolving a broadcast path. */ @@ -835,13 +767,14 @@ export class Producer implements Table { * application still holds a consumer clone. An announced local broadcast competes with * a remote route at the same path on cost, winning ties. */ - createBroadcast(path: Path.Valid): broadcast.Producer { + createBroadcast(id: Path.Valid | broadcast.Id): broadcast.Producer { + const epoch = typeof id === "string" ? undefined : id.epoch; + let path = typeof id === "string" ? id : id.path; path = this.#scope.path(path); - refuseMisplacedEpoch(path); const created = this.#state.created; if (!created) throw new Error("origin is closed"); - const producer = new broadcast.Producer(); + const producer = new broadcast.Producer(epoch ?? Epoch.mint()); hooks.stampPath(producer, path); const front = producer.consume(); @@ -906,7 +839,7 @@ export class Producer implements Table { */ dynamic( prefix: Path.Valid, - route: Route | { hops?: Route["hops"]; cost?: Route["cost"] | bigint } = Route.default, + route: Route | { hops?: Route["hops"]; cost?: Route["cost"] | bigint; epoch?: Epoch.Valid } = Route.default, ): Dynamic { return this.#insertRoute(prefix, Route.normalize(route), true); } @@ -919,15 +852,13 @@ export class Producer implements Table { */ #receive( prefix: Path.Valid, - route: Route | { hops?: Route["hops"]; cost?: Route["cost"] | bigint } = Route.default, + route: Route | { hops?: Route["hops"]; cost?: Route["cost"] | bigint; epoch?: Epoch.Valid } = Route.default, ): Dynamic { return this.#insertRoute(prefix, Route.normalize(route), false); } #insertRoute(prefix: Path.Valid, route: Route, originated: boolean): Dynamic { prefix = this.#scope.prefix(prefix); - // A peer's announcements are its own; only refuse what this origin originates. - if (originated) refuseMisplacedEpoch(prefix); const server = new ServeState(this.#scope.root); server.onChange = (path) => this.#state.refresh(path); const entry: RouteEntry = { @@ -1192,9 +1123,7 @@ export class Requesting { * The resolved broadcast, or undefined while nothing provides the path. * * The table's route when it has one: a local publish (no round trip) or an announced - * broadcast, swapping when a republish takes the path. A bare name nothing routes - * follows its newest epoch (`name/@`), swapping to a new broadcast when a newer - * epoch appears or falling back when the newest goes away. Otherwise a session's blind + * broadcast, swapping when a republish takes the path. Otherwise a session's blind * answer, which is assumed present rather than known live: a missing broadcast * surfaces as a reset on the first track subscription, not here. Drops back to * undefined when the providing route dies and resolves again when another appears. @@ -1284,8 +1213,8 @@ export class Consumer { scope === Scope.all ? state.originated : new Derived([state.originated], (routes) => scope.projectRoutes(routes)), - local: (path) => this.#local(scope.path(path)), - demand: (path) => this.#demand(scope.path(path)), + local: (path, epoch) => this.#local(scope.path(path), epoch), + demand: (path, epoch) => this.#demand(scope.path(path), epoch), }); } @@ -1326,9 +1255,8 @@ export class Consumer { * @internal */ #routes(path: Path.Valid): boolean { - const target = this.#state.target(path); - if (this.#state.local.peek()?.has(target)) return true; - return this.#state.bestEntry(target) !== undefined; + if (this.#state.local.peek()?.has(path)) return true; + return this.#state.bestEntry(path) !== undefined; } /** @@ -1625,9 +1553,14 @@ export class Consumer { * The announced local broadcast at `path`, when it beats the originated routes there. * Resolves through what rebuildOriginated advertised: a peer never sees received routes. */ - #local(path: Path.Valid): broadcast.Consumer | undefined { + #local(path: Path.Valid, epoch?: Epoch.Valid): broadcast.Consumer | undefined { const local = this.#state.local.peek()?.get(path); - if (local && this.#state.localWins(path, this.#state.bestEntry(path, received))) return local; + if ( + local && + (epoch === undefined || local.epoch === epoch) && + this.#state.localWins(path, this.#state.bestEntry(path, received, epoch)) + ) + return local; return undefined; } @@ -1637,10 +1570,10 @@ export class Consumer { * * @internal */ - async #demand(path: Path.Valid): Promise { - const local = this.#local(path); + async #demand(path: Path.Valid, epoch?: Epoch.Valid): Promise { + const local = this.#local(path, epoch); if (local) return local; - const entry = this.#state.bestEntry(path, received); + const entry = this.#state.bestEntry(path, received, epoch); if (!entry?.server) return undefined; const server = entry.server; @@ -1704,9 +1637,11 @@ export class Dynamic { } /** Re-price the route in place. The prefix is fixed at announce time. */ - update(route: Route | { hops?: Route["hops"]; cost?: Route["cost"] | bigint }): void { + update(route: Route | { hops?: Route["hops"]; cost?: Route["cost"] | bigint; epoch?: Epoch.Valid }): void { if (this.#closed) throw new Error("dynamic is closed"); - this.#entry.route.set(Route.normalize(route)); + const next = Route.normalize(route); + if (next.epoch !== this.#entry.route.peek().epoch) throw new Error("a route cannot change publisher epoch"); + this.#entry.route.set(next); this.#state.rebuildOriginated(); this.#state.refreshPrefix(Path.join(this.#entry.scope.root, this.prefix)); this.#state.routes.mutate(() => {}); diff --git a/js/net/src/path.test.ts b/js/net/src/path.test.ts index 5b88a5b78cc..40919c91112 100644 --- a/js/net/src/path.test.ts +++ b/js/net/src/path.test.ts @@ -1,4 +1,4 @@ -import { expect, spyOn, test } from "bun:test"; +import { expect, test } from "bun:test"; import * as Epoch from "./epoch.ts"; import * as Path from "./path.ts"; @@ -333,7 +333,6 @@ const epochs = (await Bun.file(new URL("../../../rs/moq-net/src/path/epoch.json" valid: Array<{ text: string; unix_ms: number }>; invalid: string[]; ordered: string[]; - paths: Array<{ path: string; name: string; epoch: string | null; misplaced?: boolean }>; }; test("shared epoch parse, reject, order and time vectors", () => { @@ -346,68 +345,3 @@ test("shared epoch parse, reject, order and time vectors", () => { const ordered = epochs.ordered.map(Epoch.parse); expect([...ordered].reverse().sort()).toEqual(ordered); }); - -test("shared epoch path vectors", () => { - for (const row of epochs.paths) { - const path = Path.from(row.path); - const { name, epoch } = Path.splitEpoch(path); - expect(name).toBe(row.name as Path.Valid); - expect(epoch ?? null).toBe(row.epoch as Epoch.Valid | null); - if (!row.misplaced) expect(Path.withEpoch(name, epoch)).toBe(path); - } -}); - -test("withEpoch sets the final epoch", () => { - const [old, next] = epochs.ordered.map(Epoch.parse); - const name = Path.from("room/alice"); - const pinned = Path.withEpoch(name, old); - expect(pinned).toBe(`room/alice/@${old}` as Path.Valid); - // Never stacks: an existing epoch is replaced, and `undefined` removes it. - expect(Path.withEpoch(pinned, next)).toBe(Path.withEpoch(name, next)); - expect(Path.withEpoch(pinned)).toBe(name); - expect(Path.withEpoch(name)).toBe(name); -}); - -test("references resolve against the name past its epoch", () => { - const [epoch, other] = epochs.ordered.map(Epoch.parse); - const name = Path.from("room/transcode"); - const pinned = Path.withEpoch(name, epoch); - for (const text of ["./source", ".", "../other", "transcode/sub"]) { - const rel = Path.normalizeRelative(text); - expect(Path.resolve(pinned, rel)).toBe(Path.resolve(name, rel)); - expect(Path.tryResolve(pinned, rel)).toBe(Path.tryResolve(name, rel)); - } - // The empty reference still names the catalog broadcast itself. - expect(Path.resolve(pinned, "" as Path.Relative)).toBe(pinned); - // And `relative` stays its inverse. - for (const text of ["room/source", `room/source/@${other}`, "room", "other"]) { - const target = Path.from(text); - const rel = Path.relative(target, pinned); - expect(rel).toBeDefined(); - expect(Path.resolve(pinned, rel as Path.Relative)).toBe(target); - } -}); - -test("epoch segments are literal pattern components", () => { - const epoch = Epoch.parse(epochs.valid[1].text); - const path = Path.withEpoch(Path.from("demo/video"), epoch); - expect(Path.Pattern.parse("demo/**").matches(path)).toBe(true); - expect(Path.Pattern.parse("demo/video/@*").matches(path)).toBe(true); - expect(Path.Pattern.parse("demo/video").matches(path)).toBe(false); - expect(Path.Pattern.parse(path).matches(path)).toBe(true); -}); - -test("mintEpoch appends a fresh epoch", () => { - // UUIDv7 minting stays monotonic across a process, so a real clock here would push - // every later fixed-clock mint (epoch.test.ts) forward. Pin one earlier than theirs. - const now = spyOn(Date, "now").mockReturnValue(1_600_000_000_000); - try { - const minted = Path.mintEpoch(Path.from("room/alice")); - const { name, epoch } = Path.splitEpoch(minted); - expect(name).toBe(Path.from("room/alice")); - expect(epoch).toBeDefined(); - expect(Path.mintEpoch(Path.from("room/alice"))).not.toBe(minted); - } finally { - now.mockRestore(); - } -}); diff --git a/js/net/src/path.ts b/js/net/src/path.ts index 28313a74b3b..0ea78131d62 100644 --- a/js/net/src/path.ts +++ b/js/net/src/path.ts @@ -35,7 +35,6 @@ * ``` * @module */ -import * as Epoch from "./epoch.ts"; /** A normalized broadcast path. */ export type Valid = string & { __brand: "Name" }; @@ -217,8 +216,6 @@ export function normalizeRelative(rel: string): Relative { * resolution. `..` segments then pop another segment; other segments are appended. * `.` and empty segments are no-ops. Excess `..` once the base is empty is also a no-op * (subsequent named segments still append). An empty `rel` returns the base unchanged. - * A base's final epoch is not a segment here: `a/b/@` resolves like `a/b`, so a - * catalog's references mean the same whether it was requested by name or by epoch. * * Mirrors the Rust `Path::resolve`, used by hang catalogs to express * cross-broadcast track references (a rendition's `broadcast` field). @@ -233,8 +230,7 @@ export function normalizeRelative(rel: string): Relative { export function resolve(base: Valid, rel: Relative): Valid { if (rel === "") return base; - const { name } = splitEpoch(base); - const segments = name === "" ? [] : name.split("/"); + const segments = base === "" ? [] : base.split("/"); segments.pop(); for (const seg of rel.split("/")) { @@ -261,8 +257,7 @@ export function resolve(base: Valid, rel: Relative): Valid { export function tryResolve(base: Valid, rel: Relative): Valid | undefined { if (rel === "") return base; - const { name } = splitEpoch(base); - const segments = name === "" ? [] : name.split("/"); + const segments = base === "" ? [] : base.split("/"); segments.pop(); for (const seg of rel.split("/")) { @@ -312,9 +307,8 @@ export function relative(target: Valid, base: Valid): Relative | undefined { // since resolution replaces that segment rather than emitting it. if (target === base) return "" as Relative; - // Resolution replaces the base's last segment, past any epoch, so walk from its parent. - const { name } = splitEpoch(base); - const dir = name === "" ? [] : name.split("/"); + // Resolution replaces the base's last segment, so walk from its parent. + const dir = base === "" ? [] : base.split("/"); dir.pop(); const parts = target === "" ? [] : target.split("/"); @@ -345,29 +339,3 @@ export { type Segment, type Specificity, } from "@moq/pattern"; - -/** Split off a final `@` segment, leaving all other paths unchanged. */ -export function splitEpoch(path: Valid): { name: Valid; epoch?: Epoch.Valid } { - const slash = path.lastIndexOf("/"); - const segment = path.slice(slash + 1); - if (segment.startsWith("@")) { - try { - const epoch = Epoch.parse(segment.slice(1)); - return { name: path.slice(0, Math.max(0, slash)) as Valid, epoch }; - } catch { - // `@alice` and other application segments remain valid literal paths. - } - } - return { name: path }; -} - -/** `path` with its final epoch set to `epoch`, replacing any it has, or removed for `undefined`. */ -export function withEpoch(path: Valid, epoch?: Epoch.Valid): Valid { - const { name } = splitEpoch(path); - return epoch === undefined ? name : join(name, from(`@${epoch}`)); -} - -/** `path` under a freshly minted epoch, naming a new instance of the broadcast. */ -export function mintEpoch(path: Valid): Valid { - return withEpoch(path, Epoch.mint()); -} diff --git a/js/net/src/wire.ts b/js/net/src/wire.ts index a71c9ab1e4c..a0f408b389b 100644 --- a/js/net/src/wire.ts +++ b/js/net/src/wire.ts @@ -10,6 +10,7 @@ import type { Dispose, GetPromise, Getter } from "@moq/signals"; import type * as broadcast from "./broadcast.ts"; import type { Drain } from "./connection/goaway.ts"; +import type * as Epoch from "./epoch.ts"; import type { Consumer as GroupConsumer } from "./group.ts"; import type { Route } from "./hop.ts"; import type * as origin from "./origin.ts"; @@ -32,7 +33,7 @@ export interface OriginProducer { accepts(prefix: Path.Valid): boolean; receive( prefix: Path.Valid, - route?: Route | { hops?: Route["hops"]; cost?: Route["cost"] | bigint }, + route?: Route | { hops?: Route["hops"]; cost?: Route["cost"] | bigint; epoch?: Epoch.Valid }, ): origin.Dynamic; attach(discovery: boolean): Dispose; expect(): Dispose; @@ -55,8 +56,8 @@ export interface OriginConsumer { readonly broadcasts: Getter | undefined>; readonly advertised: Getter; /** The announced local broadcast at `path`, when it is the route peers are offered there. */ - local(path: Path.Valid): broadcast.Consumer | undefined; - demand(path: Path.Valid): Promise; + local(path: Path.Valid, epoch?: Epoch.Valid): broadcast.Consumer | undefined; + demand(path: Path.Valid, epoch?: Epoch.Valid): Promise; } /** One originated advertisement exposed to the publishing wire. */ @@ -75,7 +76,7 @@ export type Advertisements = ReadonlyMap; /** The protocol-facing operations behind an established session. */ export interface Established { - consume(path: Path.Valid): broadcast.Consumer; + consume(path: Path.Valid, epoch?: Epoch.Valid): broadcast.Consumer; /** Settles with the peer's GOAWAY; the session keeps serving until it closes. */ readonly goaway: GetPromise; } diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 96cd191a8ea..78f1bb96000 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -2,109 +2,46 @@ ## Goal -A path, with its `@epoch`, is the only content identity, and no first-party -publisher reuses one for different content. With #4741, any route covering a -path resumes its subscriptions from the first frame the subscriber lacks, -whoever serves it. So epochs are a correctness requirement: a publisher that -restarts its group numbering at 0 under an un-epoched name, while its old -route lingers, is resumed into the old broadcast and stalls viewers until its -sequence catches up. - -Each first-party publish of `demo/BBB.hang` goes out as -`demo/BBB.hang/@`, so a restart is a new broadcast. A smart viewer -switches to the newest epoch as soon as it is announced, and a bare-name viewer -binds to the newest when it subscribes. Moving to -a new epoch is a clean boundary (a fresh catalog and tracks, never resumed -across), and each run stays addressable by its full path. - -The epoch rides in the path, so it survives any moq-transport relay, and no -wire message changes. At an epoch-aware relay, a request for a bare name -resolves to its newest live epoch on every protocol version. - -Non-goals: pooling, which needs nothing here, since every publisher of one -path is already one source; a redundant pair shares an explicit epoch through -[`--hop` removal](/quest/m0/broadcast-epoch/hop-removal.md). Also out of -scope: trusting the publisher's clock (a far-future epoch wins until its -route goes away). +A broadcast path and its publisher epoch identify immutable content. Each new +local broadcast mints an epoch automatically, while replicas may explicitly +share one. Routes may resume a subscription only when they attest the same +requested epoch. Publisher restarts create a fresh catalog and decoder boundary. ## Plan -Decided: - -- This line gates the next release (decided 2026-10-03: #4741 can merge to - main, but without epochs every restarting first-party publisher stalls its - viewers). -- The marker is a child segment `@`, parsed into - `Option` by [the shared primitive](/doc/concept/moq-lite.md#publisher-epochs). Not a lite-07 flag: - the path is the only carrier. -- Publishing does not mint an epoch by default; the path is published as - given (decided 2026-10-04 by the maintainer, replacing "mint unless the path - already carries one"). Minting is one call: `Path::mint_epoch` in Rust and - `Path.mintEpoch` in TypeScript append a fresh `@`. Each first-party - publisher calls it once per run; a redundant pair passes a shared epoch. -- Smart subscribers use epochs natively (decided 2026-10-05 in #4817): they - watch the announcements below a name, request each epoch by its full path, - and treat a new epoch as a discontinuity (a fresh decoder). Dumb subscribers - use bare names and are sticky. -- A bare request binds once, when made, to the newest epoch with a live route, - ahead of any route covering the name (a fully qualified epoch wins). With no - epoch it goes through the covering route, such as an on-demand transcode - claim, which never announces its output. The binding never moves: a newer - epoch is a different broadcast, and the request ends with the epoch it bound - to. In TypeScript the long-lived request's `active` swaps to the newer epoch - as a new broadcast. -- Only an epoch names one origin, so only an epoch path resumes across routes. - A path without an epoch stays on the route that first served it and ends - when that route goes; it is never stitched (decided 2026-10-05). Two - unrelated epochs are never stitched either. -- A grant that admits a name admits its epochs (a `name/@*` sibling); a grant - on one epoch reaches only that epoch. The sibling admits any single `@` - segment, not only UUIDv7 text, since a pattern cannot spell one (decided - 2026-10-05: accepted and documented). -- An epoch only ever ends a path (decided 2026-10-05). Publishing - `name/@e/more` fails with `MisplacedEpoch`, and `with_epoch` - (`Path.withEpoch` in TypeScript) replaces a final epoch rather than stacking - one, with `None` removing it. -- A catalog `broadcast` reference is bare by default (decided 2026-10-05 in - #4817): it resolves against the catalog's name past its final epoch, so a - bare and a pinned fetch agree, and binds to the target's newest epoch when - requested unless it spells one. A transcoder pins its source by writing `./source/@`. -- An unmodified third-party relay routes `foo/@` but never resolves a - bare `foo`, since a route covers its descendants, not its parent. A - bare-name viewer behind one needs a publisher that publishes the bare name. - Document this rather than promise it works. -- Publishers such as moq-boy and moq-room mint their epoch at publish. - moq-stats mints its own through - [Stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md), which also gates the release - (decided 2026-10-04): a restarted stats node under a reused name stalls its - viewers the same way. -- Decided in the 2026-10-05 audit: the m1 quests gating this line (stats - epochs, the bounded stats aggregate it requires, and retracted demand - release) moved under it, and the OBS half of GStreamer and OBS moved to m1 - as [OBS publishes under epochs](/quest/m1/obs-epoch.md), so the release - gate no longer waits on m1 work. -- Derived output served on demand through a claim stays bare and sticky per - relay (decided 2026-10-05): a worker dying costs its subscribers one reset - and a cold start on the next claimant, never a splice. Whether that removes - the [wildcard](/quest/m0/wildcard/README.md) line's mirrored-epoch and - group-start requirements is the wildcard line's call. - -This README owns: - -- An end-to-end relay test: republish a name while the old publisher's session - stays open. A new-API viewer following announcements reaches the new epoch - within one RTT-scale bound rather than the idle timeout, and a lite-06 or - IETF bare-path viewer that resubscribes binds to it. -- A `doc/concept` page on broadcast naming: what an epoch is, publish and - consume behavior, smart and sticky subscribers, bare-path binding, and the - bare-name opt-out. +The core uses structured metadata, not a path suffix. Lite peers negotiate the +Epoch SETUP parameter and carry it in announcements, TRACK, SUBSCRIBE and FETCH. +Requests without an epoch stay pinned to the first serving route, never bind to +an epoch implicitly, and never merge with explicit-epoch subscriptions. They end +when their route disappears; clients resubscribe. A known epoch never follows a +new one. Route costs keep their meaning; epoch timestamps do not pick a winner. + +Legacy Lite and moq-transport peers see plain paths and no epoch metadata. +Unknown incoming identity cannot be resumed across routes. This preserves +legacy discovery and delivery, but external caches still require immutable +wire names and object positions. Audit that boundary before claiming restart +safety through arbitrary third-party relays. + +The remaining client work follows announcements, learns the selected epoch, +and opens a fresh broadcast with fresh decoders on a change. JS request.active +already delivers distinct broadcast handles. Native clients need an explicit +announcement-following helper; the core plain-path request does not follow. + +This line still gates the release. Validate publisher restarts through the +first-party applications and bindings. Derived output identity and the +[Wildcard](/quest/m0/wildcard/README.md) line's group-start requirements need a +separate decision: an unidentified sticky route is not proof of shared content. + +This README owns the final end-to-end republish test and the documentation +review after its children land. The core metadata and failover rules are in +[Publisher epochs](/doc/concept/moq-lite.md#publisher-epochs). ## Required -- [Apps](/quest/m0/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web publish under epochs and play bare names +- [Apps](/quest/m0/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web expose epoch metadata and reset playback on a new instance - [Gateways](/quest/m0/broadcast-epoch/gateways.md) - RTMP, SRT, and WHIP ingest mint an epoch per incoming connection, so an encoder reconnect is a clean takeover - [TS restart](/quest/m0/broadcast-epoch/ts-restart.md) - a signalled backward TS discontinuity finishes the broadcast and continues the same input under a fresh epoch -- [Bindings](/quest/m0/broadcast-epoch/bindings.md) - moq-ffi and every wrapper expose the epoch and a one-call mint +- [Bindings](/quest/m0/broadcast-epoch/bindings.md) - moq-ffi and every wrapper expose the epoch and inherit the default - [GStreamer](/quest/m0/broadcast-epoch/gst.md) - moqsink publishes each run under a fresh epoch - [Remove `--hop`](/quest/m0/broadcast-epoch/hop-removal.md) - `moq` takes an optional `--epoch` instead of `--hop`, a plain publisher declares a random Hop ID, and the per-session hop stamp is gone - [Stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md) - moq-stats publishes each group announcement under its own epoch, so neither a restarted node nor a returning idle group stalls its viewers diff --git a/quest/m0/broadcast-epoch/apps.md b/quest/m0/broadcast-epoch/apps.md index adf3ef287bf..3ac5b70bda1 100644 --- a/quest/m0/broadcast-epoch/apps.md +++ b/quest/m0/broadcast-epoch/apps.md @@ -1,22 +1,22 @@ -# [M] Apps publish under epochs and play bare names +# [M] Apps publish with epoch metadata and play bare names ## Goal -`moq-cli` publish and play, `@moq/publish`, `@moq/watch`, and `demo/web` -publish each run under a fresh epoch (`Path::mint_epoch`, `Path.mintEpoch`; -publishing does not mint one by default). Each publish run is a new epoch, so a restart while the +`moq-cli` publish and play, `@moq/publish`, `@moq/watch`, and `demo/web` use +the origin default. Each publish run is a new epoch, so a restart while the old route lingers is a new broadcast rather than a resume into the old one, which stalls viewers until the new run's group sequence catches up. Watching a bare name switches to a republish within an RTT. The UI and logs show the -full epoch path, and a watch link can pin one. +path and epoch metadata, and a watch link can pin one. ## Plan -- Publish sides mint the epoch once per run where they create the broadcast. - Check that nothing caches the announced path across a restart. -- Watch sides on the old JS path wait for an announcement covering the bare - name; `@moq/net` now treats an epoch below it as routing the name. +- Publish sides need little beyond passing bare names. Check that nothing + caches the announced path across a restart. - Watch sides handle "the broadcast changed" as a fresh catalog and decoder reset. Test a republish mid-playback in the browser and native players. - Update `doc/bin/cli.md` and every example invocation that shows a published path. + +Native playback must learn epochs from announcements and request explicit identities. +A plain-path request stays pinned; a helper that follows announcements is still needed. diff --git a/quest/m0/broadcast-epoch/bindings.md b/quest/m0/broadcast-epoch/bindings.md index c8dcaf07635..0351111091b 100644 --- a/quest/m0/broadcast-epoch/bindings.md +++ b/quest/m0/broadcast-epoch/bindings.md @@ -2,9 +2,8 @@ ## Goal -`moq-ffi` and the py, swift, kt, go, and dart wrappers make minting an epoch -one call (publishing does not mint one by default) and bind bare names like -Rust. The generated C and C++ +`moq-ffi` and the py, swift, kt, go, and dart wrappers publish under the +default epoch and follow bare names like Rust. The generated C and C++ bindings pick it up from moq-ffi; libmoq gets no new API. The epoch of a published or consumed broadcast is readable, and a caller can pass an explicit one. The reconnect counter `session.epoch()` is renamed so "epoch" has one meaning. diff --git a/quest/m0/broadcast-epoch/gateways.md b/quest/m0/broadcast-epoch/gateways.md index f0b8f9ec1e2..199691f90f2 100644 --- a/quest/m0/broadcast-epoch/gateways.md +++ b/quest/m0/broadcast-epoch/gateways.md @@ -10,7 +10,7 @@ up. ## Plan -Mint the epoch (`Path::mint_epoch`) where the gateways create broadcasts (`moq-rtmp`, +Use the origin default where the gateways create broadcasts (`moq-rtmp`, `moq-srt`, `moq-rtc`, and the relay wiring). Test a reconnect under the same key with the stale connection still open. Update `doc/bin/relay/` where it describes ingest paths. diff --git a/quest/m0/broadcast-epoch/gst.md b/quest/m0/broadcast-epoch/gst.md index ed47763d230..3d84a6de415 100644 --- a/quest/m0/broadcast-epoch/gst.md +++ b/quest/m0/broadcast-epoch/gst.md @@ -1,4 +1,4 @@ -# [S] GStreamer publishes under epochs +# [S] GStreamer publishes with epoch metadata ## Goal @@ -7,16 +7,17 @@ a clean takeover for viewers. ## Plan -`moqsink` mints an epoch per session. When +`moqsink` takes the origin default per session. When [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) lands, each of its publication generations is a new epoch. Update `doc/bin/gstreamer.md` if it shows paths. Decided in the 2026-10-05 audit: the OBS half moved to -[OBS publishes under epochs](/quest/m1/obs-epoch.md), so the release gate no +[OBS publishes with epoch metadata](/quest/m1/obs-epoch.md), so the release gate no longer waits on the C++ line. `moqsink` is Rust on moq-net and needs nothing -from it. +from it. moq-c announces through `broadcast::Producer::announce`, so it only +inherits an epoch if Origin mints one there; the OBS quest checks that. ## Related -- [OBS publishes under epochs](/quest/m1/obs-epoch.md) - the OBS plugin's half, after the C++ line +- [OBS publishes with epoch metadata](/quest/m1/obs-epoch.md) - the OBS plugin's half, after the C++ line diff --git a/quest/m0/broadcast-epoch/hop-removal.md b/quest/m0/broadcast-epoch/hop-removal.md index 5cb10fd5ccb..7de4eed3263 100644 --- a/quest/m0/broadcast-epoch/hop-removal.md +++ b/quest/m0/broadcast-epoch/hop-removal.md @@ -2,11 +2,10 @@ ## Goal -Nothing names a publisher's identity outside its path. `moq` loses `--hop`, +Publisher identity is the path plus epoch metadata. `moq` loses `--hop`, `MOQ_HOP`, and the hidden `--origin` alias; an optional `--epoch` takes their -place for publishing. Omitted, each run mints a fresh epoch -(`Path::mint_epoch`, since publishing does not mint one); a redundant pair -passes the same value. A plain publisher declares +place for publishing. Omitted, each run gets a fresh epoch (the origin +default); a redundant pair passes the same value. A plain publisher declares a random Hop ID per process with no flag, as the bindings and js already do, so a multi-homed publisher still catches its own loops. `--cluster-id` names a node and no longer falls back to `--hop`. Relays stop stamping an unnamed diff --git a/quest/m0/broadcast-epoch/stats-epoch.md b/quest/m0/broadcast-epoch/stats-epoch.md index 85f21240f1f..68d087c0f20 100644 --- a/quest/m0/broadcast-epoch/stats-epoch.md +++ b/quest/m0/broadcast-epoch/stats-epoch.md @@ -3,7 +3,7 @@ ## Goal Each stats group broadcast publishes under its own epoch, -`[/]/node//@`, minted each time the group is +`[/]/node/` plus epoch metadata, minted each time the group is announced, so neither a restarted node nor a group returning from idle reuses a broadcast name or the group numbers a relay cached under it. @@ -16,7 +16,7 @@ a broadcast name or the group numbers a relay cached under it. linger and drops its totals; when it returns it announces under a new epoch counted from zero. Why: a producer never holds an idle group's state, so its memory is bounded by active and lingering groups, and readers see every - reset as a new path rather than detecting one. The cost: a reader that + reset as a new identity rather than inferring a reset. The cost: a reader that misses every frame across the linger loses that epoch's tail; billing under-bills by that tail, consistent with the 0-bill baseline. At depth 0 the single broadcast never unannounces, so its epoch still lasts @@ -45,5 +45,6 @@ a broadcast name or the group numbers a relay cached under it. - demo/web stats keys include the epoch. Update `doc/concept/stats.md`, `doc/bin/relay/config.md`, and the relay stats config docs. -Public API: path shape change for every stats consumer. Wire: stats broadcast -names gain a trailing epoch segment. +Public API: stats consumers key by path and epoch. Wire: the negotiated Lite +epoch metadata carries identity without a suffix; legacy cache compatibility +needs validation before removing the release seed. diff --git a/quest/m0/broadcast-epoch/stats-split.md b/quest/m0/broadcast-epoch/stats-split.md index 51d3addf001..bebe6035de5 100644 --- a/quest/m0/broadcast-epoch/stats-split.md +++ b/quest/m0/broadcast-epoch/stats-split.md @@ -18,7 +18,7 @@ Decided 2026-10-05 (planned from moq-dev/moq.pro#2202): ends inside a group a reader missed shows in no later frame, so a lagging reader undercounts. The maps also grow with every live broadcast, and readers like billing want only per-project sums. -- **Totals.** Per group broadcast (`[/]/node//@`), +- **Totals.** Per group broadcast (`[/]/node/` plus epoch metadata), per tier and role, cumulative within the [stats epoch](/quest/m0/broadcast-epoch/stats-epoch.md). Every group announcement, and so every restart, starts a new epoch counted from zero; nothing is serialized to disk. `Registry`'s unpruned lifetime totals @@ -41,10 +41,11 @@ Decided 2026-10-05 (planned from moq-dev/moq.pro#2202): the linger (same epoch, totals continue), and one returning after it (new epoch from zero). - **Prefix tracks** (decided 2026-10-05, replacing per-broadcast tracks). - Routing is by prefix, and with epochs a broadcast is `/@`, so + Routing uses the plain broadcast path; epoch metadata is not a child segment, so a reader requests any prefix of a member path (so its depth is bounded by `Path::MAX_PARTS` less the group's own segments) and gets one track: the prefix's rollup plus a one-level map of - each direct child's rollup (a broadcast's epochs, a channel's broadcasts). + each direct child's rollup (a channel's broadcasts). Epochs remain part of the + aggregation key, not the path hierarchy. Nothing is produced for a prefix no one holds. The relay's `--stats-depth` only places the group broadcasts; requests are not capped by it. - Flow counters (bytes, frames, groups, fetches) count from zero when the diff --git a/quest/m0/broadcast-epoch/ts-restart.md b/quest/m0/broadcast-epoch/ts-restart.md index 76bd24dc460..2e65d7e4206 100644 --- a/quest/m0/broadcast-epoch/ts-restart.md +++ b/quest/m0/broadcast-epoch/ts-restart.md @@ -19,13 +19,11 @@ and a flagged forward jump publishes break markers and carries on. Decided (maintainer, 2026-09-30): -- A rewind is new content, so it is always a new broadcast at a new epoch - path (`Path::mint_epoch`), never a continuation of the old name. Smart viewers - switch to it from its announcement; a bare-name viewer binds to it on its - next subscribe. +- A rewind is new content, so it is always a new broadcast at a new epoch, never a continuation of the old name. Viewers of the bare name follow + it through [epoch metadata](/doc/concept/moq-lite.md#publisher-epochs). - `decode` stops at the flagged rewind and reports it. The caller finishes the old broadcast (a clean end, not an abort, so its viewers read to its end), - publishes a new broadcast at a fresh epoch path, and calls + publishes a new broadcast at a fresh epoch, and calls `import.restart(broadcast)`. The importer carries over only the PAT/PMT layout and the bytes it has not consumed, so there is no wait for the next PSI repetition; tracks, groups, and timestamps start fresh. `ts::Programs` diff --git a/quest/m1/obs-epoch.md b/quest/m1/obs-epoch.md index af40fff046a..5a85a3a956c 100644 --- a/quest/m1/obs-epoch.md +++ b/quest/m1/obs-epoch.md @@ -15,9 +15,11 @@ release gate waits only on `moqsink`. - OBS gets the epoch through the generated C++ bindings from moq-ffi, which the C++ line moves the plugin onto (decided in the 2026-09-30 audit: libmoq, now moq-c, gets no new API). -- Origin publishes the path as given, so the plugin mints its own epoch per - Start Streaming. -- Show the full epoch path in the dock, and update `doc/bin/obs.md` if it +- First check whether the plugin already inherits it: today it announces + through moq-c's `moq_publish_announce`, which calls + `broadcast::Producer::announce`. If Origin mints the epoch on that path, + the plugin needs no code, only a test. +- Show the full epoch identity in the dock, and update `doc/bin/obs.md` if it shows paths. ## Required diff --git a/rs/moq-e2ee/README.md b/rs/moq-e2ee/README.md index 448b1e137fc..17ed1556c7c 100644 --- a/rs/moq-e2ee/README.md +++ b/rs/moq-e2ee/README.md @@ -23,13 +23,15 @@ authenticated channel. Every publisher instance mints a shared `moq_net::Epoch` ```rust let credential = Credential::new(credential::Config { context, kid, secret })?; let generation = credential.generation(moq_net::Epoch::mint()); -let path = credential.path("meeting.hang")?.with_epoch(generation.epoch()); +let id = moq_net::broadcast::Id::from(credential.path("meeting.hang")?) + .with_epoch(generation.epoch().clone()); +let broadcast = origin.create_broadcast(id)?; let name = generation.name("video")?; let producer = generation.produce(broadcast.create_track(name.as_str(), None)?)?; ``` -A subscriber discovers instances under `credential.path(semantic)`, takes the greatest -epoch from the last `@` path segment using `Path::split_epoch`, binds the same generation, and calls +A subscriber discovers instances under `credential.path(semantic)`, takes the selected +epoch from negotiated announcement metadata (or an authenticated application channel), binds the same generation, and calls `generation.consume(subscriber)` on a track whose name it derived or read from the decrypted catalog. Nothing survives a publisher instance: a restart mints a new epoch. diff --git a/rs/moq-e2ee/src/tests.rs b/rs/moq-e2ee/src/tests.rs index e23ae704c54..1e7650bbfea 100644 --- a/rs/moq-e2ee/src/tests.rs +++ b/rs/moq-e2ee/src/tests.rs @@ -338,18 +338,6 @@ fn datagram_ciphertext(generation: &Generation, name: &Name, sequence: u64, plai protect(&key, sequence, 0, plaintext, MAX_DATAGRAM_PAYLOAD).unwrap() } -#[test] -fn path_joins_epoch() { - let cred = test_credential(); - let epoch = Epoch::mint(); - let path = cred.path("meeting.hang").unwrap(); - assert_eq!(path.as_str().len(), 22); - let full = path.with_epoch(&epoch); - let (opaque, parsed) = full.split_epoch(); - assert_eq!(opaque, path); - assert_eq!(parsed.unwrap(), epoch); -} - #[test] fn grouped_roundtrip() { let mut pair = pair("video"); diff --git a/rs/moq-e2ee/tests/transport.rs b/rs/moq-e2ee/tests/transport.rs index 8917201ade3..958e8100f7a 100644 --- a/rs/moq-e2ee/tests/transport.rs +++ b/rs/moq-e2ee/tests/transport.rs @@ -33,13 +33,15 @@ async fn connect_protected(version: Version, track: &str) -> Fixture { }) .unwrap(); let generation = cred.generation(Epoch::mint()); - let path = cred.path("meeting.hang").unwrap().with_epoch(generation.epoch()); + let path = cred.path("meeting.hang").unwrap(); let name = generation.name(track).unwrap(); let publisher = produce_origin(1); let consumer_origin = produce_origin(2); - let broadcast = publisher.create_broadcast(&path).unwrap(); + let broadcast = publisher + .create_broadcast(moq_net::broadcast::Id::from(&path).with_epoch(generation.epoch().clone())) + .unwrap(); let net = broadcast.create_track(name.as_str(), None).unwrap(); broadcast.announce(Default::default()).unwrap(); @@ -48,12 +50,10 @@ async fn connect_protected(version: Version, track: &str) -> Fixture { options.client_subscribe = Some(consumer_origin.clone()); let pair = connect_mock(options).await; - // The subscriber knows the opaque prefix and takes the epoch from the discovered path. + // Encryption identity is provided by the authenticated application context here, + // including on transports without epoch metadata. let consumer = consumer_origin.consume(); consumer.routed(&path).await.unwrap(); - let (_, epoch) = path.split_epoch(); - let epoch = epoch.unwrap(); - let generation = cred.generation(epoch); let remote = consumer.request_broadcast(&path).await.unwrap(); let subscriber = remote .track(name.as_str()) diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 0c3fa226a18..e7c45437fe4 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -1645,17 +1645,21 @@ mod tests { #[tokio::test(start_paused = true)] async fn truncated_resumed_group_skips_to_the_next_clean_group() { + let epoch = moq_net::Epoch::mint(); let origin = crate::source::produce_origin(); - // Only an epoch path resumes across routes. - let live = moq_net::Path::new("live").mint_epoch(); let hops = moq_net::Hops::try_from(vec![moq_net::Hop::new(10).unwrap()]).unwrap(); let first_route = origin .dynamic( - &live, - moq_net::origin::Route::default().with_hops(hops.clone()).with_cost(5), + "live", + moq_net::origin::Route::default() + .with_epoch(epoch.clone()) + .with_hops(hops.clone()) + .with_cost(5), ) .unwrap(); - let pending = origin.consume().request_broadcast(&live); + let pending = origin + .consume() + .request_broadcast(moq_net::broadcast::Id::from("live").with_epoch(epoch.clone())); let first = moq_net::broadcast::Info::new().produce(); let info = hang::container::track_info(hang::catalog::PRIORITY.video); let first_track = first.create_track("video", info.clone()).unwrap(); @@ -1692,8 +1696,9 @@ mod tests { for sequence in 1..=4 { let route = origin .dynamic( - &live, + "live", moq_net::origin::Route::default() + .with_epoch(epoch.clone()) .with_hops(hops.clone()) .with_cost(5 - sequence), ) diff --git a/rs/moq-net/benches/origin.rs b/rs/moq-net/benches/origin.rs index 17e159b1f0a..9071ef1f29c 100644 --- a/rs/moq-net/benches/origin.rs +++ b/rs/moq-net/benches/origin.rs @@ -425,36 +425,29 @@ fn bench_request(c: &mut Criterion) { group.finish(); } -/// Binding a bare name to its newest epoch, with `names` names in the table -/// each published under `epochs` live epochs: the walk reads only the epochs -/// one segment below the requested name, so `names` must not show. -fn bench_bind(c: &mut Criterion) { - let mut group = c.benchmark_group("origin/bind"); - for names in [100, 1_000] { - for epochs in [1, 8, 64] { - let (producer, mut driver) = origin::Producer::new(origin::Config::default()); - let consumer = producer.consume(); - let _publishers: Vec = (0..names) - .flat_map(|i| { - let name = format!("room/{i}"); - (0..epochs) - .map(|_| { - let path = moq_net::Path::new(&name).mint_epoch(); - producer.publish(path, origin::Route::default()).unwrap() - }) - .collect::>() - }) - .collect(); - let waiter = kio::Waiter::noop(); - group.bench_function(BenchmarkId::from_parameter(format!("{names}n_{epochs}e")), |b| { +/// An epoch lookup touches routes covering one path, not unrelated publishers. +fn bench_epoch_request(c: &mut Criterion) { + let mut group = c.benchmark_group("origin/epoch_request"); + for publishers in [1, 1_000] { + for routes in [1, 32] { + group.bench_function(format!("{publishers}p_{routes}r"), |b| { + let (producer, mut driver) = origin::Producer::new(origin::Config::default()); + let consumer = producer.consume(); + let mut sources = Vec::new(); + for i in 0..publishers { + for _ in 0..routes { + sources.push(producer.publish(format!("room/{i}"), origin::Route::default()).unwrap()); + } + } + let id = moq_net::broadcast::Id { + path: "room/0".into(), + epoch: sources[0].info().epoch.clone(), + }; + let waiter = kio::Waiter::noop(); b.iter(|| { - let pending = consumer.request_broadcast("room/0"); - // The front's driver resolves the first request; later ones join it. + let pending = consumer.request_broadcast(id.clone()); driver.poll(moq_net::time::Instant::now(), &waiter).unwrap(); - pending - .now_or_never() - .expect("resolves once driven") - .expect("newest epoch"); + pending.now_or_never().expect("driven").expect("matching instance"); }); }); } @@ -552,14 +545,14 @@ fn bench_pool_churn(c: &mut Criterion) { group.finish(); } -/// Publisher handoff at one epoch path: a subscriber is reading from one local +/// Publisher handoff at one path: a subscriber is reading from one local /// source when a second announces at the same path and takes over (newest -/// wins). Only an epoch path resumes across sources. Measured from the standby's attach to the subscriber receiving its +/// wins). Measured from the standby's attach to the subscriber receiving its /// first group, with `publishers` unrelated broadcasts in the table. fn bench_handoff(c: &mut Criterion) { + let id = moq_net::broadcast::Id::from("room/live").with_epoch(moq_net::Epoch::mint()); let mut group = c.benchmark_group("origin/handoff"); group.measurement_time(Duration::from_secs(5)); - let live = moq_net::Path::new("room/live").mint_epoch(); for publishers in [1, 1_000] { group.bench_function(BenchmarkId::from_parameter(format!("{publishers}p")), |b| { let runtime = tokio::runtime::Builder::new_current_thread() @@ -578,18 +571,18 @@ fn bench_handoff(c: &mut Criterion) { runtime.block_on(async { let mut total = Duration::ZERO; for _ in 0..iterations { - let incumbent = producer.publish(&live, origin::Route::default()).unwrap(); + let incumbent = producer.publish(id.clone(), origin::Route::default()).unwrap(); let track = incumbent.create_track("video", None).unwrap(); let mut first = track.append_group().unwrap(); first.write_frame(Timestamp::ZERO, b"one".as_ref()).unwrap(); first.finish().unwrap(); - let resolved = consumer.request_broadcast(&live).await.unwrap(); + let resolved = consumer.request_broadcast(id.clone()).await.unwrap(); let mut subscription = resolved.track("video").unwrap().subscribe(None).await.unwrap(); subscription.recv_group().await.unwrap().expect("first group"); let started = std::time::Instant::now(); - let standby = producer.create_broadcast(&live).unwrap(); + let standby = producer.create_broadcast(id.clone()).unwrap(); let track = standby.create_track("video", None).unwrap(); let mut second = track.create_group(moq_net::group::Info { sequence: 1 }).unwrap(); second.write_frame(Timestamp::ZERO, b"two".as_ref()).unwrap(); @@ -733,7 +726,7 @@ criterion_group!( bench_serve_idle, bench_subscribe, bench_request, - bench_bind, + bench_epoch_request, bench_pool_churn, bench_handoff, bench_relay, diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index ac95f02a8d0..14c38673f4e 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -173,6 +173,7 @@ impl Client { // no media. Versions without a Setup Stream have nothing to advertise. let our_setup = if version.has_setup_stream() { lite::Setup { + epoch: false, probe: lite::ProbeLevel::detect(&session), path: self.setup_path.clone(), role: lite::Role::from_origins(self.publish.is_some(), self.subscribe.is_some()), diff --git a/rs/moq-net/src/epoch.rs b/rs/moq-net/src/epoch.rs index 39b64ea6389..cc316cf020b 100644 --- a/rs/moq-net/src/epoch.rs +++ b/rs/moq-net/src/epoch.rs @@ -19,7 +19,7 @@ impl Epoch { Self(uuid::Uuid::now_v7().hyphenated().to_string().into()) } - /// The UUID text, without the path segment's `@` marker. + /// The canonical UUID text. pub fn as_str(&self) -> &str { &self.0 } diff --git a/rs/moq-net/src/error.rs b/rs/moq-net/src/error.rs index eef4d77a6d2..f569438999f 100644 --- a/rs/moq-net/src/error.rs +++ b/rs/moq-net/src/error.rs @@ -290,10 +290,6 @@ pub enum Error { #[error("invalid path: {0}")] InvalidPath(#[from] crate::InvalidPattern), - /// A path holds an epoch (`@`) before its last segment; an epoch only ever ends a path. - #[error("misplaced epoch: an epoch must be the last path segment")] - MisplacedEpoch, - /// A duplicate ID was used // The broadcast/track is a duplicate #[error("duplicate")] @@ -541,8 +537,7 @@ impl From<&Error> for SessionError { | Error::Encode(_) | Error::WrongSize | Error::BoundsExceeded(_) - | Error::InvalidPath(_) - | Error::MisplacedEpoch => Self::ProtocolViolation, + | Error::InvalidPath(_) => Self::ProtocolViolation, Error::App(app) => Self::App(*app), // A code we did not recognize, so we cannot say which space it came from. // Forwarding it into this one risks landing on a value that IS registered here @@ -580,11 +575,9 @@ impl From<&Error> for StreamError { Error::Timeout => Self::DeliveryTimeout, Error::GoingAway => Self::GoingAway, // Our own parse failure is, from the peer's side, a malformed track. - Error::Decode(_) - | Error::BoundsExceeded(_) - | Error::InvalidPath(_) - | Error::MisplacedEpoch - | Error::MalformedTrack => Self::MalformedTrack, + Error::Decode(_) | Error::BoundsExceeded(_) | Error::InvalidPath(_) | Error::MalformedTrack => { + Self::MalformedTrack + } Error::App(app) => Self::App(*app), // See the SessionError impl: an unregistered code carries no registry, so // re-sending the number could mistranslate it. diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index b98f5c89df2..e475160638d 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -198,6 +198,7 @@ impl AnnounceWriter { Announced::Start(suffix, hops) => { let (_, suffix, hops) = self.encoder.start(suffix.clone(), hops.clone()); lite::AnnounceBroadcast::Active { + epoch: None, suffix, hops, cost: Default::default(), @@ -320,6 +321,7 @@ impl LiteSample { .encode(w, version) .unwrap(), Self::Subscribe => lite::Subscribe { + epoch: None, id: 3, broadcast: Path::new("room/alice"), track: "video".into(), @@ -503,6 +505,7 @@ impl Default for Messages { Self { lite_subscribe: lite::Subscribe { + epoch: None, id: 7, broadcast: Path::new("room/alice"), track: "video".into(), diff --git a/rs/moq-net/src/lite/announce.rs b/rs/moq-net/src/lite/announce.rs index 4f7177ed6f0..83d091f96bc 100644 --- a/rs/moq-net/src/lite/announce.rs +++ b/rs/moq-net/src/lite/announce.rs @@ -43,6 +43,8 @@ pub enum AnnounceBroadcast<'a> { /// Carries the path suffix, the hop chain, and (lite-06+) the warm and cold /// route costs, and assigns the next announce id. Active { + /// The immutable publisher instance, when negotiated. + epoch: Option, suffix: PathRef<'a>, hops: HopsRef, cost: Cost, @@ -165,7 +167,13 @@ impl AnnounceBroadcast<'_> { #[cfg(test)] pub fn into_owned(self) -> AnnounceBroadcast<'static> { match self { - Self::Active { suffix, hops, cost } => AnnounceBroadcast::Active { + Self::Active { + suffix, + hops, + cost, + epoch, + } => AnnounceBroadcast::Active { + epoch, suffix: PathRef { base: suffix.base, keep: suffix.keep, @@ -228,10 +236,16 @@ impl Encode for AnnounceBroadcast<'_> { let prefix = w.prefix_varint(); match self { - Self::Active { suffix, hops, cost } => { + Self::Active { + suffix, + hops, + cost, + epoch, + } => { suffix.encode(w, version)?; hops.encode(w, version)?; cost.encode(w, version)?; + super::epoch::encode(w, version, epoch.as_ref())?; } Self::EndedId { id } => w.varint(*id)?, Self::Restart { id, hops, cost } => { @@ -249,7 +263,9 @@ impl Encode for AnnounceBroadcast<'_> { let prefix = w.prefix_varint(); match self { // The cost is a lite-06 addition, so it is simply not on the wire here. - Self::Active { suffix, hops, .. } => { + Self::Active { + suffix, hops, epoch, .. + } => { // Bases are a lite-07 addition; PathRef and HopsRef refuse one here. if suffix.base != 0 || hops.base != 0 { return Err(EncodeError::Version); @@ -257,6 +273,7 @@ impl Encode for AnnounceBroadcast<'_> { AnnounceStatus::Active.encode(w, version)?; suffix.rest.encode(w, version)?; encode_hops(w, version, &hops.literal)?; + super::epoch::encode(w, version, epoch.as_ref())?; } Self::Ended { suffix, hops } => { AnnounceStatus::Ended.encode(w, version)?; @@ -284,6 +301,7 @@ impl Decode for AnnounceBroadcast<'_> { suffix: PathRef::decode(&mut body, version)?, hops: HopsRef::decode(&mut body, version)?, cost: Cost::decode(&mut body, version)?, + epoch: super::epoch::decode(&mut body, version)?, }, ANNOUNCE_END => Self::EndedId { id: body.varint()? }, ANNOUNCE_RESTART => Self::Restart { @@ -341,6 +359,7 @@ impl AnnounceBroadcast<'_> { suffix: PathRef::literal(suffix), hops: HopsRef::literal(hops), cost: Cost::UNKNOWN, + epoch: super::epoch::decode(r, version)?, }, AnnounceStatus::Ended => Self::Ended { suffix, hops }, // On lite-05 a restart travels as a duplicate ANNOUNCE (a second `Active`), so accept @@ -349,6 +368,7 @@ impl AnnounceBroadcast<'_> { // fresh announce. Older versions never defined this status, so it's an // invalid value there. AnnounceStatus::Restart if restart_supported(version) => Self::Active { + epoch: super::epoch::decode(r, version)?, suffix: PathRef::literal(suffix), hops: HopsRef::literal(hops), cost: Cost::UNKNOWN, @@ -534,6 +554,7 @@ mod tests { // Encode a normal Active, then flip its status byte (1 -> 2). let mut buf = Vec::new(); AnnounceBroadcast::Active { + epoch: None, suffix: PathRef::literal(Path::new("foo/bar")), hops: HopsRef::default(), cost: Cost::default(), @@ -624,6 +645,7 @@ mod tests { let mut hops = Hops::new(); hops.push(Hop::new(7).unwrap()).unwrap(); let msg = AnnounceBroadcast::Active { + epoch: None, suffix: PathRef::literal(Path::new("room/cam")), hops: HopsRef::literal(hops.clone()), cost: Cost::UNKNOWN, @@ -647,6 +669,7 @@ mod tests { let cost = Cost { warm: 12, cold: 30 }; let active = AnnounceBroadcast::Active { + epoch: None, suffix: PathRef::literal(Path::new("room/cam")), hops: HopsRef::literal(hops.clone()), cost, @@ -672,6 +695,7 @@ mod tests { let cost = Cost { warm: 12, cold: 30 }; let active = AnnounceBroadcast::Active { + epoch: None, suffix: PathRef { base: 2, keep: 3, @@ -717,6 +741,7 @@ mod tests { #[test] fn a_base_needs_lite07() { let msg = AnnounceBroadcast::Active { + epoch: None, suffix: PathRef { base: 1, keep: 1, @@ -769,6 +794,7 @@ mod tests { #[test] fn route_cost_is_dropped_before_lite06() { let msg = AnnounceBroadcast::Active { + epoch: None, suffix: PathRef::literal(Path::new("room/cam")), hops: HopsRef::default(), cost: Cost { warm: 9, cold: 9 }, @@ -777,6 +803,7 @@ mod tests { assert_eq!( got, AnnounceBroadcast::Active { + epoch: None, suffix: PathRef::literal(Path::new("room/cam")), hops: HopsRef::default(), cost: Cost::UNKNOWN, diff --git a/rs/moq-net/src/lite/epoch.rs b/rs/moq-net/src/lite/epoch.rs new file mode 100644 index 00000000000..0dc15177b3e --- /dev/null +++ b/rs/moq-net/src/lite/epoch.rs @@ -0,0 +1,23 @@ +//! Negotiated publisher identity trailers; absent on legacy messages. +use super::Version; +use crate::{Epoch, coding::*}; + +pub(super) fn encode(w: &mut Encoder<'_>, version: Version, epoch: Option<&Epoch>) -> Result<(), EncodeError> { + if let Some(epoch) = epoch { + if !version.has_setup_stream() { + return Err(EncodeError::Version); + } + w.string(epoch.as_str())?; + } + Ok(()) +} + +pub(super) fn decode(r: &mut Decoder<'_>, version: Version) -> Result, DecodeError> { + if r.is_empty() { + return Ok(None); + } + if !version.has_setup_stream() { + return Err(DecodeError::Version); + } + Ok(Some(r.string()?.parse().map_err(|_| DecodeError::InvalidValue)?)) +} diff --git a/rs/moq-net/src/lite/fetch.rs b/rs/moq-net/src/lite/fetch.rs index 7bb16636c64..8027ec0db74 100644 --- a/rs/moq-net/src/lite/fetch.rs +++ b/rs/moq-net/src/lite/fetch.rs @@ -12,6 +12,8 @@ use super::{Message, Version}; /// Lite03+ only. #[derive(Clone, Debug)] pub struct Fetch<'a> { + /// The requested publisher instance, only sent after epoch negotiation. + pub epoch: Option, pub broadcast: Path<'a>, pub track: Cow<'a, str>, pub priority: u8, @@ -47,6 +49,7 @@ impl Message for Fetch<'_> { } Ok(Self { + epoch: super::epoch::decode(r, version)?, broadcast, track, priority, @@ -77,6 +80,7 @@ impl Message for Fetch<'_> { return Err(EncodeError::Version); } + super::epoch::encode(w, version, self.epoch.as_ref())?; Ok(()) } } @@ -87,6 +91,7 @@ mod test { fn fetch_sample() -> Fetch<'static> { Fetch { + epoch: None, broadcast: Path::new("room").to_owned(), track: Cow::Borrowed("video"), priority: 3, diff --git a/rs/moq-net/src/lite/mod.rs b/rs/moq-net/src/lite/mod.rs index 566f2c5b8aa..cff9345d99c 100644 --- a/rs/moq-net/src/lite/mod.rs +++ b/rs/moq-net/src/lite/mod.rs @@ -7,6 +7,7 @@ mod announce; mod compress; mod datagram; +mod epoch; mod fetch; mod goaway; mod group; diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 5d6e30b8406..01fdd302075 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -563,6 +563,8 @@ impl AnnounceServe { self.start(prefix, exclude_hop, hidden); } AnnounceState::Run { origin, announced, run } => { + run.epochs = + self.shared.version.has_setup_stream() && ready!(self.shared.peer_setup.poll_epoch(waiter)); let stream = self.stream.as_mut().expect("stream present"); if self.shared.withdrawal.poll(waiter).is_ready() { run.withdraw(stream, origin, announced)?; @@ -625,6 +627,7 @@ impl AnnounceServe { /// The announce loop's state, minus the handles it borrows per poll so the test /// shim can supply its own. struct AnnounceRun { + epochs: bool, self_origin: Hop, version: Version, // Lite06+: announce ids. Every `active` we send implicitly assigns the next @@ -640,6 +643,7 @@ struct AnnounceRun { /// What the peer holds for one advertised suffix. struct Advertised { + epoch: Option, /// The announce id, on versions that assign them. id: Option, /// The chain and cost last put on the wire. The origin also reports changes the @@ -660,6 +664,7 @@ enum AnnouncePhase { impl AnnounceRun { fn new(self_origin: Hop, version: Version) -> Self { Self { + epochs: false, self_origin, version, encoder: lite::AnnounceEncoder::new(version), @@ -670,7 +675,11 @@ impl AnnounceRun { /// The chain and cost to put on the wire for `route`, or `None` when it must /// not be forwarded. - fn outgoing(&self, route: &crate::origin::Route, absolute: &crate::Path) -> Option<(Hops, crate::origin::Cost)> { + fn outgoing( + &self, + route: &crate::origin::Route, + absolute: &crate::Path, + ) -> Option<(Hops, crate::origin::Cost, Option)> { let mut hops = route.hops.clone(); // A route that already passed through us is a reflection. The origin @@ -694,7 +703,7 @@ impl AnnounceRun { true => route.cost.clamped(), false => crate::origin::Cost::UNKNOWN, }; - Some((hops, cost)) + Some((hops, cost, route.epoch.clone())) } /// Start advertising `suffix`, recording its announce id. @@ -704,10 +713,20 @@ impl AnnounceRun { suffix: crate::PathOwned, hops: Hops, cost: crate::origin::Cost, + epoch: Option, ) -> Result<(), Error> { let (id, wire, chain) = self.encoder.start(suffix.clone(), hops.clone()); - self.live.insert(suffix, Advertised { id, hops, cost }); + self.live.insert( + suffix, + Advertised { + id, + hops, + cost, + epoch: epoch.clone(), + }, + ); stream.writer.buffer(&lite::AnnounceBroadcast::Active { + epoch: epoch.filter(|_| self.epochs), suffix: wire, hops: chain, cost, @@ -751,7 +770,7 @@ impl AnnounceRun { ) -> Result<(), Error> { match self.version { Version::Lite01 | Version::Lite02 => { - let mut init: Vec<(crate::PathOwned, Hops, crate::origin::Cost)> = Vec::new(); + let mut init: Vec<(crate::PathOwned, Hops, crate::origin::Cost, Option)> = Vec::new(); // Send ANNOUNCE_INIT as the first message with all currently active routes. // We use `try_next()` to synchronously get the initial updates. @@ -767,12 +786,12 @@ impl AnnounceRun { let suffix = update.prefix; if active { - let Some((hops, cost)) = self.outgoing(&update.route, &absolute) else { + let Some((hops, cost, epoch)) = self.outgoing(&update.route, &absolute) else { continue; }; tracing::debug!(route = %absolute, "announce"); init.retain(|(s, ..)| s != &suffix); - init.push((suffix, hops, cost)); + init.push((suffix, hops, cost, epoch)); } else { // A potential race: a just-announced route already retracted. tracing::debug!(route = %absolute, "unannounce"); @@ -783,8 +802,16 @@ impl AnnounceRun { let suffixes = init.iter().map(|(suffix, ..)| suffix.clone()).collect(); stream.writer.buffer(&lite::AnnounceInit { suffixes })?; // Record the initial set so a later end reaches the peer. - for (suffix, hops, cost) in init { - self.live.insert(suffix, Advertised { id: None, hops, cost }); + for (suffix, hops, cost, epoch) in init { + self.live.insert( + suffix, + Advertised { + id: None, + hops, + cost, + epoch, + }, + ); } } _ if self.version.has_announce_ok() => { @@ -792,7 +819,7 @@ impl AnnounceRun { // stashing suffix+hops so we can both COUNT them for AnnounceOk and re-send // them afterward. The receiver stamps our origin onto each hop chain, so we // forward the stored chain as-is (no self push here). - let mut initial: Vec<(crate::PathOwned, Hops, crate::origin::Cost)> = Vec::new(); + let mut initial: Vec<(crate::PathOwned, Hops, crate::origin::Cost, Option)> = Vec::new(); while let Some(event) = announced.try_next() { let (update, active) = match event { announce::Event::Start(update) | announce::Event::Update(update) => (update, true), @@ -805,12 +832,12 @@ impl AnnounceRun { let suffix = update.prefix; if active { - let Some((hops, cost)) = self.outgoing(&update.route, &absolute) else { + let Some((hops, cost, epoch)) = self.outgoing(&update.route, &absolute) else { continue; }; tracing::debug!(route = %absolute, "announce"); initial.retain(|(s, ..)| s != &suffix); - initial.push((suffix, hops, cost)); + initial.push((suffix, hops, cost, epoch)); } else { // A potential race: a just-announced route already retracted. tracing::debug!(route = %absolute, "unannounce"); @@ -825,8 +852,8 @@ impl AnnounceRun { active: initial.len() as u64, }; stream.writer.buffer(&ok)?; - for (suffix, hops, cost) in initial { - self.start(stream, suffix, hops, cost)?; + for (suffix, hops, cost, epoch) in initial { + self.start(stream, suffix, hops, cost, epoch)?; } } _ => { @@ -915,38 +942,44 @@ impl AnnounceRun { } match self.outgoing(&update.route, &absolute) { - Some((hops, cost)) => match self.live.get_mut(&suffix) { - // The peer would decode what it already holds. - Some(advertised) if advertised.hops == hops && advertised.cost == cost => {} - // A metadata update on a live advertisement: restart it in - // place (lite-05 restarts via a duplicate ANNOUNCE). - Some(advertised) if lite::restart_supported(self.version) => { - tracing::debug!(route = %absolute, "reannounce"); - advertised.hops = hops.clone(); - advertised.cost = cost; - match advertised.id { - Some(id) => { - let hops = self.encoder.update(id, hops); - stream - .writer - .buffer(&lite::AnnounceBroadcast::Restart { id, hops, cost })? + Some((hops, cost, epoch)) => { + if self.live.get(&suffix).is_some_and(|old| old.epoch != epoch) { + self.retract(stream, suffix.clone(), &absolute)?; + } + match self.live.get_mut(&suffix) { + // The peer would decode what it already holds. + Some(advertised) if advertised.hops == hops && advertised.cost == cost => {} + // A metadata update on a live advertisement: restart it in + // place (lite-05 restarts via a duplicate ANNOUNCE). + Some(advertised) if lite::restart_supported(self.version) => { + tracing::debug!(route = %absolute, "reannounce"); + advertised.hops = hops.clone(); + advertised.cost = cost; + match advertised.id { + Some(id) => { + let hops = self.encoder.update(id, hops); + stream + .writer + .buffer(&lite::AnnounceBroadcast::Restart { id, hops, cost })? + } + // lite-05: a duplicate ANNOUNCE, which assigns no id. + None => stream.writer.buffer(&lite::AnnounceBroadcast::Active { + epoch: epoch.filter(|_| self.epochs), + suffix: lite::PathRef::literal(suffix), + hops: lite::HopsRef::literal(hops), + cost, + })?, } - // lite-05: a duplicate ANNOUNCE, which assigns no id. - None => stream.writer.buffer(&lite::AnnounceBroadcast::Active { - suffix: lite::PathRef::literal(suffix), - hops: lite::HopsRef::literal(hops), - cost, - })?, + } + // Pre-restart versions have no way to update a live + // advertisement; the peer keeps the original chain. + Some(_) => {} + None => { + tracing::debug!(route = %absolute, "announce"); + self.start(stream, suffix, hops, cost, epoch)?; } } - // Pre-restart versions have no way to update a live - // advertisement; the peer keeps the original chain. - Some(_) => {} - None => { - tracing::debug!(route = %absolute, "announce"); - self.start(stream, suffix, hops, cost)?; - } - }, + } // The chain must not be forwarded (reflected, or full): retract // whatever the peer holds. None => self.retract(stream, suffix, &absolute)?, @@ -981,6 +1014,7 @@ trait Request: Sized { /// The broadcast and track the request names. fn target(msg: &Self::Message) -> (&crate::Path<'static>, &str); + fn epoch(msg: &Self::Message) -> Option<&crate::Epoch>; /// Start answering, once the broadcast resolves. fn start(shared: &Shared, msg: Self::Message, broadcast: crate::broadcast::Consumer) -> Result; @@ -1109,7 +1143,18 @@ impl> RequestServe { // served on demand by the route covering it (an `origin::Dynamic`), or // errors when there is none. let origin = ready!(self.shared.poll_serving_origin(waiter)); - *requesting = Some(origin.request_broadcast(R::target(msg).0).into_inner()); + let epoch = R::epoch(msg).cloned(); + if epoch.is_some() + && (!self.shared.version.has_setup_stream() + || !ready!(self.shared.peer_setup.poll_epoch(waiter))) + { + return Poll::Ready(Err(Error::ProtocolViolation)); + } + let id = crate::broadcast::Id { + path: R::target(msg).0.to_owned(), + epoch, + }; + *requesting = Some(origin.request_broadcast(id).into_inner()); } let broadcast = ready!(requesting.as_ref().expect("requesting").poll_ok(waiter))?; // Any placeholder but `Decode`, so a failed start is answered on the stream. @@ -1174,6 +1219,9 @@ impl Request for TrackInfoServe { type Message = lite::Track<'static>; type Update = NoUpdate; + fn epoch(msg: &Self::Message) -> Option<&crate::Epoch> { + msg.epoch.as_ref() + } fn target(msg: &Self::Message) -> (&crate::Path<'static>, &str) { (&msg.broadcast, &msg.track) } @@ -1212,7 +1260,7 @@ impl Request for TrackInfoServe { enum SubscribeServe { /// Waiting for the model subscription to be confirmed. Confirm { - msg: lite::Subscribe<'static>, + msg: Box>, subscribing: track::Subscribing, /// The newest group when the SUBSCRIBE arrived; see [`position_cursor`]. latest: Option, @@ -1232,6 +1280,9 @@ impl Request for SubscribeServe { type Message = lite::Subscribe<'static>; type Update = lite::SubscribeUpdate; + fn epoch(msg: &Self::Message) -> Option<&crate::Epoch> { + msg.epoch.as_ref() + } fn target(msg: &Self::Message) -> (&crate::Path<'static>, &str) { (&msg.broadcast, &msg.track) } @@ -1250,7 +1301,7 @@ impl Request for SubscribeServe { let latest = track.latest(); let subscribing = track.subscribe(subscription).into_inner(); Ok(Self::Confirm { - msg, + msg: Box::new(msg), subscribing, latest, update: None, @@ -1331,7 +1382,7 @@ impl Request for SubscribeServe { opens: Default::default(), }; - let bounds = Bounds::from(&msg); + let bounds = Bounds::from(msg.as_ref()); position_cursor(&mut track, shared.version, bounds.start_group, latest); let mut run = TrackRun::new(sub, track, bounds, track_priority_tx); if let Some(update) = update { @@ -1389,6 +1440,9 @@ impl Request for FetchServe { type Message = lite::Fetch<'static>; type Update = NoUpdate; + fn epoch(msg: &Self::Message) -> Option<&crate::Epoch> { + msg.epoch.as_ref() + } fn target(msg: &Self::Message) -> (&crate::Path<'static>, &str) { (&msg.broadcast, &msg.track) } @@ -1823,7 +1877,7 @@ mod announce_test { let mut wire = Wire { writes, cursor: 0 }; assert_eq!(wire.take_ok().active, 1, "expected one initial announce"); match wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::Active { suffix, hops, cost }] => { + [lite::AnnounceBroadcast::Active { suffix, hops, cost, .. }] => { assert_eq!(suffix.rest.as_str(), "cam"); assert_eq!(hops, &lite::HopsRef::literal(pub_hops())); assert_eq!(*cost, crate::origin::Cost::new(7)); @@ -4020,12 +4074,14 @@ mod tests { for wait in [Wait::Broadcast, Wait::Track] { for close in [Close::Fin, Close::Reset] { let track = lite::Track { + epoch: None, broadcast: broadcast.clone(), track: "video".into(), }; leave_request::(version, &track, wait, close).await; let subscribe = lite::Subscribe { + epoch: None, id: 0, broadcast: broadcast.clone(), track: "video".into(), @@ -4039,6 +4095,7 @@ mod tests { leave_request::>(version, &subscribe, wait, close).await; let fetch = lite::Fetch { + epoch: None, broadcast: broadcast.clone(), track: "video".into(), priority: 0, @@ -4077,6 +4134,7 @@ mod tests { let mut script = Vec::new(); lite::Subscribe { + epoch: None, id: 0, broadcast: crate::Path::new("room"), track: "video".into(), diff --git a/rs/moq-net/src/lite/session.rs b/rs/moq-net/src/lite/session.rs index 2b54fce287c..a5e14c0b031 100644 --- a/rs/moq-net/src/lite/session.rs +++ b/rs/moq-net/src/lite/session.rs @@ -190,6 +190,7 @@ where peer_setup, } = config; + our_setup.epoch = true; let recv_bw = bandwidth::Producer::new(); let recv_bw_consumer = match version { diff --git a/rs/moq-net/src/lite/setup.rs b/rs/moq-net/src/lite/setup.rs index 9aba62a5e53..57ff567362e 100644 --- a/rs/moq-net/src/lite/setup.rs +++ b/rs/moq-net/src/lite/setup.rs @@ -15,6 +15,7 @@ const PARAM_ROLE: u64 = 0x3; const PARAM_COST: u64 = 0x4; /// Setup Parameter id for the endpoint's Hop ID. const PARAM_HOP: u64 = 0x5; +const PARAM_EPOCH: u64 = 0x6; /// The cost of crossing a link that neither end priced. /// @@ -157,6 +158,8 @@ impl std::fmt::Display for Role { /// depends on a negotiated capability (e.g. PROBE) must wait for it. #[derive(Debug, Clone, Default, PartialEq, Eq)] pub struct Setup { + /// Whether this endpoint understands publisher epochs in announcements and requests. + pub epoch: bool, /// The probe capability this endpoint supports. [`ProbeLevel::None`] when absent. pub probe: ProbeLevel, /// The request path, for transports that carry no request URI (native QUIC, @@ -214,6 +217,11 @@ impl Message for Setup { .and_then(|id| crate::Hop::new(id).ok()); Ok(Self { + epoch: match params.get_varint(PARAM_EPOCH, version)? { + None => false, + Some(1) => true, + _ => return Err(DecodeError::InvalidValue), + }, probe, path, role, @@ -228,6 +236,9 @@ impl Message for Setup { } let mut params = Parameters::default(); + if self.epoch { + params.set_varint(PARAM_EPOCH, 1, version)?; + } // None is the wire default, so omit it to keep the message empty when nothing is set. if self.probe != ProbeLevel::None { params.set_varint(PARAM_PROBE, self.probe.to_code(), version)?; @@ -266,6 +277,11 @@ struct PeerSetupState { } impl PeerSetup { + /// Whether the peer accepts publisher identities, once its SETUP arrives. + pub(crate) fn poll_epoch(&self, waiter: &kio::Waiter) -> std::task::Poll { + self.poll_get(waiter, |setup| setup.epoch) + } + /// Record the peer's SETUP. pub fn set(&self, setup: Setup) { let mut state = self.0.lock(); diff --git a/rs/moq-net/src/lite/subscribe.rs b/rs/moq-net/src/lite/subscribe.rs index 84ce0f3eee9..f46b728ce86 100644 --- a/rs/moq-net/src/lite/subscribe.rs +++ b/rs/moq-net/src/lite/subscribe.rs @@ -12,6 +12,8 @@ use super::{Message, Version}; /// Objects will use the provided ID instead of the full track name, to save bytes. #[derive(Clone, Debug)] pub struct Subscribe<'a> { + /// The requested publisher instance, only sent after epoch negotiation. + pub epoch: Option, pub id: u64, pub broadcast: Path<'a>, pub track: Cow<'a, str>, @@ -65,6 +67,7 @@ impl Message for Subscribe<'_> { let start_group = canonical_start_group(version, start_group, start_frame); Ok(Self { + epoch: super::epoch::decode(r, version)?, id, broadcast, track, @@ -102,6 +105,7 @@ impl Message for Subscribe<'_> { self.end_frame, )?; + super::epoch::encode(w, version, self.epoch.as_ref())?; Ok(()) } } @@ -706,6 +710,7 @@ mod test { fn subscribe_sample() -> Subscribe<'static> { Subscribe { + epoch: None, id: 1, broadcast: Path::new("room").to_owned(), track: Cow::Borrowed("video"), diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index d04e0d9a71f..0cd72264ad8 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -86,7 +86,7 @@ pub(super) struct Subscriber { cost: Option, /// Sources created by the announce half, drained by the driver into /// [`SourceServe`] machines. - sources: kio::Queue<(PathOwned, crate::broadcast::Dynamic)>, + sources: kio::Queue<(crate::broadcast::Id, crate::broadcast::Dynamic)>, going_away: crate::goaway::GoingAway, /// What this session may allocate up front for frames still arriving. frames: frame::Budget, @@ -189,7 +189,12 @@ impl Subscriber { run: &mut PrefixRun, ) -> Result<(), Error> { match announce { - lite::AnnounceBroadcast::Active { suffix, hops, cost } => { + lite::AnnounceBroadcast::Active { + suffix, + hops, + cost, + epoch, + } => { let (suffix, hops) = match self.version.has_announce_id() { // Every `active` assigns the next ordinal, even ones we drop locally. true => run.decoder.start(suffix, hops)?, @@ -205,6 +210,13 @@ impl Subscriber { // atomically replace the broadcast. Lite06+ restarts by announce id, and older // versions never defined restarts, so both fall through to start_announce, which // rejects the duplicate (Error::ProtocolViolation). + if run + .announced + .attached(&path) + .is_some_and(|entry| entry.route.epoch != epoch) + { + return Err(Error::ProtocolViolation); + } self.restart_announce( path, hops, @@ -215,7 +227,10 @@ impl Subscriber { )?; } else { self.start_announce( - path, + crate::broadcast::Id { + path, + epoch: epoch.clone(), + }, hops, cost, run.link_cost, @@ -259,7 +274,7 @@ impl Subscriber { /// and attached a route, or `Ok(false)` if it was declined locally. fn start_announce( &mut self, - path: PathOwned, + id: crate::broadcast::Id, mut hops: crate::Hops, // The route cost off the wire, i.e. as the peer advertised it. // [`Cost::UNKNOWN`] before lite-06, leaving the hop chain as the only @@ -274,6 +289,7 @@ impl Subscriber { responder_origin: Option, announced: &mut Announced, ) -> Result { + let crate::broadcast::Id { path, epoch } = id; // One current advertisement per prefix per stream. Test what the peer // advertised, not only what we accepted locally. if announced.contains(&path) { @@ -328,7 +344,8 @@ impl Subscriber { // resolve through this session on demand. An error means the prefix is // outside our scope, so don't serve it. Reflections are already // filtered above. - let route = self.announced_route(hops, cost, link_cost, responder_origin); + let mut route = self.announced_route(hops, cost, link_cost, responder_origin); + route.epoch = epoch; let Ok(dynamic) = self.origin.dynamic(&path, route.clone()) else { return Ok(false); }; @@ -420,7 +437,8 @@ impl Subscriber { } tracing::debug!(route = %self.log_path(&path), hops = hops.len(), "restart"); - let metadata = self.announced_route(hops, cost, link_cost, responder_origin); + let mut metadata = self.announced_route(hops, cost, link_cost, responder_origin); + metadata.epoch = announced.attached(&path).and_then(|entry| entry.route.epoch.clone()); // A restart is a metadata update: the route keeps its prefix (and its // served paths) and re-prices in place. In-flight tracks keep flowing. @@ -1366,7 +1384,7 @@ impl AnnouncePrefix { // an empty chain and an unpriced link. Stats are attributed in the // model when this enters the origin via `create_broadcast`. self.subscriber.start_announce( - path, + crate::broadcast::Id { path, epoch: None }, crate::Hops::new(), crate::origin::Cost::UNKNOWN, 0, @@ -1382,6 +1400,8 @@ impl AnnouncePrefix { self.state = PrefixState::Run { stream, run }; } PrefixState::Run { stream, run } => { + let epochs = self.subscriber.version.has_setup_stream() + && ready!(self.subscriber.peer_setup.poll_epoch(waiter)); // A draining peer usually stops announcing, so react to the // GOAWAY itself; waiting for another message would leave the // route primary until the session finally closed. Idempotent, @@ -1397,6 +1417,11 @@ impl AnnouncePrefix { Poll::Ready(Ok(Some(announce))) => { // The count is of ANNOUNCE_STARTs, not every message. let start = matches!(announce, lite::AnnounceBroadcast::Active { .. }); + if matches!(&announce, lite::AnnounceBroadcast::Active { epoch: Some(_), .. }) + && !epochs + { + return Poll::Ready(Err(Error::ProtocolViolation)); + } self.subscriber.handle_announce(&self.prefix, announce, run)?; match &mut run.landing { Landing::Count(remaining) if start => *remaining = remaining.saturating_sub(1), @@ -1434,6 +1459,7 @@ impl AnnouncePrefix { /// retraction does not disturb subscriptions already in flight); the session /// dying drops them. struct SourceServe { + epoch: Option, subscriber: Subscriber, path: PathOwned, dynamic: crate::broadcast::Dynamic, @@ -1445,11 +1471,12 @@ struct SourceServe { } impl SourceServe { - fn new(subscriber: Subscriber, path: PathOwned, dynamic: crate::broadcast::Dynamic) -> Self { + fn new(subscriber: Subscriber, id: crate::broadcast::Id, dynamic: crate::broadcast::Dynamic) -> Self { let closed = subscriber.session.clone(); Self { subscriber, - path, + path: id.path, + epoch: id.epoch, dynamic, closed, tracks: kio::Tasks::new(), @@ -1477,6 +1504,7 @@ impl kio::Task for SourceServe { match self.dynamic.poll_requested_track(waiter) { Poll::Ready(Ok(request)) => { let serve = TrackServe { + epoch: self.epoch.clone(), subscriber: self.subscriber.clone(), path: self.path.clone(), name: request.name().to_string(), @@ -1727,6 +1755,7 @@ mod tests { going_away: Default::default(), }); let serve = TrackServe { + epoch: None, subscriber, path: Path::new("room").to_owned(), name: "video".to_string(), @@ -1779,6 +1808,7 @@ mod tests { going_away: Default::default(), }); let serve = TrackServe { + epoch: None, subscriber, path: Path::new("room").to_owned(), name: "video".to_string(), @@ -1947,6 +1977,7 @@ mod tests { let run = TrackServeRun::new( TrackServe { + epoch: None, subscriber: subscriber.clone(), path: Path::new("room").to_owned(), name: "video".to_string(), @@ -2003,6 +2034,7 @@ mod tests { let mut run = TrackServeRun::new( TrackServe { + epoch: None, subscriber, path: Path::new("room").to_owned(), name: "video".to_string(), @@ -2051,6 +2083,7 @@ mod tests { }); let subscribes = subscriber.subscribes.clone(); let serve = TrackServe { + epoch: None, subscriber, path: Path::new("room/host").to_owned(), name: "catalog.json".to_string(), @@ -2127,6 +2160,7 @@ mod tests { Self { serve: TrackServe { + epoch: None, subscriber, path: Path::new("room/host").to_owned(), name: "catalog.json".to_string(), @@ -2556,7 +2590,10 @@ mod tests { assert!( subscriber .start_announce( - path.clone(), + crate::broadcast::Id { + path: path.clone(), + epoch: None + }, crate::Hops::new(), crate::origin::Cost::default(), 0, @@ -2572,7 +2609,10 @@ mod tests { assert!( matches!( subscriber.start_announce( - path.clone(), + crate::broadcast::Id { + path: path.clone(), + epoch: None + }, reflected, crate::origin::Cost::default(), 0, @@ -2608,7 +2648,10 @@ mod tests { assert!( subscriber .start_announce( - Path::new(&format!("room/{i}")).to_owned(), + crate::broadcast::Id { + path: Path::new(&format!("room/{i}")).to_owned(), + epoch: None + }, crate::Hops::new(), crate::origin::Cost::default(), 0, @@ -2667,7 +2710,10 @@ mod tests { assert!( !subscriber .start_announce( - path.clone(), + crate::broadcast::Id { + path: path.clone(), + epoch: None + }, hops, crate::origin::Cost::default(), 0, @@ -2684,7 +2730,10 @@ mod tests { assert!( matches!( subscriber.start_announce( - path.clone(), + crate::broadcast::Id { + path: path.clone(), + epoch: None + }, fresh, crate::origin::Cost::default(), 0, @@ -2722,7 +2771,10 @@ mod tests { assert!( !subscriber .start_announce( - path.clone(), + crate::broadcast::Id { + path: path.clone(), + epoch: None + }, reflected, crate::origin::Cost::default(), 0, @@ -2738,7 +2790,10 @@ mod tests { hops.push(crate::Hop::new(7).unwrap()).unwrap(); let err = subscriber .start_announce( - path.clone(), + crate::broadcast::Id { + path: path.clone(), + epoch: None, + }, hops, crate::origin::Cost::default(), 0, @@ -2778,7 +2833,10 @@ mod tests { let mut announced = Announced::default(); let accepted = subscriber .start_announce( - Path::new("room/host").to_owned(), + crate::broadcast::Id { + path: Path::new("room/host").to_owned(), + epoch: None, + }, hops, crate::origin::Cost::default(), 0, @@ -2842,7 +2900,10 @@ mod tests { let mut announced = Announced::default(); let accepted = subscriber .start_announce( - Path::new("room/host").to_owned(), + crate::broadcast::Id { + path: Path::new("room/host").to_owned(), + epoch: None, + }, hops, crate::origin::Cost::default(), 0, @@ -2900,7 +2961,10 @@ mod tests { let mut announced = Announced::default(); let accepted = subscriber .start_announce( - Path::new("room/host").to_owned(), + crate::broadcast::Id { + path: Path::new("room/host").to_owned(), + epoch: None, + }, crate::Hops::new(), crate::origin::Cost::UNKNOWN, 0, @@ -2947,7 +3011,10 @@ mod tests { assert!( subscriber .start_announce( - Path::new("room/host").to_owned(), + crate::broadcast::Id { + path: Path::new("room/host").to_owned(), + epoch: None + }, hops, crate::origin::Cost::UNKNOWN, 0, @@ -2977,7 +3044,10 @@ mod tests { let mut announced = Announced::default(); first .start_announce( - Path::new("room/host").to_owned(), + crate::broadcast::Id { + path: Path::new("room/host").to_owned(), + epoch: None, + }, crate::Hops::new(), crate::origin::Cost::UNKNOWN, 0, @@ -3034,7 +3104,10 @@ mod tests { let path = Path::new("room/host").to_owned(); subscriber .start_announce( - path.clone(), + crate::broadcast::Id { + path: path.clone(), + epoch: None, + }, crate::Hops::new(), crate::origin::Cost::UNKNOWN, 0, @@ -3089,7 +3162,10 @@ mod tests { let mut announced = Announced::default(); subscriber .start_announce( - path.clone(), + crate::broadcast::Id { + path: path.clone(), + epoch: None, + }, hops, crate::origin::Cost::default(), 1, @@ -3110,7 +3186,10 @@ mod tests { let mut announced = Announced::default(); subscriber .start_announce( - path.clone(), + crate::broadcast::Id { + path: path.clone(), + epoch: None, + }, hops, crate::origin::Cost::default(), 1, @@ -3132,6 +3211,7 @@ mod tests { async fn the_count_lands_at_the_last_initial_start() { const VERSION: Version = Version::Lite06; let start = |suffix| lite::AnnounceBroadcast::Active { + epoch: None, suffix: lite::PathRef::literal(Path::new(suffix)), hops: lite::HopsRef::literal(crate::Hops::new()), cost: crate::origin::Cost::default(), @@ -3160,7 +3240,11 @@ mod tests { origin, recv_bandwidth: None, version: VERSION, - peer_setup: Default::default(), + peer_setup: { + let setup = lite::PeerSetup::default(); + setup.set(lite::Setup::default()); + setup + }, cost: Some(1), peer_hop: None, going_away: Default::default(), @@ -3349,8 +3433,12 @@ impl Announced { continue; }; let path = path.to_owned(); - let source = subscriber.origin.create_source(&path); - let _ = subscriber.sources.try_push((path.clone(), source.dynamic())); + let id = crate::broadcast::Id { + path: path.clone(), + epoch: entry.route.epoch.clone(), + }; + let source = subscriber.origin.create_source(id.clone()); + let _ = subscriber.sources.try_push((id, source.dynamic())); request.accept(&source); entry .sources @@ -3458,6 +3546,7 @@ enum ServeEnd { /// the last one leaves) concurrently with any number of one-shot fetches. #[derive(Clone)] struct TrackServe { + epoch: Option, subscriber: Subscriber, path: PathOwned, name: String, @@ -3770,6 +3859,7 @@ impl Establish { let bounds = WireBounds::new(self.subscription.start, self.subscription.end); let msg = lite::Subscribe { + epoch: self.serve.epoch.clone(), id: self.id, broadcast: self.serve.path.as_path(), track: self.serve.name.as_str().into(), @@ -4009,6 +4099,7 @@ impl TrackInfoFetch { let mut stream = ready!(Stream::poll_open(&mut self.session, serve.subscriber.version, &mut cx))?; stream.writer.buffer(&lite::ControlType::Track)?; stream.writer.buffer(&lite::Track { + epoch: serve.epoch.clone(), broadcast: serve.path.as_path(), track: serve.name.as_str().into(), })?; @@ -4503,6 +4594,7 @@ impl kio::Task for FetchServeRun { }; let msg = lite::Fetch { + epoch: self.serve.epoch.clone(), broadcast: self.serve.path.as_path(), track: self.serve.name.as_str().into(), priority: request.priority(), diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index 0c96058ac93..7f6588f38a4 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -16,6 +16,8 @@ const LEGACY_UNLIMITED: u64 = (1u64 << 53) - 1; /// Lite05+ only. #[derive(Clone, Debug)] pub struct Track<'a> { + /// The requested publisher instance, only sent after epoch negotiation. + pub epoch: Option, pub broadcast: Path<'a>, pub track: Cow<'a, str>, } @@ -29,7 +31,11 @@ impl Message for Track<'_> { let broadcast = Path::decode(r, version)?; let track = Cow::Owned(r.string()?); - Ok(Self { broadcast, track }) + Ok(Self { + broadcast, + track, + epoch: super::epoch::decode(r, version)?, + }) } fn encode_msg(&self, w: &mut Encoder<'_>, version: Version) -> Result<(), EncodeError> { @@ -39,6 +45,7 @@ impl Message for Track<'_> { self.broadcast.encode(w, version)?; w.string(&self.track)?; + super::epoch::encode(w, version, self.epoch.as_ref())?; Ok(()) } } @@ -269,6 +276,7 @@ mod test { #[test] fn track_request_roundtrips_on_lite05() { let msg = Track { + epoch: None, broadcast: Path::new("room").to_owned(), track: Cow::Borrowed("video"), }; @@ -284,6 +292,7 @@ mod test { #[test] fn track_request_errors_before_lite05() { let msg = Track { + epoch: None, broadcast: Path::new("room").to_owned(), track: Cow::Borrowed("video"), }; diff --git a/rs/moq-net/src/model/broadcast.rs b/rs/moq-net/src/model/broadcast.rs index dc27f76cc07..53802a1750c 100644 --- a/rs/moq-net/src/model/broadcast.rs +++ b/rs/moq-net/src/model/broadcast.rs @@ -18,6 +18,32 @@ use crate::origin::Route; use super::origin_impl::Announcer; use super::{Requests, WeakCache}; +/// A broadcast path and the publisher instance to request, if known. +#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)] +pub struct Id { + /// The broadcast's path, relative to the origin handle. + pub path: crate::PathOwned, + /// The immutable publisher instance; absent requests stay on one serving route. + pub epoch: Option, +} + +impl From for Id { + fn from(path: T) -> Self { + Self { + path: path.as_path().to_owned(), + epoch: None, + } + } +} + +impl Id { + /// Select one publisher instance without changing the path. + pub fn with_epoch(mut self, epoch: crate::Epoch) -> Self { + self.epoch = Some(epoch); + self + } +} + /// A collection of media tracks that can be published and subscribed to. /// /// Create via [`Info::produce`] to obtain both [`Producer`] and [`Consumer`] pair. @@ -45,6 +71,8 @@ pub struct Info { /// Empty (the default) for a standalone broadcast with no origin, which is then its own /// root: any `..` reference escapes. pub path: crate::PathOwned, + /// The publisher instance selected for this broadcast, if known. + pub epoch: Option, } impl Default for Info { @@ -53,6 +81,7 @@ impl Default for Info { pool: cache::Pool::new(cache::Config::default().with_expiry(cache::DEFAULT_EXPIRY)), cache_duration: std::time::Duration::MAX, path: crate::PathOwned::default(), + epoch: None, } } } @@ -210,7 +239,11 @@ impl Producer { /// Fails with [`Error::Closed`] on a standalone broadcast (one not created /// through an origin, so there is nothing to announce into), once the broadcast /// has closed, or once the origin's driver has been dropped. - pub fn announce(&self, route: Route) -> Result<(), Error> { + pub fn announce(&self, mut route: Route) -> Result<(), Error> { + if route.epoch.is_some() && route.epoch != self.info.epoch { + return Err(Error::ProtocolViolation); + } + route.epoch = self.info.epoch.clone(); let mut announcer = self.alive.announcer.lock(); let announcer = announcer.as_mut().ok_or(Error::Closed)?; announcer.announce(route) diff --git a/rs/moq-net/src/model/front.rs b/rs/moq-net/src/model/front.rs index 124491ff5f2..3b151a2fc99 100644 --- a/rs/moq-net/src/model/front.rs +++ b/rs/moq-net/src/model/front.rs @@ -9,11 +9,9 @@ //! sources, the tracks, the clock) and executes the actions; see //! `origin::run_front`. //! -//! A path naming an epoch names one origin's broadcast, whoever relays it, so any -//! route serving it may take over from another and its tracks resume where they -//! stopped. A path without an epoch carries no such promise: the driver keeps it -//! on the route that first served it (see `origin::run_front`), and the machine -//! never sees another. +//! The origin admits replacement routes only for the front's known epoch. +//! Every admitted source must preserve immutable track metadata and frame positions. +//! A front without an epoch remains pinned to its first serving route. //! //! Sources and tracks are named by ids and names, never handles, so a //! transition can be checked in a unit test by comparing the actions it emits. @@ -219,19 +217,18 @@ impl Front { self.excluded.retain(|route| standing(*route)); } - /// The attached source, if any. - pub(super) fn serving(&self) -> Option { - self.serving.map(|(source, _)| source) + /// Whether a source has ever served this front. + pub(super) fn has_served(&self) -> bool { + self.resolved } - - /// The route the attached source came through, if any. + /// The attached route, if any. pub(super) fn serving_route(&self) -> Option { - self.serving.map(|(_, candidate)| candidate) + self.serving.map(|(_, route)| route) } - /// Whether a source ever attached: the front has served bytes. - pub(super) fn has_served(&self) -> bool { - self.resolved + /// The attached source, if any. + pub(super) fn serving(&self) -> Option { + self.serving.map(|(source, _)| source) } /// Whether the front is over. @@ -481,7 +478,7 @@ impl Front { let spliced = track.state == (TrackState::Spliced { source }); if track.draining == Some(source) { track.draining = None; - // A path is one broadcast, so a copy that completed ends the track whoever + // An identity is one broadcast, so a copy that completed ends the track whoever // serves it now. One that failed leaves the track to the serving source. if result.is_ok() && !track.ended { track.state = TrackState::Idle; @@ -1261,7 +1258,7 @@ mod tests { } /// A newer publisher at the path takes over, local or not, and closing or not: the - /// path is the same broadcast. + /// identity is the same broadcast. #[test] fn a_newcomer_takes_over_the_incumbent() { for closing in [false, true] { @@ -1567,7 +1564,7 @@ mod tests { } /// The serving source closed and the front reselected, but the pump still reads the - /// closed source's copy. That copy ending cleanly ends the track: a path is one + /// closed source's copy. That copy ending cleanly ends the track: an identity is one /// broadcast, whoever serves it. #[test] fn a_closed_sources_clean_end_finishes_the_track() { diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 5ff4f8379a7..044a8c81686 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -472,6 +472,8 @@ impl From for Cost { #[derive(Clone, Debug, PartialEq, Eq)] #[non_exhaustive] pub struct Route { + /// The immutable publisher instance covered by this route, if known. + pub epoch: Option, /// The chain of origins the route has traversed, oldest first. Each relay /// appends its own [`crate::Hop`] when forwarding; used for loop detection /// and as the selection tie-break. A 0 entry is the anonymous mark and @@ -499,6 +501,7 @@ pub struct Route { impl Default for Route { fn default() -> Self { Self { + epoch: None, hops: Hops::new(), cost: Cost::default(), via: Hop::UNKNOWN, @@ -523,6 +526,12 @@ pub enum Source { } impl Route { + /// Declare the publisher instance served by this route. + pub fn with_epoch(mut self, epoch: crate::Epoch) -> Self { + self.epoch = Some(epoch); + self + } + /// Replace the hop chain. pub fn with_hops(mut self, hops: Hops) -> Self { self.hops = hops; @@ -626,8 +635,8 @@ fn route_order(path: &Path, entry: &RouteEntry) -> (bool, Cost, bool, usize, u64 ) } -/// The `(hops, cost, source)` metadata an announce cursor delivers alongside a prefix. -type RouteMeta = (Hops, Cost, Source); +/// The `(hops, cost, source, epoch)` metadata an announce cursor delivers alongside a prefix. +type RouteMeta = (Hops, Cost, Source, Option); /// A pending update's hold, keyed by prefix in its [`AnnounceConsumer`]. /// @@ -828,6 +837,7 @@ impl OriginConsumerState { cost: meta.1, via: Hop::UNKNOWN, source: meta.2, + epoch: meta.3, }, })) } @@ -835,6 +845,7 @@ impl OriginConsumerState { /// One announced route in the origin's table, absolute prefix. struct RouteEntry { + epoch: Option, id: u64, prefix: PathOwned, /// The absolute patterns the announcing producer may serve. The prefix is @@ -956,7 +967,7 @@ struct ServeState { /// [`Horizon`]. Requesters excluding different peers get separate fronts, so a /// front's failover never adopts a route flowing back through one of its own /// readers, nor a local view a peer's route. -type FrontKey = (PathOwned, Horizon); +type FrontKey = (PathOwned, Option, Horizon); /// Which routes a reader sees: the split-horizon exclusion and the local-only view. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] @@ -1005,9 +1016,6 @@ struct RemoteFront { /// The front's broadcast, weak: dead once the front ends, so a /// later request re-creates the front instead of joining a corpse. broadcast: broadcast::WeakConsumer, - /// The absolute path it is served from: its own, or the epoch a bare name - /// resolved to when the front was made. - target: PathOwned, } /// The last route a cursor observed: entry id, metadata, servability, and captures. @@ -1108,7 +1116,7 @@ impl TableCursor { fn update(&mut self, presented: &PathOwned, best: Option<&RouteEntry>) { match best { Some(entry) => { - let meta = (entry.hops.clone(), entry.cost, entry.entered()); + let meta = (entry.hops.clone(), entry.cost, entry.entered(), entry.epoch.clone()); let served = entry.server.is_some(); let captures = self.captures(&entry.prefix); let previous = self @@ -1293,28 +1301,6 @@ impl Default for OriginScope { } } -/// `patterns` with each name they admit also admitting its epochs: a member not -/// ending in `**` gains a `/@*` sibling. A grant on one epoch names that epoch, so -/// it never widens to the bare name or its siblings. -fn with_epochs(patterns: Patterns) -> Patterns { - let epoch = Segment::Partial { - prefix: "@".to_string(), - suffix: String::new(), - }; - let mut widened = patterns.clone(); - for member in patterns.iter() { - // `**` already reaches every epoch, and a member that is one is already widened. - if matches!(member.segments().last(), Some(last) if *last == Segment::Globstar || *last == epoch) { - continue; - } - // A member at the depth limit names nothing with room for an epoch. - if let Ok(member) = Pattern::new(member.segments().iter().cloned().chain([epoch.clone()])) { - widened.insert(member); - } - } - widened -} - /// The announce-interest prefixes that cover a pattern scope on a prefix-only /// wire: each member's literal head, minus heads another already covers. pub(crate) fn interest_prefixes(allowed: &Patterns) -> Vec { @@ -1582,25 +1568,23 @@ impl Producer { /// polled. Register a [`broadcast::Producer::dynamic`] handler before /// announcing, so the first consumer finds the tracks it serves. /// + /// A missing epoch mints a fresh publisher identity. Supply an explicit epoch + /// only when replicating the same immutable content. + /// /// End the broadcast with [`broadcast::Producer::close`] or by dropping it; /// either way the path closes once it was the last source. /// - /// The path is published as given. A publisher that may restart publishes - /// each run under a fresh epoch ([`Path::mint_epoch`]), so a restart is a new - /// broadcast that bare-name consumers follow (see - /// [`Consumer::request_broadcast`]) rather than a reused name resumed into - /// the old run. - /// /// Fails with [`Error::Unauthorized`] if `path` is outside the prefixes this /// producer may publish under (after [`scope`](Self::scope)) or beneath a /// [`mount`](Self::mount), - /// [`Error::BoundsExceeded`] if the full rooted path (an epoch segment - /// included) exceeds [`Path::MAX_PARTS`], [`Error::InvalidPath`] if it holds a segment no - /// pattern can spell (`*` or `**`), [`Error::MisplacedEpoch`] if an epoch - /// segment comes before its last, or [`Error::Closed`] once the origin's + /// [`Error::BoundsExceeded`] if the full rooted path exceeds + /// [`Path::MAX_PARTS`], [`Error::InvalidPath`] if it holds a segment no + /// pattern can spell (`*` or `**`), or [`Error::Closed`] once the origin's /// [`Driver`] has been dropped. - pub fn create_broadcast(&self, path: impl AsPath) -> Result { - let path = path.as_path(); + pub fn create_broadcast(&self, id: impl Into) -> Result { + let mut id = id.into(); + id.epoch.get_or_insert_with(crate::Epoch::mint); + let path = id.path.as_path(); let full = self.root.join(&path).to_owned(); if !self.scope.permits(&full) || !self.scope.publishes(&full) { @@ -1612,9 +1596,6 @@ impl Producer { if full.parts().count() > Path::MAX_PARTS { return Err(BoundsExceeded.into()); } - if full.has_misplaced_epoch() { - return Err(Error::MisplacedEpoch); - } // A path only a pattern could spell (a `*` segment) advertises nowhere, so // refuse it here rather than publish a broadcast no cursor can see. let claim = prefix_claim(&full)?; @@ -1640,10 +1621,14 @@ impl Producer { pool: self.pool.clone(), cache_duration: self.cache_duration, path: full, + epoch: id.epoch.clone(), }; let source = info.produce().with_stats(ingress.clone()); let entry = announcing.announce( - Route::default(), + Route { + epoch: id.epoch, + ..Route::default() + }, Serving { server: None, source: Some(source.consume()), @@ -1658,7 +1643,7 @@ impl Producer { } /// Create and advertise a broadcast in one call. - pub fn publish(&self, path: impl AsPath, route: Route) -> Result { + pub fn publish(&self, path: impl Into, route: Route) -> Result { let broadcast = self.create_broadcast(path)?; broadcast.announce(route)?; Ok(broadcast) @@ -1669,14 +1654,16 @@ impl Producer { /// is *not* entered into the route table. Sessions answer /// [`Dynamic`] requests with one of these; the requester already holds /// the request's result channel, so the table never needs to resolve it. - pub(crate) fn create_source(&self, path: impl AsPath) -> broadcast::Producer { - let path = path.as_path(); + pub(crate) fn create_source(&self, id: impl Into) -> broadcast::Producer { + let id = id.into(); + let path = id.path.as_path(); let full = self.root.join(&path).to_owned(); let ingress = self.stats.ingress(&full); broadcast::Info { pool: self.pool.clone(), cache_duration: self.cache_duration, path: full, + epoch: id.epoch, } .produce() .with_stats(ingress) @@ -1774,13 +1761,12 @@ impl Producer { /// Returns a producer rooted at `root` and restricted to matching `patterns`. /// /// `root` is relative to this producer's root, and `patterns` are relative to - /// the new root. A pattern that admits a name also admits its epochs - /// (`name/@`). Returns [`Error::Unauthorized`] when the requested scope has + /// the new root. Returns [`Error::Unauthorized`] when the requested scope has /// no overlap with this producer's scope, or [`Error::BoundsExceeded`] when /// rooting the patterns would exceed the path limit. pub fn scope(&self, root: impl AsPath, patterns: &Patterns) -> Result { let root = self.root.join(root).to_owned(); - let rooted = with_epochs(patterns.rooted(root.as_str()).map_err(|_| BoundsExceeded)?); + let rooted = patterns.rooted(root.as_str()).map_err(|_| BoundsExceeded)?; let scope = self.scope.narrow(&rooted).ok_or(Error::Unauthorized)?; Ok(Producer { hop: self.hop, @@ -1914,9 +1900,6 @@ impl Announcing { if requested.parts().count() > Path::MAX_PARTS { return Err(BoundsExceeded.into()); } - if requested.has_misplaced_epoch() { - return Err(Error::MisplacedEpoch); - } let claim = prefix_claim(&requested)?; if !producer.scope.allowed.overlaps(&claim) || !producer.scope.publishes(&requested) { return Err(Error::Unauthorized); @@ -1957,6 +1940,7 @@ impl Announcing { prefix: prefix.clone(), scope: self.scope.clone(), hops: route.hops.clone(), + epoch: route.epoch.clone(), cost: route.cost, via, local: self.local, @@ -2061,6 +2045,9 @@ impl AnnounceProducer { let Some(entry) = shared.routes.entry_mut(prefix, *id) else { return Err(Error::Closed); }; + if route.epoch != entry.epoch { + return Err(Error::ProtocolViolation); + } entry.hops = route.hops.clone(); entry.stale = stale; entry.cost = route.cost; @@ -2275,12 +2262,12 @@ impl Drop for DriverState { /// Everything [`run_front`] owns, queued by [`Consumer::request_broadcast`]. struct FrontTask { + epoch: Option, /// The route table the front selects from. shared: kio::Shared, /// The broadcast the front serves. broadcast: broadcast::Producer, - /// Absolute path the front selects routes for and requests through: its own, - /// or the epoch a bare name was bound to. + /// Absolute path of the front. path: PathOwned, /// The requesters' horizon, applied to every (re)selection. horizon: Horizon, @@ -2399,6 +2386,7 @@ async fn run_front(task: FrontTask, origin: TasksWeak) { /// twice. async fn serve_front(task: FrontTask) -> Vec { let FrontTask { + epoch, shared, broadcast, path, @@ -2422,6 +2410,7 @@ async fn serve_front(task: FrontTask) -> Vec { // The front serves its broadcast on demand: every track a reader names is // handed here, and its readers read it from whichever source serves the path. + let pinned = epoch.is_none(); let mut dynamic = broadcast.dynamic(); let mut front = Front::new(track::IDLE_LINGER); let mut sources: HashMap = HashMap::new(); @@ -2433,10 +2422,6 @@ async fn serve_front(task: FrontTask) -> Vec { // The watch generation the last selection saw. let mut seen = 0; let mut events: VecDeque = VecDeque::new(); - // Only an epoch names one origin, so only its routes are interchangeable. A - // path without one stays on the route that first served it: it never resumes - // through another, whose bytes may differ, and ends once that route is gone. - let pinned = path.split_epoch().1.is_none(); // Read the table for the machine: the best route and whether // the serving source is on its way out. Also what the watch wakes for. @@ -2448,6 +2433,13 @@ async fn serve_front(task: FrontTask) -> Vec { // Read alongside the decision, under the lock a poke takes first. *seen = watch.seen(); front.retain_routes(|route| table.routes.covers(&path.as_path(), route)); + + let best = table + .best_route(&path.as_path(), horizon, front.excluded_routes(), epoch.as_ref()) + .map(|entry| Candidate { + route: entry.id, + local: entry.local, + }); let serving_closing = front .serving() .and_then(|id| sources.get(&id)) @@ -2458,12 +2450,6 @@ async fn serve_front(task: FrontTask) -> Vec { .filter(|serving| table.routes.covers(&path.as_path(), serving.route)); return Event::Selected { best, serving_closing }; } - let best = table - .best_route(&path.as_path(), horizon, front.excluded_routes()) - .map(|entry| Candidate { - route: entry.id, - local: entry.local, - }); Event::Selected { best, serving_closing } }; @@ -2473,7 +2459,7 @@ async fn serve_front(task: FrontTask) -> Vec { let standing = |front: &Front, route: u64| { shared .read() - .best_route(&path.as_path(), horizon, front.excluded_routes()) + .best_route(&path.as_path(), horizon, front.excluded_routes(), epoch.as_ref()) .is_some_and(|best| best.id == route) }; @@ -3197,13 +3183,6 @@ impl RouteTable { } } - /// Wake the watches at exactly `path`. - fn poke_at(&self, path: &Path) { - if let (_, Some(node)) = self.split(path) { - node.poke(); - } - } - /// Wake every watch: the origin is tearing down. fn poke_all(&self) { self.root.walk(&mut |node| node.poke()); @@ -3397,10 +3376,6 @@ impl OriginState { } // The fronts and requesters under the prefix re-select from the table. routes.poke_below(prefix); - // So do those following the bare name an epoch route sits under. - if let (name, Some(_)) = prefix.split_epoch() { - routes.poke_at(&name); - } } /// Register a [`Watch`] on the routes covering `path`. @@ -3498,7 +3473,13 @@ impl OriginState { /// equal-cost advertisers of one prefix share its paths. A broadcast /// published on this origin competes on cost like any other route and wins a /// tie. - fn best_route(&self, path: &Path, horizon: Horizon, excluded: &HashSet) -> Option<&RouteEntry> { + fn best_route( + &self, + path: &Path, + horizon: Horizon, + excluded: &HashSet, + epoch: Option<&crate::Epoch>, + ) -> Option<&RouteEntry> { // Covering prefixes of one path form a chain, so the deepest node with a // candidate holds the unique longest prefix; walking down, the last such // node decides. @@ -3509,6 +3490,7 @@ impl OriginState { .entries .iter() .filter(|entry| entry.live()) + .filter(|entry| epoch.is_none_or(|epoch| entry.epoch.as_ref() == Some(epoch))) .filter(|entry| entry.scope.matches(path.as_str())) .filter(|entry| horizon.admits(entry)) .filter(|entry| !excluded.contains(&entry.id)) @@ -3521,36 +3503,6 @@ impl OriginState { } best } - - /// The path a request for the absolute `path` is served from, for a requester - /// seeing `horizon`: the newest epoch below a bare `path` that a route serves, - /// otherwise `path` itself when a route covers it. `None` when nothing serves it. - fn resolve(&self, path: &Path, horizon: Horizon) -> Option { - let none: HashSet = HashSet::new(); - // A fully qualified epoch wins over a route covering the bare name. A path - // naming an epoch pins it: there is nothing newer to bind to. - if path.split_epoch().1.is_none() - && let (_, Some(node)) = self.routes.split(path) - { - // Canonical UUIDv7 text orders by mint time, so the greatest is the newest. - // Sorted as text and parsed lazily: the newest is usually the one served. - let mut segments: Vec<&str> = node - .children - .keys() - .filter_map(|segment| segment.strip_prefix('@')) - .collect(); - segments.sort_unstable_by(|a, b| b.cmp(a)); - let newest = segments - .into_iter() - .filter_map(|text| text.parse::().ok()) - .map(|epoch| path.with_epoch(&epoch)) - .find(|epoch| self.best_route(epoch, horizon, &none).is_some()); - if newest.is_some() { - return newest; - } - } - self.best_route(path, horizon, &none).map(|_| path.to_owned()) - } } /// A remote announce source still replaying its initial set, from @@ -4261,9 +4213,8 @@ impl Consumer { /// Block until an announced route covers `path`, and return it. /// /// Covering means the route's prefix is a (segment-wise) prefix of `path`, - /// including the exact path itself. A bare `path` is also routed by an epoch - /// one segment below it (`path/@`). Returns `None` if the path is - /// outside this consumer's scope or the consumer is closed first. + /// including the exact path itself. Returns `None` if the path is outside this + /// consumer's scope or the consumer is closed first. /// /// To resolve a broadcast rather than inspect the route, use /// [`Self::routed_broadcast`]: pairing this with [`Self::request_broadcast`] @@ -4292,12 +4243,9 @@ impl Consumer { // forwarding, so it must not drive the announce guards. Hiding narrows // discovery, not lookup, so a hidden path resolves like any other. let mut announced = consumer.untagged().with_hidden(true).announced(); - // A bare name is also routed by an epoch one segment below it. - let bare = path.split_epoch().1.is_none(); loop { if let AnnounceEvent::Start(announce) | AnnounceEvent::Update(announce) = announced.next().await? - && (path.has_prefix(&announce.prefix) - || bare && matches!(announce.prefix.split_epoch(), (name, Some(_)) if name == path)) + && path.has_prefix(&announce.prefix) { return Some(announce.route); } @@ -4305,9 +4253,7 @@ impl Consumer { } /// Block until `path` resolves to a broadcast: [`Self::request_broadcast`], - /// retried whenever the routes covering the path, or the epochs below a bare - /// name, change. To switch to a newer epoch as soon as it appears, watch - /// [`Self::announced`] and request it by its full path. + /// retried whenever the routes covering the path change. /// /// A request answers for the routes as they stand, so it can miss an /// announcement that has not arrived yet, lose its covering route to @@ -4363,13 +4309,12 @@ impl Consumer { /// Returns a consumer rooted at `root` and restricted to matching `patterns`. /// /// `root` is relative to this consumer's root, and `patterns` are relative to - /// the new root. A pattern that admits a name also admits its epochs - /// (`name/@`). Returns [`Error::Unauthorized`] when the requested scope has + /// the new root. Returns [`Error::Unauthorized`] when the requested scope has /// no overlap with this consumer's scope, or [`Error::BoundsExceeded`] when /// rooting the patterns would exceed the path limit. pub fn scope(&self, root: impl AsPath, patterns: &Patterns) -> Result { let root = self.root.join(root).to_owned(); - let rooted = with_epochs(patterns.rooted(root.as_str()).map_err(|_| BoundsExceeded)?); + let rooted = patterns.rooted(root.as_str()).map_err(|_| BoundsExceeded)?; let scope = self.scope.narrow(&rooted).ok_or(Error::Unauthorized)?; Ok(Consumer { scope, @@ -4378,38 +4323,19 @@ impl Consumer { }) } - /// Resolve a broadcast by exact path. + /// Resolve a broadcast by path and optional publisher epoch. /// - /// Returns a [`kio::Pending`] future, mirroring - /// [`track::Consumer::fetch_group`](track::Consumer::fetch_group). Every - /// path resolves through a front the origin's [`Driver`] runs: the request - /// mints one or joins the one already serving the path, and the front picks - /// the best announced route covering it (the most specific prefix, then the - /// cheapest, a broadcast published on this origin winning ties) and - /// materializes it, from the broadcast itself or from the peer that - /// announced the route. For a path naming an epoch, which names one origin, - /// the front switches to the best remaining route when its serving source dies - /// or a better route appears, invisibly to subscribers. A path without an epoch - /// stays on the route that first served it, since another route's bytes may - /// differ, and ends once that route goes. Either way, the broadcast ends when - /// nothing it may use is left, and the next request re-serves the path. - /// Tracks already in flight carry on to their own end. + /// Requests for the same identity and horizon share a front. A known epoch + /// selects only routes attesting that epoch and can resume through another + /// matching route. An absent epoch pins the first route that serves the front; + /// it never binds to an epoch or joins a known-epoch front. /// - /// A bare name binds once, at request time, to its newest epoch: the greatest - /// `path/@` a route serves, ahead of any route covering the name. With - /// no epoch it binds to a route covering the name itself. The broadcast is - /// still named `path` and never moves: a newer epoch is a different broadcast, - /// served to later requests, and the bound one ends with its epoch. A path - /// naming an epoch pins it. - /// - /// The returned future fails with [`Error::Unroutable`] at once when no - /// announced route covers the path, including a broadcast created on this - /// origin but not announced. - /// A route claims capability, not inventory: resolving a covered path - /// succeeds optimistically, and a path that names nothing surfaces as - /// [`Error::NotFound`] on its tracks instead. - pub fn request_broadcast(&self, path: impl AsPath) -> kio::Pending { - let path = path.as_path(); + /// No matching announced route returns [`Error::Unroutable`]. Retraction ends + /// new work while existing tracks drain their source. A route claims capability, + /// not inventory: missing content surfaces as [`Error::NotFound`] on its tracks. + pub fn request_broadcast(&self, id: impl Into) -> kio::Pending { + let id = id.into(); + let path = id.path.as_path(); // The path as this handle names it, absolute: what its scope authorizes and // what its egress is counted under, so a read through a mount bills where @@ -4439,28 +4365,26 @@ impl Consumer { return kio::Pending::new(Requesting::failed(Error::Closed)); } - // Nothing serves the path: no announced broadcast, no served route, and - // no epoch below a bare name. Checked before joining a front, so a front - // still draining after its route retracted takes no newcomers. - let Some(target) = state.resolve(&absolute.as_path(), self.horizon) else { + // Nothing serves the path: no announced broadcast and no served route. + // Checked before joining a front, so a front still draining after its + // route retracted takes no newcomers. + if state + .best_route(&absolute.as_path(), self.horizon, &HashSet::new(), id.epoch.as_ref()) + .is_none() + { return kio::Pending::new(Requesting::failed(Error::Unroutable)); - }; + } // Join the live front for this path and exclusion, if any: its watcher // resolves (or already resolved) the request channel with the front's // broadcast, so repeat requests share one upstream subscription. Whichever - // route serves the path, it is the same broadcast. - let key = (absolute.clone(), self.horizon); + // route serves a known epoch, it must carry the same content. + let key = (absolute.clone(), id.epoch.clone(), self.horizon); if let Some(front) = state.fronts.get(&key) { - if front.target == target { - let pending = Requesting::queued(front.request.consume()) - .with_path(requested) - .with_stats(scope); - return kio::Pending::new(pending); - } - // The front stays bound to an older epoch for its own readers, and a - // newcomer binds to the newest: a fresh front, never the old one moved. - state.fronts.remove(&key); + let pending = Requesting::queued(front.request.consume()) + .with_path(requested) + .with_stats(scope); + return kio::Pending::new(pending); } // A route covers the path: mint the front and hand its watcher the @@ -4471,16 +4395,16 @@ impl Consumer { pool: self.pool.clone(), cache_duration: self.cache_duration, path: absolute.clone(), + epoch: id.epoch.clone(), }); let request = kio::Producer::::default(); let consumer = request.consume(); - let watch = state.watch(&self.shared, &target); + let watch = state.watch(&self.shared, &absolute); state.fronts.insert( key, RemoteFront { request: request.clone(), broadcast: broadcast.consume().weak(), - target: target.clone(), }, ); // Released before the push: a set whose handles are gone drops the task, @@ -4488,9 +4412,10 @@ impl Consumer { drop(state); self.tasks.push(run_front( FrontTask { + epoch: id.epoch, shared: self.shared.clone(), broadcast, - path: target, + path: absolute, horizon: self.horizon, watch, request, @@ -5583,7 +5508,7 @@ mod tests { .map(|i| { let path = Path::new(&format!("pool/job-{i}")).to_owned(); let entry = table - .best_route(&path.as_path(), Horizon::default(), &HashSet::new()) + .best_route(&path.as_path(), Horizon::default(), &HashSet::new(), None) .expect("the pool serves every path"); entry.hops.iter().next().copied().unwrap() }) @@ -5912,24 +5837,30 @@ mod tests { } /// A cheaper route that appears after a front was minted takes the front over: the - /// path is one broadcast whoever serves it, so a newcomer joins the front. + /// epoch identifies the same content, so a newcomer joins the front. #[moq_net_sim::test] async fn cheaper_route_after_a_front_takes_it_over() { let producer = origin(1).produce(); let consumer = producer.consume(); let _local = producer - .publish(epoch("room/alice", OLD), Route::default().with_cost(5)) + .publish( + instance("room/alice"), + Route::default().with_epoch(test_epoch()).with_cost(5), + ) .unwrap(); let first = consumer - .request_broadcast(epoch("room/alice", OLD)) + .request_broadcast(instance("room/alice")) .await .expect("resolves locally"); let server = producer .dynamic( - epoch("room/alice", OLD), - Route::default().with_hops(hops(&[10])).with_cost(1), + "room/alice", + Route::default() + .with_epoch(test_epoch()) + .with_hops(hops(&[10])) + .with_cost(1), ) .unwrap(); let request = queued(&server).await; @@ -5937,7 +5868,7 @@ mod tests { request.accept(&upstream); let second = consumer - .request_broadcast(epoch("room/alice", OLD)) + .request_broadcast(instance("room/alice")) .await .expect("resolves"); assert!(first.is_clone(&second), "the newcomer joins the front"); @@ -6169,11 +6100,14 @@ mod tests { let producer = origin(1).produce(); let first_server = producer .dynamic( - epoch("room/alice", OLD), - Route::default().with_hops(hops(&[10])).with_cost(5), + "room/alice", + Route::default() + .with_epoch(test_epoch()) + .with_hops(hops(&[10])) + .with_cost(5), ) .unwrap(); - let pending = producer.consume().request_broadcast(epoch("room/alice", OLD)); + let pending = producer.consume().request_broadcast(instance("room/alice")); let upstream = broadcast::Info::new().produce(); let mut dynamic = upstream.dynamic(); queued(&first_server).await.accept(&upstream); @@ -6219,8 +6153,11 @@ mod tests { let cost = if dies_first { 5 } else { 0 }; let replacement_server = producer .dynamic( - epoch("room/alice", OLD), - Route::default().with_hops(hops(&[10])).with_cost(cost), + "room/alice", + Route::default() + .with_epoch(test_epoch()) + .with_hops(hops(&[10])) + .with_cost(cost), ) .unwrap(); let replacement = broadcast::Info::new().produce(); @@ -7523,6 +7460,14 @@ mod tests { /// One live subscription reading a track through a remote front, plus the /// bookkeeping to kill and replace its serving route. + fn test_epoch() -> crate::Epoch { + "01900000-0000-7000-8000-000000000001".parse().unwrap() + } + + fn instance(path: &str) -> broadcast::Id { + broadcast::Id::from(path).with_epoch(test_epoch()) + } + struct ResumeRig { producer: Producer, resolved: broadcast::Consumer, @@ -7534,16 +7479,16 @@ mod tests { impl ResumeRig { /// Announce a served route with `first` as its first hop, materialize - /// epoch("room/alice", OLD) through it with a one-group "before" track, and subscribe. + /// "room/alice" through it with a one-group "before" track, and subscribe. async fn new(first: &[u64]) -> (Self, Dynamic, broadcast::Producer) { let producer = origin(1).produce(); let consumer = producer.consume(); let server = producer - .dynamic("room", Route::default().with_hops(hops(first))) + .dynamic("room", Route::default().with_epoch(test_epoch()).with_hops(hops(first))) .unwrap(); - let pending = consumer.request_broadcast(epoch("room/alice", OLD)); + let pending = consumer.request_broadcast(instance("room/alice")); let request = queued(&server).await; let source = broadcast::Info::new().produce(); let track = source.create_track("video", None).unwrap(); @@ -7583,7 +7528,7 @@ mod tests { /// back its handle, ready to answer the front's re-request. fn standby(&self, first: &[u64]) -> Dynamic { self.producer - .dynamic("room", Route::default().with_hops(hops(first))) + .dynamic("room", Route::default().with_epoch(test_epoch()).with_hops(hops(first))) .unwrap() } } @@ -7670,11 +7615,11 @@ mod tests { } } - /// A path is one broadcast whoever publishes it: when the serving route dies, the + /// Routes attesting the same epoch serve one broadcast: when the serving route dies, the /// subscription resumes through another route, whatever its first hop, or with /// none at all. #[moq_net_sim::test] - async fn any_route_at_the_path_resumes_the_subscription() { + async fn any_route_with_the_epoch_resumes_the_subscription() { let cases = [ (&[10][..], &[10, 20][..]), (&[10][..], &[11][..]), @@ -7700,7 +7645,9 @@ mod tests { for first in [&[][..], &[0][..], &[10][..]] { let (mut rig, server, _source) = ResumeRig::new(first).await; let standby = rig.standby(&[10, 20]); - server.update(Route::default().with_hops(hops(&[11]))).unwrap(); + server + .update(Route::default().with_epoch(test_epoch()).with_hops(hops(&[11]))) + .unwrap(); let mut group = rig.incumbent_track.append_group().unwrap(); group.write_frame(crate::Timestamp::ZERO, b"after".as_ref()).unwrap(); @@ -7715,7 +7662,7 @@ mod tests { let resolved = rig .producer .consume() - .request_broadcast(epoch("room/alice", OLD)) + .request_broadcast(instance("room/alice")) .await .unwrap(); assert!(resolved.is_clone(&rig.resolved), "first hop {first:?} left the front"); @@ -7738,14 +7685,17 @@ mod tests { None => producer.consume(), }; let incumbent = producer - .dynamic("room", Route::default().with_hops(hops(&[10]))) + .dynamic("room", Route::default().with_epoch(test_epoch()).with_hops(hops(&[10]))) .unwrap(); // The same publisher, reached through the requesting peer. let echo = producer - .dynamic("room", Route::default().with_hops(hops(&[10, 7]))) + .dynamic( + "room", + Route::default().with_epoch(test_epoch()).with_hops(hops(&[10, 7])), + ) .unwrap(); - let pending = consumer.request_broadcast(epoch("room/alice", OLD)); + let pending = consumer.request_broadcast(instance("room/alice")); let request = queued(&incumbent).await; let source = broadcast::Info::new().produce(); let track = source.create_track("video", None).unwrap(); @@ -7901,7 +7851,12 @@ mod tests { // A metadata-only reprice of the only route: nothing re-requests and the // subscription keeps flowing from the same source. incumbent - .update(Route::default().with_hops(hops(&[10])).with_cost(9)) + .update( + Route::default() + .with_epoch(test_epoch()) + .with_hops(hops(&[10])) + .with_cost(9), + ) .unwrap(); let track = source.create_track("audio", None).unwrap(); @@ -7934,7 +7889,12 @@ mod tests { // keeps serving. The front migrates to the standby without waiting for // the death. incumbent - .update(Route::default().with_hops(hops(&[10])).with_cost(Cost::DRAIN)) + .update( + Route::default() + .with_epoch(test_epoch()) + .with_hops(hops(&[10])) + .with_cost(Cost::DRAIN), + ) .unwrap(); assert_resumes(&mut rig, &standby_server).await; @@ -7949,12 +7909,22 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); - let first = producer.publish("room/alice", Route::default()).unwrap(); - let resolved = consumer.request_broadcast("room/alice").await.expect("resolves"); + let first = producer + .publish(instance("room/alice"), Route::default().with_epoch(test_epoch())) + .unwrap(); + let resolved = consumer + .request_broadcast(instance("room/alice")) + .await + .expect("resolves"); // A second source at the same path joins the same front. - let second = producer.publish("room/alice", Route::default()).unwrap(); - let again = consumer.request_broadcast("room/alice").await.expect("resolves"); + let second = producer + .publish(instance("room/alice"), Route::default().with_epoch(test_epoch())) + .unwrap(); + let again = consumer + .request_broadcast(instance("room/alice")) + .await + .expect("resolves"); assert!(again.is_clone(&resolved)); // Losing one source keeps the front alive; losing both closes it. @@ -7964,7 +7934,9 @@ mod tests { settle(|| consumer.get_broadcast("room/alice").is_none()).await; // The path is free again for a fresh broadcast. - let _third = producer.publish("room/alice", Route::default()).unwrap(); + let _third = producer + .publish(instance("room/alice"), Route::default().with_epoch(test_epoch())) + .unwrap(); assert!(consumer.get_broadcast("room/alice").is_some()); } @@ -8318,10 +8290,12 @@ mod tests { let producer = origin(1).produce(); let consumer = producer.consume(); - let first = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); + let first = producer + .publish(instance("room/alice"), Route::default().with_epoch(test_epoch())) + .unwrap(); let track = first.create_track("video", None).unwrap(); let resolved = consumer - .request_broadcast(epoch("room/alice", OLD)) + .request_broadcast(instance("room/alice")) .await .expect("resolves"); let mut subscription = resolved @@ -8337,7 +8311,9 @@ mod tests { assert_eq!(&group.read_frame().await.unwrap().unwrap().payload[..], b"before"); // The newest source is dispatched the track, and refused for its metadata. - let second = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); + let second = producer + .publish(instance("room/alice"), Route::default().with_epoch(test_epoch())) + .unwrap(); let _incompatible = second .create_track("video", track::Info::default().with_timescale(crate::Timescale::MICRO)) .unwrap(); @@ -8369,9 +8345,9 @@ mod tests { ) { let producer = origin(1).produce(); let server = producer - .dynamic("room", Route::default().with_hops(hops(&[10]))) + .dynamic("room", Route::default().with_epoch(test_epoch()).with_hops(hops(&[10]))) .unwrap(); - let pending = producer.consume().request_broadcast(epoch("room/alice", OLD)); + let pending = producer.consume().request_broadcast(instance("room/alice")); let upstream = broadcast::Info::new().produce(); let old = upstream.create_track("video", None).unwrap(); queued(&server).await.accept(&upstream); @@ -8392,9 +8368,9 @@ mod tests { async fn an_unread_draining_track_releases_the_old_source() { let (producer, _server, _upstream, old, subscription) = remote_front().await; - let newcomer = producer.create_broadcast(epoch("room/alice", OLD)).unwrap(); + let newcomer = producer.create_broadcast(instance("room/alice")).unwrap(); let mut handler = newcomer.dynamic(); - newcomer.announce(Route::default()).unwrap(); + newcomer.announce(Route::default().with_epoch(test_epoch())).unwrap(); let _unanswered = moq_net_sim::timeout(Duration::from_secs(1), handler.requested_track()) .await .expect("the front asked the newcomer") @@ -8416,12 +8392,14 @@ mod tests { let (producer, _server, upstream, old, mut subscription) = remote_front().await; let resolved = producer .consume() - .request_broadcast(epoch("room/alice", OLD)) + .request_broadcast(instance("room/alice")) .await .unwrap(); // No handler and no track: refuses "video" with NotFound. - let _second = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); + let _second = producer + .publish(instance("room/alice"), Route::default().with_epoch(test_epoch())) + .unwrap(); for _ in 0..10 { moq_net_sim::yield_now().await; } @@ -8438,7 +8416,9 @@ mod tests { .expect("parked") .expect("open"); - let _third = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); + let _third = producer + .publish(instance("room/alice"), Route::default().with_epoch(test_epoch())) + .unwrap(); for _ in 0..10 { moq_net_sim::yield_now().await; } @@ -8471,10 +8451,12 @@ mod tests { async fn a_refused_copy_is_not_kept_subscribed() { let producer = origin(1).produce(); let consumer = producer.consume(); - let first = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); + let first = producer + .publish(instance("room/alice"), Route::default().with_epoch(test_epoch())) + .unwrap(); let track = first.create_track("video", None).unwrap(); let resolved = consumer - .request_broadcast(epoch("room/alice", OLD)) + .request_broadcast(instance("room/alice")) .await .expect("resolves"); let mut subscription = resolved.track("video").unwrap().subscribe(None).await.unwrap(); @@ -8484,7 +8466,9 @@ mod tests { let mut group = subscription.recv_group().await.unwrap().unwrap(); assert_eq!(&group.read_frame().await.unwrap().unwrap().payload[..], b"before"); - let second = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); + let second = producer + .publish(instance("room/alice"), Route::default().with_epoch(test_epoch())) + .unwrap(); let incompatible = second .create_track("video", track::Info::default().with_timescale(crate::Timescale::MICRO)) .unwrap(); @@ -8506,9 +8490,14 @@ mod tests { async fn the_end_never_feeds_a_refused_copy() { let producer = origin(1).produce(); let consumer = producer.consume(); - let first = producer.publish("room/alice", Route::default()).unwrap(); + let first = producer + .publish(instance("room/alice"), Route::default().with_epoch(test_epoch())) + .unwrap(); let track = first.create_track("video", None).unwrap(); - let resolved = consumer.request_broadcast("room/alice").await.expect("resolves"); + let resolved = consumer + .request_broadcast(instance("room/alice")) + .await + .expect("resolves"); let mut subscription = resolved.track("video").unwrap().subscribe(None).await.unwrap(); let mut group = track.append_group().unwrap(); group.write_frame(crate::Timestamp::ZERO, b"before".as_ref()).unwrap(); @@ -8517,7 +8506,9 @@ mod tests { assert_eq!(&group.read_frame().await.unwrap().unwrap().payload[..], b"before"); drop(group); - let second = producer.publish("room/alice", Route::default()).unwrap(); + let second = producer + .publish(instance("room/alice"), Route::default().with_epoch(test_epoch())) + .unwrap(); let incompatible = second .create_track("video", track::Info::default().with_timescale(crate::Timescale::MICRO)) .unwrap(); @@ -8557,10 +8548,12 @@ mod tests { async fn the_end_keeps_the_copy_still_serving() { let producer = origin(1).produce(); let consumer = producer.consume(); - let first = producer.publish(epoch("room/alice", OLD), Route::default()).unwrap(); + let first = producer + .publish(instance("room/alice"), Route::default().with_epoch(test_epoch())) + .unwrap(); let track = first.create_track("video", None).unwrap(); let resolved = consumer - .request_broadcast(epoch("room/alice", OLD)) + .request_broadcast(instance("room/alice")) .await .expect("resolves"); let mut subscription = resolved.track("video").unwrap().subscribe(None).await.unwrap(); @@ -8571,9 +8564,9 @@ mod tests { assert_eq!(&group.read_frame().await.unwrap().unwrap().payload[..], b"before"); drop(group); - let second = producer.create_broadcast(epoch("room/alice", OLD)).unwrap(); + let second = producer.create_broadcast(instance("room/alice")).unwrap(); let mut handler = second.dynamic(); - second.announce(Route::default()).unwrap(); + second.announce(Route::default().with_epoch(test_epoch())).unwrap(); let request = moq_net_sim::timeout(Duration::from_secs(1), handler.requested_track()) .await .expect("the front asked the newcomer") @@ -8626,25 +8619,19 @@ mod tests { let consumer = producer.consume().scope("", &scopes(&["room"])).unwrap(); assert_eq!(consumer.allowed(), scopes(&["room"])); - // A member naming a broadcast also reaches its epochs. for text in ["room", "", "*room", "room/*", "*", "**/room", "room/**/chat", "*.hang"] { let union = Patterns::from(text.parse::().unwrap()); - let reached = with_epochs(union.clone()); - assert_eq!(producer.scope("", &union).expect(text).allowed(), reached, "{text}"); + assert_eq!(producer.scope("", &union).expect(text).allowed(), union, "{text}"); assert_eq!( producer.consume().scope("", &union).expect(text).allowed(), - reached, + union, "{text}" ); } - let mixed: Patterns = [ - "room/**".parse().unwrap(), - "other".parse().unwrap(), - "other/@*".parse().unwrap(), - ] - .into_iter() - .collect(); + let mixed: Patterns = ["room/**".parse().unwrap(), "other".parse().unwrap()] + .into_iter() + .collect(); assert_eq!(producer.scope("", &mixed).unwrap().allowed(), mixed); } @@ -8913,19 +8900,13 @@ mod tests { let chats = rooms .scope("", &Patterns::from("*/chat".parse::().unwrap())) .unwrap(); - assert_eq!( - chats.allowed(), - with_epochs(Patterns::from("room/chat".parse::().unwrap())) - ); + assert_eq!(chats.allowed(), Patterns::from("room/chat".parse::().unwrap())); let exact = producer .scope("", &Patterns::from("room/alice".parse::().unwrap())) .unwrap(); let rooted = exact.scope("room", &Patterns::from(Pattern::all())).unwrap(); - assert_eq!( - rooted.allowed(), - with_epochs(Patterns::from("alice".parse::().unwrap())) - ); + assert_eq!(rooted.allowed(), Patterns::from("alice".parse::().unwrap())); assert!(matches!( exact.scope("room/bob", &Patterns::from(Pattern::all())), Err(Error::Unauthorized) @@ -9083,310 +9064,4 @@ mod tests { .encode_bytes(crate::lite::Version::Lite06) .expect("a draining route is still forwarded, so its cost must encode"); } - - /// Two epochs in mint order, older first. - const OLD: &str = "0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f"; - const NEW: &str = "0199b7f4-3c2b-7d1e-9f0b-2b6c1a9d8e7f"; - - fn epoch(name: &str, epoch: &str) -> PathOwned { - Path::new(name).with_epoch(&epoch.parse::().unwrap()) - } - - /// Publish one epoch of `room/alice` with a `video` track holding one group. - fn publish_epoch(producer: &Producer, at: &str, payload: &'static [u8]) -> (broadcast::Producer, track::Producer) { - let broadcast = producer.publish(epoch("room/alice", at), Route::default()).unwrap(); - let track = broadcast.create_track("video", None).unwrap(); - let mut group = track.append_group().unwrap(); - group.write_frame(crate::Timestamp::ZERO, payload).unwrap(); - group.finish().unwrap(); - (broadcast, track) - } - - async fn read_video(broadcast: &broadcast::Consumer) -> (crate::track::Subscriber, Vec) { - let mut subscription = broadcast.track("video").unwrap().subscribe(None).await.unwrap(); - let mut group = next_group(&mut subscription).await.unwrap().unwrap(); - let payload = group.read_frame().await.unwrap().unwrap().payload.to_vec(); - (subscription, payload) - } - - #[test] - fn mint_epoch_appends_a_fresh_epoch() { - let minted = Path::new("room/alice").mint_epoch(); - let (name, epoch) = minted.split_epoch(); - assert_eq!(name, Path::new("room/alice")); - assert!(epoch.is_some()); - assert_ne!(Path::new("room/alice").mint_epoch(), minted); - } - - #[moq_net_sim::test] - async fn a_bare_name_resolves_to_its_newest_epoch() { - let producer = origin(1).produce(); - let consumer = producer.consume(); - let _old = publish_epoch(&producer, OLD, b"old"); - let _new = publish_epoch(&producer, NEW, b"new"); - - let resolved = consumer.request_broadcast("room/alice").await.unwrap(); - // Named as asked, so a catalog's relative references resolve against the name. - assert_eq!(resolved.info().path, Path::new("room/alice")); - assert_eq!(read_video(&resolved).await.1, b"new"); - - // A path naming an epoch pins it. - let pinned = consumer.request_broadcast(epoch("room/alice", OLD)).await.unwrap(); - assert_eq!(read_video(&pinned).await.1, b"old"); - } - - #[moq_net_sim::test] - async fn a_bare_request_stays_on_its_epoch() { - let producer = origin(1).produce(); - let consumer = producer.consume(); - let (_old, old_track) = publish_epoch(&producer, OLD, b"old"); - - let bare = consumer.request_broadcast("room/alice").await.unwrap(); - let (mut following, payload) = read_video(&bare).await; - assert_eq!(payload, b"old"); - - // A newer epoch is a different broadcast: the bound request never moves to it. - let _new = publish_epoch(&producer, NEW, b"new"); - let mut group = old_track.append_group().unwrap(); - group - .write_frame(crate::Timestamp::ZERO, b"still old".as_ref()) - .unwrap(); - group.finish().unwrap(); - let mut group = next_group(&mut following) - .await - .unwrap() - .expect("the old epoch carries on"); - assert_eq!(&group.read_frame().await.unwrap().unwrap().payload[..], b"still old"); - assert!(!bare.is_closed()); - - // A later request binds to the newest. - let later = consumer.request_broadcast("room/alice").await.unwrap(); - assert!(!later.is_clone(&bare)); - assert_eq!(read_video(&later).await.1, b"new"); - } - - #[moq_net_sim::test] - async fn a_bare_request_ends_with_its_epoch() { - let producer = origin(1).produce(); - let consumer = producer.consume(); - let _old = publish_epoch(&producer, OLD, b"old"); - let (new, track) = publish_epoch(&producer, NEW, b"new"); - - let bare = consumer.request_broadcast("room/alice").await.unwrap(); - let (mut following, payload) = read_video(&bare).await; - assert_eq!(payload, b"new"); - - // Never spliced into the older epoch still live: the binding ends with its epoch. - drop((new, track)); - assert!(!matches!(next_group(&mut following).await, Ok(Some(_)))); - settle(|| bare.is_closed()).await; - let bare = consumer.request_broadcast("room/alice").await.unwrap(); - assert_eq!(read_video(&bare).await.1, b"old"); - } - - #[moq_net_sim::test] - async fn the_last_epoch_retracting_ends_like_any_route() { - let producer = origin(1).produce(); - let consumer = producer.consume(); - let (old, _track) = publish_epoch(&producer, OLD, b"old"); - - let bare = consumer.request_broadcast("room/alice").await.unwrap(); - read_video(&bare).await; - old.unannounce(); - settle(|| bare.is_closed()).await; - assert!(matches!( - consumer.request_broadcast("room/alice").await, - Err(Error::Unroutable) - )); - } - - #[moq_net_sim::test] - async fn an_epoch_beats_a_route_covering_the_name() { - let producer = origin(1).produce(); - let consumer = producer.consume(); - let _new = publish_epoch(&producer, NEW, b"new"); - let _claim = producer.dynamic("room", Route::default()).unwrap(); - let raw = producer.publish("room/alice", Route::default()).unwrap(); - let track = raw.create_track("video", None).unwrap(); - let mut group = track.append_group().unwrap(); - group.write_frame(crate::Timestamp::ZERO, b"raw".as_ref()).unwrap(); - group.finish().unwrap(); - - let bare = consumer.request_broadcast("room/alice").await.unwrap(); - assert_eq!(read_video(&bare).await.1, b"new"); - } - - /// A worker's answer for bare `room/alice`: its broadcast, its `video` track, - /// and that track's open group. - type Worker = (broadcast::Producer, track::Producer, crate::group::Producer); - - /// Serve bare `room/alice` through `server` with a `video` track holding one - /// open group that has written `payload`. - async fn serve_bare(server: &Dynamic, payload: &'static [u8]) -> Worker { - let request = queued(server).await; - let source = broadcast::Info::new().produce(); - let track = source.create_track("video", None).unwrap(); - let mut group = track.append_group().unwrap(); - group.write_frame(crate::Timestamp::ZERO, payload).unwrap(); - request.accept(&source); - (source, track, group) - } - - #[moq_net_sim::test] - async fn a_bare_path_stays_on_its_first_route() { - let producer = origin(1).produce(); - let consumer = producer.consume(); - let first = producer - .dynamic("room/alice", Route::default().with_hops(hops(&[10])).with_cost(5)) - .unwrap(); - - let pending = consumer.request_broadcast("room/alice"); - let (_source, _track, mut open) = serve_bare(&first, b"first").await; - let bare = pending.await.unwrap(); - let mut subscription = bare.track("video").unwrap().subscribe(None).await.unwrap(); - let mut reading = next_group(&mut subscription).await.unwrap().unwrap(); - assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"first"); - - // A cheaper route serving the same bare path is never asked: its bytes may differ. - let cheaper = producer - .dynamic("room/alice", Route::default().with_hops(hops(&[11])).with_cost(1)) - .unwrap(); - for _ in 0..10 { - moq_net_sim::yield_now().await; - } - assert!(cheaper.poll_requested_broadcast(&kio::Waiter::noop()).is_pending()); - open.write_frame(crate::Timestamp::ZERO, b"more".as_ref()).unwrap(); - assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"more"); - } - - /// Two claimants serve one bare path with different bytes. Killing the serving one - /// mid-group ends the subscription instead of resuming it on the other. - #[moq_net_sim::test] - async fn a_bare_path_never_resumes_on_another_route() { - let producer = origin(1).produce(); - let consumer = producer.consume(); - let first = producer - .dynamic("room/alice", Route::default().with_hops(hops(&[10]))) - .unwrap(); - let second = producer - .dynamic("room/alice", Route::default().with_hops(hops(&[11])).with_cost(5)) - .unwrap(); - - let pending = consumer.request_broadcast("room/alice"); - let (source, track, open) = serve_bare(&first, b"worker one").await; - let bare = pending.await.unwrap(); - let mut subscription = bare.track("video").unwrap().subscribe(None).await.unwrap(); - let mut reading = next_group(&mut subscription).await.unwrap().unwrap(); - assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"worker one"); - - drop((open, track, source, first)); - // The open group and the track end; nothing from the other worker is spliced in. - assert!(!matches!(reading.read_frame().await, Ok(Some(_)))); - assert!(!matches!(next_group(&mut subscription).await, Ok(Some(_)))); - settle(|| bare.is_closed()).await; - assert!(second.poll_requested_broadcast(&kio::Waiter::noop()).is_pending()); - - // Asking again binds afresh, to the survivor. - let pending = consumer.request_broadcast("room/alice"); - let _worker = serve_bare(&second, b"worker two").await; - let again = pending.await.unwrap(); - assert!(!again.is_clone(&bare)); - } - - #[moq_net_sim::test] - async fn routed_broadcast_follows_an_epoch_announced_later() { - let producer = origin(1).produce(); - let consumer = producer.consume(); - - let routed = moq_net_sim::spawn({ - let consumer = consumer.clone(); - async move { consumer.routed_broadcast("room/alice").await } - }); - moq_net_sim::yield_now().await; - let _old = publish_epoch(&producer, OLD, b"old"); - let resolved = routed.await.unwrap().unwrap(); - assert_eq!(read_video(&resolved).await.1, b"old"); - - let route = consumer.routed("room/alice").await.unwrap(); - assert!(route.hops.is_empty()); - } - - #[moq_net_sim::test] - async fn an_epoch_through_the_requester_is_not_followed() { - let producer = origin(1).produce(); - let consumer = producer.consume(); - let _route = producer - .dynamic(epoch("room/alice", NEW), Route::default().with_hops(hops(&[10]))) - .unwrap(); - - assert!(matches!( - consumer - .clone() - .excluding(origin(10)) - .request_broadcast("room/alice") - .await, - Err(Error::Unroutable) - )); - let pending = consumer.request_broadcast("room/alice"); - assert!(pending.is_queued()); - } - - #[moq_net_sim::test] - async fn an_epoch_only_ends_a_path() { - let producer = origin(1).produce(); - let source = epoch("room/alice", OLD); - for path in [ - source.join("transcode"), - source.with_epoch(&NEW.parse::().unwrap()).join("x"), - ] { - assert!(matches!( - producer.publish(&path, Route::default()), - Err(Error::MisplacedEpoch) - )); - assert!(matches!( - producer.dynamic(&path, Route::default()), - Err(Error::MisplacedEpoch) - )); - } - // A derived broadcast carries the source's epoch at its own end instead. - producer - .publish( - Path::new("room/alice/transcode").with_epoch(&OLD.parse::().unwrap()), - Route::default(), - ) - .unwrap(); - } - - #[moq_net_sim::test] - async fn a_grant_on_a_name_admits_its_epochs() { - let producer = origin(1).produce(); - let exact = Patterns::from(Pattern::literal("room/alice").unwrap()); - - // Publish: an exact grant admits the name's epochs, not its other children. - let publisher = producer.scope("", &exact).unwrap(); - let _broadcast = publisher.publish(epoch("room/alice", OLD), Route::default()).unwrap(); - assert!(matches!( - publisher.publish("room/alice/other", Route::default()), - Err(Error::Unauthorized) - )); - - // Subscribe: the same grant reaches the bare name, a pinned epoch, and sees it announced. - let viewer = producer.consume().scope("", &exact).unwrap(); - viewer.request_broadcast("room/alice").await.unwrap(); - viewer.request_broadcast(epoch("room/alice", OLD)).await.unwrap(); - viewer.announced().assert_next_active(epoch("room/alice", OLD)); - - // A grant on one epoch never widens to the bare name or a sibling epoch. - let one = Patterns::from(Pattern::literal(epoch("room/alice", OLD).as_str()).unwrap()); - let viewer = producer.consume().scope("", &one).unwrap(); - viewer.request_broadcast(epoch("room/alice", OLD)).await.unwrap(); - assert!(matches!( - viewer.request_broadcast("room/alice").await, - Err(Error::Unauthorized) - )); - assert!(matches!( - viewer.request_broadcast(epoch("room/alice", NEW)).await, - Err(Error::Unauthorized) - )); - } } diff --git a/rs/moq-net/src/path/epoch.json b/rs/moq-net/src/path/epoch.json index c8965139438..baa8065bf82 100644 --- a/rs/moq-net/src/path/epoch.json +++ b/rs/moq-net/src/path/epoch.json @@ -44,84 +44,5 @@ "0199b7f4-3c2a-7d1e-af0b-2b6c1a9d8e7f", "0199b7f4-9e10-7f42-8a3c-5d7e2b1c0f9a", "ffffffff-ffff-7fff-bfff-ffffffffffff" - ], - "paths": [ - { - "path": "", - "name": "", - "epoch": null - }, - { - "path": "demo/BBB.hang/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f", - "name": "demo/BBB.hang", - "epoch": "0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f" - }, - { - "path": "@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f", - "name": "", - "epoch": "0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f" - }, - { - "path": ".private/demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f", - "name": ".private/demo", - "epoch": "0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f" - }, - { - "path": "demo/.private/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f", - "name": "demo/.private", - "epoch": "0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f" - }, - { - "path": "demo/@alice", - "name": "demo/@alice", - "epoch": null - }, - { - "path": "demo/0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f", - "name": "demo/0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f", - "epoch": null - }, - { - "path": "demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f/track", - "name": "demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f/track", - "epoch": null, - "misplaced": true - }, - { - "path": "demo/@0199B7F4-3C2A-7D1E-9F0B-2B6C1A9D8E7F", - "name": "demo/@0199B7F4-3C2A-7D1E-9F0B-2B6C1A9D8E7F", - "epoch": null - }, - { - "path": "demo/@0199b7f4-3c2a-7d1e-cf0b-2b6c1a9d8e7f", - "name": "demo/@0199b7f4-3c2a-7d1e-cf0b-2b6c1a9d8e7f", - "epoch": null - }, - { - "path": "demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f/@0199b7f4-9e10-7f42-8a3c-5d7e2b1c0f9a", - "name": "demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f", - "epoch": "0199b7f4-9e10-7f42-8a3c-5d7e2b1c0f9a", - "misplaced": true - }, - { - "path": "demo/@0199b7f4-3c2a-4d1e-9f0b-2b6c1a9d8e7f", - "name": "demo/@0199b7f4-3c2a-4d1e-9f0b-2b6c1a9d8e7f", - "epoch": null - }, - { - "path": "demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f.hang", - "name": "demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f.hang", - "epoch": null - }, - { - "path": "demo/@", - "name": "demo/@", - "epoch": null - }, - { - "path": "demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f\n", - "name": "demo/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f\n", - "epoch": null - } ] } diff --git a/rs/moq-net/src/path/mod.rs b/rs/moq-net/src/path/mod.rs index 929e3149121..ae0f52fb126 100644 --- a/rs/moq-net/src/path/mod.rs +++ b/rs/moq-net/src/path/mod.rs @@ -353,52 +353,10 @@ impl<'a> Path<'a> { } } - /// Split off a final `@` segment, leaving all other paths unchanged. - pub fn split_epoch(&self) -> (Path<'_>, Option) { - let text = self.as_str(); - let (name, segment) = text.rsplit_once('/').unwrap_or(("", text)); - if let Some(epoch) = segment.strip_prefix('@').and_then(|text| text.parse().ok()) { - (Path::new(name), Some(epoch)) - } else { - (self.borrow(), None) - } - } - - /// This path with its final epoch set to `epoch`, replacing any it has, or removed for `None`. - pub fn with_epoch<'e>(&self, epoch: impl Into>) -> PathOwned { - let (name, _) = self.split_epoch(); - match epoch.into() { - Some(epoch) => name.join(format!("@{epoch}")), - None => name.to_owned(), - } - } - - /// This path under a freshly minted epoch, naming a new instance of the broadcast. - pub fn mint_epoch(&self) -> PathOwned { - self.with_epoch(&crate::Epoch::mint()) - } - - /// Whether an epoch segment sits anywhere but the end, which no broadcast may publish. - pub(crate) fn has_misplaced_epoch(&self) -> bool { - let mut parts = self.parts().peekable(); - while let Some(part) = parts.next() { - if parts.peek().is_some() - && part - .strip_prefix('@') - .is_some_and(|text| text.parse::().is_ok()) - { - return true; - } - } - false - } - /// Resolve a [`Relative`] against this path. /// /// A non-empty reference replaces the last segment of the base, matching relative URL /// resolution. `..` segments then pop another segment; other segments are appended. - /// A base's final epoch is not a segment here: `a/b/@` resolves like `a/b`, so a - /// catalog's references mean the same whether it was requested by name or by epoch. /// Excess `..` is a no-op once the base is empty (subsequent named segments still append). /// An empty `rel` returns this path as an owned copy. /// @@ -419,8 +377,7 @@ impl<'a> Path<'a> { return self.to_owned(); } - let (name, _) = self.split_epoch(); - let mut segments: Vec<&str> = name.parts().collect(); + let mut segments: Vec<&str> = self.parts().collect(); segments.pop(); for seg in rel.as_str().split('/') { @@ -454,8 +411,7 @@ impl<'a> Path<'a> { return Some(self.to_owned()); } - let (name, _) = self.split_epoch(); - let mut segments: Vec<&str> = name.parts().collect(); + let mut segments: Vec<&str> = self.parts().collect(); segments.pop(); for seg in rel.as_str().split('/') { @@ -521,9 +477,8 @@ impl<'a> Path<'a> { return Some(Relative::empty()); } - // Resolution replaces the base's last segment, past any epoch, so walk from its parent. - let (name, _) = base.split_epoch(); - let mut dir: Vec<&str> = name.parts().collect(); + // Resolution replaces the base's last segment, so walk from its parent. + let mut dir: Vec<&str> = base.parts().collect(); dir.pop(); let target: Vec<&str> = self.parts().collect(); @@ -828,68 +783,6 @@ mod tests { .map(|row| row.as_str().unwrap().parse().unwrap()) .collect(); assert!(ordered.windows(2).all(|pair| pair[0] < pair[1])); - for row in vectors["paths"].as_array().unwrap() { - let path = Path::new(row["path"].as_str().unwrap()); - let (name, epoch) = path.split_epoch(); - assert_eq!(name.as_str(), row["name"].as_str().unwrap()); - assert_eq!(epoch.as_ref().map(|epoch| epoch.as_str()), row["epoch"].as_str()); - let misplaced = row["misplaced"].as_bool().unwrap_or(false); - assert_eq!(path.has_misplaced_epoch(), misplaced, "{path}"); - if !misplaced { - assert_eq!(name.with_epoch(epoch.as_ref()), path); - } - assert_eq!(path.is_hidden(), name.is_hidden()); - } - } - - #[test] - fn with_epoch_sets_the_final_epoch() { - let old: crate::Epoch = "0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f".parse().unwrap(); - let new: crate::Epoch = "0199b7f4-3c2b-7d1e-9f0b-2b6c1a9d8e7f".parse().unwrap(); - let name = Path::new("room/alice"); - let pinned = name.with_epoch(&old); - assert_eq!(pinned.as_str(), format!("room/alice/@{old}")); - // Never stacks: an existing epoch is replaced, and `None` removes it. - assert_eq!(pinned.with_epoch(&new), name.with_epoch(&new)); - assert_eq!(pinned.with_epoch(None), name); - assert_eq!(name.with_epoch(None), name); - assert_eq!(pinned.mint_epoch().split_epoch().0, name); - } - - #[test] - fn references_resolve_against_the_name_past_its_epoch() { - let epoch: crate::Epoch = "0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f".parse().unwrap(); - let name = Path::new("room/transcode"); - let pinned = name.with_epoch(&epoch); - for rel in ["./source", ".", "../other", "transcode/sub"] { - let rel = Relative::new(rel); - assert_eq!(pinned.resolve(&rel), name.resolve(&rel), "{rel}"); - assert_eq!(pinned.try_resolve(&rel), name.try_resolve(&rel), "{rel}"); - } - // The empty reference still names the catalog broadcast itself. - assert_eq!(pinned.resolve(&Relative::empty()), pinned); - // And `relative` stays its inverse. - for target in [ - "room/source", - "room/source/@0199b7f4-3c2b-7d1e-9f0b-2b6c1a9d8e7f", - "room", - "other", - ] { - let target = Path::new(target); - let rel = target.relative(&pinned).unwrap(); - assert_eq!(pinned.resolve(&rel), target, "{target}"); - } - } - - #[test] - fn epoch_segments_are_literal_pattern_components() { - let epoch: crate::Epoch = "0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f".parse().unwrap(); - let path = Path::new("demo/video").with_epoch(&epoch); - assert!("demo/**".parse::().unwrap().matches(path.as_str())); - assert!("demo/video/@*".parse::().unwrap().matches(path.as_str())); - assert!(!"demo/video".parse::().unwrap().matches(path.as_str())); - assert!(path.as_str().parse::().unwrap().matches(path.as_str())); - assert!(!path.is_hidden()); } #[test] diff --git a/rs/moq-net/src/server.rs b/rs/moq-net/src/server.rs index 78bcfb64b1f..f1dab046061 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -98,6 +98,7 @@ impl Server { // link. Versions without a Setup Stream have nothing to advertise. let our_setup = if version.has_setup_stream() { lite::Setup { + epoch: false, probe: lite::ProbeLevel::detect(&session), path: None, role: None, @@ -1002,6 +1003,7 @@ mod tests { .encode(&mut crate::coding::Encoder::new(&mut buf, v.into()), v) .unwrap(); lite::Setup { + epoch: false, probe: lite::ProbeLevel::None, path: path.map(str::to_string), role, diff --git a/rs/moq-net/tests/epochs.rs b/rs/moq-net/tests/epochs.rs new file mode 100644 index 00000000000..cd9978bb5e5 --- /dev/null +++ b/rs/moq-net/tests/epochs.rs @@ -0,0 +1,166 @@ +//! Epoch identity is metadata, including across protocol and route boundaries. +mod support; + +use moq_net::{Epoch, Error, Hop, Timestamp, Version, broadcast, origin, track}; +use support::harness::{MockConnectOptions, connect_mock, spawn}; + +const A: &str = "01900000-0000-7000-8000-000000000001"; +const B: &str = "01900000-0001-7000-8000-000000000001"; + +fn id(epoch: &str) -> broadcast::Id { + broadcast::Id::from("live").with_epoch(epoch.parse::().unwrap()) +} + +fn origin(hop: u64) -> origin::Producer { + let (origin, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); + spawn(driver); + origin +} + +fn publish(origin: &origin::Producer, epoch: &str, bytes: &'static [u8]) -> (broadcast::Producer, track::Producer) { + let source = origin.create_broadcast(id(epoch)).unwrap(); + let track = source.create_track("video", None).unwrap(); + let mut group = track.append_group().unwrap(); + group.write_frame(Timestamp::ZERO, bytes).unwrap(); + group.finish().unwrap(); + source.announce(Default::default()).unwrap(); + (source, track) +} + +async fn read(source: &broadcast::Consumer) -> Vec { + let mut track = source.track("video").unwrap().subscribe(None).await.unwrap(); + let mut group = track.recv_group().await.unwrap().unwrap(); + group.read_frame().await.unwrap().unwrap().payload.to_vec() +} + +#[moq_net_sim::test] +async fn epochs_select_content_without_changing_paths() { + let source = origin(1); + let _a = publish(&source, A, b"a"); + let a = source.consume().request_broadcast(id(A)).await.unwrap(); + let _b = publish(&source, B, b"b"); + let b = source.consume().request_broadcast(id(B)).await.unwrap(); + assert_eq!(a.info().path.as_str(), "live"); + assert_eq!(a.info().epoch.as_ref().unwrap().as_str(), A); + assert_eq!(read(&a).await, b"a"); + assert_eq!(read(&b).await, b"b"); + assert!(!a.is_clone(&b)); +} + +#[moq_net_sim::test] +async fn a_stale_epoch_never_falls_back_to_the_current_instance() { + let source = origin(1); + let _b = publish(&source, B, b"b"); + assert!(matches!( + source.consume().request_broadcast(id(A)).await, + Err(Error::Unroutable) + )); +} + +#[moq_net_sim::test] +async fn unknown_and_known_requests_are_not_merged() { + for known_first in [false, true] { + let source = origin(1); + let _a = publish(&source, A, b"a"); + let consumer = source.consume(); + let first = if known_first { id(A) } else { "live".into() }; + let second = if known_first { "live".into() } else { id(A) }; + let first = consumer.request_broadcast(first).await.unwrap(); + let second = consumer.request_broadcast(second).await.unwrap(); + assert!(!first.is_clone(&second)); + assert_eq!(read(&first).await, b"a"); + assert_eq!(read(&second).await, b"a"); + } +} + +#[moq_net_sim::test] +async fn an_unknown_subscription_does_not_adopt_a_new_epoch() { + let source = origin(1); + let a = publish(&source, A, b"a"); + let bare = source.consume().request_broadcast("live").await.unwrap(); + assert_eq!(read(&bare).await, b"a"); + let _b = publish(&source, B, b"b"); + let again = source.consume().request_broadcast("live").await.unwrap(); + assert!(bare.is_clone(&again)); + assert_eq!(read(&again).await, b"a"); + a.0.unannounce(); + // Existing handles may drain cached tracks, but never acquire B's new tracks. + let track = bare.track("new-track").unwrap(); + assert!(track.subscribe(None).await.is_err()); +} + +#[moq_net_sim::test] +async fn announced_epochs_survive_a_lite_session() { + for alpn in ["moq-lite-05", "moq-lite-06", "moq-lite-07-wip"] { + let source = origin(1); + let sink = origin(2); + let a = publish(&source, A, b"a"); + let mut options = MockConnectOptions::new(alpn.parse::().unwrap()); + options.server_publish = Some(source.consume()); + options.client_subscribe = Some(sink.clone()); + let _pair = connect_mock(options).await; + let mut announced = sink.consume().announced(); + loop { + if let Some(moq_net::announce::Event::Start(event)) = announced.next().await { + assert_eq!(event.prefix.as_str(), "live"); + assert_eq!(event.route.epoch.as_ref().unwrap().as_str(), A); + break; + } + } + let pinned = sink.consume().request_broadcast(id(A)).await.unwrap(); + assert_eq!(read(&pinned).await, b"a"); + // B is announced before A's next track request reaches the publisher. + let _b = publish(&source, B, b"b"); + let late = a.0.create_track("late", None).unwrap(); + let mut group = late.append_group().unwrap(); + group.write_frame(Timestamp::ZERO, b"still-a".as_ref()).unwrap(); + group.finish().unwrap(); + let mut sub = pinned.track("late").unwrap().subscribe(None).await.unwrap(); + let mut group = sub.recv_group().await.unwrap().unwrap(); + assert_eq!(group.read_frame().await.unwrap().unwrap().payload.as_ref(), b"still-a"); + } +} + +#[moq_net_sim::test] +async fn legacy_protocols_announce_plain_paths_without_claiming_an_epoch() { + for alpn in ["moq-lite-04", "moq-transport-19", "moq-transport-22"] { + let source = origin(1); + let sink = origin(2); + let _a = publish(&source, A, b"a"); + let mut options = MockConnectOptions::new(alpn.parse::().unwrap()); + options.server_publish = Some(source.consume()); + options.client_subscribe = Some(sink.clone()); + let _pair = connect_mock(options).await; + let mut announced = sink.consume().announced(); + loop { + if let Some(moq_net::announce::Event::Start(event)) = announced.next().await { + assert_eq!(event.prefix.as_str(), "live"); + assert_eq!(event.route.epoch, None); + break; + } + } + let bare = sink.consume().request_broadcast("live").await.unwrap(); + assert_eq!(read(&bare).await, b"a"); + assert!(matches!( + sink.consume().request_broadcast(id(A)).await, + Err(Error::Unroutable) + )); + } +} + +#[moq_net_sim::test] +async fn route_repricing_cannot_change_identity() { + let origin = origin(1); + let source = origin.create_broadcast(id(A)).unwrap(); + assert!(matches!( + source.announce(origin::Route::default().with_epoch(B.parse().unwrap())), + Err(Error::ProtocolViolation) + )); + let route = origin + .dynamic("live", origin::Route::default().with_epoch(A.parse().unwrap())) + .unwrap(); + assert!(matches!( + route.update(origin::Route::default().with_epoch(B.parse().unwrap())), + Err(Error::ProtocolViolation) + )); +} diff --git a/rs/moq-net/tests/route_change.rs b/rs/moq-net/tests/route_change.rs index dc87004e30b..ddc1f6c4c45 100644 --- a/rs/moq-net/tests/route_change.rs +++ b/rs/moq-net/tests/route_change.rs @@ -1,8 +1,8 @@ //! A subscription survives its route changing, end to end over real sessions. //! //! A publisher `P` is pulled by two relays `A` and `B`, both of which re-advertise -//! it to the subscribing relay `R`. A path naming an epoch is one broadcast whoever -//! relays it, so `R` may resume a subscription served through one onto the other. The reader on `R` +//! it to the subscribing relay `R`. Matching epochs identify the same content, so `R` +//! may resume a subscription served through one onto the other. The reader on `R` //! must see every frame exactly once, in order, whether the route changes between //! groups or in the middle of one, and however it changes. @@ -19,9 +19,6 @@ const TEST_TIMEOUT: Duration = Duration::from_secs(30); /// Frames per group. const FRAMES: u64 = 4; -/// The broadcast, under an epoch: only an epoch path resumes across routes. -const LIVE: &str = "live/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f"; - fn produce_origin(hop: u64) -> origin::Producer { let (producer, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); support::harness::spawn(driver); @@ -89,7 +86,7 @@ impl Topology { let relay_b = produce_origin(3); let subscriber = produce_origin(4); - let broadcast = publisher.create_broadcast(LIVE).unwrap(); + let broadcast = publisher.create_broadcast("live").unwrap(); let track = broadcast.create_track("video", None).unwrap(); broadcast.announce(Default::default()).unwrap(); @@ -98,8 +95,18 @@ impl Topology { let a_to_r = link(version, &relay_a, &subscriber).await; let consumer = subscriber.consume(); - consumer.routed(LIVE).await.unwrap(); - let remote = consumer.request_broadcast(LIVE).await.unwrap(); + consumer.routed("live").await.unwrap(); + let route = consumer.announced().next().await.unwrap(); + let moq_net::announce::Event::Start(route) = route else { + panic!("expected start") + }; + let remote = consumer + .request_broadcast(broadcast::Id { + path: "live".into(), + epoch: route.route.epoch, + }) + .await + .unwrap(); let prefs = track::Subscription::default().with_max_age(Duration::from_secs(60)); let sub = remote.track("video").unwrap().subscribe(prefs).await.unwrap(); @@ -338,9 +345,6 @@ route_change_tests! { lite_07: "moq-lite-07-wip", lite_06: "moq-lite-06", lite_05: "moq-lite-05", - lite_04: "moq-lite-04", - ietf_19: "moq-transport-19", - ietf_22: "moq-transport-22", } /// `P` feeds `A` slowly and `B` promptly, and `R` reads through `A` until that route dies @@ -357,8 +361,18 @@ async fn lagging_route_dies(version: Version) -> mpsc::UnboundedReceiver<(u64, m } async fn subscribe(origin: &origin::Producer) -> track::Subscriber { let consumer = origin.consume(); - consumer.routed(LIVE).await.unwrap(); - let remote = consumer.request_broadcast(LIVE).await.unwrap(); + consumer.routed("live").await.unwrap(); + let route = consumer.announced().next().await.unwrap(); + let moq_net::announce::Event::Start(route) = route else { + panic!("expected start") + }; + let remote = consumer + .request_broadcast(broadcast::Id { + path: "live".into(), + epoch: route.route.epoch, + }) + .await + .unwrap(); let preferences = track::Subscription::default().with_max_age(Duration::from_secs(60)); remote.track("video").unwrap().subscribe(preferences).await.unwrap() } @@ -374,7 +388,7 @@ async fn lagging_route_dies(version: Version) -> mpsc::UnboundedReceiver<(u64, m produce_origin(4), produce_origin(5), ); - let broadcast = p.create_broadcast(LIVE).unwrap(); + let broadcast = p.create_broadcast("live").unwrap(); let track = broadcast.create_track("video", None).unwrap(); broadcast.announce(Default::default()).unwrap(); let p_a = lagged(version, &p, &a, Duration::from_millis(300)).await; @@ -430,19 +444,38 @@ async fn lite_resumes_after_a_lagging_route_dies() { } } -/// Before draft 20 the resume rides a joining FETCH from group 1 through Largest, which -/// a moq-rs publisher refuses for spanning several groups, so the subscription joins -/// live instead. The rest of group 1 is still fetched on its own. +/// Unidentified routes end the subscription instead of joining a second route. #[moq_net_sim::test] -async fn an_older_ietf_draft_still_resumes_the_open_group() { - let version: Version = "moq-transport-19".parse().unwrap(); - let mut rx = lagging_route_dies(version).await; - assert_eq!(next(&mut rx).await, (1, payload(1, 2))); - assert_eq!(next(&mut rx).await, (1, payload(1, 3))); +async fn legacy_routes_do_not_resume() { + for version in ["moq-lite-04", "moq-transport-19", "moq-transport-22"] { + for trigger in [Trigger::Disconnect, Trigger::Unannounce] { + let (mut topology, mut sub) = Topology::new(version.parse().unwrap()).await; + topology.standby().await; + let mut group = topology.track.append_group().unwrap(); + group.write_frame(Timestamp::ZERO, b"before".as_ref()).unwrap(); + group.finish().unwrap(); + let mut received = sub.recv_group().await.unwrap().unwrap(); + assert_eq!( + received.read_frame().await.unwrap().unwrap().payload.as_ref(), + b"before" + ); + topology.trigger(trigger).await; + let mut group = topology.track.append_group().unwrap(); + group.write_frame(Timestamp::ZERO, b"after".as_ref()).unwrap(); + group.finish().unwrap(); + let next = moq_net_sim::timeout(TEST_TIMEOUT, sub.recv_group()) + .await + .expect("must terminate"); + assert!(!matches!(next, Ok(Some(_))), "{version} stitched an unidentified route"); + // The client can make a fresh request through the surviving route. + let remote = topology.subscriber.consume().request_broadcast("live").await.unwrap(); + let mut replacement = remote.track("video").unwrap().subscribe(None).await.unwrap(); + let mut received = replacement.recv_group().await.unwrap().unwrap(); + assert_eq!(received.read_frame().await.unwrap().unwrap().payload.as_ref(), b"after"); + } + } } -/// moq-transport 22 is left out: its relay fills a group's missing frames with a FETCH, -/// which draft 20+ does not serve yet (see `quest/m1/ietf-fetch-location.md`). macro_rules! route_flap_tests { ($($name:ident: $version:literal,)*) => { $( @@ -460,7 +493,4 @@ route_flap_tests! { flaps_lite_07: "moq-lite-07-wip", flaps_lite_06: "moq-lite-06", flaps_lite_05: "moq-lite-05", - flaps_lite_04: "moq-lite-04", - flaps_ietf_19: "moq-transport-19", - flaps_ietf_22: "moq-transport-22", } diff --git a/rs/moq-relay/tests/auth_embedder.rs b/rs/moq-relay/tests/auth_embedder.rs index 471be2bae42..6c295340a93 100644 --- a/rs/moq-relay/tests/auth_embedder.rs +++ b/rs/moq-relay/tests/auth_embedder.rs @@ -147,49 +147,3 @@ async fn a_moved_gateway_tier_retags_its_stats() { assert_eq!(active("gateway"), 0); work.abort(); } - -/// Admit one session holding `grant` for both roles. -async fn admit_both(cluster: &cluster::Cluster, grant: Grant) -> cluster::Admitted { - let (auth, mut admissions) = auth::Auth::embedded("edge"); - tokio::spawn(async move { - let admission = admissions.next().await.unwrap(); - admission.grant(lease::Consumer::fixed(grant)); - }); - cluster - .admit(&auth, auth.request(Transport::Rtmp, "/room")) - .await - .unwrap() -} - -#[tokio::test] -async fn an_exact_grant_admits_the_names_epochs_and_no_further() { - const OLD: &str = "room/alice/@0199b7f4-3c2a-7d1e-9f0b-2b6c1a9d8e7f"; - const NEW: &str = "room/alice/@0199b7f4-3c2b-7d1e-9f0b-2b6c1a9d8e7f"; - let cluster = cluster::Cluster::new(cluster::Options::default()).unwrap(); - - let name = admit_both( - &cluster, - Grant::new(patterns(&["room/alice"]), patterns(&["room/alice"])), - ) - .await; - let publisher = name.publisher.as_ref().unwrap(); - let _old = publisher.publish(OLD, moq_net::origin::Route::default()).unwrap(); - assert!(matches!( - publisher.publish("room/alice/cam", moq_net::origin::Route::default()), - Err(moq_net::Error::Unauthorized) - )); - let subscriber = name.subscriber.as_ref().unwrap(); - subscriber.request_broadcast("room/alice").await.unwrap(); - subscriber.request_broadcast(OLD).await.unwrap(); - - // A grant on one epoch reaches that epoch only. - let one = admit_both(&cluster, Grant::new(Patterns::new(), patterns(&[OLD]))).await; - let subscriber = one.subscriber.as_ref().unwrap(); - subscriber.request_broadcast(OLD).await.unwrap(); - for path in ["room/alice", NEW] { - assert!(matches!( - subscriber.request_broadcast(path).await, - Err(moq_net::Error::Unauthorized) - )); - } -} diff --git a/rs/moq-relay/tests/goaway_cluster.rs b/rs/moq-relay/tests/goaway_cluster.rs index 97d0294ef02..4c73f261dec 100644 --- a/rs/moq-relay/tests/goaway_cluster.rs +++ b/rs/moq-relay/tests/goaway_cluster.rs @@ -726,16 +726,18 @@ async fn collect_group(sub: &mut moq_net::track::Subscriber, seen: &mut BTreeSet } /// An empty-URI GOAWAY ("reconnect to me") makes the cluster redial the same -/// endpoint. The broadcast names an epoch, so the subscription through the drained -/// session re-splices onto the redial and keeps delivering. +/// endpoint. Both sessions' routes name the same first hop, so the subscription +/// through the drained session re-splices onto the redial and keeps delivering. async fn cluster_reconnects_on_empty_uri_goaway_inner() { let _ = rustls::crypto::aws_lc_rs::default_provider().install_default(); let upstream_origin = moq_tokio::origin::spawn(); - // Only an epoch path resumes across sessions. - let cam = moq_net::Path::new("cam").mint_epoch(); - let broadcast = upstream_origin.create_broadcast(&cam).expect("create broadcast"); + let broadcast = upstream_origin.create_broadcast("cam").expect("create broadcast"); broadcast.announce(Default::default()).expect("create broadcast"); + let id = moq_net::broadcast::Id { + path: "cam".into(), + epoch: broadcast.info().epoch.clone(), + }; let track = broadcast.create_track("video", None).expect("create track"); let (port, mut accepted, _handle) = spawn_upstream(upstream_origin.clone()).await; @@ -761,8 +763,8 @@ async fn cluster_reconnects_on_empty_uri_goaway_inner() { // Downstream consumer sees group 0 through the first session. let bc = within("broadcast announced", async { let consumer = cluster.origin.consume(); - consumer.routed(&cam).await?; - consumer.request_broadcast(&cam).await.ok() + consumer.routed("cam").await?; + consumer.request_broadcast(id).await.ok() }) .await .expect("broadcast announced"); diff --git a/rs/moq-tokio/tests/broadcast.rs b/rs/moq-tokio/tests/broadcast.rs index 8a27e406da5..8fa4ee09960 100644 --- a/rs/moq-tokio/tests/broadcast.rs +++ b/rs/moq-tokio/tests/broadcast.rs @@ -991,13 +991,12 @@ async fn read_payloads(sub: &mut moq_net::track::Subscriber, count: usize) -> Ve /// The client connects to two servers announcing the same route. The preferred /// (cheaper) route serves the track; when that session dies, the broadcast /// re-splices through the standby at a group boundary, without the path ever -/// being retracted: the path names an epoch, so both routes serve one origin -/// reached different ways and the subscription rides the failover. +/// being retracted: both routes name the same first hop, so they are the same +/// origin reached different ways and the subscription rides the failover. #[tracing_test::traced_test] #[tokio::test] async fn broadcast_route_migration() { - // Only an epoch path resumes across sessions. - let path = moq_net::Path::new("test").mint_epoch(); + let id = moq_net::broadcast::Id::from("test").with_epoch(moq_net::Epoch::mint()); use moq_net::Timestamp; let publisher = Hop::new(0x42).unwrap(); @@ -1006,7 +1005,7 @@ async fn broadcast_route_migration() { let origin_a = moq_tokio::origin::spawn(); let mut hops_a = moq_net::Hops::new(); hops_a.push(publisher).unwrap(); - let broadcast_a = origin_a.create_broadcast(&path).expect("create broadcast"); + let broadcast_a = origin_a.create_broadcast(id.clone()).expect("create broadcast"); broadcast_a .announce(moq_net::origin::Route::default().with_hops(hops_a).with_cost(1)) .expect("announce"); @@ -1026,7 +1025,7 @@ async fn broadcast_route_migration() { let mut hops_b = moq_net::Hops::new(); hops_b.push(publisher).unwrap(); hops_b.push(Hop::new(0x1234).unwrap()).unwrap(); - let broadcast_b = origin_b.create_broadcast(&path).expect("create broadcast"); + let broadcast_b = origin_b.create_broadcast(id.clone()).expect("create broadcast"); broadcast_b .announce(moq_net::origin::Route::default().with_hops(hops_b).with_cost(2)) .expect("announce"); @@ -1100,14 +1099,14 @@ async fn broadcast_route_migration() { // One path, announced once even though two sessions route it (the cheaper // route wins the advertisement). let (update, active) = next_announce(&mut announcements).await; - assert_eq!(update.prefix, path); + assert_eq!(update.prefix.as_str(), "test"); assert!(active, "expected announce"); // Resolve and subscribe: the cheaper route (A) serves the track. let subscription = moq_net::track::Subscription::default() .with_start(moq_net::track::Position::group(1)) .with_max_age(Duration::from_secs(10)); - let broadcast = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast(&path)) + let broadcast = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast(id.clone())) .await .expect("request timeout") .expect("routed broadcast resolves");