diff --git a/doc/concept/hang.md b/doc/concept/hang.md index 879ddf0bffe..e61b2a71d30 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -65,6 +65,7 @@ A few things the catalog can express beyond decoder config: - **Labels.** Any rendition may carry a human-readable `label` for a track picker. The map key stays the rendition's ID, so labels need not be unique and renaming one doesn't rename the track. - **Renditions in another broadcast.** A rendition may point at a relative broadcast path, so a transcoder can publish a ladder that adds low rungs and references the source's original rendition without re-publishing its bytes. The path resolves against where the consumer found the catalog, so a reference that escapes above the root names nothing and the catalog is rejected. A consumer reads each referenced path from the first broadcast it resolves there. An optional `epoch` beside the path names the [publisher instance](/concept/moq-lite#publisher-epochs) it expects: a route proving another instance fails the rendition instead of falling back to it, while a route without an epoch (an older version) cannot prove one, so there it is best effort. - **Track names.** The map key is a rendition's ID and, by default, its track name. A rendition sets `track` only when the two must differ, such as two renditions of same-named tracks in different broadcasts, or a rendition whose media changed and so needs a new name; readers subscribe to `track` when present. An ID can't name both a video and an audio rendition. +- **Whole contributions.** A catalog can list relative broadcast references without fetching their catalogs. Explicit selection opens a contribution, which resolves like a rendition's reference, including its optional `epoch`. Its rendition names remain separate from the source. `@moq/watch` exposes this as a scoped child broadcast, and listing contributions alone never starts their media producers. - **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. - **Disabled renditions.** An audio or video rendition with `enabled: false` has no frames coming, and a player must not select it. Pausing a rendition in `@moq/publish` keeps it in the catalog this way rather than removing it, so a mute is a one-field update; a disabled video rendition encodes one black keyframe first, so a player that predates the field shows black instead of a frozen picture. The field is written only when false. The older video `stalled` field is no longer written, and readers ignore it. diff --git a/drafts/draft-lcurley-moq-hang.md b/drafts/draft-lcurley-moq-hang.md index 7fc74faa1fc..e1bc528e7d1 100644 --- a/drafts/draft-lcurley-moq-hang.md +++ b/drafts/draft-lcurley-moq-hang.md @@ -123,6 +123,10 @@ The root of the catalog is a JSON document with the following schema: ~~~ type Catalog = { + "contributions": Record | undefined, "audio": AudioSchema | undefined, "video": VideoSchema | undefined, "archive": ArchiveSchema | undefined, @@ -144,6 +148,17 @@ The `json` and `binary` sections ({{data}}) are how a track like that is listed. This specification defines audio, video, and text media tracks, plus an optional `archive` entry ({{archive-catalog}}) naming the timeline track ({{timeline}}) that indexes each track, an optional root `clock` entry ({{clock}}) mapping content time to wall time, and the application data tracks in {{data}}. +## Contributions {#contributions} +The optional `contributions` map names whole broadcasts whose catalogs describe their renditions. +Each entry MUST contain a string `broadcast`, resolved relative to this catalog's broadcast using {{field-broadcast}}, and MAY contain an `epoch` using {{field-epoch}}. +A malformed entry or a reference escaping the root MUST cause the catalog to be rejected. + +Listing an entry MUST NOT subscribe to the contribution; a consumer opens its catalog only upon explicit selection. +A selected contribution resolves like a rendition's reference, under the same rules for `epoch` and restarts ({{field-epoch}}). +A contribution's rendition identifiers belong to that contribution and MUST NOT replace identifiers in the referring catalog. +An unavailable contribution does not invalidate the referring catalog. +References are not recursively expanded: each further contribution requires an explicit selection. + ## Clock {#clock} The catalog's root `clock` field is the broadcast's one continuous clock: @@ -1168,6 +1183,8 @@ This document has no IANA actions. - Specified conversion between relative broadcast references and MSF track namespaces without changing track identity, reading a namespace aligned with the catalog path's trailing segments as the catalog itself. - Added optional audio and video `warmup` durations, rounded up to whole milliseconds, and allowed video groups to start at convergent random access pictures. +- Added optional whole-broadcast `contributions` with explicit lazy selection and scoped rendition identifiers. + - Defined encoder `jitter` as flush lateness above the rendition's own recent minimum, replacing fixed frame-duration hints; container batches retain media-span estimates. - Timed CMAF samples from the frame timestamp, which is the fragment's earliest presentation time; `tfdt` is only relative within the fragment, and places the samples of an untimed frame. A timed CMAF track counts in its `mdhd` ticks. - Allowed a DVR to delete timeline objects no checkpoint recovery needs, oldest first. diff --git a/js/hang/src/catalog/root.test.ts b/js/hang/src/catalog/root.test.ts index 15e96a3dddc..e4800dbf3d1 100644 --- a/js/hang/src/catalog/root.test.ts +++ b/js/hang/src/catalog/root.test.ts @@ -49,6 +49,7 @@ test("rendition broadcast reference is parsed and normalized", () => { test("every reference-bearing section carries an optional epoch", () => { const EPOCH = "01890a5d-ac96-774b-bcce-b302099a8057" as ReferenceEpoch; const catalog = (epoch: string) => ({ + contributions: { c: { broadcast: "./a", epoch } }, video: { renditions: { v: { broadcast: "./a", epoch, codec: "avc1.64001f", container: { kind: "legacy" } }, @@ -81,6 +82,7 @@ test("every reference-bearing section carries an optional epoch", () => { expect(parsed.json?.tracks.j?.epoch).toBe(EPOCH); expect(parsed.binary?.tracks.b?.epoch).toBe(EPOCH); expect(parsed.archive?.replayEpoch).toBe(EPOCH); + expect(parsed.contributions?.c?.epoch).toBe(EPOCH); // A malformed or noncanonical epoch refuses the catalog, as in Rust. for (const bad of ["not-a-uuid", EPOCH.toUpperCase(), "01890a5d-ac96-474b-bcce-b302099a8057"]) { diff --git a/js/hang/src/catalog/root.ts b/js/hang/src/catalog/root.ts index d8e7c459ee9..bb8d24d38f6 100644 --- a/js/hang/src/catalog/root.ts +++ b/js/hang/src/catalog/root.ts @@ -8,7 +8,7 @@ import { BinarySchema } from "./binary"; import { ClockSchema } from "./clock"; import { TRACK } from "./format"; import { JsonSchema } from "./json"; -import type { RelativeBroadcast } from "./path"; +import { EpochSchema, type RelativeBroadcast, RelativeBroadcastSchema } from "./path"; import { PRIORITY } from "./priority"; import { section } from "./section"; import { TextSchema } from "./text"; @@ -20,7 +20,7 @@ import { VideoSchema } from "./video"; * The media sections are `video`, `audio`, and `text`, alongside the broadcast's `archive` * (the segment index and any durable recording) and its `clock` (the one wall-clock mapping); * `json` and `binary` list application data tracks that aren't media. A section is omitted - * when it holds no tracks. + * when it holds no tracks. `contributions` lists whole broadcasts without opening them. * * This is a *loose* object: unknown root sections pass through validation untouched, so an * application can add its own sections (e.g. `scte35`) without modifying hang. A base consumer @@ -28,6 +28,10 @@ import { VideoSchema } from "./video"; * built via `z.extend(RootSchema, { ... })`. */ export const RootSchema = z.looseObject({ + // Whole broadcasts are listed without opening their catalogs. IDs stay scoped to each broadcast. + contributions: z.optional( + z.record(z.string(), z.object({ broadcast: RelativeBroadcastSchema, epoch: z.optional(EpochSchema) })), + ), video: z.optional(VideoSchema), audio: z.optional(AudioSchema), // An incompatible archive disables seeking/recording, not the rest of the catalog. @@ -108,6 +112,7 @@ export function checkResolvable(root: Root, base: Moq.Path.Valid): Root { root.text?.renditions, root.json?.tracks, root.binary?.tracks, + root.contributions, ]; for (const section of sections) { for (const { broadcast } of Object.values(section ?? {})) { diff --git a/js/watch/src/broadcast.ts b/js/watch/src/broadcast.ts index 5a0f9ab8a26..be3a14df7bd 100644 --- a/js/watch/src/broadcast.ts +++ b/js/watch/src/broadcast.ts @@ -3,7 +3,7 @@ import * as Json from "@moq/json"; import * as Msf from "@moq/msf"; import type * as Moq from "@moq/net"; import { Error as NetError, Path, StreamCode } from "@moq/net"; -import { Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals"; +import { Derived, Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals"; import { toHang } from "./msf"; @@ -152,6 +152,10 @@ export class Broadcast { // strands the filtered copy on the previous contents. readonly #raw = new Signal(undefined); + // Set only on a contribution: its broadcast resolves through the parent catalog's references, + // so the two never resolve one path independently. + readonly #resolve = new Signal<((effect: Effect) => Moq.Broadcast.Consumer | undefined) | undefined>(undefined); + #signals: Effect; constructor(props?: Inputs) { @@ -244,6 +248,12 @@ export class Broadcast { const enabled = effect.get(this.in.enabled); if (!enabled) return; + const resolve = effect.get(this.#resolve); + if (resolve) { + effect.set(this.#out.active, resolve(effect), undefined); + return; + } + const origin = effect.get(this.in.origin); if (!origin) return; @@ -436,6 +446,52 @@ export class Broadcast { return this.#requestBroadcast(effect, origin, target.path); } + /** + * Select a whole contribution, opening its catalog only while the caller owns this effect. + * The child tracks the catalog entry and resolves like a rendition's reference (see + * `relativeBroadcast`): without an `epoch` it follows restarts, and with one it is offline + * while its broadcast proves another instance. An absent entry leaves the child disabled. + * Wire the returned broadcast into a media source inside a nested effect. Its rendition + * IDs stay local to that broadcast, so they never replace the parent catalog's IDs. + * + * ```ts + * effects.run((effect) => { + * const child = broadcast.contribution(effect, "extra"); + * const source = new Video.Source({ broadcast: child, supported: Video.Decoder.supported }); + * effect.cleanup(() => source.close()); + * const decoder = new Video.Decoder({ source, sync }); + * effect.cleanup(() => decoder.close()); + * // Feed decoder.out.frame into your renderer. + * }); + * ``` + */ + contribution(effect: Effect, id: string): Broadcast { + // Each computed only notifies on a real change, so an update that leaves the child's path + // alone (such as a new `epoch`) never restarts its catalog. + const entry = effect.computed((run) => { + const contributions = run.get(this.out.catalog)?.contributions; + return contributions && Object.hasOwn(contributions, id) ? contributions[id] : undefined; + }); + const name = effect.computed((run) => { + // An empty reference is present: it names the catalog's own broadcast. + const selected = run.get(entry); + return selected && Path.tryResolve(run.get(this.in.name), selected.broadcast); + }); + const enabled = effect.computed((run) => run.get(entry) !== undefined); + const child = new Broadcast({ + origin: this.in.origin, + name: new Derived([name], (name) => name ?? Path.empty()), + enabled: new Derived([enabled], (enabled) => enabled === true), + announced: this.in.announced, + }); + child.#resolve.set((run) => { + const selected = run.get(entry); + return selected && this.relativeBroadcast(run, selected.broadcast, selected.epoch); + }); + effect.cleanup(() => child.close()); + return child; + } + close() { this.#signals.close(); for (const entry of this.#references.values()) entry.request.close(); diff --git a/js/watch/src/contribution.test.ts b/js/watch/src/contribution.test.ts new file mode 100644 index 00000000000..1cdedbdcb05 --- /dev/null +++ b/js/watch/src/contribution.test.ts @@ -0,0 +1,330 @@ +import { expect, it } from "bun:test"; +import * as Catalog from "@moq/hang/catalog"; +import { Epoch, Origin, Path } from "@moq/net"; +import { Effect, Signal } from "@moq/signals"; +import { Broadcast } from "./broadcast"; +import { Source } from "./video/source"; + +it("lists contributions without demand and keeps selected rendition IDs in their own broadcast", async () => { + const origin = new Origin.Producer(); + const parent = origin.createBroadcast(Path.from("room/main.hang")); + const contribution = origin.createBroadcast(Path.from("room/extra.hang")); + parent.announce(); + contribution.announce(); + const track = contribution.createTrack(Catalog.TRACK); + const catalog = Catalog.RootSchema.parse({ + video: { renditions: { video: { codec: "avc1.42001f", container: { kind: "legacy" } } } }, + contributions: { extra: { broadcast: "./extra.hang" }, missing: { broadcast: "./absent.hang" } }, + }); + const source = new Broadcast({ + origin, + name: Path.from("room/main.hang"), + catalogFormat: "manual", + catalog, + announced: false, + }); + const selection = new Effect(); + for (const [publisher, content] of [ + [parent, "source frames"], + [contribution, "contribution frames"], + ] as const) { + publisher.createTrack("video").writeFrame({ payload: new TextEncoder().encode(content) }); + } + try { + await source.out.catalog.changed(); + expect(source.out.catalog.peek()?.contributions).toEqual(catalog.contributions); + // Listing the reference does not subscribe to its existing catalog track. + expect(contribution.demand().used.peek()).toBe(false); + const child = source.contribution(selection, "extra"); + expect(child).toBeDefined(); + if (!child) throw new Error("missing selected contribution"); + await contribution.demand().used.changed(); + expect(contribution.demand().used.peek()).toBe(true); + track.writeFrame({ + timestamp: undefined, + payload: new TextEncoder().encode( + JSON.stringify({ + video: { renditions: { video: { codec: "vp8", container: { kind: "legacy" } } } }, + }), + ), + }); + await child.out.catalog.changed(); + expect(child.out.catalog.peek()?.video?.renditions.video.codec).toBe("vp8"); + expect(source.out.catalog.peek()?.video?.renditions.video.codec).toBe("avc1.42001f"); + const media = new Source({ broadcast: child, target: { name: "video" }, supported: async () => true }); + selection.cleanup(() => media.close()); + await media.out.config.changed(); + expect(media.out.track.peek()).toBe("video"); + const selected = child.relativeBroadcast(selection, media.out.config.peek()?.broadcast); + const frames = selected + ?.track(media.out.track.peek() ?? "") + .subscribe() + .ordered(); + const original = source.relativeBroadcast(selection, undefined)?.track("video").subscribe().ordered(); + try { + expect(await frames?.readString()).toBe("contribution frames"); + expect(await original?.readString()).toBe("source frames"); + } finally { + frames?.close(); + original?.close(); + } + expect(source.contribution(selection, "unknown").in.enabled.peek()).toBe(false); + const absent = origin.dynamic(Path.from("room/absent.hang")); + selection.cleanup(() => absent.close()); + const requests = absent.requested(); + const missing = source.contribution(selection, "missing"); + if (!missing) throw new Error("missing contribution selection"); + const { value: request } = await requests.next(); + expect(request?.path).toBe(Path.from("room/absent.hang")); + request?.reject(new Error("contribution unavailable")); + await settle(); + // Like a rendition's reference, an unavailable contribution is offline. + expect(missing.out.active.peek()).toBeUndefined(); + expect(missing.out.status.peek()).toBe("offline"); + expect(source.out.catalog.peek()?.video?.renditions.video.codec).toBe("avc1.42001f"); + selection.close(); + await contribution.demand().unused(); + expect(contribution.demand().used.peek()).toBe(false); + } finally { + selection.close(); + source.close(); + origin.close(); + } +}); + +it("refuses malformed and escaping contribution entries", () => { + for (const entry of [null, {}, { broadcast: 42 }, { broadcast: "./extra.hang", epoch: "not-an-epoch" }]) { + expect(() => Catalog.RootSchema.parse({ contributions: { extra: entry } })).toThrow(); + } + const catalog = Catalog.RootSchema.parse({ contributions: { extra: { broadcast: "../../escape" } } }); + expect(() => Catalog.checkResolvable(catalog, Path.from("room/main.hang"))).toThrow(Catalog.EscapingBroadcast); +}); + +const settle = async (): Promise => { + for (let i = 0; i < 5; i++) await new Promise((resolve) => setTimeout(resolve, 0)); +}; + +async function quietly(fn: () => Promise): Promise { + const warn = console.warn; + console.warn = () => {}; + try { + return await fn(); + } finally { + console.warn = warn; + } +} + +it("tracks the contribution entry without reopening it on unrelated catalog updates", async () => { + const origin = new Origin.Producer(); + const main = origin.createBroadcast(Path.from("room/main.hang")); + main.announce(); + const first = origin.createBroadcast(Path.from("room/first.hang")); + const second = origin.createBroadcast(Path.from("room/second.hang")); + for (const publisher of [first, second]) { + publisher.announce(); + publisher.createTrack(Catalog.TRACK).writeFrame({ payload: new TextEncoder().encode("{}") }); + } + const catalog = new Signal(Catalog.RootSchema.parse({ contributions: { extra: { broadcast: "./first.hang" } } })); + const parent = new Broadcast({ + origin, + name: Path.from("room/main.hang"), + catalogFormat: "manual", + catalog, + announced: false, + }); + const owner = new Effect(); + try { + const child = parent.contribution(owner, "extra"); + await child.out.catalog.changed(); + const active = child.out.active.peek(); + expect(active?.path).toBe(Path.from("room/first.hang")); + + // An update that leaves the entry alone keeps the same request. + let withdrawals = 0; + owner.cleanup( + first.demand().used.subscribe((used) => { + if (!used) withdrawals += 1; + }), + ); + catalog.set( + Catalog.RootSchema.parse({ + contributions: { extra: { broadcast: "./first.hang" }, other: { broadcast: "./other.hang" } }, + metadata: "changed", + }), + ); + await settle(); + expect(child.out.active.peek()).toBe(active); + expect(withdrawals).toBe(0); + + // A changed path is a different reference, so the child follows it. + catalog.set(Catalog.RootSchema.parse({ contributions: { extra: { broadcast: "./second.hang" } } })); + await settle(); + expect(child.out.active.peek()?.path).toBe(Path.from("room/second.hang")); + + // Removing the entry disables the child. + catalog.set(Catalog.RootSchema.parse({})); + await settle(); + expect(child.in.enabled.peek()).toBe(false); + expect(child.out.active.peek()).toBeUndefined(); + } finally { + owner.close(); + parent.close(); + origin.close(); + } +}); + +it("follows a restarted contribution only for an entry that names no epoch", async () => { + const origin = new Origin.Producer(); + const main = origin.createBroadcast(Path.from("room/main.hang")); + main.announce(); + const [oldEpoch, newEpoch] = [Epoch.mint(), Epoch.mint()]; + const old = origin.createBroadcast(Path.from("room/extra.hang")); + old.announce({ epoch: oldEpoch }); + const parent = new Broadcast({ + origin, + name: Path.from("room/main.hang"), + catalogFormat: "manual", + catalog: Catalog.RootSchema.parse({ + contributions: { + following: { broadcast: "./extra.hang" }, + pinned: { broadcast: "./extra.hang", epoch: oldEpoch }, + }, + }), + }); + const owner = new Effect(); + try { + const following = parent.contribution(owner, "following"); + const pinned = parent.contribution(owner, "pinned"); + await settle(); + expect(following.out.active.peek()?.epoch).toBe(oldEpoch); + expect(pinned.out.active.peek()?.epoch).toBe(oldEpoch); + + // The announcement is the online signal: the plain entry follows the restart, while the + // one naming the old instance goes offline rather than reading the new one. + const replacement = origin.createBroadcast(Path.from("room/extra.hang")); + replacement.announce({ epoch: newEpoch }); + await quietly(settle); + expect(following.out.active.peek()?.epoch).toBe(newEpoch); + expect(pinned.out.active.peek()).toBeUndefined(); + expect(pinned.out.status.peek()).toBe("offline"); + replacement.close(); + } finally { + owner.close(); + parent.close(); + old.close(); + origin.close(); + } +}); + +it("never reads a contribution proven to be another epoch, but reads an epochless route", async () => { + const origin = new Origin.Producer(); + const main = origin.createBroadcast(Path.from("room/main.hang")); + main.announce(); + const served = Epoch.mint(); + const proven = origin.createBroadcast(Path.from("room/proven.hang")); + proven.announce({ epoch: served }); + const track = proven.createTrack(Catalog.TRACK); + const plain = origin.createBroadcast(Path.from("room/plain.hang")); + plain.announce(); + plain.createTrack(Catalog.TRACK).writeFrame({ payload: new TextEncoder().encode("{}") }); + const named = Epoch.mint(); + const contributions = (epoch: Epoch.Valid) => + Catalog.RootSchema.parse({ + contributions: { + proven: { broadcast: "./proven.hang", epoch }, + plain: { broadcast: "./plain.hang", epoch: named }, + }, + }); + const catalog = new Signal(contributions(named)); + const parent = new Broadcast({ + origin, + name: Path.from("room/main.hang"), + catalogFormat: "manual", + catalog, + announced: false, + }); + const owner = new Effect(); + try { + const refused = parent.contribution(owner, "proven"); + const accepted = parent.contribution(owner, "plain"); + await quietly(settle); + expect(refused.out.active.peek()).toBeUndefined(); + expect(refused.out.error.peek()).toBeUndefined(); + expect(track.demand().used.peek()).toBe(false); + // An epochless route cannot prove its instance, so the epoch cannot refuse it. + expect(accepted.out.active.peek()?.path).toBe(Path.from("room/plain.hang")); + + // A catalog update naming the served epoch admits the instance the request already holds. + catalog.set(contributions(served)); + await settle(); + expect(refused.out.active.peek()?.epoch).toBe(served); + } finally { + owner.close(); + parent.close(); + origin.close(); + } +}); + +it("shares the parent's resolution, so a new epoch checks the held handle", async () => { + const origin = new Origin.Producer(); + const [served, other] = [Epoch.mint(), Epoch.mint()]; + const main = origin.createBroadcast(Path.from("room/main.hang")); + main.announce({ epoch: served }); + const extra = origin.createBroadcast(Path.from("room/extra.hang")); + extra.announce({ epoch: served }); + const entries = (epoch?: Epoch.Valid) => + Catalog.RootSchema.parse({ + contributions: { + sibling: { broadcast: "./extra.hang", epoch }, + self: { broadcast: "./main.hang", epoch }, + empty: { broadcast: "", epoch }, + }, + }); + const catalog = new Signal(entries()); + const parent = new Broadcast({ + origin, + name: Path.from("room/main.hang"), + catalogFormat: "manual", + catalog, + announced: false, + }); + const owner = new Effect(); + try { + const sibling = parent.contribution(owner, "sibling"); + const self = parent.contribution(owner, "self"); + await settle(); + const held = sibling.out.active.peek(); + expect(held?.epoch).toBe(served); + // A self-reference is the parent's own handle, not a request of its own. An empty one is + // too, and is named like the parent, so its own references resolve against the same base. + expect(self.out.active.peek()).toBe(parent.out.active.peek()); + const empty = parent.contribution(owner, "empty"); + await settle(); + expect(empty.in.name.peek()).toBe(Path.from("room/main.hang")); + expect(empty.in.enabled.peek()).toBe(true); + + let withdrawals = 0; + owner.cleanup( + extra.demand().used.subscribe((used) => { + if (!used) withdrawals += 1; + }), + ); + + // Naming the held instance keeps the same handle rather than resolving the path again. + catalog.set(entries(served)); + await settle(); + expect(sibling.out.active.peek()).toBe(held); + expect(self.out.active.peek()).toBe(parent.out.active.peek()); + expect(withdrawals).toBe(0); + + // Naming another instance fails the held one. + catalog.set(entries(other)); + await quietly(settle); + expect(sibling.out.active.peek()).toBeUndefined(); + expect(self.out.active.peek()).toBeUndefined(); + } finally { + owner.close(); + parent.close(); + origin.close(); + } +}); diff --git a/rs/hang/src/catalog/consumer.rs b/rs/hang/src/catalog/consumer.rs index aa67dd7c70a..53d82cc1633 100644 --- a/rs/hang/src/catalog/consumer.rs +++ b/rs/hang/src/catalog/consumer.rs @@ -66,6 +66,7 @@ fn check_resolvable(base: &PathOwned, catalog: &Catalog) -> Result<()> { .chain(text.map(|(_, config)| config.broadcast.as_ref())) .chain(json.map(|(_, config)| config.broadcast.as_ref())) .chain(binary.map(|(_, config)| config.broadcast.as_ref())) + .chain(catalog.contributions.values().map(|entry| Some(&entry.broadcast))) .flatten() { if !rel.is_empty() && base.try_resolve(rel).is_none() { @@ -80,6 +81,12 @@ fn check_resolvable(base: &PathOwned, catalog: &Catalog) -> Result<()> { mod test { use super::*; + #[test] + fn contributions_cannot_escape_the_root() { + let catalog = Catalog::<()>::from_str(r#"{"contributions":{"extra":{"broadcast":"../../escape"}}}"#).unwrap(); + assert!(check_resolvable(&PathOwned::from("room/main.hang"), &catalog).is_err()); + } + #[tokio::test] async fn subscribe_reads_a_typed_root() { let broadcast = moq_net::broadcast::Info::new().produce(); diff --git a/rs/hang/src/catalog/root.rs b/rs/hang/src/catalog/root.rs index 3698856fbb2..ea6c1c5a3b5 100644 --- a/rs/hang/src/catalog/root.rs +++ b/rs/hang/src/catalog/root.rs @@ -13,7 +13,7 @@ use serde::{Deserialize, Serialize}; /// `archive` (each track's timeline and any durable recording), the optional `clock` (the /// broadcast's one wall-clock mapping), the data sections /// (`json`, `binary`) for application tracks that aren't media, and the optional `m2ts` (a -/// transport stream carried whole). +/// transport stream carried whole). `contributions` names whole broadcasts for explicit selection. /// Applications extend it with their own root sections (e.g. `scte35`) through `E`. The catalog /// does not deny unknown fields, so a base consumer ignores the extra sections and an extended /// catalog stays wire-compatible. See the `extension_roundtrip` test. @@ -29,6 +29,10 @@ use serde::{Deserialize, Serialize}; #[serde(bound(serialize = "E: Serialize", deserialize = "E: DeserializeOwned + Default"))] #[non_exhaustive] pub struct Catalog { + /// Whole broadcasts offered for explicit, lazy selection, keyed by contribution ID. + #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")] + pub contributions: std::collections::BTreeMap, + /// Video track information with multiple renditions. /// /// Contains a map of video track renditions that the viewer can choose from @@ -112,6 +116,30 @@ pub struct Catalog { pub ext: E, } +/// A whole broadcast whose catalog describes its own renditions. +/// +/// Marked `#[non_exhaustive]` so optional fields can be added later. External callers build one +/// with [`Contribution::new`]. +#[serde_with::serde_as] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] +#[non_exhaustive] +pub struct Contribution { + /// Reference resolved relative to the catalog broadcast. + pub broadcast: moq_net::path::RelativeOwned, + + /// The publisher instance the contribution names, with a rendition `epoch`'s meaning. + #[serde(default, skip_serializing_if = "Option::is_none")] + #[serde_as(as = "Option")] + pub epoch: Option, +} + +impl Contribution { + /// A contribution at `broadcast`, accepting whichever instance resolves. + pub fn new(broadcast: moq_net::path::RelativeOwned) -> Self { + Self { broadcast, epoch: None } + } +} + impl Catalog<()> { /// The default name for the catalog track. pub const DEFAULT_NAME: &str = "catalog.json"; @@ -167,6 +195,7 @@ impl Catalog { /// Copy the media sections into a catalog with no application extension. pub fn media(&self) -> Catalog<()> { Catalog { + contributions: self.contributions.clone(), video: self.video.clone(), audio: self.audio.clone(), archive: self.archive.clone(), @@ -303,6 +332,7 @@ mod test { const EPOCH: &str = "01890a5d-ac96-774b-bcce-b302099a8057"; let encoded = format!( r#"{{ + "contributions": {{"c": {{"broadcast": "./a", "epoch": "{EPOCH}"}}}}, "video": {{"renditions": {{"v": {{"broadcast": "./a", "epoch": "{EPOCH}", "codec": "avc1.64001f", "container": {{"kind": "legacy"}}}}}}}}, "audio": {{"renditions": {{"a": {{"broadcast": "./a", "epoch": "{EPOCH}", "codec": "opus", "sampleRate": 48000, "numberOfChannels": 2, "container": {{"kind": "legacy"}}}}}}}}, "text": {{"renditions": {{"t": {{"broadcast": "./a", "epoch": "{EPOCH}", "format": "vtt"}}}}}}, @@ -323,7 +353,8 @@ mod test { for reference in references { assert_eq!(reference.epoch(), Some(&epoch)); } - assert_eq!(catalog.archive.as_ref().unwrap().replay_epoch, Some(epoch)); + assert_eq!(catalog.archive.as_ref().unwrap().replay_epoch.as_ref(), Some(&epoch)); + assert_eq!(catalog.contributions["c"].epoch.as_ref(), Some(&epoch)); assert_eq!(Catalog::<()>::from_str(&catalog.to_json().unwrap()).unwrap(), catalog); // Omitted stays omitted, and a malformed or noncanonical epoch refuses the catalog. @@ -338,6 +369,26 @@ mod test { } } + #[test] + fn contributions_round_trip_and_refuse_malformed_entries() { + let json = r#"{"contributions":{"extra":{"broadcast":"./extra.hang","epoch":"01890a5d-ac96-774b-bcce-b302099a8057"}}}"#; + let catalog = Catalog::<()>::from_str(json).unwrap(); + assert_eq!(catalog.contributions["extra"].broadcast.as_str(), "extra.hang"); + assert_eq!( + catalog.contributions["extra"].epoch.as_ref().unwrap().to_string(), + "01890a5d-ac96-774b-bcce-b302099a8057" + ); + assert_eq!(Catalog::<()>::from_str(&catalog.to_json().unwrap()).unwrap(), catalog); + for json in [ + r#"{"contributions":{"extra":null}}"#, + r#"{"contributions":{"extra":{}}}"#, + r#"{"contributions":{"extra":{"broadcast":42}}}"#, + r#"{"contributions":{"extra":{"broadcast":"./extra.hang","epoch":"not-an-epoch"}}}"#, + ] { + assert!(Catalog::<()>::from_str(json).is_err()); + } + } + #[test] fn cross_kind_duplicate_id_is_refused() { let catalog = Catalog::<()>::from_str(