diff --git a/doc/bin/hls.md b/doc/bin/hls.md index 33f088adec9..4615307572b 100644 --- a/doc/bin/hls.md +++ b/doc/bin/hls.md @@ -56,7 +56,7 @@ What that means for you: - **The publisher declares the interval.** Only a broadcast whose catalog carries `media.join.interval` gets playlists. Rust publishers built on `moq-mux` (the CLI, the RTMP, SRT, and WebRTC gateways, and the native bindings) declare it: an encoder that knows its GOP passes it as a hint, and an ingest without one measures each track over its first second or group, whichever is longer, then declares the longest. `@moq/publish` declares its keyframe interval. - **Every rendition shares the grid.** A group spans from its first frame's timestamp to the next group's and belongs to the first grid line it contains, or, containing none, the line it starts after. Segment N therefore starts at the group containing N times the segment length, every rendition numbers its segments alike, and each cuts its boundaries at its own keyframes. A grid line no group starts a segment at, because a GOP ran past it or the content paused, is listed as an `EXT-X-GAP` so the numbering never skips: on a 2 s grid, a GOP from 0 to 7 s is segment 0, segments 1 and 2 are gaps, and the next GOP starts segment 3. Timestamps that go back start a discontinuity on that rendition alone; `EXT-X-PROGRAM-DATE-TIME`, written after every discontinuity when the catalog has a clock, lets players resync. -- **Contribution media starts on selection.** The HTTP multivariant playlist reads each root `contributions` entry's catalog and lists its audio and video beside the broadcast's own. A contribution shares the broadcast's timeline: its renditions are segmented on the broadcast's join interval and clock, whatever its own catalog declares, so publish it on the same timestamps. One not yet routed is listed once its broadcast is announced. Reading its catalog starts no encoding: only a request to one of its rendition URLs subscribes to that rendition's media. Demand lasts through active responses and, after the last one finishes, for three target durations or the playlist window plus one target duration, whichever is longer (20 s by default); a later request starts it again. The broadcast's own renditions stay subscribed. A segment is servable for as long as the relay's [cache](/bin/relay/config#cache) retains it. Keep `--window` (the playlist length, default 16 s) within that retention and within the media's max age (30 s by default), after which a superseded segment's groups are stale. +- **Include media starts on selection.** The HTTP multivariant playlist reads each root `include` entry's catalog and lists its audio and video beside the broadcast's own. An include shares the broadcast's timeline: its renditions are segmented on the broadcast's join interval and clock, whatever its own catalog declares, so publish it on the same timestamps. One not yet routed is listed once its broadcast is announced. Reading its catalog starts no encoding: only a request to one of its rendition URLs subscribes to that rendition's media. Demand lasts through active responses and, after the last one finishes, for three target durations or the playlist window plus one target duration, whichever is longer (20 s by default); a later request starts it again. The broadcast's own renditions stay subscribed. A segment is servable for as long as the relay's [cache](/bin/relay/config#cache) retains it. Keep `--window` (the playlist length, default 16 s) within that retention and within the media's max age (30 s by default), after which a superseded segment's groups are stale. - **Live joins cost the window.** The exporter subscribes 30 s behind the live edge and lists at most 256 segments. One joining partway through a segment lists nothing before the first segment it sees start. - **Segments are timed by the grid.** A segment is listed once a later one starts or the track ends. It starts at its first group's timestamp, or at its line when that group starts after it (as one resuming from a pause does), or a gap at its line, and lasts until the next segment starts, so a segment's bytes never change with a catalog estimate. A GOP longer than the segment is listed at its first line, so its duration understates its media. - **The target duration is twice the segment.** Every media playlist keeps one `EXT-X-TARGETDURATION` while its rendition stays in the catalog, even across a reconfigure: twice the segment length, rounded up to whole seconds (twice the interval for a GOP of a second or more, 2 s for 20 ms audio groups), since the GOP containing a grid line starts at most one interval before it, and a gap ends under two segment lengths after its line. Only a final GOP longer than that is listed past it, against RFC 8216's rule: hls.js plays it, but Apple's `mediastreamvalidator` flags it, so keep keyframe intervals within the declared interval. @@ -65,13 +65,13 @@ What that means for you: - **URLs name the stream.** Every URL the multivariant playlist and DASH manifest list sits under `@`, the stream's instance, so every edge and every reload derive the same URLs and a CDN in front of export caches them. A restarted publisher gets URLs of its own, whose numbering starts over. The multivariant playlist and manifest switch to it at once, while the old stream's playlists end at the segments they listed before the switch, even if its publisher keeps sending; a player already on it plays those out and then has to reload the multivariant playlist. A stream that reached export over moq-lite-06 or older, or moq-transport, has an instance its session minted, so only that export serves its URLs. - **Only a clean finish ends a playlist.** `EXT-X-ENDLIST` and a `static` DASH manifest mean the media tracks finished, or, on a replaced stream's media playlists, that another publisher took the broadcast over. A rendition whose media track fails instead, such as a publisher dropping its session, answers HTTP 500 with `Cache-Control: no-store`, so a truncated recording never looks complete, and leaves the multivariant playlist and DASH manifest so players switch to a sibling. With none left, the DASH manifest answers the error too. -Contribution URLs nest under the served broadcast's (see -[`Contribution`](https://docs.rs/moq-hls/latest/moq_hls/export/struct.Contribution.html)), so +Include URLs nest under the served broadcast's (see +[`Include`](https://docs.rs/moq-hls/latest/moq_hls/export/struct.Include.html)), so access middleware sees the parent broadcast's path, while the server resolves each -[contribution](/draft/moq-hang#contributions) through its own scoped origin and leaves out -one it may not read. They follow contribution restarts unless the entry pins an `instance`; -an unavailable contribution leaves the multivariant playlist until it returns. DASH and -`--output` include only the broadcast's own renditions; record a contribution as its own +[include](/draft/moq-hang#include) through its own scoped origin and leaves out +one it may not read. They follow include restarts unless the entry pins an `instance`; +an unavailable include leaves the multivariant playlist until it returns. DASH and +`--output` include only the broadcast's own renditions; record an include as its own broadcast. A [broadcast archive](/concept/archives) is served the same diff --git a/doc/concept/hang.md b/doc/concept/hang.md index a7b9e77fbd4..c8ec33f8394 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -63,7 +63,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. `@moq/watch` and `moqsrc` follow a referenced path's announcements like their own, restarting the rendition on each instance that serves it; every other reader, such as `moq play`, the exporters, and the bindings, waits for the first one announced and keeps it, and an exporter ends the rendition with it. An optional `instance` beside the path names the [stream](/concept/moq-lite#publisher-instances) it expects: a route of another instance ends the rendition instead of falling back to it, while a route whose instance a session minted (one that crossed an older version) cannot prove one, so there it is best effort. Omit `instance` for a broadcast produced on demand, which has none until a worker answers; see [identity and recovery](/concept/identity). -- **Whole contributions.** A root `contributions` map names whole broadcasts, such as each guest feed in a composed room, by the same relative path and optional `instance` as a rendition's reference. Listing one opens nothing, so a contribution produced on demand starts only once a viewer selects it, which `@moq/watch` does with `broadcast.contribution(effect, id)`. Its rendition IDs stay its own. +- **Whole includes.** A root `include` map names whole broadcasts, such as transcoded renditions of the source, by the same relative path and optional `instance` as a rendition's reference. They share the listing catalog's PTS timeline and root settings, including its clock and join interval. Listing one opens nothing, so an include produced on demand starts only once a viewer selects it, which `@moq/watch` does with `broadcast.include(effect, id)`. Its rendition IDs stay its own. - **Track names.** The map key is a rendition's ID and, by default, its track name. A rendition sets `track` only when the two must differ, such as two renditions of same-named tracks in different broadcasts, or a rendition whose media changed and so needs a new name; readers subscribe to `track` when present. An ID can't name both a video and an audio rendition. - **Jitter.** A rendition can say how much media it writes behind a frame's timestamp, in whole milliseconds rounded up: the reorder delay of B-frames and the span of a fragment or batch written together. It is measured from media timestamps alone, never the time a frame was written, so neither a constant encoder delay nor a capture clock counts. 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' timestamps trail those another rendition already wrote, so a video encoder running 200 ms behind audio advertises `delay: 200` on video. A rendition alone measures none. It follows the same rules as jitter. A player holds the largest `delay + jitter` among the renditions it subscribes to, and never subtracts one rendition's `delay` from another's. diff --git a/drafts/draft-lcurley-moq-hang.md b/drafts/draft-lcurley-moq-hang.md index c8cf35e9acd..11a905b72f8 100644 --- a/drafts/draft-lcurley-moq-hang.md +++ b/drafts/draft-lcurley-moq-hang.md @@ -156,7 +156,7 @@ type Catalog = { "text": TextSchema | undefined, "json": JsonTracks | undefined, "binary": BinaryTracks | undefined, - "contributions": Record | undefined, @@ -172,7 +172,7 @@ For example, a chat entry should name a chat track, not carry individual chat me This way catalog updates are rare and a client MAY choose to not subscribe. The `json` and `binary` sections ({{data}}) are how a track like that is listed. -This specification defines audio, video, and text media tracks, an optional `media` section ({{media}}) holding the clock that maps content time to wall time and the interval a viewer can join on, the root `version` ({{catalog-version}}), the application data tracks in {{data}}, optional publisher statistics and solicited viewer feedback ({{media-stats}}), and whole broadcasts listed as `contributions` ({{contributions}}). +This specification defines audio, video, and text media tracks, an optional `media` section ({{media}}) holding the clock that maps content time to wall time and the interval a viewer can join on, the root `version` ({{catalog-version}}), the application data tracks in {{data}}, optional publisher statistics and solicited viewer feedback ({{media-stats}}), and whole broadcasts listed in `include` ({{include}}). ## Version {#catalog-version} The root `version` field is the oldest draft of this specification that reads the catalog correctly, by draft number: `4` needs a consumer of moq-hang-04 or later. @@ -188,7 +188,7 @@ This draft needs `version` 4 for: - a `track` ({{field-track}}) other than the entry's ID, which an older consumer subscribes to instead; - a video `warmup` ({{field-warmup}}) above zero, since an older consumer starts decoding a group at a picture that is not a keyframe. -Every other catalog change in this draft is safe to ignore: `enabled` ({{field-enabled}}) leaves an older consumer selecting a disabled rendition, which plays nothing; `media` ({{media}}) only offers the clock and join interval, which an older consumer goes without; `stats` and `echo` ({{media-stats}}) only offer optional tracks; `contributions` ({{contributions}}) only offer broadcasts to open on selection; video `reorder` leaves an older consumer inferring decode times from timestamps; `jitter`, `delay`, audio `warmup`, and the data track estimates are hints. +Every other catalog change in this draft is safe to ignore: `enabled` ({{field-enabled}}) leaves an older consumer selecting a disabled rendition, which plays nothing; `media` ({{media}}) only offers the clock and join interval, which an older consumer goes without; `stats` and `echo` ({{media-stats}}) only offer optional tracks; `include` ({{include}}) only offers broadcasts to open on selection; video `reorder` leaves an older consumer inferring decode times from timestamps; `jitter`, `delay`, audio `warmup`, and the data track estimates are hints. ## Media {#media} The catalog's root `media` field holds what applies to every audio and video track: @@ -238,22 +238,25 @@ A group longer than the interval is an overrun, which an edge tolerates. A consumer that cannot decode `join`, including a zero `interval`, MUST treat it as absent. Nesting the interval under `join` leaves room for a later join mechanism that is not a fixed grid. -## Contributions {#contributions} -The optional root `contributions` map names whole broadcasts, such as each guest feed in a composed room, whose own catalogs describe their renditions. -Each key is a contribution ID. +## Includes {#include} +The optional root `include` map names whole broadcasts, such as transcoded renditions of the source, whose own catalogs describe their renditions. +Each key is an include ID. Each entry MUST contain a string `broadcast`, resolved against the catalog's broadcast as in {{field-broadcast}}, and MAY contain an `instance` as in {{field-instance}}. A consumer MUST reject a catalog with a malformed entry or a reference that escapes above the root. -Listing an entry MUST NOT subscribe to the contribution: a consumer opens its catalog only when it selects the contribution or one of its renditions. -An HLS master selects every contribution it lists, reading their catalogs to describe their renditions, but MUST NOT subscribe to their media until requested by a player. -It segments a contribution's renditions on the listing catalog's `media` ({{media}}), whatever the contribution's own catalog declares. +An include MUST share the listing catalog's PTS timeline and root settings, including its `media.clock` and `media.join.interval` ({{media}}). +A consumer uses the listing catalog's settings without comparing the include's own settings; a mismatch is a publisher error. + +Listing an entry MUST NOT subscribe to the include: a consumer opens its catalog only when it selects the include or one of its renditions. +An HLS master selects every include it lists, reading their catalogs to describe their renditions, but MUST NOT subscribe to their media until requested by a player. +It segments an include's renditions on the listing catalog's `media` ({{media}}), whatever the include's own catalog declares. A publisher producing media on demand MUST answer its catalog without starting media production. -A selected contribution resolves like a rendition's reference, under the same rules for `instance` and restarts ({{field-instance}}). -A contribution produced on demand has no stream until it resolves, so a publisher omits its `instance` until then. +A selected include resolves like a rendition's reference, under the same rules for `instance` and restarts ({{field-instance}}). +An include produced on demand has no stream until it resolves, so a publisher omits its `instance` until then. -A contribution's rendition IDs belong to its own catalog and MUST NOT replace IDs in the listing catalog, so the same ID MAY name a contribution, a rendition in the listing catalog, and a rendition in the contribution. -An unavailable contribution does not invalidate the listing catalog. -A consumer does not expand a contribution's own `contributions`: each needs a selection of its own. +An include's rendition IDs belong to its own catalog and MUST NOT replace IDs in the listing catalog, so the same ID MAY name an include, a rendition in the listing catalog, and a rendition in the include. +An unavailable include does not invalidate the listing catalog. +A consumer does not expand an include's own `include`: each needs a selection of its own. ## Track Identity {#identity} A track name always means the same content, so a catalog update never redefines an audio or video track. @@ -1096,7 +1099,7 @@ the broadcast path, not the payload. This track is distinct from an application' `hang/chat.json` snapshot extension. # Security Considerations -A rendition's `broadcast` reference ({{field-broadcast}}), like a contribution's ({{contributions}}), resolves against the consumer's root, which is the subtree it is authorized for. +A rendition's `broadcast` reference ({{field-broadcast}}), like an include's ({{include}}), resolves against the consumer's root, which is the subtree it is authorized for. Clamping a reference that escapes above that root would silently redirect the subscription to an unrelated broadcast, so a consumer rejects the catalog instead. TODO Security @@ -1127,8 +1130,9 @@ This document has no IANA actions. - Added the optional video `preference` field: a consumer selects automatically among the highest preference it can decode. - Added the optional video `reorder` field: the most frames that can precede one in decode order and follow it in presentation, fixed for the track once declared. A consumer that authors decode times derives them from it and the current group alone, refusing deeper reordering; without it, a consumer infers them from timestamps. - Added an optional `instance` beside every rendition and data track `broadcast` reference ({{field-instance}}). A consumer reads each referenced path from the first broadcast it resolves for a catalog instance; a present `instance` fails a rendition that resolves another stream, and is best effort against an Instance a receiver minted. -- Added the optional root `contributions` map ({{contributions}}): whole broadcasts named by a relative `broadcast` and an optional `instance`, opened only on selection, whose rendition IDs stay their own. -- An HLS master selects the contributions it lists by reading their catalogs, without demanding media, and segments them on the listing catalog's `media`; an on-demand publisher answers its catalog without starting media production. +- Added the optional root `include` map ({{include}}): whole broadcasts named by a relative `broadcast` and an optional `instance`, opened only on selection, whose rendition IDs stay their own. +- Includes share the listing catalog's PTS timeline and root settings, including its clock and join interval. +- An HLS master selects the includes it lists by reading their catalogs, without demanding media, and segments them on the listing catalog's `media`; an on-demand publisher answers its catalog without starting media production. - Added optional `stats` and `echo` catalog sections, publisher/viewer snapshots keyed by rendition ID, and the `.echo` feedback broadcast convention. - An Opus frame timestamp counts the OpusHead pre-skip: a consumer presents each decoded sample the pre-skip earlier than its frame timestamp places it. diff --git a/js/hang/api/catalog.api.md b/js/hang/api/catalog.api.md index 1c767ae7171..fe423896544 100644 --- a/js/hang/api/catalog.api.md +++ b/js/hang/api/catalog.api.md @@ -173,13 +173,6 @@ export const ContainerSchema: ZodMiniDefault>]>>; -export type Contribution = infer; - -export const ContributionSchema: ZodMiniObject<{ - broadcast: ZodMiniType>; - instance: ZodMiniOptional>>; -}, $strip>; - export const DEFAULT_FORMAT: Format; export class DuplicateRendition extends Error { @@ -204,6 +197,13 @@ export type Format = typeof FORMATS[number]; export type Hex = infer; +export type Include = infer; + +export const IncludeSchema: ZodMiniObject<{ + broadcast: ZodMiniType>; + instance: ZodMiniOptional>>; +}, $strip>; + export const InstanceSchema: ZodMiniType; export type Join = infer; @@ -330,13 +330,13 @@ export const RootSchema: ZodMiniObject<{ track?: string | undefined; }>, Record>>; }, $strip>, ZodMiniPipe, ZodMiniTransform>]>>; - contributions: ZodMiniOptional, Record>, ZodMiniTransform, Record>>>; echo: ZodMiniOptional>; }, $strip>, ZodMiniPipe, ZodMiniTransform>]>>; + include: ZodMiniOptional, Record>, ZodMiniTransform, Record>>>; json: ZodMiniOptional, Record>, ZodMiniTransform - ({ contributions: { entry: { broadcast: Moq.Path.normalizeRelative(broadcast) } } }) as Root; - expect(() => checkResolvable(contribution("../../x"), base)).toThrow(EscapingBroadcast); - expect(checkResolvable(contribution("../x"), base)).toBeDefined(); + // An include is a whole broadcast, keyed directly under its section. + const include = (broadcast: string) => + ({ include: { entry: { broadcast: Moq.Path.normalizeRelative(broadcast) } } }) as Root; + expect(() => checkResolvable(include("../../x"), base)).toThrow(EscapingBroadcast); + expect(checkResolvable(include("../x"), base)).toBeDefined(); }); test("watch yields a catalog with many renditions", async () => { diff --git a/js/hang/src/catalog/contribution.ts b/js/hang/src/catalog/include.ts similarity index 58% rename from js/hang/src/catalog/contribution.ts rename to js/hang/src/catalog/include.ts index 68368a85793..b59bf112e97 100644 --- a/js/hang/src/catalog/contribution.ts +++ b/js/hang/src/catalog/include.ts @@ -4,18 +4,21 @@ import { InstanceSchema, RelativeBroadcastSchema } from "./path"; /** * A whole broadcast whose own catalog describes its renditions, listed without opening it. * - * Listing one subscribes to nothing: a consumer opens the contribution's catalog only when it + * It shares the listing catalog's PTS timeline and root settings, including `media.clock` and + * `media.join.interval`; its own catalog's settings are ignored. + * + * Listing one subscribes to nothing: a consumer opens the include's catalog only when it * selects it, including an HLS master listing its renditions. An on-demand publisher answers * the catalog without starting media. Its rendition IDs belong to that broadcast, never the * listing catalog. */ -export const ContributionSchema = z.object({ - // The contribution's broadcast, relative to the broadcast serving this catalog. +export const IncludeSchema = z.object({ + // The include's broadcast, relative to the broadcast serving this catalog. broadcast: RelativeBroadcastSchema, // The stream the reference names, with a rendition `instance`'s meaning. A composer leaves it - // out until the contribution resolves. + // out until the include resolves. instance: z.optional(InstanceSchema), }); /** A whole broadcast listed for explicit, lazy selection. */ -export type Contribution = z.infer; +export type Include = z.infer; diff --git a/js/hang/src/catalog/index.ts b/js/hang/src/catalog/index.ts index e99954e9dbf..6ca97df89eb 100644 --- a/js/hang/src/catalog/index.ts +++ b/js/hang/src/catalog/index.ts @@ -2,8 +2,8 @@ * JSON catalog schema and types describing a broadcast's tracks: audio/video decoder configs for * WebCodecs, container format, rendition layout, the `media` section (the broadcast's `clock` and * `join` interval), - * plus the `json` and `binary` data sections, optional `stats` and `echo` discovery, and whole - * `contributions` listed without opening them. + * plus the `json` and `binary` data sections, optional `stats` and `echo` discovery, and + * broadcasts listed in `include` without opening them. * * @module */ @@ -25,10 +25,10 @@ export { AudioConfigSchema, AudioSchema } from "./audio"; export * from "./binary"; export * from "./clock"; export * from "./container"; -export * from "./contribution"; export * from "./echo"; export * from "./format"; export * from "./hex"; +export * from "./include"; export * from "./integers"; export * from "./json"; export * from "./media"; diff --git a/js/hang/src/catalog/parity.test.ts b/js/hang/src/catalog/parity.test.ts index 9cb15ec7bfc..a33d90219a7 100644 --- a/js/hang/src/catalog/parity.test.ts +++ b/js/hang/src/catalog/parity.test.ts @@ -10,11 +10,11 @@ interface Case { text?: string[]; json?: string[]; binary?: string[]; - contributions?: string[]; + include?: string[]; } // The corpus rs/hang also loads: both languages accept the same catalogs and keep the same -// rendition, data track, and contribution IDs, so a divergence fails CI on whichever side drifts. +// rendition, data track, and include IDs, so a divergence fails CI on whichever side drifts. const cases = (await Bun.file( new URL("../../../../rs/hang/fixtures/catalog-parity.json", import.meta.url), ).json()) as Case[]; @@ -35,6 +35,6 @@ for (const c of cases) { expect(ids(root.text?.renditions)).toEqual(c.text ?? []); expect(ids(root.json?.tracks)).toEqual(c.json ?? []); expect(ids(root.binary?.tracks)).toEqual(c.binary ?? []); - expect(ids(root.contributions)).toEqual(c.contributions ?? []); + expect(ids(root.include)).toEqual(c.include ?? []); }); } diff --git a/js/hang/src/catalog/root.test.ts b/js/hang/src/catalog/root.test.ts index 1e8123f7cee..1abfc205ad0 100644 --- a/js/hang/src/catalog/root.test.ts +++ b/js/hang/src/catalog/root.test.ts @@ -54,7 +54,7 @@ test("rendition broadcast reference is parsed and normalized", () => { test("every reference-bearing section carries an optional instance", () => { const INSTANCE = "01890a5d-ac96-774b-bcce-b302099a8057" as ReferenceInstance; const catalog = (instance: string) => ({ - contributions: { c: { broadcast: "./a", instance } }, + include: { c: { broadcast: "./a", instance } }, video: { renditions: { v: { broadcast: "./a", instance, codec: "avc1.64001f", container: { kind: "legacy" } }, @@ -85,36 +85,36 @@ test("every reference-bearing section carries an optional instance", () => { expect(parsed.text?.renditions.t?.instance).toBe(INSTANCE); expect(parsed.json?.tracks.j?.instance).toBe(INSTANCE); expect(parsed.binary?.tracks.b?.instance).toBe(INSTANCE); - expect(parsed.contributions?.c?.instance).toBe(INSTANCE); + expect(parsed.include?.c?.instance).toBe(INSTANCE); // An empty instance refuses the catalog, as in Rust. expect(RootSchema.safeParse(catalog("")).success).toBe(false); }); -// Mirrors Rust's `contributions_roundtrip_and_refuse_malformed_entries`. -test("a contribution parses beside a same-ID rendition and a malformed one is refused", () => { +// Mirrors Rust's `includes_roundtrip_and_refuse_malformed_entries`. +test("an include parses beside a same-ID rendition and a malformed one is refused", () => { const video = { alice: { codec: "avc1.64001f", container: { kind: "legacy" } } }; const parsed = RootSchema.parse({ - contributions: { alice: { broadcast: "./alice.hang" } }, + include: { alice: { broadcast: "./alice.hang" } }, video: { renditions: video }, }); - expect(parsed.contributions?.alice).toEqual({ broadcast: "alice.hang" as RelativeBroadcast }); - // Contribution IDs are their own namespace, so one may share a rendition's ID. + expect(parsed.include?.alice).toEqual({ broadcast: "alice.hang" as RelativeBroadcast }); + // Include IDs are their own namespace, so one may share a rendition's ID. expect(() => checkRenditions(parsed)).not.toThrow(); expect(encode(parsed).version).toBeUndefined(); - for (const contributions of [ + for (const include of [ [], { alice: null }, { alice: {} }, { alice: { broadcast: 42 } }, { alice: { broadcast: "./alice.hang", instance: "" } }, ]) { - expect(RootSchema.safeParse({ contributions }).success).toBe(false); + expect(RootSchema.safeParse({ include }).success).toBe(false); } - // The issue names a contribution, not a rendition. - const refused = RootSchema.safeParse({ contributions: { alice: {} } }); - expect(refused.error?.message).toContain("malformed contribution alice"); + // The issue names an include, not a rendition. + const refused = RootSchema.safeParse({ include: { alice: {} } }); + expect(refused.error?.message).toContain("malformed include alice"); }); test("rendition parent broadcast reference stays distinct from empty", () => { diff --git a/js/hang/src/catalog/root.ts b/js/hang/src/catalog/root.ts index b5c4a9fe29a..80f80eb11d4 100644 --- a/js/hang/src/catalog/root.ts +++ b/js/hang/src/catalog/root.ts @@ -4,9 +4,9 @@ import { Path } from "@moq/net"; import * as z from "zod/mini"; import { AudioSchema } from "./audio"; import { BinarySchema } from "./binary"; -import { ContributionSchema } from "./contribution"; import { EchoSchema } from "./echo"; import { TRACK } from "./format"; +import { IncludeSchema } from "./include"; import { JsonSchema } from "./json"; import { MediaSchema } from "./media"; import type { RelativeBroadcast } from "./path"; @@ -50,8 +50,8 @@ const VersionSchema = z.number().check( * to every audio and video track: the broadcast's `clock` (the one wall-clock mapping) and its * `join` interval. `json` and `binary` list application data tracks that aren't media. A section is omitted * when it holds no tracks. `stats` names the publisher's media snapshot track, `echo` - * solicits viewer feedback under a relative broadcast prefix, and `contributions` lists whole - * broadcasts without opening them. + * solicits viewer feedback under a relative broadcast prefix, and `include` lists whole + * broadcasts without opening them; each shares this catalog's PTS timeline and root settings. * * 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 @@ -85,7 +85,7 @@ export const RootSchema = z.looseObject({ json: section(JsonSchema, "tracks"), binary: section(BinarySchema, "tracks"), // A new key, so a malformed entry fails the catalog, the same as Rust. - contributions: z.optional(renditions(ContributionSchema, "contribution")), + include: z.optional(renditions(IncludeSchema, "include")), }); /** The root catalog object: the media sections, `media`, the data track sections, plus any app extensions. */ @@ -172,7 +172,7 @@ export function checkResolvable(root: Root, base: Moq.Path.Valid): Root { root.text?.renditions, root.json?.tracks, root.binary?.tracks, - root.contributions, + root.include, ]; for (const section of sections) { for (const { broadcast } of Object.values(section ?? {})) { diff --git a/js/hang/src/catalog/section.ts b/js/hang/src/catalog/section.ts index a6f0c1a15c8..b739c2944ad 100644 --- a/js/hang/src/catalog/section.ts +++ b/js/hang/src/catalog/section.ts @@ -35,7 +35,7 @@ export function section(schema: T, map: string) { } /** - * A catalog map keyed by ID (renditions, data tracks, contributions), refusing the catalog if any + * A catalog map keyed by ID (renditions, data tracks, includes), refusing the catalog if any * entry is malformed. * * Each entry must parse with `schema`; the issue names the entry. An unknown container @@ -43,7 +43,7 @@ export function section(schema: T, map: string) { * `deserialize_renditions`. * * @param schema - one entry's schema. - * @param kind - what an entry is, naming it in the issue (`rendition`, `contribution`). + * @param kind - what an entry is, naming it in the issue (`rendition`, `include`). */ export function renditions(schema: T, kind = "rendition") { return z.pipe( diff --git a/js/watch/api/index.api.md b/js/watch/api/index.api.md index 14e18975ac4..707d73820c8 100644 --- a/js/watch/api/index.api.md +++ b/js/watch/api/index.api.md @@ -105,8 +105,8 @@ export namespace Audio { export class Broadcast { constructor(props?: Signals.Inputs); close(): void; - contribution(effect: Signals.Effect, id: string): Broadcast; readonly in: Signals.Readonlys; + include(effect: Signals.Effect, id: string): Broadcast; readonly out: Signals.Readonlys; } diff --git a/js/watch/src/broadcast.ts b/js/watch/src/broadcast.ts index ef63f0abde2..a71ab564d54 100644 --- a/js/watch/src/broadcast.ts +++ b/js/watch/src/broadcast.ts @@ -191,7 +191,7 @@ 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, + // Set only on an include: 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); @@ -530,31 +530,31 @@ export class Broadcast { } /** - * Select a whole contribution, opening its catalog only while the caller owns this effect. + * Select a whole include, opening its catalog only while the caller owns this effect. * - * Listing a contribution in the catalog opens nothing; this is the demand. The child tracks + * Listing an include in the catalog opens nothing; this is the demand. The child tracks * the catalog entry and resolves through this broadcast's `relativeBroadcast`, sharing - * its request: while following announcements it follows the contribution's restarts, and + * its request: while following announcements it follows the include's restarts, and * otherwise it requests the first instance once. With an `instance` it is offline while its * broadcast resolves another stream. An absent entry leaves the child disabled, and an - * unavailable contribution reads as offline. Its rendition IDs stay local to the child, so + * unavailable include reads as offline. Its rendition IDs stay local to the child, so * they never shadow this catalog's IDs. * * ```ts * effects.run((effect) => { - * const child = broadcast.contribution(effect, "alice"); + * const child = broadcast.include(effect, "alice"); * const source = new Video.Source({ broadcast: child, supported: Video.Decoder.supported }); * effect.cleanup(() => source.close()); * // Feed source into a decoder as with any broadcast. * }); * ``` */ - contribution(effect: Effect, id: string): Broadcast { + include(effect: Effect, id: string): Broadcast { // Each computed notifies only on a real change, so an update that leaves the child's path // alone (such as a new `instance`) 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 include = run.get(this.out.catalog)?.include; + return include && Object.hasOwn(include, id) ? include[id] : undefined; }); const name = effect.computed((run) => { // An empty reference is present: it names the catalog's own broadcast. diff --git a/js/watch/src/contribution.test.ts b/js/watch/src/include.test.ts similarity index 78% rename from js/watch/src/contribution.test.ts rename to js/watch/src/include.test.ts index b87ead8372d..a8e1eab8973 100644 --- a/js/watch/src/contribution.test.ts +++ b/js/watch/src/include.test.ts @@ -35,20 +35,20 @@ async function unwanted(track: Track.Producer): Promise { const video = (codec: string) => ({ codec, container: { kind: "legacy" as const } }); -it("opens a listed contribution only on selection, keeping its rendition IDs its own", async () => { +it("opens a listed include only on selection, keeping its rendition IDs its own", async () => { const origin = new Origin.Producer(); const parent = publish(origin, "room/main.hang"); - const contribution = publish(origin, "room/extra.hang"); - const contributionCatalog = contribution.createTrack(Catalog.TRACK); - const catalog = new Json.Snapshot.Producer({ track: contributionCatalog, deltas: false }); + const include = publish(origin, "room/extra.hang"); + const includeCatalog = include.createTrack(Catalog.TRACK); + const catalog = new Json.Snapshot.Producer({ track: includeCatalog, deltas: false }); parent.createTrack("video").writeFrame({ payload: new TextEncoder().encode("source frames") }); - const contributionVideo = contribution.createTrack("video"); - contributionVideo.writeFrame({ payload: new TextEncoder().encode("contribution frames") }); + const includeVideo = include.createTrack("video"); + includeVideo.writeFrame({ payload: new TextEncoder().encode("include frames") }); - // The contribution and a source rendition share the ID "video". + // The include and a source rendition share the ID "video". const root = Catalog.RootSchema.parse({ video: { renditions: { video: video("avc1.42001f") } }, - contributions: { video: { broadcast: "./extra.hang" } }, + include: { video: { broadcast: "./extra.hang" } }, }); const source = new Broadcast({ origin, @@ -59,14 +59,14 @@ it("opens a listed contribution only on selection, keeping its rendition IDs its const selection = new Effect(); try { await settle(); - expect(source.out.catalog.peek()?.contributions).toEqual(root.contributions); + expect(source.out.catalog.peek()?.include).toEqual(root.include); // Listing the entry does not subscribe to its catalog. - expect(contributionCatalog.demand().wanted.peek()).toBeUndefined(); + expect(includeCatalog.demand().wanted.peek()).toBeUndefined(); - const child = source.contribution(selection, "video"); + const child = source.include(selection, "video"); catalog.update({ value: { video: { renditions: { video: video("vp8") } } } }); await settle(); - expect(contributionCatalog.demand().wanted.peek()).toBeDefined(); + expect(includeCatalog.demand().wanted.peek()).toBeDefined(); expect(child.out.catalog.peek()?.video?.renditions.video?.codec).toBe("vp8"); expect(source.out.catalog.peek()?.video?.renditions.video?.codec).toBe("avc1.42001f"); @@ -81,7 +81,7 @@ it("opens a listed contribution only on selection, keeping its rendition IDs its .ordered(); const original = source.relativeBroadcast(selection, undefined)?.track("video").subscribe().ordered(); try { - expect(await frames?.readString()).toBe("contribution frames"); + expect(await frames?.readString()).toBe("include frames"); expect(await original?.readString()).toBe("source frames"); } finally { frames?.close(); @@ -89,11 +89,11 @@ it("opens a listed contribution only on selection, keeping its rendition IDs its } // An unlisted ID leaves the child disabled. - expect(source.contribution(selection, "unknown").in.enabled.peek()).toBe(false); + expect(source.include(selection, "unknown").in.enabled.peek()).toBe(false); selection.close(); - await unwanted(contributionCatalog); - await unwanted(contributionVideo); + await unwanted(includeCatalog); + await unwanted(includeVideo); } finally { selection.close(); source.close(); @@ -101,7 +101,7 @@ it("opens a listed contribution only on selection, keeping its rendition IDs its } }); -it("reads an unavailable contribution as offline without touching the parent", async () => { +it("reads an unavailable include as offline without touching the parent", async () => { const origin = new Origin.Producer(); publish(origin, "room/main.hang"); const claim = origin.requests(Path.from("room/absent.hang")); @@ -112,19 +112,19 @@ it("reads an unavailable contribution as offline without touching the parent", a catalogFormat: "manual", catalog: Catalog.RootSchema.parse({ video: { renditions: { hd: video("avc1.42001f") } }, - contributions: { missing: { broadcast: "./absent.hang" } }, + include: { missing: { broadcast: "./absent.hang" } }, }), follow: false, }); const selection = new Effect(); try { await settle(); - const missing = source.contribution(selection, "missing"); + const missing = source.include(selection, "missing"); const { value: request } = await requests.next(); expect(request?.path).toBe(Path.from("room/absent.hang")); - request?.reject(new Error("contribution unavailable")); + request?.reject(new Error("include unavailable")); await settle(); - // Like a rendition's reference, an unavailable contribution is offline, not an error. + // Like a rendition's reference, an unavailable include is offline, not an error. expect(missing.out.active.peek()).toBeUndefined(); expect(missing.out.error.peek()).toBeUndefined(); expect(missing.out.status.peek()).toBe("offline"); @@ -138,7 +138,7 @@ it("reads an unavailable contribution as offline without touching the parent", a } }); -it("reports a contribution outside the origin's scope as an error, leaving the parent live", async () => { +it("reports an include outside the origin's scope as an error, leaving the parent live", async () => { const origin = new Origin.Producer(); const scoped = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("room/*")])); publish(scoped, "room/main.hang"); @@ -146,12 +146,12 @@ it("reports a contribution outside the origin's scope as an error, leaving the p origin: scoped, name: Path.from("room/main.hang"), catalogFormat: "manual", - catalog: Catalog.RootSchema.parse({ contributions: { outside: { broadcast: "../other/extra.hang" } } }), + catalog: Catalog.RootSchema.parse({ include: { outside: { broadcast: "../other/extra.hang" } } }), follow: false, }); const owner = new Effect(); try { - const child = parent.contribution(owner, "outside"); + const child = parent.include(owner, "outside"); await settle(); expect(child.out.active.peek()).toBeUndefined(); expect(child.out.error.peek()?.message).toContain("outside the origin scope"); @@ -163,12 +163,12 @@ it("reports a contribution outside the origin's scope as an error, leaving the p } }); -it("tracks the contribution entry without reopening it on unrelated catalog updates", async () => { +it("tracks the include entry without reopening it on unrelated catalog updates", async () => { const origin = new Origin.Producer(); publish(origin, "room/main.hang"); const firstCatalog = publish(origin, "room/first.hang").createTrack(Catalog.TRACK); publish(origin, "room/second.hang"); - const catalog = new Signal(Catalog.RootSchema.parse({ contributions: { extra: { broadcast: "./first.hang" } } })); + const catalog = new Signal(Catalog.RootSchema.parse({ include: { extra: { broadcast: "./first.hang" } } })); const parent = new Broadcast({ origin, name: Path.from("room/main.hang"), @@ -178,7 +178,7 @@ it("tracks the contribution entry without reopening it on unrelated catalog upda }); const owner = new Effect(); try { - const child = parent.contribution(owner, "extra"); + const child = parent.include(owner, "extra"); await settle(); const active = child.out.active.peek(); expect(active?.path).toBe(Path.from("room/first.hang")); @@ -193,7 +193,7 @@ it("tracks the contribution entry without reopening it on unrelated catalog upda ); catalog.set( Catalog.RootSchema.parse({ - contributions: { extra: { broadcast: "./first.hang" }, other: { broadcast: "./other.hang" } }, + include: { extra: { broadcast: "./first.hang" }, other: { broadcast: "./other.hang" } }, metadata: "changed", }), ); @@ -202,7 +202,7 @@ it("tracks the contribution entry without reopening it on unrelated catalog upda 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" } } })); + catalog.set(Catalog.RootSchema.parse({ include: { extra: { broadcast: "./second.hang" } } })); await settle(); expect(child.out.active.peek()?.path).toBe(Path.from("room/second.hang")); @@ -228,7 +228,7 @@ it("follows a restarted contributor only for an entry that names no instance", a name: Path.from("room/main.hang"), catalogFormat: "manual", catalog: Catalog.RootSchema.parse({ - contributions: { + include: { following: { broadcast: "./extra.hang" }, pinned: { broadcast: "./extra.hang", instance: oldInstance }, }, @@ -236,8 +236,8 @@ it("follows a restarted contributor only for an entry that names no instance", a }); const owner = new Effect(); try { - const following = parent.contribution(owner, "following"); - const pinned = parent.contribution(owner, "pinned"); + const following = parent.include(owner, "following"); + const pinned = parent.include(owner, "pinned"); await settle(); expect(following.out.active.peek()?.instance).toBe(oldInstance); expect(pinned.out.active.peek()?.instance).toBe(oldInstance); @@ -258,7 +258,7 @@ it("follows a restarted contributor only for an entry that names no instance", a } }); -it("pins the first instance of a contribution when not following announcements", async () => { +it("pins the first instance of an include when not following announcements", async () => { const origin = new Origin.Producer(); publish(origin, "room/main.hang"); const first = publish(origin, "room/extra.hang", Instance.random()); @@ -266,12 +266,12 @@ it("pins the first instance of a contribution when not following announcements", origin, name: Path.from("room/main.hang"), catalogFormat: "manual", - catalog: Catalog.RootSchema.parse({ contributions: { extra: { broadcast: "./extra.hang" } } }), + catalog: Catalog.RootSchema.parse({ include: { extra: { broadcast: "./extra.hang" } } }), follow: false, }); const owner = new Effect(); try { - const child = parent.contribution(owner, "extra"); + const child = parent.include(owner, "extra"); await settle(); const pinned = child.out.active.peek(); expect(pinned?.path).toBe(Path.from("room/extra.hang")); @@ -290,7 +290,7 @@ it("pins the first instance of a contribution when not following announcements", } }); -it("never reads a contribution of another instance, but reads a minted one", async () => { +it("never reads an include of another instance, but reads a minted one", async () => { const origin = new Origin.Producer(); publish(origin, "room/main.hang"); const served = Instance.random(); @@ -299,14 +299,14 @@ it("never reads a contribution of another instance, but reads a minted one", asy // A route over a wire that carries no instance has one its session minted. publish(origin, "room/plain.hang", Instance.minted()); const named = Instance.random(); - const contributions = (instance: Instance.Valid) => + const include = (instance: Instance.Valid) => Catalog.RootSchema.parse({ - contributions: { + include: { proven: { broadcast: "./proven.hang", instance }, plain: { broadcast: "./plain.hang", instance: named }, }, }); - const catalog = new Signal(contributions(named)); + const catalog = new Signal(include(named)); const parent = new Broadcast({ origin, name: Path.from("room/main.hang"), @@ -316,8 +316,8 @@ it("never reads a contribution of another instance, but reads a minted one", asy }); const owner = new Effect(); try { - const refused = parent.contribution(owner, "proven"); - const accepted = parent.contribution(owner, "plain"); + const refused = parent.include(owner, "proven"); + const accepted = parent.include(owner, "plain"); await quietly(settle); expect(refused.out.active.peek()).toBeUndefined(); expect(refused.out.error.peek()).toBeUndefined(); @@ -327,7 +327,7 @@ it("never reads a contribution of another instance, but reads a minted one", asy expect(accepted.out.active.peek()?.path).toBe(Path.from("room/plain.hang")); // A catalog update naming the served instance admits the stream the request already holds. - catalog.set(contributions(served)); + catalog.set(include(served)); await settle(); expect(refused.out.active.peek()?.instance).toBe(served); } finally { @@ -344,7 +344,7 @@ it("shares the parent's resolution, so a new instance checks the held handle", a const extraCatalog = publish(origin, "room/extra.hang", served).createTrack(Catalog.TRACK); const entries = (instance?: Instance.Valid) => Catalog.RootSchema.parse({ - contributions: { + include: { sibling: { broadcast: "./extra.hang", instance }, self: { broadcast: "./main.hang", instance }, empty: { broadcast: "", instance }, @@ -360,15 +360,15 @@ it("shares the parent's resolution, so a new instance checks the held handle", a }); const owner = new Effect(); try { - const sibling = parent.contribution(owner, "sibling"); - const self = parent.contribution(owner, "self"); + const sibling = parent.include(owner, "sibling"); + const self = parent.include(owner, "self"); await settle(); const held = sibling.out.active.peek(); expect(held?.instance).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"); + const empty = parent.include(owner, "empty"); await settle(); expect(empty.in.name.peek()).toBe(Path.from("room/main.hang")); expect(empty.in.enabled.peek()).toBe(true); diff --git a/quest/m1/README.md b/quest/m1/README.md index 82de10e4135..f6e981cfdbf 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -174,7 +174,6 @@ their end report, so an embedder's drain alert pages on real cuts. - [Calibrate the paired nightly benchmarks](/quest/m1/bench-ci.md) - A/A and deliberately slowed Nightly runs set the paired comparison's threshold, so its regression alerts can be trusted - [moq-json's table/deltas bench measures the same work every iteration](/quest/m1/bench-json-deltas.md) - the `table/deltas/1%` cases stop flipping between snapshot and delta timings, so their trend history is usable - [Publish moq-bench to crates.io](/quest/m1/bench-publish.md) - `cargo install moq-bench` installs one binary, with the host sampler as `moq-bench host`, first as 0.1.0 -- [Catalog contributions become includes on the root's timeline](/quest/m1/catalog-include.md) - rename the unreleased `contributions` map before the cut and state that included broadcasts share the root's timeline - [Unbounded groups](/quest/m1/unbounded-groups/README.md) - groups and frames lose their size caps; a group keeps a 32 MB tail, and readers behind it replay through paced flights or refresh - [Session policy lives in moq-net](/quest/m1/session-policy/README.md) - accept and connect deadlines, admission, window widening and reconnect live once in moq-net; moq-tokio and moq-relay's io_uring path call them - [moq auth serve scopes each client certificate by its chain](/quest/m1/auth-cert-rules.md) - per-certificate and per-intermediate rules in a reloaded TOML config, keyed by the chain hashes the relay sends diff --git a/quest/m1/catalog-include.md b/quest/m1/catalog-include.md deleted file mode 100644 index c34fa5c2529..00000000000 --- a/quest/m1/catalog-include.md +++ /dev/null @@ -1,41 +0,0 @@ -# [S] Catalog contributions become includes on the root's timeline - -## Goal - -The hang catalog's root `contributions` map is renamed to say what it is: other -broadcasts the root includes, which share the root's PTS timeline and its -catalog-root settings (clock, join interval). The rename covers the Rust and JS -catalog types and schemas, `@moq/watch`'s `broadcast.contribution(effect, id)`, -the parity fixture, `doc/concept/hang.md`, and the draft's -`{#contributions}` section, with the shared-timeline rule stated in the draft. -Done before the next release cut, while the field is still unreleased. - -## Plan - -Planned 2026-11-04 with the maintainer, while settling -[moq-dev/moq#7836](https://github.com/moq-dev/moq/pull/7836)'s HLS listing. -The maintainer: keep contributions; "consider renaming them. Afaik the -use-case is moq.pro transcodes so they must share PTS and really everything in -the catalog root. Its why I wanted to call the section `include` originally." - -- ✅ **Contributions stay** (maintainer, 2026-11-04). Not chosen: removing them. -- ✅ **They share the root's timeline** (maintainer, 2026-11-04): consumers - such as moq-hls treat a contribution as on the root's PTS timeline and grid, - with no clock or interval comparison; a mismatch is the publisher's bug. - #7836 implements that for HLS. -- **The name is the open decision.** `include` is the maintainer's original - preference; confirm it (or another) in this quest's PR before renaming, then - rename the field, the types (`Contribution`), the watch method and the draft - section consistently in Rust, JS and the bindings that expose them. -- The field arrived in [moq-dev/moq#7312](https://github.com/moq-dev/moq/pull/7312) - (2026-11-01) and isn't on `release`, so no compatibility alias is needed and - the catalog `version` stays. -- Update the HLS listing's code, landed in - [moq-dev/moq#7836](https://github.com/moq-dev/moq/pull/7836), to the new name. - -Public API: breaking but unreleased (Rust `hang`, `@moq/hang`, `@moq/watch`). -Wire: the catalog JSON key changes; unreleased. - -## Related - -- [HLS lists contributions](https://github.com/moq-dev/moq/pull/7836) - the HLS consumer settled with the shared-timeline rule diff --git a/rs/hang/fixtures/catalog-parity.json b/rs/hang/fixtures/catalog-parity.json index 92cf1a0f078..c64baa31b66 100644 --- a/rs/hang/fixtures/catalog-parity.json +++ b/rs/hang/fixtures/catalog-parity.json @@ -3717,9 +3717,9 @@ "refused": true }, { - "name": "contribution IDs are any string", + "name": "include IDs are any string", "catalog": { - "contributions": { + "include": { "": { "broadcast": "./a.hang" }, @@ -3734,12 +3734,12 @@ } } }, - "contributions": ["", "__proto__", "constructor", "toString"] + "include": ["", "__proto__", "constructor", "toString"] }, { - "name": "contribution malformed __proto__ refuses the catalog", + "name": "include malformed __proto__ refuses the catalog", "catalog": { - "contributions": { + "include": { "ok": { "broadcast": "./a.hang" }, @@ -3749,9 +3749,9 @@ "refused": true }, { - "name": "contribution malformed bad refuses the catalog", + "name": "include malformed bad refuses the catalog", "catalog": { - "contributions": { + "include": { "__proto__": { "broadcast": "./a.hang" }, diff --git a/rs/hang/src/catalog/consumer.rs b/rs/hang/src/catalog/consumer.rs index 20ac6b6768f..1a37fdf3d27 100644 --- a/rs/hang/src/catalog/consumer.rs +++ b/rs/hang/src/catalog/consumer.rs @@ -34,7 +34,7 @@ impl Consumer { /// Get the next catalog update, or `None` when the track ends. /// /// Fails with [`Error::EscapingBroadcast`](crate::Error::EscapingBroadcast) if any rendition's - /// `broadcast` reference, contribution, or echo prefix walks above the root. Such a reference names no broadcast, and the + /// `broadcast` reference, include, or echo prefix walks above the root. Such a reference names no broadcast, and the /// root is the consumer's authorized subtree, so it is an attempt to reference content the /// consumer cannot name. The whole catalog is rejected rather than the one rendition: a /// publisher that emits one has a bug (or is hostile), and silently serving the rest hides @@ -58,7 +58,7 @@ impl Consumer { } } -/// Reject the catalog if a track reference, contribution, or echo prefix walks above the root. +/// Reject the catalog if a track reference, include, or echo prefix walks above the root. /// /// Every section carrying a relative broadcast path must be included here; a section left out /// silently exempts its paths from the containment check. @@ -76,7 +76,7 @@ fn check_resolvable(base: &Path, catalog: &Catalog) -> Result<()> { .chain(json.map(|(_, config)| config.broadcast.as_ref())) .chain(binary.map(|(_, config)| config.broadcast.as_ref())) .flatten() - .chain(catalog.contributions.values().map(|entry| &entry.broadcast)) + .chain(catalog.include.values().map(|entry| &entry.broadcast)) { if !rel.is_empty() && base.try_resolve(rel).is_none() { return Err(crate::Error::EscapingBroadcast(rel.to_string())); @@ -112,10 +112,10 @@ mod test { } #[test] - fn contributions_cannot_escape_the_root() { + fn includes_cannot_escape_the_root() { let base = moq_net::Path::from_static("room/main.hang"); for (reference, accepted) in [("./alice.hang", true), ("../alice.hang", true), ("../../escape", false)] { - let json = serde_json::json!({ "contributions": { "alice": { "broadcast": reference } } }).to_string(); + let json = serde_json::json!({ "include": { "alice": { "broadcast": reference } } }).to_string(); let catalog = Catalog::<()>::from_str(&json).unwrap(); match check_resolvable(&base, &catalog) { Ok(()) => assert!(accepted, "{reference} must be refused"), diff --git a/rs/hang/src/catalog/contribution.rs b/rs/hang/src/catalog/include.rs similarity index 71% rename from rs/hang/src/catalog/contribution.rs rename to rs/hang/src/catalog/include.rs index 823c4a546a5..5d7c893f421 100644 --- a/rs/hang/src/catalog/contribution.rs +++ b/rs/hang/src/catalog/include.rs @@ -2,18 +2,21 @@ use serde::{Deserialize, Serialize}; /// A whole broadcast whose own catalog describes its renditions, listed without opening it. /// -/// Listing one subscribes to nothing: a consumer opens the contribution's catalog only when it +/// It shares the listing catalog's PTS timeline and root settings, including `media.clock` and +/// `media.join.interval`; its own catalog's settings are ignored. +/// +/// Listing one subscribes to nothing: a consumer opens the include's catalog only when it /// selects it, including an HLS master listing its renditions. An on-demand publisher answers /// the catalog without starting media. Its rendition IDs belong to that broadcast, never the /// listing catalog. /// /// Marked `#[non_exhaustive]` so optional fields can be added later. External callers build one -/// with [`Contribution::new`]. +/// with [`Include::new`]. #[serde_with::serde_as] #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)] #[non_exhaustive] -pub struct Contribution { - /// The contribution's broadcast, relative to the broadcast serving this catalog. +pub struct Include { + /// The include's broadcast, relative to the broadcast serving this catalog. /// /// Resolve it with [`Path::try_resolve`](moq_net::Path::try_resolve): a reference that walks /// above the root names no broadcast, so the catalog is rejected. @@ -21,14 +24,14 @@ pub struct Contribution { /// The stream the reference names, with a rendition `instance`'s meaning: a route of another /// instance refuses it, and against one a relay minted it is best effort. A composer leaves it - /// out until the contribution resolves. + /// out until the include resolves. #[serde(default, skip_serializing_if = "Option::is_none")] #[serde_as(as = "Option")] pub instance: Option, } -impl Contribution { - /// A contribution at `broadcast`, accepting whichever stream resolves. +impl Include { + /// An include at `broadcast`, accepting whichever stream resolves. pub fn new(broadcast: impl Into) -> Self { Self { broadcast: broadcast.into(), diff --git a/rs/hang/src/catalog/mod.rs b/rs/hang/src/catalog/mod.rs index 8d792d033dc..634bf60a76e 100644 --- a/rs/hang/src/catalog/mod.rs +++ b/rs/hang/src/catalog/mod.rs @@ -10,9 +10,9 @@ mod binary; mod clock; mod consumer; mod container; -mod contribution; mod echo; mod hex; +mod include; mod json; mod m2ts; mod media; @@ -30,8 +30,8 @@ pub use binary::*; pub use clock::*; pub use consumer::*; pub use container::*; -pub use contribution::*; pub use echo::*; +pub use include::*; pub use json::*; pub use m2ts::*; pub use media::*; diff --git a/rs/hang/src/catalog/root.rs b/rs/hang/src/catalog/root.rs index 495fda5738b..cbac094b9ca 100644 --- a/rs/hang/src/catalog/root.rs +++ b/rs/hang/src/catalog/root.rs @@ -12,7 +12,7 @@ use serde::{Deserialize, Serialize}; /// section (the broadcast's one wall-clock mapping and join interval), the data sections /// (`json`, `binary`) for application tracks that aren't media, and the optional `m2ts` (a /// transport stream carried whole), plus `stats` naming the publisher's media snapshot track and -/// `echo` soliciting viewer feedback under a relative broadcast prefix, and `contributions` naming +/// `echo` soliciting viewer feedback under a relative broadcast prefix, and `include` naming /// 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 @@ -85,11 +85,13 @@ pub struct Catalog { /// An `echo` value without a string `path` decodes as absent, the same as [`stats`](Self::stats). pub echo: Option, - /// Whole broadcasts listed for explicit, lazy selection, keyed by contribution ID. + /// Whole broadcasts listed for explicit, lazy selection, keyed by include ID. /// - /// Listing one subscribes to nothing; see [`Contribution`](crate::catalog::Contribution). + /// Each shares this catalog's PTS timeline and root settings, including `media.clock` and + /// `media.join.interval`; its own settings are ignored. Listing one subscribes to nothing; + /// see [`Include`](crate::catalog::Include). /// Omitted from the wire when empty. A malformed entry refuses the catalog. - pub contributions: std::collections::BTreeMap, + pub include: std::collections::BTreeMap, /// Application-defined root sections, flattened alongside the base catalog sections. /// @@ -166,7 +168,7 @@ struct Wire { echo: Option, #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")] - contributions: std::collections::BTreeMap, + include: std::collections::BTreeMap, #[serde(flatten, serialize_with = "serialize_ext")] ext: E, @@ -202,7 +204,7 @@ impl From> for Catalog { m2ts, stats, echo, - contributions, + include, ext, } = wire; Self { @@ -215,7 +217,7 @@ impl From> for Catalog { m2ts, stats, echo, - contributions, + include, ext, } } @@ -441,11 +443,11 @@ mod test { #[serde(default)] binary: Vec, #[serde(default)] - contributions: Vec, + include: Vec, } /// The corpus `js/hang` also loads: both languages accept the same catalogs and keep the same - /// rendition, data track, and contribution IDs, so a divergence fails CI on whichever side drifts. + /// rendition, data track, and include IDs, so a divergence fails CI on whichever side drifts. #[test] fn shared_parity_fixtures() { let cases: Vec = serde_json::from_str(include_str!("../../fixtures/catalog-parity.json")).unwrap(); @@ -465,18 +467,18 @@ mod test { let text: Vec<_> = catalog.text.renditions.keys().cloned().collect(); let json: Vec<_> = catalog.json.tracks.keys().cloned().collect(); let binary: Vec<_> = catalog.binary.tracks.keys().cloned().collect(); - let contributions: Vec<_> = catalog.contributions.keys().cloned().collect(); - if (&video, &audio, &text, &json, &binary, &contributions) + let include: Vec<_> = catalog.include.keys().cloned().collect(); + if (&video, &audio, &text, &json, &binary, &include) != ( &case.video, &case.audio, &case.text, &case.json, &case.binary, - &case.contributions, + &case.include, ) { failures.push(format!( - "{}: kept video {video:?} audio {audio:?} text {text:?} json {json:?} binary {binary:?} contributions {contributions:?}", + "{}: kept video {video:?} audio {audio:?} text {text:?} json {json:?} binary {binary:?} include {include:?}", case.name )); } @@ -537,28 +539,28 @@ mod test { assert_eq!(Catalog::<()>::from_str(&catalog.to_json().unwrap()).unwrap(), catalog); } - /// A contribution round-trips, stays off the wire when none is listed, and a malformed entry + /// An include round-trips, stays off the wire when none is listed, and a malformed entry /// refuses the catalog rather than being dropped. #[test] - fn contributions_roundtrip_and_refuse_malformed_entries() { - let json = r#"{"contributions":{"alice":{"broadcast":"./alice.hang"}},"video":{"renditions":{"alice":{"codec":"avc1.64001f","container":{"kind":"legacy"}}}}}"#; + fn includes_roundtrip_and_refuse_malformed_entries() { + let json = r#"{"include":{"alice":{"broadcast":"./alice.hang"}},"video":{"renditions":{"alice":{"codec":"avc1.64001f","container":{"kind":"legacy"}}}}}"#; let catalog = Catalog::<()>::from_str(json).unwrap(); assert_eq!( - catalog.contributions["alice"], - crate::catalog::Contribution::new(moq_net::path::Relative::new("./alice.hang").unwrap()) + catalog.include["alice"], + crate::catalog::Include::new(moq_net::path::Relative::new("./alice.hang").unwrap()) ); - // Contribution IDs are their own namespace, so one may share a rendition's ID. + // Include IDs are their own namespace, so one may share a rendition's ID. assert!(catalog.check_renditions().is_ok()); assert!(catalog.video.renditions.contains_key("alice")); assert_eq!(Catalog::<()>::from_str(&catalog.to_json().unwrap()).unwrap(), catalog); - assert!(!Catalog::<()>::default().to_json().unwrap().contains("contributions")); + assert!(!Catalog::<()>::default().to_json().unwrap().contains("include")); for bad in [ - r#"{"contributions":[]}"#, - r#"{"contributions":{"alice":null}}"#, - r#"{"contributions":{"alice":{}}}"#, - r#"{"contributions":{"alice":{"broadcast":42}}}"#, - r#"{"contributions":{"alice":{"broadcast":"./alice.hang","instance":""}}}"#, + r#"{"include":[]}"#, + r#"{"include":{"alice":null}}"#, + r#"{"include":{"alice":{}}}"#, + r#"{"include":{"alice":{"broadcast":42}}}"#, + r#"{"include":{"alice":{"broadcast":"./alice.hang","instance":""}}}"#, ] { assert!(Catalog::<()>::from_str(bad).is_err(), "{bad} must be refused"); } @@ -572,7 +574,7 @@ mod test { const INSTANCE: &str = "01890a5d-ac96-774b-bcce-b302099a8057"; let encoded = format!( r#"{{ - "contributions": {{"c": {{"broadcast": "./a", "instance": "{INSTANCE}"}}}}, + "include": {{"c": {{"broadcast": "./a", "instance": "{INSTANCE}"}}}}, "video": {{"renditions": {{"v": {{"broadcast": "./a", "instance": "{INSTANCE}", "codec": "avc1.64001f", "container": {{"kind": "legacy"}}}}}}}}, "audio": {{"renditions": {{"a": {{"broadcast": "./a", "instance": "{INSTANCE}", "codec": "opus", "sampleRate": 48000, "numberOfChannels": 2, "container": {{"kind": "legacy"}}}}}}}}, "text": {{"renditions": {{"t": {{"broadcast": "./a", "instance": "{INSTANCE}", "format": "vtt"}}}}}}, @@ -592,7 +594,7 @@ mod test { for reference in references { assert_eq!(reference.instance(), Some(&instance)); } - assert_eq!(catalog.contributions["c"].instance.as_ref(), Some(&instance)); + assert_eq!(catalog.include["c"].instance.as_ref(), Some(&instance)); assert_eq!(Catalog::<()>::from_str(&catalog.to_json().unwrap()).unwrap(), catalog); // Omitted stays omitted, and an empty instance refuses the catalog. diff --git a/rs/moq-hls/Cargo.toml b/rs/moq-hls/Cargo.toml index 61f2365a1da..8e85e323b2d 100644 --- a/rs/moq-hls/Cargo.toml +++ b/rs/moq-hls/Cargo.toml @@ -59,7 +59,7 @@ tracing-test = { workspace = true } workspace-hack = { path = "../workspace-hack" } [[bench]] -name = "contributions" +name = "include" harness = false required-features = ["server"] diff --git a/rs/moq-hls/MIGRATE.md b/rs/moq-hls/MIGRATE.md index 3b2877431ee..cd78e16c76d 100644 --- a/rs/moq-hls/MIGRATE.md +++ b/rs/moq-hls/MIGRATE.md @@ -16,15 +16,15 @@ and `poll_ready`, `Rendition::poll_playable`, and `poll_next` on the `renditions `segments::Consumer` cursors. A `segments::Consumer::next` dropped mid-fetch leaves that fetch to the next call, which resumes it rather than starting over. -### HTTP HLS lists contributions without starting their media +### HTTP HLS lists includes without starting their media -`Server` follows the root catalog's contributions and lists their renditions from their -catalogs, on the root catalog's join interval and clock. Contribution media starts +`Server` follows the root catalog's includes and lists their renditions from their +catalogs, on the root catalog's join interval and clock. Include media starts only when requested and stops once responses finish and it idles for the longer of three target durations and the playlist window plus one target duration. Their URLs include both instances: -`@{instance}/contribution/{id}/{kind}/{rendition}/@{contribution-instance}/...`. -`Route::contribution` identifies that contribution; `Resource::instance` still names the +`@{instance}/include/{id}/{kind}/{rendition}/@{include-instance}/...`. +`Route::include` identifies that include; `Resource::instance` still names the parent broadcast's instance. Embedders using `Server::respond` need no routing change. DASH, `Broadcaster::new`, and the recorder cursor continue serving the broadcast's own renditions only. diff --git a/rs/moq-hls/benches/contributions.rs b/rs/moq-hls/benches/include.rs similarity index 87% rename from rs/moq-hls/benches/contributions.rs rename to rs/moq-hls/benches/include.rs index c8c22bdb77b..7ca1990666a 100644 --- a/rs/moq-hls/benches/contributions.rs +++ b/rs/moq-hls/benches/include.rs @@ -1,11 +1,11 @@ -//! Master rendering and one contribution lookup, swept over contributions x renditions. +//! Master rendering and one include lookup, swept over includes x renditions. //! The catalogs have no media, so setup also verifies that listing does not need an encode. use std::hint::black_box; use std::time::Duration; use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; -use hang::catalog::{Contribution, Join, VideoCodec, VideoConfig}; +use hang::catalog::{Include, Join, VideoCodec, VideoConfig}; use moq_hls::{Server, export::Route}; use moq_mux::catalog::hang::Catalog; @@ -23,12 +23,12 @@ fn publish_catalog( producer } -fn contributions(c: &mut Criterion) { +fn include(c: &mut Criterion) { let runtime = tokio::runtime::Builder::new_current_thread() .enable_all() .build() .unwrap(); - let mut group = c.benchmark_group("hls/contributions"); + let mut group = c.benchmark_group("hls/include"); for count in [1, 8, 64] { for renditions in [1, 4, 16] { let (server, broadcaster, route, _publications, _catalogs, _origin) = runtime.block_on(async { @@ -56,9 +56,9 @@ fn contributions(c: &mut Criterion) { .announce(moq_net::origin::Route::default().with_instance(instance, 0)) .unwrap(); publications.push(broadcast); - root.contributions.insert( + root.include.insert( id.clone(), - Contribution::new(moq_net::path::Relative::new(&format!("./{id}")).unwrap()), + Include::new(moq_net::path::Relative::new(&format!("./{id}")).unwrap()), ); } let parent = moq_net::Instance::random(); @@ -79,7 +79,7 @@ fn contributions(c: &mut Criterion) { .await .expect("every catalog is listed without media"); let route = Route::parse(&format!( - "/room/live/@{parent}/contribution/c0/video/missing/@{}/media.m3u8", + "/room/live/@{parent}/include/c0/video/missing/@{}/media.m3u8", first.unwrap() )) .unwrap(); @@ -100,5 +100,5 @@ fn contributions(c: &mut Criterion) { group.finish(); } -criterion_group!(benches, contributions); +criterion_group!(benches, include); criterion_main!(benches); diff --git a/rs/moq-hls/src/export/driver.rs b/rs/moq-hls/src/export/driver.rs index abbbdf20005..17e7e668879 100644 --- a/rs/moq-hls/src/export/driver.rs +++ b/rs/moq-hls/src/export/driver.rs @@ -12,7 +12,7 @@ use std::task::Poll; /// Dropping it early stops all of that work. #[must_use = "the broadcaster does nothing until its driver runs"] pub struct Driver { - /// The catalog watchers, the broadcast's and each contribution's, polled before the other + /// The catalog watchers, the broadcast's and each include's, polled before the other /// tasks in every pass: a reconfigure must retire its rendition before that rendition's /// watcher reads groups published after it. leads: kio::Tasks, @@ -155,7 +155,7 @@ impl kio::Task for Job { mod tests { use super::*; - /// A lead a spawner starts, such as a contribution's catalog watcher, runs before the tasks + /// A lead a spawner starts, such as an include's catalog watcher, runs before the tasks /// started ahead of it. #[test] fn spawned_leads_run_first() { diff --git a/rs/moq-hls/src/export/contributions.rs b/rs/moq-hls/src/export/include.rs similarity index 85% rename from rs/moq-hls/src/export/contributions.rs rename to rs/moq-hls/src/export/include.rs index a0c35d66f1f..6cdcfae29a1 100644 --- a/rs/moq-hls/src/export/contributions.rs +++ b/rs/moq-hls/src/export/include.rs @@ -1,11 +1,11 @@ -//! Catalog-only contribution discovery for the HTTP HLS master. +//! Catalog-only include discovery for the HTTP HLS master. use std::collections::BTreeMap; use std::sync::Arc; use std::task::{Poll, ready}; use std::time::Duration; -use hang::catalog::{Contribution, Media}; +use hang::catalog::{Include, Media}; use moq_mux::{catalog::hang::Catalog, follow}; #[cfg(feature = "server")] @@ -23,7 +23,7 @@ struct Context { origin: moq_net::origin::Consumer, window: Duration, spawner: driver::Spawner, - /// The root catalog's `media`. A contribution is included in the root broadcast, so its + /// The root catalog's `media`. An include is part of the root broadcast, so its /// renditions share the root's timeline and segment on the root's grid. root: kio::Producer, } @@ -34,7 +34,7 @@ struct State { } struct Entry { - reference: Contribution, + reference: Include, current: kio::Producer, _owner: Option, } @@ -88,8 +88,8 @@ impl Producer { } state .entries - .retain(|id, entry| catalog.contributions.get(id) == Some(&entry.reference)); - for (id, reference) in &catalog.contributions { + .retain(|id, entry| catalog.include.get(id) == Some(&entry.reference)); + for (id, reference) in &catalog.include { if state.entries.contains_key(id) || !master::is_path_segment(id) { continue; } @@ -117,7 +117,7 @@ impl Producer { } } - /// Stop following every contribution for good. Closing the state under the same lock + /// Stop following every include for good. Closing the state under the same lock /// makes this terminal: a [`sync`](Self::sync) racing past its catalog await finds the /// state closed and cannot re-add entries or spawn follow tasks. pub fn clear(&self) { @@ -179,7 +179,7 @@ impl Producer { { continue; } - let uri = master::contribution_uri(parent, id, &instance.id, &rendition, query); + let uri = master::include_uri(parent, id, &instance.id, &rendition, query); match rendition.kind { Kind::Video => video.push(master::VideoVariant { uri, @@ -206,7 +206,7 @@ impl Producer { pub fn poll_rendition( &self, waiter: &kio::Waiter, - at: &super::route::Contribution, + at: &super::route::Include, kind: Kind, name: &str, ) -> Poll>>> { @@ -231,7 +231,7 @@ impl Producer { } } -/// Follows a contribution's instances into its [`Current`], watching each one's catalog. +/// Follows an include's instances into its [`Current`], watching each one's catalog. struct FollowInstances { instances: follow::Instances, current: kio::Producer, @@ -256,7 +256,7 @@ impl kio::Task for FollowInstances { let owner = self.context.spawner.lead(super::WatchCatalog::new( source, renditions.clone(), - super::Role::Contribution(self.context.root.consume()), + super::Role::Include(self.context.root.consume()), )); Current::Online(Arc::new(Instance { id, @@ -265,9 +265,9 @@ impl kio::Task for FollowInstances { })) } Ok(None) => Current::Offline, - // An authorization refusal is final: the contribution stays out and its URLs answer 403. + // An authorization refusal is final: the include stays out and its URLs answer 403. Err(err @ moq_mux::Error::Moq(moq_net::Error::Unauthorized)) => { - tracing::debug!(%err, "contribution refused"); + tracing::debug!(%err, "include refused"); if let Ok(mut state) = self.current.write() { *state = Current::Failed(err.into()); } @@ -282,7 +282,7 @@ impl kio::Task for FollowInstances { // Not routed yet, or refused otherwise: wait for the path's next announcement, which // the follower hands out, however long it takes. Until then nothing is listed. Err(err) => { - tracing::debug!(%err, "contribution not routed; waiting for its next announcement"); + tracing::debug!(%err, "include not routed; waiting for its next announcement"); match &*self.current.read() { Current::Pending => Current::Offline, _ => continue, @@ -307,16 +307,16 @@ mod tests { let _parent = origin.publish("room/live", Default::default()).unwrap(); let source = crate::resolved(&origin, "room/live").await; let mut catalog = Catalog::default(); - catalog.contributions.insert( + catalog.include.insert( "child".into(), - Contribution::new(moq_net::path::Relative::new("./child").unwrap()), + Include::new(moq_net::path::Relative::new("./child").unwrap()), ); let (spawner, _driver) = driver::Spawner::new(); - let contributions = Producer::new(origin.consume(), Duration::from_secs(16), spawner); - contributions.clear(); + let include = Producer::new(origin.consume(), Duration::from_secs(16), spawner); + include.clear(); // A watcher already past its catalog await syncs after the clear. - contributions.sync(&source, &catalog); - assert!(contributions.state.read().entries.is_empty()); + include.sync(&source, &catalog); + assert!(include.state.read().entries.is_empty()); } #[tokio::test(start_paused = true)] @@ -344,24 +344,24 @@ mod tests { json.update(moq_net::Timed::from(&catalog).at(moq_net::Timestamp::ZERO)) .unwrap(); catalog.video.renditions.clear(); - catalog.contributions.insert( + catalog.include.insert( "child".into(), - Contribution::new(moq_net::path::Relative::new("./child").unwrap()), + Include::new(moq_net::path::Relative::new("./child").unwrap()), ); let (spawner, driver) = driver::Spawner::new(); - let contributions = Producer::new(origin.consume(), Duration::from_secs(16), spawner); - contributions.sync(&source, &catalog); - let at = super::super::Contribution { + let include = Producer::new(origin.consume(), Duration::from_secs(16), spawner); + include.sync(&source, &catalog); + let at = super::super::Include { id: "child".into(), instance: child_id.to_string(), }; - let mut lookup = Box::pin(contributions.rendition(&at, Kind::Video, "v")); + let mut lookup = Box::pin(include.rendition(&at, Kind::Video, "v")); // The catalog has been read, but the driver has not yet polled its follow task. assert!(futures::poll!(lookup.as_mut()).is_pending()); let running = tokio::spawn(driver.run()); let rendition = lookup.await.unwrap().unwrap(); assert_eq!(rendition.name, "v"); - drop((rendition, contributions)); + drop((rendition, include)); running.await.unwrap(); } } diff --git a/rs/moq-hls/src/export/master.rs b/rs/moq-hls/src/export/master.rs index 0aa107bef89..53a38ef2ecb 100644 --- a/rs/moq-hls/src/export/master.rs +++ b/rs/moq-hls/src/export/master.rs @@ -46,7 +46,7 @@ pub(crate) fn rendition_uri(instance: &str, kind: Kind, name: &str, query: Optio uri } -pub(crate) fn contribution_uri( +pub(crate) fn include_uri( parent: &str, id: &str, instance: &str, @@ -54,7 +54,7 @@ pub(crate) fn contribution_uri( query: Option<&str>, ) -> String { let mut uri = format!( - "@{}/contribution/{}/{}/{}/@{}/media.m3u8", + "@{}/include/{}/{}/{}/@{}/media.m3u8", utf8_percent_encode(parent, PATH_SEGMENT), utf8_percent_encode(id, PATH_SEGMENT), rendition.kind.as_str(), @@ -340,7 +340,7 @@ mod tests { Route::parse(url.path()).unwrap(), Route { broadcast: "live".into(), - contribution: None, + include: None, resource: Resource::Media { instance: instance.into(), kind: Kind::Video, diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index de216f0fc45..3cf54874fc5 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -32,9 +32,9 @@ #[cfg(test)] mod archive_tests; -mod contributions; mod driver; mod grid; +mod include; pub mod master; mod mpd; mod playlist; @@ -56,7 +56,7 @@ pub(crate) use playlist::render_media; #[cfg(feature = "server")] pub(crate) use rendition::Demand; pub use rendition::{Kind, Rendition}; -pub use route::{Contribution, Resource, Route}; +pub use route::{Include, Resource, Route}; /// Backoff bounds for the initial catalog subscription. /// @@ -109,7 +109,7 @@ pub struct Broadcaster { instance: Arc, /// The current rendition set, reconciled from the catalog by the watcher task. renditions: renditions::Producer, - contributions: Option, + include: Option, /// Shared by every clone; its drop with the last one ends the catalog watcher. _guard: Arc, } @@ -117,7 +117,7 @@ pub struct Broadcaster { /// What the last [`Broadcaster`] clone releases. struct Guard { renditions: renditions::Producer, - contributions: Option, + include: Option, /// Ends the catalog watcher when dropped, or when [`replaced`](Broadcaster::replaced) takes it. watcher: Mutex>, } @@ -129,8 +129,8 @@ impl Drop for Guard { // media flowing, so its final segments are not truncated. Each rendition stops // following its media once no recording cursor holds it. self.renditions.clear(); - if let Some(contributions) = &self.contributions { - contributions.clear(); + if let Some(include) = &self.include { + include.clear(); } } } @@ -160,25 +160,25 @@ impl Broadcaster { .clone() .unwrap_or_else(moq_net::Instance::random); let (spawner, mut driver) = driver::Spawner::new(); - let contributions = origin.map(|origin| contributions::Producer::new(origin, config.window, spawner.clone())); + let include = origin.map(|origin| include::Producer::new(origin, config.window, spawner.clone())); let renditions = renditions::Producer::new(config.window, spawner); // The watcher owns its own producer clone; dropping the `Broadcaster` ends it so the // standing catalog subscription stops when nobody's serving from this broadcaster. let watcher = driver.lead(WatchCatalog::new( source, renditions.clone(), - Role::Root(contributions.clone().map(Box::new)), + Role::Root(include.clone().map(Box::new)), )); let broadcaster = Self { broadcast, instance: Arc::from(instance.as_str()), _guard: Arc::new(Guard { renditions: renditions.clone(), - contributions: contributions.clone(), + include: include.clone(), watcher: Mutex::new(Some(watcher)), }), renditions, - contributions, + include, }; (broadcaster, driver) } @@ -259,12 +259,12 @@ impl Broadcaster { #[cfg_attr(any(test, feature = "server"), kio::wrapper)] pub(crate) fn poll_advertised(&self, waiter: &kio::Waiter) -> Poll<()> { let own = self.renditions.poll_advertised(waiter); - let contribution = self - .contributions + let include = self + .include .as_ref() - .is_some_and(|contributions| contributions.poll_advertised(waiter).is_ready()); - // Contributions alone answer only while no own rendition could still be listed. - if own.is_ready() || (!self.renditions.listable() && contribution) { + .is_some_and(|include| include.poll_advertised(waiter).is_ready()); + // Includes alone answer only while no own rendition could still be listed. + if own.is_ready() || (!self.renditions.listable() && include) { Poll::Ready(()) } else { Poll::Pending @@ -303,9 +303,9 @@ impl Broadcaster { /// holding different tokens; a credential in `Config` would embed one viewer's in /// another's playlist. /// - /// A broadcaster obtained from `Server` also lists contribution renditions from their + /// A broadcaster obtained from `Server` also lists include renditions from their /// catalogs, starting their media only on request. `Broadcaster::new` exports the own - /// renditions only, so a recorder never demands contributions. + /// renditions only, so a recorder never demands includes. /// /// Lists only enabled own renditions a player can start, i.e. ones listing at least one segment, /// so an early render may list audio alone, or nothing at all. A disabled rendition (catalog `enabled: false`) is left out until @@ -339,27 +339,27 @@ impl Broadcaster { }), } } - if let Some(contributions) = &self.contributions { - let (extra_video, extra_audio) = contributions.variants(&self.instance, query); + if let Some(include) = &self.include { + let (extra_video, extra_audio) = include.variants(&self.instance, query); video.extend(extra_video); audio.extend(extra_audio); } (video, audio) } - /// The contribution rendition `at` names, once the catalog is read. + /// The include rendition `at` names, once the catalog is read. #[cfg(feature = "server")] #[kio::wrapper] - pub(crate) fn poll_contribution( + pub(crate) fn poll_include( &self, waiter: &kio::Waiter, - at: &Contribution, + at: &Include, kind: Kind, name: &str, ) -> Poll>>> { ready!(self.renditions.poll_catalogued(waiter)); - match &self.contributions { - Some(contributions) => contributions.poll_rendition(waiter, at, kind, name), + match &self.include { + Some(include) => include.poll_rendition(waiter, at, kind, name), None => Poll::Ready(Ok(None)), } } @@ -496,8 +496,8 @@ impl Broadcaster { let watcher = self._guard.watcher.lock().unwrap().take(); drop(watcher); self.renditions.cut(); - if let Some(contributions) = &self.contributions { - contributions.clear(); + if let Some(include) = &self.include { + include.clear(); } } @@ -513,11 +513,11 @@ impl Broadcaster { /// What a catalog watcher reconciles besides its own rendition set. enum Role { - /// A root broadcast, following its catalog's contributions when an HTTP server serves it. - Root(Option>), - /// A contribution included in a root broadcast. Its renditions take the root catalog's - /// `media`, so they share the root's timeline and grid whatever the contribution declares. - Contribution(kio::Consumer), + /// A root broadcast, following its catalog's includes when an HTTP server serves it. + Root(Option>), + /// A broadcast included in a root broadcast. Its renditions take the root catalog's + /// `media`, so they share the root's timeline and grid whatever the include declares. + Include(kio::Consumer), } /// Follows a broadcast's catalog into its rendition set, as a driver task. @@ -547,7 +547,7 @@ enum Watch { Backoff(kio::clock::Sleep), Reading { consumer: catalog::Consumer<()>, - /// A contribution's latest catalog, re-synced when the root's media changes. + /// An include's latest catalog, re-synced when the root's media changes. latest: Option, }, } @@ -588,7 +588,7 @@ impl WatchCatalog { err.into() })); } - if let (Role::Contribution(root), Some(catalog)) = (&self.role, &latest) + if let (Role::Include(root), Some(catalog)) = (&self.role, &latest) && let Poll::Ready(Ok(())) = root.poll(waiter, |media| match **media != catalog.media { true => Poll::Ready(()), false => Poll::Pending, @@ -601,12 +601,12 @@ impl WatchCatalog { /// Reconcile the renditions with `catalog`. fn sync(&mut self, mut catalog: catalog::hang::Catalog) { match &self.role { - Role::Root(Some(contributions)) => contributions.sync(&self.source, &catalog), + Role::Root(Some(include)) => include.sync(&self.source, &catalog), Role::Root(None) => {} - Role::Contribution(root) => catalog.media = *root.read(), + Role::Include(root) => catalog.media = *root.read(), } self.renditions.sync(&self.source, &catalog); - if let (Role::Contribution(_), Watch::Reading { latest, .. }) = (&self.role, &mut self.state) { + if let (Role::Include(_), Watch::Reading { latest, .. }) = (&self.role, &mut self.state) { *latest = Some(catalog); } } @@ -615,11 +615,11 @@ impl WatchCatalog { fn finish(&self, result: crate::Result<()>) { let failed = result.is_err(); self.renditions.finish(result); - // The root catalog lists the contributions: once it fails, stop following and advertising + // The root catalog lists the includes: once it fails, stop following and advertising // them too. A clean end freezes the final catalog, which keeps its entries, as the own // renditions keep their final set. - if failed && let Role::Root(Some(contributions)) = &self.role { - contributions.clear(); + if failed && let Role::Root(Some(include)) = &self.role { + include.clear(); } } } diff --git a/rs/moq-hls/src/export/route.rs b/rs/moq-hls/src/export/route.rs index 122d1ea33da..230e39cfb2b 100644 --- a/rs/moq-hls/src/export/route.rs +++ b/rs/moq-hls/src/export/route.rs @@ -12,26 +12,26 @@ pub struct Route { /// The broadcast path, percent-decoded. An embedder that scopes its origin rewrites /// this relative to that scope before looking it up. pub broadcast: String, - /// The contribution ID and publisher instance, when the resource belongs to one. - pub contribution: Option, + /// The include ID and publisher instance, when the resource belongs to one. + pub include: Option, /// The resource requested under the broadcast. pub resource: Resource, } -/// The contribution catalog and stream named inside a broadcast's instance URL. +/// The include catalog and stream named inside a broadcast's instance URL. /// -/// A contribution's resource nests under the served broadcast as -/// `{broadcast}/@{instance}/contribution/{id}/{kind}/{rendition}/@{contribution-instance}/` +/// An include's resource nests under the served broadcast as +/// `{broadcast}/@{instance}/include/{id}/{kind}/{rendition}/@{include-instance}/` /// followed by the [`Resource`] file (`media.m3u8`, `init.{hash}.mp4`, or `seg/{segment}.m4s`). /// The broadcast's own `@{instance}` comes first, so [`Route::broadcast`] stays the parent's -/// path and a path-based policy check covers its contributions. A denied contribution answers +/// path and a path-based policy check covers its includes. A denied include answers /// `403`. #[derive(Clone, Debug, PartialEq, Eq)] #[non_exhaustive] -pub struct Contribution { - /// The contribution ID in the parent catalog, percent-decoded. +pub struct Include { + /// The include ID in the parent catalog, percent-decoded. pub id: String, - /// The contribution's publisher instance, percent-decoded and without its `@`. + /// The include's publisher instance, percent-decoded and without its `@`. pub instance: String, } @@ -114,23 +114,23 @@ impl Route { _ => 0, }; let end = parts.len() - tail; - let contribution = if tail != 0 { + let include = if tail != 0 { match &parts[..end] { [.., parent, directory, id, kind, _, child] - if directory == "contribution" + if directory == "include" && instance_id(parent).is_some() && Kind::parse(kind).is_some() && instance_id(child).is_some() => { - // Every slot has the contribution shape; otherwise the ordinary arms below + // Every slot has the include shape; otherwise the ordinary arms below // parse the untouched parts as a longer broadcast path. - let contribution = Contribution { + let include = Include { id: id.clone(), instance: instance_id(child)?, }; parts.remove(end - 1); parts.drain(end - 5..end - 3); - Some(contribution) + Some(include) } _ => None, } @@ -175,7 +175,7 @@ impl Route { } Some(Self { broadcast: broadcast.join("/"), - contribution, + include, resource, }) } @@ -206,7 +206,7 @@ mod tests { Route::parse("/project/live/@run/video/cam%231%2Fmain%3Falt/media.m3u8"), Some(Route { broadcast: "project/live".to_string(), - contribution: None, + include: None, resource: Resource::Media { instance: "run".to_string(), kind: Kind::Video, @@ -315,16 +315,16 @@ mod tests { } #[test] - fn contribution_resources_keep_the_parent_policy_path() { + fn include_resources_keep_the_parent_policy_path() { for suffix in ["media.m3u8", "init.abcd.mp4", "seg/abcd.7.m4s"] { let route = Route::parse(&format!( - "/room/live/@parent/contribution/a%2Fb/video/same%2Fname/@child/{suffix}" + "/room/live/@parent/include/a%2Fb/video/same%2Fname/@child/{suffix}" )) .unwrap(); assert_eq!(route.broadcast, "room/live"); assert_eq!( - route.contribution, - Some(Contribution { + route.include, + Some(Include { id: "a/b".into(), instance: "child".into() }) @@ -337,14 +337,14 @@ mod tests { }; assert_eq!(instance, "parent"); } - let own = Route::parse("/room/@parent/contribution/id/@child/video/main/media.m3u8").unwrap(); - assert_eq!(own.broadcast, "room/@parent/contribution/id"); - assert!(own.contribution.is_none()); - assert!(Route::parse("/room%2Flive/@parent/contribution/id/video/main/@child/media.m3u8").is_none()); - // Contribution-shaped but for the child slot: an ordinary URL on a longer broadcast path. - let own = Route::parse("/room/@parent/contribution/id/video/@run/audio/seg/media.m3u8").unwrap(); - assert_eq!(own.broadcast, "room/@parent/contribution/id/video"); - assert!(own.contribution.is_none()); + let own = Route::parse("/room/@parent/include/id/@child/video/main/media.m3u8").unwrap(); + assert_eq!(own.broadcast, "room/@parent/include/id"); + assert!(own.include.is_none()); + assert!(Route::parse("/room%2Flive/@parent/include/id/video/main/@child/media.m3u8").is_none()); + // Include-shaped but for the child slot: an ordinary URL on a longer broadcast path. + let own = Route::parse("/room/@parent/include/id/video/@run/audio/seg/media.m3u8").unwrap(); + assert_eq!(own.broadcast, "room/@parent/include/id/video"); + assert!(own.include.is_none()); match own.resource { Resource::Media { instance, diff --git a/rs/moq-hls/src/server/contributions_tests.rs b/rs/moq-hls/src/server/include_tests.rs similarity index 76% rename from rs/moq-hls/src/server/contributions_tests.rs rename to rs/moq-hls/src/server/include_tests.rs index 5bfdc1ed23e..9eb3841ab26 100644 --- a/rs/moq-hls/src/server/contributions_tests.rs +++ b/rs/moq-hls/src/server/include_tests.rs @@ -2,7 +2,7 @@ use std::time::Duration; use axum::body::Body; use axum::http::{Request, StatusCode}; -use hang::catalog::{AudioCodec, AudioConfig, Contribution, Join, VideoCodec, VideoConfig}; +use hang::catalog::{AudioCodec, AudioConfig, Include, Join, VideoCodec, VideoConfig}; use moq_mux::catalog::hang::Catalog; use moq_net::{Instance, Timestamp, track}; use tower::ServiceExt; @@ -101,29 +101,29 @@ async fn master(server: &Server, contains: &str, present: bool) -> String { fn parent_catalog() -> Catalog { let mut catalog = catalog(); catalog.audio.renditions.get_mut("sound").unwrap().track = Some("audio".into()); - catalog.contributions.insert( + catalog.include.insert( "rung/a".into(), - Contribution::new(moq_net::path::Relative::new("./ladder").unwrap()), + Include::new(moq_net::path::Relative::new("./ladder").unwrap()), ); catalog } #[tokio::test(start_paused = true)] -async fn a_contribution_does_not_hide_the_parents_first_variants() { +async fn an_include_does_not_hide_the_parents_first_variants() { let origin = moq_tokio::origin::spawn(); let root = Instance::random(); let child = Instance::random(); let parent = publish(&origin, "room/live", &root, &parent_catalog()); - let _contribution = publish(&origin, "room/ladder", &child, &catalog()); + let _include = publish(&origin, "room/ladder", &child, &catalog()); let server = Server::new(origin.consume(), Default::default()).unwrap(); let broadcaster = server.broadcaster("room/live").await.unwrap(); - let at = crate::export::Contribution { + let at = crate::export::Include { id: "rung/a".into(), instance: child.to_string(), }; assert!( broadcaster - .contribution(&at, crate::export::Kind::Video, "same") + .include(&at, crate::export::Kind::Video, "same") .await .unwrap() .is_some() @@ -135,7 +135,7 @@ async fn a_contribution_does_not_hide_the_parents_first_variants() { let (status, body) = pending.await; assert_eq!(status, StatusCode::OK); assert!(body.contains(&format!("@{root}/video/same/media.m3u8"))); - assert!(body.contains(&format!("contribution/rung%2Fa/video/same/@{child}/media.m3u8"))); + assert!(body.contains(&format!("include/rung%2Fa/video/same/@{child}/media.m3u8"))); } #[tokio::test(start_paused = true)] @@ -146,20 +146,20 @@ async fn an_idle_predecessor_does_not_strand_a_requested_reconfigure() { let parent = publish(&origin, "room/live", &root, &parent_catalog()); frames(&parent.video, 0); let mut value = catalog(); - let mut contribution = publish(&origin, "room/ladder", &child, &value); - frames(&contribution.video, 0); + let mut include = publish(&origin, "room/ladder", &child, &value); + frames(&include.video, 0); let server = Server::new(origin.consume(), Default::default()).unwrap(); - master(&server, "contribution/", true).await; - let uri = format!("/room/live/@{root}/contribution/rung%2Fa/video/same/@{child}/media.m3u8"); + master(&server, "include/", true).await; + let uri = format!("/room/live/@{root}/include/rung%2Fa/video/same/@{child}/media.m3u8"); assert_eq!(request(&server, &uri).await.0, StatusCode::OK); - let next = contribution + let next = include .publication .create_track("next", hang::container::track_info(1)) .unwrap(); let video = value.video.renditions.get_mut("same").unwrap(); video.track = Some("next".into()); video.coded_width = Some(640); - contribution + include .catalog .update(moq_net::Timed::from(&value).at(Timestamp::ZERO)) .unwrap(); @@ -179,22 +179,22 @@ async fn an_idle_predecessor_does_not_strand_a_requested_reconfigure() { }) .await .expect("the requested replacement must start after the idle predecessor releases"); - assert_eq!(contribution.video.demand().wanted(), None); + assert_eq!(include.video.demand().wanted(), None); frames(&next, 3); drop(held); } #[tokio::test(start_paused = true)] -async fn a_finished_parent_catalog_keeps_its_contributions() { +async fn a_finished_parent_catalog_keeps_its_includes() { let origin = moq_tokio::origin::spawn(); let root = Instance::random(); let child = Instance::random(); let mut parent = publish(&origin, "room/live", &root, &parent_catalog()); frames(&parent.video, 0); frames(&parent.audio, 0); - let _contribution = publish(&origin, "room/ladder", &child, &catalog()); + let _include = publish(&origin, "room/ladder", &child, &catalog()); let server = Server::new(origin.consume(), Default::default()).unwrap(); - let listed = format!("contribution/rung%2Fa/video/same/@{child}"); + let listed = format!("include/rung%2Fa/video/same/@{child}"); master(&server, &listed, true).await; // A clean end freezes the final catalog, entries included. parent.catalog.finish().unwrap(); @@ -203,7 +203,7 @@ async fn a_finished_parent_catalog_keeps_its_contributions() { } #[tokio::test(start_paused = true)] -async fn a_failed_parent_catalog_stops_its_contributions() { +async fn a_failed_parent_catalog_stops_its_includes() { let origin = moq_tokio::origin::spawn(); let root = Instance::random(); let child = Instance::random(); @@ -215,35 +215,27 @@ async fn a_failed_parent_catalog_stops_its_contributions() { } = publish(&origin, "room/live", &root, &parent_catalog()); frames(&video, 0); frames(&audio, 0); - let contribution = publish(&origin, "room/ladder", &child, &catalog()); + let include = publish(&origin, "room/ladder", &child, &catalog()); let server = Server::new(origin.consume(), Default::default()).unwrap(); - master(&server, "contribution/", true).await; - let uri = format!("/room/live/@{root}/contribution/rung%2Fa/video/same/@{child}/media.m3u8"); + master(&server, "include/", true).await; + let uri = format!("/room/live/@{root}/include/rung%2Fa/video/same/@{child}/media.m3u8"); parent_catalog_track.abort(moq_net::Error::Cancel).unwrap(); let deadline = kio::clock::now() + Duration::from_secs(10); - // A live contribution's playlist waits for media this test never writes, so bound each request. + // A live include's playlist waits for media this test never writes, so bound each request. while !matches!( kio::clock::timeout(Duration::from_secs(1), request(&server, &uri)).await, Ok((StatusCode::NOT_FOUND, _)) ) { - assert!( - kio::clock::now() < deadline, - "the contribution outlived its parent catalog" - ); + assert!(kio::clock::now() < deadline, "the include outlived its parent catalog"); kio::clock::sleep(Duration::from_millis(10)).await; } - assert!( - !request(&server, "/room/live/master.m3u8") - .await - .1 - .contains("contribution/") - ); - let mut catalog = contribution.catalog.demand(); + assert!(!request(&server, "/room/live/master.m3u8").await.1.contains("include/")); + let mut catalog = include.catalog.demand(); kio::clock::timeout(Duration::from_secs(1), async { while catalog.wanted_changed().await.unwrap().is_some() {} }) .await - .expect("the contribution catalog is released"); + .expect("the include catalog is released"); } #[tokio::test(start_paused = true)] @@ -253,21 +245,21 @@ async fn idle_release_waits_out_the_playlist_window() { let child = Instance::random(); let parent = publish(&origin, "room/live", &root, &parent_catalog()); frames(&parent.video, 0); - let contribution = publish(&origin, "room/ladder", &child, &catalog()); - frames(&contribution.video, 0); + let include = publish(&origin, "room/ladder", &child, &catalog()); + frames(&include.video, 0); let server = Server::new(origin.consume(), Default::default()).unwrap(); - master(&server, "contribution/", true).await; - let uri = format!("/room/live/@{root}/contribution/rung%2Fa/video/same/@{child}/media.m3u8"); + master(&server, "include/", true).await; + let uri = format!("/room/live/@{root}/include/rung%2Fa/video/same/@{child}/media.m3u8"); assert_eq!(request(&server, &uri).await.0, StatusCode::OK); let settle = || kio::clock::sleep(Duration::from_millis(10)); settle().await; // Three target durations (12 s) would forget rows the 16 s window still lists. tokio::time::advance(Duration::from_secs(13)).await; settle().await; - assert!(contribution.video.demand().wanted().is_some()); + assert!(include.video.demand().wanted().is_some()); tokio::time::advance(Duration::from_secs(8)).await; settle().await; - assert_eq!(contribution.video.demand().wanted(), None); + assert_eq!(include.video.demand().wanted(), None); } #[tokio::test(start_paused = true)] @@ -278,26 +270,26 @@ async fn idle_release_keeps_an_ended_playlists_inherited_segments() { let parent = publish(&origin, "room/live", &root, &parent_catalog()); frames(&parent.video, 0); let mut value = catalog(); - let mut contribution = publish(&origin, "room/ladder", &child, &value); - frames(&contribution.video, 0); + let mut include = publish(&origin, "room/ladder", &child, &value); + frames(&include.video, 0); let server = Server::new(origin.consume(), Default::default()).unwrap(); - master(&server, "contribution/", true).await; - let uri = format!("/room/live/@{root}/contribution/rung%2Fa/video/same/@{child}/media.m3u8"); + master(&server, "include/", true).await; + let uri = format!("/room/live/@{root}/include/rung%2Fa/video/same/@{child}/media.m3u8"); assert_eq!(request(&server, &uri).await.0, StatusCode::OK); // Reconfigure onto another track; the predecessor ends with its own track. - let next = contribution + let next = include .publication .create_track("next", hang::container::track_info(1)) .unwrap(); let video = value.video.renditions.get_mut("same").unwrap(); video.track = Some("next".into()); video.coded_width = Some(640); - contribution + include .catalog .update(moq_net::Timed::from(&value).at(Timestamp::ZERO)) .unwrap(); master(&server, "RESOLUTION=640x240", true).await; - contribution.video.finish().unwrap(); + include.video.finish().unwrap(); let held = server .router() .oneshot(Request::builder().uri(&uri).body(Body::empty()).unwrap()) @@ -331,12 +323,12 @@ async fn idle_release_keeps_an_ended_playlists_inherited_segments() { assert_eq!(after, ended); // The finished window keeps the track pin its retained groups are read through. let broadcaster = server.broadcaster("room/live").await.unwrap(); - let at = crate::export::Contribution { + let at = crate::export::Include { id: "rung/a".into(), instance: child.to_string(), }; let rendition = broadcaster - .contribution(&at, crate::export::Kind::Video, "same") + .include(&at, crate::export::Kind::Video, "same") .await .unwrap() .unwrap(); @@ -344,7 +336,7 @@ async fn idle_release_keeps_an_ended_playlists_inherited_segments() { } #[tokio::test(start_paused = true)] -async fn a_contribution_rendition_whose_broadcast_failed_is_not_listed() { +async fn an_include_rendition_whose_broadcast_failed_is_not_listed() { let origin = moq_tokio::origin::spawn(); let root = Instance::random(); let parent = publish(&origin, "room/live", &root, &parent_catalog()); @@ -355,7 +347,7 @@ async fn a_contribution_rendition_whose_broadcast_failed_is_not_listed() { let mut value = catalog(); value.audio.renditions.clear(); value.video.renditions.get_mut("same").unwrap().broadcast = Some(moq_net::path::Relative::new("./other").unwrap()); - let _contribution = publish(&origin, "room/ladder", &child, &value); + let _include = publish(&origin, "room/ladder", &child, &value); let server = Server::new(origin.consume(), Default::default()).unwrap(); master(&server, &format!("@{root}/video/same"), true).await; // Not a denial, but its media still can't be read. @@ -366,11 +358,11 @@ async fn a_contribution_rendition_whose_broadcast_failed_is_not_listed() { .reject(moq_net::Error::Unroutable); kio::clock::sleep(Duration::from_secs(1)).await; let listed = master(&server, &format!("@{root}/video/same"), true).await; - assert!(!listed.contains("contribution/"), "{listed}"); + assert!(!listed.contains("include/"), "{listed}"); } #[tokio::test(start_paused = true)] -async fn a_contribution_answers_the_master_when_no_own_rendition_is_listable() { +async fn an_include_answers_the_master_when_no_own_rendition_is_listable() { let origin = moq_tokio::origin::spawn(); let root = Instance::random(); let child = Instance::random(); @@ -378,16 +370,16 @@ async fn a_contribution_answers_the_master_when_no_own_rendition_is_listable() { value.video.renditions.get_mut("same").unwrap().enabled = false; value.audio.renditions.get_mut("sound").unwrap().enabled = false; let _parent = publish(&origin, "room/live", &root, &value); - let _contribution = publish(&origin, "room/ladder", &child, &catalog()); + let _include = publish(&origin, "room/ladder", &child, &catalog()); let server = Server::new(origin.consume(), Default::default()).unwrap(); let broadcaster = server.broadcaster("room/live").await.unwrap(); - let at = crate::export::Contribution { + let at = crate::export::Include { id: "rung/a".into(), instance: child.to_string(), }; assert!( broadcaster - .contribution(&at, crate::export::Kind::Video, "same") + .include(&at, crate::export::Kind::Video, "same") .await .unwrap() .is_some() @@ -397,30 +389,30 @@ async fn a_contribution_answers_the_master_when_no_own_rendition_is_listable() { let (status, body) = request(&server, "/room/live/master.m3u8").await; assert_eq!(status, StatusCode::OK, "{body}"); assert!( - body.contains(&format!("contribution/rung%2Fa/video/same/@{child}")), + body.contains(&format!("include/rung%2Fa/video/same/@{child}")), "{body}" ); assert!(kio::clock::now() - start < Duration::from_secs(1)); } #[tokio::test(start_paused = true)] -async fn a_contribution_rendition_is_listed_once_its_broadcast_resolves() { +async fn an_include_rendition_is_listed_once_its_broadcast_resolves() { let origin = moq_tokio::origin::spawn(); let root = Instance::random(); let parent = publish(&origin, "room/live", &root, &parent_catalog()); frames(&parent.video, 0); frames(&parent.audio, 0); - // The contribution's only rendition reads a sibling whose route has not answered yet. + // The include's only rendition reads a sibling whose route has not answered yet. let other = origin.requests("room/other").unwrap(); let child = Instance::random(); let mut value = catalog(); value.audio.renditions.clear(); value.video.renditions.get_mut("same").unwrap().broadcast = Some(moq_net::path::Relative::new("./other").unwrap()); - let _contribution = publish(&origin, "room/ladder", &child, &value); + let _include = publish(&origin, "room/ladder", &child, &value); let server = Server::new(origin.consume(), Default::default()).unwrap(); let listed = master(&server, &format!("@{root}/video/same"), true).await; assert!( - !listed.contains("contribution/"), + !listed.contains("include/"), "a pending binding may yet be denied: {listed}" ); let request = kio::clock::timeout(Duration::from_secs(5), other.requested_broadcast()) @@ -428,7 +420,7 @@ async fn a_contribution_rendition_is_listed_once_its_broadcast_resolves() { .expect("the binding never asked") .unwrap(); request.serve(moq_net::broadcast::Info::new().produce()); - master(&server, &format!("contribution/rung%2Fa/video/same/@{child}"), true).await; + master(&server, &format!("include/rung%2Fa/video/same/@{child}"), true).await; } #[tokio::test(start_paused = true)] @@ -442,29 +434,29 @@ async fn listing_is_catalog_only_and_requests_own_the_lazy_media_lifetime() { frames(&parent.audio, 0); let mut child_catalog = catalog(); child_catalog.audio.renditions.get_mut("sound").unwrap().track = Some("audio".into()); - let contribution = publish(&origin, "room/ladder", &child, &child_catalog); + let include = publish(&origin, "room/ladder", &child, &child_catalog); let server = Server::new(origin.consume(), Default::default()).unwrap(); - let prefix = format!("@{root}/contribution/rung%2Fa"); + let prefix = format!("@{root}/include/rung%2Fa"); let listed = master(&server, &prefix, true).await; assert!(listed.contains(&format!("@{root}/video/same/media.m3u8?jwt=viewer"))); assert!(listed.contains(&format!("{prefix}/video/same/@{child}/media.m3u8?jwt=viewer"))); assert!(listed.contains("NAME=\"rung/a/sound\"")); - assert_eq!(contribution.video.demand().wanted(), None); - assert_eq!(contribution.audio.demand().wanted(), None); - assert!(contribution.catalog.demand().wanted().is_some()); + assert_eq!(include.video.demand().wanted(), None); + assert_eq!(include.audio.demand().wanted(), None); + assert!(include.catalog.demand().wanted().is_some()); let uri = format!("/room/live/{prefix}/video/same/@{child}/media.m3u8"); let mut pending = Box::pin(request(&server, &uri)); assert!(futures::poll!(pending.as_mut()).is_pending()); - let mut demand = contribution.video.demand(); + let mut demand = include.video.demand(); while demand.wanted_changed().await.unwrap().is_none() {} - assert_eq!(contribution.audio.demand().wanted(), None); + assert_eq!(include.audio.demand().wanted(), None); // The idle window is 20 s (the 16 s playlist window plus TARGETDURATION 4), and this first // encode is slower than all of it. tokio::time::advance(Duration::from_secs(21)).await; assert!(futures::poll!(pending.as_mut()).is_pending()); - assert!(contribution.video.demand().wanted().is_some()); - frames(&contribution.video, 0); + assert!(include.video.demand().wanted().is_some()); + frames(&include.video, 0); let (status, playlist) = pending.await; assert_eq!(status, StatusCode::OK, "{playlist}"); assert!(playlist.contains("#EXT-X-MEDIA-SEQUENCE:0")); @@ -478,35 +470,30 @@ async fn listing_is_catalog_only_and_requests_own_the_lazy_media_lifetime() { assert_eq!(held.status(), StatusCode::OK); tokio::time::advance(Duration::from_secs(21)).await; assert!( - contribution.video.demand().wanted().is_some(), + include.video.demand().wanted().is_some(), "a slow body still holds demand" ); drop(held); // The reload window starts at completion, and another request renews it. tokio::time::advance(Duration::from_secs(19)).await; - assert!(contribution.video.demand().wanted().is_some()); + assert!(include.video.demand().wanted().is_some()); assert_eq!(request(&server, &uri).await.0, StatusCode::OK); tokio::time::advance(Duration::from_secs(19)).await; - assert!(contribution.video.demand().wanted().is_some()); + assert!(include.video.demand().wanted().is_some()); tokio::time::advance(Duration::from_secs(2)).await; while demand.wanted_changed().await.unwrap().is_some() {} - assert_eq!(contribution.audio.demand().wanted(), None); + assert_eq!(include.audio.demand().wanted(), None); // A later request creates fresh demand and indexes later segments on the same grid. let mut resumed = Box::pin(request(&server, &uri)); assert!(futures::poll!(resumed.as_mut()).is_pending()); while demand.wanted_changed().await.unwrap().is_none() {} - frames(&contribution.video, 3); + frames(&include.video, 3); let (status, playlist) = resumed.await; assert_eq!(status, StatusCode::OK); assert!(playlist.contains("#EXT-X-MEDIA-SEQUENCE:3"), "{playlist}"); - assert_eq!(contribution.audio.demand().wanted(), None); - // Neither the DASH manifest nor the recorder cursor expands the contribution. - assert!( - !request(&server, "/room/live/manifest.mpd") - .await - .1 - .contains("contribution") - ); + assert_eq!(include.audio.demand().wanted(), None); + // Neither the DASH manifest nor the recorder cursor expands the include. + assert!(!request(&server, "/room/live/manifest.mpd").await.1.contains("include")); let broadcaster = server.broadcaster("room/live").await.unwrap(); let mut recorder = broadcaster.renditions(); for _ in 0..2 { @@ -525,28 +512,28 @@ async fn late_instances_replace_unpinned_entries_and_do_not_replace_pins() { let first = Instance::random(); let second = Instance::random(); let mut value = parent_catalog(); - let mut pin = value.contributions["rung/a"].clone(); + let mut pin = value.include["rung/a"].clone(); pin.instance = Some(first.clone()); - value.contributions.insert("pinned".into(), pin); + value.include.insert("pinned".into(), pin); let parent = publish(&origin, "room/live", &root, &value); frames(&parent.video, 0); frames(&parent.audio, 0); let server = Server::new(origin.consume(), Default::default()).unwrap(); - master(&server, "contribution/", false).await; + master(&server, "include/", false).await; let old = publish(&origin, "room/ladder", &first, &catalog()); - let old_uri = format!("contribution/rung%2Fa/video/same/@{first}"); + let old_uri = format!("include/rung%2Fa/video/same/@{first}"); let listed = master(&server, &old_uri, true).await; - assert!(listed.contains(&format!("contribution/pinned/video/same/@{first}"))); + assert!(listed.contains(&format!("include/pinned/video/same/@{first}"))); assert_eq!(old.video.demand().wanted(), None); old.publication.unannounce(); - master(&server, "contribution/", false).await; + master(&server, "include/", false).await; old.publication .announce(moq_net::origin::Route::default().with_instance(first.clone(), 0)) .unwrap(); - master(&server, &format!("contribution/pinned/video/same/@{first}"), true).await; + master(&server, &format!("include/pinned/video/same/@{first}"), true).await; let new = publish(&origin, "room/ladder", &second, &catalog()); - let listed = master(&server, &format!("contribution/rung%2Fa/video/same/@{second}"), true).await; - assert!(!listed.contains("contribution/pinned/")); + let listed = master(&server, &format!("include/rung%2Fa/video/same/@{second}"), true).await; + assert!(!listed.contains("include/pinned/")); assert!(!listed.contains(&old_uri)); assert_eq!(new.video.demand().wanted(), None); assert_eq!( @@ -556,59 +543,59 @@ async fn late_instances_replace_unpinned_entries_and_do_not_replace_pins() { StatusCode::NOT_FOUND ); new.publication.unannounce(); - master(&server, &format!("contribution/pinned/video/same/@{first}"), true).await; + master(&server, &format!("include/pinned/video/same/@{first}"), true).await; } #[tokio::test(start_paused = true)] #[tracing_test::traced_test] -async fn contributions_take_the_roots_grid_and_denied_ones_are_not_advertised() { +async fn includes_take_the_roots_grid_and_denied_ones_are_not_advertised() { let origin = moq_tokio::origin::spawn(); let root = Instance::random(); let parent = publish(&origin, "room/live", &root, &parent_catalog()); frames(&parent.video, 0); frames(&parent.audio, 0); let child = Instance::random(); - // The contribution declares its own interval, which HLS ignores for the root's. + // The include declares its own interval, which HLS ignores for the root's. let mut value = catalog(); value.media.join = Join::new(Duration::from_secs(1)); - let contribution = publish(&origin, "room/ladder", &child, &value); + let include = publish(&origin, "room/ladder", &child, &value); let server = Server::new(origin.consume(), Default::default()).unwrap(); - master(&server, "contribution/", true).await; + master(&server, "include/", true).await; let patterns = ["room/live".parse::().unwrap()].into_iter().collect(); let denied = Server::new(origin.consume().scope("", &patterns).unwrap(), Default::default()).unwrap(); - master(&denied, "contribution/", false).await; + master(&denied, "include/", false).await; for resource in ["media.m3u8", "init.abcd.mp4", "seg/abcd.0.m4s"] { assert_eq!( request( &denied, - &format!("/room/live/@{root}/contribution/rung%2Fa/video/same/@{child}/{resource}") + &format!("/room/live/@{root}/include/rung%2Fa/video/same/@{child}/{resource}") ) .await .0, StatusCode::FORBIDDEN ); } - assert_eq!(contribution.video.demand().wanted(), None); - let uri = format!("/room/live/@{root}/contribution/rung%2Fa/video/same/@{child}/media.m3u8"); + assert_eq!(include.video.demand().wanted(), None); + let uri = format!("/room/live/@{root}/include/rung%2Fa/video/same/@{child}/media.m3u8"); let mut pending = Box::pin(request(&server, &uri)); assert!(futures::poll!(pending.as_mut()).is_pending()); - let mut demand = contribution.video.demand(); + let mut demand = include.video.demand(); kio::clock::timeout(Duration::from_secs(10), async { while demand.wanted_changed().await.unwrap().is_none() {} }) .await - .expect("the request never demanded the contribution's media"); - frames(&contribution.video, 0); + .expect("the request never demanded the include's media"); + frames(&include.video, 0); let (status, playlist) = kio::clock::timeout(Duration::from_secs(10), pending) .await - .expect("the contribution never listed a segment"); + .expect("the include never listed a segment"); assert_eq!(status, StatusCode::OK, "{playlist}"); // Twice the root's 2 s interval; its own 1 s interval would give 2. assert!(playlist.contains("#EXT-X-TARGETDURATION:4"), "{playlist}"); } #[tokio::test(start_paused = true)] -async fn a_refused_contribution_is_listed_once_announced() { +async fn a_refused_include_is_listed_once_announced() { let origin = moq_tokio::origin::spawn(); let root = Instance::random(); let parent = publish(&origin, "room/live", &root, &parent_catalog()); @@ -626,7 +613,7 @@ async fn a_refused_contribution_is_listed_once_announced() { }; let own = format!("@{root}/video/same"); let (listed, ()) = futures::join!(master(&server, &own, true), refuse); - assert!(!listed.contains("contribution/"), "{listed}"); + assert!(!listed.contains("include/"), "{listed}"); // The refusing route is not asked again on a timer. assert!( kio::clock::timeout(Duration::from_secs(30), claim.requested_broadcast()) @@ -635,6 +622,6 @@ async fn a_refused_contribution_is_listed_once_announced() { ); drop(claim); let child = Instance::random(); - let _contribution = publish(&origin, "room/ladder", &child, &catalog()); - master(&server, &format!("contribution/rung%2Fa/video/same/@{child}"), true).await; + let _include = publish(&origin, "room/ladder", &child, &catalog()); + master(&server, &format!("include/rung%2Fa/video/same/@{child}"), true).await; } diff --git a/rs/moq-hls/src/server/mod.rs b/rs/moq-hls/src/server/mod.rs index 98399973d82..044295ab852 100644 --- a/rs/moq-hls/src/server/mod.rs +++ b/rs/moq-hls/src/server/mod.rs @@ -62,7 +62,7 @@ //! ``` #[cfg(test)] -mod contributions_tests; +mod include_tests; mod routes; use std::collections::HashMap; diff --git a/rs/moq-hls/src/server/routes.rs b/rs/moq-hls/src/server/routes.rs index e6d9261eb2d..d3021e0ef4e 100644 --- a/rs/moq-hls/src/server/routes.rs +++ b/rs/moq-hls/src/server/routes.rs @@ -213,15 +213,12 @@ async fn rendition_for(server: &Server, at: At<'_>) -> crate::Result