diff --git a/doc/concept/hang.md b/doc/concept/hang.md index ca042523e23..dec3293498c 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -74,7 +74,7 @@ A few things the catalog can express beyond decoder config: - **Preference.** A video rendition may carry a signed `preference`, default `0`. A player keeps only the highest preference it can decode, then picks by size and bitrate within it, as do the single-rendition egresses (RTMP play, WHEP, FLV, the transcoder's source). A publisher that adds its own H.264 copy of an H.265 source marks the copy `-1`, so only a viewer that can't decode H.265 pulls it. Picking a rendition by name still overrides it. The field is written only when nonzero. - **Join interval.** The root `sync.interval` promises that every audio and video track starts a group at least that often outside a pause, such as a muted microphone sending nothing: the longest GOP any of them publishes. It is fixed for the broadcast, and the [HLS gateway](/bin/hls) numbers every rendition's segments on the grid it fixes, segments the smallest whole multiple of it at least a second long, from each group's first timestamp, so renditions share segment numbers. A publisher that knows its GOP declares it; Rust publishers (`moq-mux` and everything built on it) without one measure each track over its first second or group, whichever is longer, and `@moq/publish` declares its encoders' `join`. A broadcast without it gets no HLS playlists. - **Clock.** The optional `sync.clock` maps PTS zero to wall time so every media track shares one fixed epoch after timescale conversion. Publish independent sources as sibling broadcasts under one prefix, such as `robot/front.hang` and `robot/rear.hang`; each broadcast's audio and video entries are renditions of that source. In one Rust publisher, pass the same `moq_mux::Clock` to each `catalog::Config::with_clock`; JS publishers on one page already share the page clock. Consumers discover the siblings by prefix and align their timestamps through the advertised wall mapping; `@moq/watch` plays one broadcast at a time. -- **Version.** The root `version` is the oldest moq-hang draft that reads the catalog correctly, written only when a field needs one newer than 03: a `track` that differs from its ID. Readers ignore fields they don't know, but refuse a `version` above their own with a typed "unsupported catalog version" error, so a player can say to upgrade instead of misreading the catalog. An additive field never raises it. +- **Version.** A `version` is the oldest moq-hang draft that reads what carries it correctly. Each rendition, data track, and include carries its own, written only when it uses a field newer than 03 that an older reader would misread: a `track` that differs from its ID. A reader skips an entry whose `version` is above its own and plays the rest, so a new-style rendition beside a compatibility one costs an older player only the new one, and the parsed catalog lists what was skipped so a player can say to upgrade. The root `version` is for a change to the root itself, which nothing in 04 makes: a reader refuses a catalog whose root `version` is above its own with a typed "unsupported catalog version" error. An additive field never raises either. - **Extensions.** The root is a loose object. Applications add their own sections next to the ones hang defines, under a namespaced key such as `com.example.scte35`, optionally naming a track that carries the data. Every library exposes a way to write your section without clobbering the built-in ones, and readers ignore what they don't know. A section hang defines must have its shape: a `text`, `stats`, or any other built-in key holding something else refuses the whole catalog rather than reading as absent. ## Media reports diff --git a/doc/lib/js/hang.md b/doc/lib/js/hang.md index 44b124f927b..a3856538684 100644 --- a/doc/lib/js/hang.md +++ b/doc/lib/js/hang.md @@ -11,7 +11,7 @@ description: The media layer in TypeScript The [hang media format](/concept/hang) as TypeScript types and codecs, shared by [`@moq/watch`](/lib/js/watch) and [`@moq/publish`](/lib/js/publish). -- **Catalog**: zod schemas for the root, renditions, data tracks, and `sync`. The root is a loose object, so `z.extend(Catalog.RootSchema, { yourSection })` adds your own. `Catalog.watch(broadcast, { delay })` iterates validated catalog updates, each with the media timestamp it takes effect at: the newest only, or with a `delay`, every update a reader that far behind the live edge may still need. Parsing throws `Catalog.UnsupportedVersion` on a catalog that needs a newer moq-hang draft. `Catalog.Audio.ranked(renditions)` and `Catalog.Video.ranked(renditions)` order renditions best first, with enabled renditions ahead; `` uses the video order. +- **Catalog**: zod schemas for the root, renditions, data tracks, includes, and `sync`. The root is a loose object, so `z.extend(Catalog.RootSchema, { yourSection })` adds your own. `Catalog.watch(broadcast, { delay })` iterates validated catalog updates, each with the media timestamp it takes effect at: the newest only, or with a `delay`, every update a reader that far behind the live edge may still need. Parsing throws `Catalog.UnsupportedVersion` on a catalog that needs a newer moq-hang draft; an entry that needs one is skipped instead, and `Catalog.skipped(root)` lists it. `Catalog.Audio.ranked(renditions)` and `Catalog.Video.ranked(renditions)` order renditions best first, with enabled renditions ahead; `` uses the video order. - **Containers**: `Container.Legacy` producer/consumer and separate `@moq/hang/cmaf` decoding. Import the CMAF module only when reading fMP4. - **Utilities**: priority and latency math, a libav polyfill (Opus, plus AAC decoding) for runtimes without native WebCodecs audio, and the browser quirks the media packages work around. diff --git a/doc/lib/rs/hang.md b/doc/lib/rs/hang.md index f1ea1d1f47e..783ae6ab2a7 100644 --- a/doc/lib/rs/hang.md +++ b/doc/lib/rs/hang.md @@ -12,7 +12,7 @@ The [hang media format](/concept/hang) on top of `moq-net`: the catalog that describes renditions with WebCodecs-style decoder configs, and the frame that carries a timestamp with each payload. -- **Catalog.** `Catalog` types video, audio, and text renditions, the `json` and `binary` data tracks, and the `sync` section. Add your own sections through its type parameter, or read unknown ones as raw JSON. `Catalog::subscribe(&broadcast)` follows it live, yielding the newest update with the media timestamp it takes effect at; `catalog::Consumer::new(track, delay)` instead yields, in order, every update a reader playing `delay` behind the live edge may still need. Both fail with `Error::UnsupportedVersion` on a catalog that needs a newer moq-hang draft. +- **Catalog.** `Catalog` types video, audio, and text renditions, the `json` and `binary` data tracks, and the `sync` section. Add your own sections through its type parameter, or read unknown ones as raw JSON. `Catalog::subscribe(&broadcast)` follows it live, yielding the newest update with the media timestamp it takes effect at; `catalog::Consumer::new(track, delay)` instead yields, in order, every update a reader playing `delay` behind the live edge may still need. Both fail with `Error::UnsupportedVersion` on a catalog that needs a newer moq-hang draft; an entry that needs one is skipped instead and listed in `Catalog::skipped`. - **Frames.** `container::Frame` encodes and decodes the `legacy` container, and `container::track_info` declares a media track. A rendition may instead declare `cmaf` or `loc`; an unknown container kind is kept rather than failing the catalog. - **Codecs described**: H.264, H.265, VP8, VP9, AV1, AAC, Opus, PCM, FLAC, MP3, MP2, AC-3, E-AC-3. diff --git a/drafts/draft-lcurley-moq-hang.md b/drafts/draft-lcurley-moq-hang.md index 3635f8d6ef8..85d7d35d85c 100644 --- a/drafts/draft-lcurley-moq-hang.md +++ b/drafts/draft-lcurley-moq-hang.md @@ -130,6 +130,7 @@ type Catalog = { "json": JsonTracks | undefined, "binary": BinaryTracks | undefined, "include": Record | undefined, @@ -149,18 +150,22 @@ 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 `sync` section ({{sync}}) 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}}). +This specification defines audio, video, and text media tracks, an optional `sync` section ({{sync}}) holding the clock that maps content time to wall time and the interval a viewer can join on, the `version` of the catalog and of each entry ({{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. +The `version` field is the oldest draft of this specification that reads what carries it correctly, by draft number: `4` needs a consumer of moq-hang-04 or later. If absent, it is 3. +The root carries one for the whole catalog, and each entry of a map keyed by ID (an audio, video, or text rendition, a data track, or an include) carries one for itself. A consumer MUST ignore fields it does not recognize. -A consumer MUST refuse a catalog whose `version` is above the draft it implements, or is not a non-negative integer, rather than read it; one that refuses SHOULD tell its user to upgrade. +A consumer MUST refuse a catalog whose root `version` is above the draft it implements, or any `version` that is not a non-negative integer, rather than read it; one that refuses SHOULD tell its user to upgrade. +A consumer MUST read an entry's `version` before the rest of the entry, and MUST skip an entry whose `version` is above the draft it implements: it reads the catalog as if that entry were absent, so the entry is never malformed. +One that skips an entry SHOULD tell its user that an upgrade would show more. -A publisher writes the highest draft whose fields the catalog uses that an older consumer would misread, and omits `version` while that is 3. -A change raises the version only when a consumer that ignored it would misread the catalog, never for a field it can safely ignore. -This draft needs `version` 4 only for a `track` ({{field-track}}) other than the entry's ID, which an older consumer subscribes to instead. +A publisher writes on each entry the highest draft whose fields the entry uses that an older consumer would misread, and on the root the highest such draft for the root's own fields, omitting each `version` while it is 3. +A field one entry carries raises only that entry's `version`, so an older consumer still plays the rest of the catalog, including a compatibility rendition beside the new one. +A change raises a version only when a consumer that ignored it would misread the catalog, never for a field it can safely ignore. +This draft writes no root `version`, and needs an entry `version` of 4 only for a `track` ({{field-track}}) other than the entry's ID, which an older consumer subscribes to instead. 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; `sync` ({{sync}}) 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` ({{field-warmup}}), and the data track estimates are hints. @@ -593,6 +598,7 @@ A consumer discovers these tracks the same way it discovers media, by reading th ### JSON {#json-tracks} ~~~ type JsonSchema = { + "version": number | undefined, "mode": Mode, "schema": string | undefined, "broadcast": string | undefined, @@ -610,6 +616,7 @@ It is descriptive: a consumer that does not recognize it MUST still be able to r ### Binary {#binary-tracks} ~~~ type BinarySchema = { + "version": number | undefined, "mode": Mode, "mime": string | undefined, "broadcast": string | undefined, @@ -682,6 +689,7 @@ Audio, video, and text renditions share the following fields, extending the WebC ~~~ type CommonExtensions = { + "version": number | undefined, "broadcast": string | undefined, "instance": string | undefined, "track": string | undefined, @@ -1085,7 +1093,7 @@ This document has no IANA actions. - Replaced the root `archive` section and its per-track timelines with the root `sync` section ({{sync}}). Its `interval` is the longest group of any audio or video track, fixed for the broadcast, and the grid an edge numbers HLS and DASH segments on, each segment the smallest whole multiple of it at least a second long, from each group's first timestamp ({{hls}}); the root `clock` moved to `sync.clock`. Segment indexes, frame positions, `end`, `keyframe`, `timescale`, `replay`, `replayEpoch`, `store`, and `version` are gone. - A reader refuses a JSON frame in which an object repeats a member name. - A malformed audio or video rendition ({{malformed}}) refuses the catalog: a known codec string without valid parameters, a zero or out-of-range dimension, sample rate, or channel count, a bitrate or duration above 2^53 - 1, or a container without a string `kind`. -- Added the root `version` ({{catalog-version}}): the oldest draft that reads the catalog, which a consumer refuses when above its own. A `track` other than the entry's ID needs 4. Consumers MUST ignore unknown fields. +- Added `version` on the root and on each rendition, data track, and include ({{catalog-version}}): the oldest draft that reads it. A consumer refuses a catalog whose root `version` is above its own, and skips an entry whose `version` is. A `track` other than the entry's ID needs an entry `version` of 4. Consumers MUST ignore unknown fields. - A data track marks a discontinuity with a group of one object with no bytes, since its empty payload is data. An object with no bytes on an audio or video track, or sharing its group, is malformed. - Removed the Recording section: the store layout is a moq-archive format, documented with that crate, not part of this draft. - Removed the viewer feedback `latency` field. diff --git a/js/hang/api/catalog.api.md b/js/hang/api/catalog.api.md index 83f6eac5cad..61ac495170b 100644 --- a/js/hang/api/catalog.api.md +++ b/js/hang/api/catalog.api.md @@ -501,6 +501,16 @@ export const RootSchema: ZodMiniObject<{ }, $strip>>; }, $loose>; +export interface Skipped { + audio: Record; + binary: Record; + include: Record; + json: Record; + text: Record; + version: number; + video: Record; +} + export type Stats = infer; export const StatsSchema: ZodMiniObject<{ @@ -825,6 +835,8 @@ export function modeSupported(mode: Mode): mode is KnownMode; export const nonzeroU53Schema: $ZodBranded, "u53", "out">; +export function skipped(root: Root): Skipped | undefined; + export function track(id: string, config: { track?: string; }): string; diff --git a/js/hang/src/catalog/parity.test.ts b/js/hang/src/catalog/parity.test.ts index a33d90219a7..a75149895ab 100644 --- a/js/hang/src/catalog/parity.test.ts +++ b/js/hang/src/catalog/parity.test.ts @@ -1,5 +1,5 @@ import { expect, test } from "bun:test"; -import { checkRenditions, RootSchema } from "./root.ts"; +import { checkRenditions, RootSchema, skipped } from "./root.ts"; interface Case { name: string; @@ -11,10 +11,12 @@ interface Case { json?: string[]; binary?: string[]; include?: string[]; + skipped?: Record>; } // The corpus rs/hang also loads: both languages accept the same catalogs and keep the same -// rendition, data track, and include IDs, so a divergence fails CI on whichever side drifts. +// rendition, data track, and include IDs, and skip the same newer entries, 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[]; @@ -36,5 +38,8 @@ for (const c of cases) { expect(ids(root.json?.tracks)).toEqual(c.json ?? []); expect(ids(root.binary?.tracks)).toEqual(c.binary ?? []); expect(ids(root.include)).toEqual(c.include ?? []); + const { version: _, ...sections } = skipped(root) ?? { version: 0 }; + const nonempty = Object.entries(sections).filter(([, entries]) => Object.keys(entries).length > 0); + expect(Object.fromEntries(nonempty)).toEqual(c.skipped ?? {}); }); } diff --git a/js/hang/src/catalog/root.test.ts b/js/hang/src/catalog/root.test.ts index adbf2228db5..ee2f041da80 100644 --- a/js/hang/src/catalog/root.test.ts +++ b/js/hang/src/catalog/root.test.ts @@ -2,7 +2,16 @@ import { expect, test } from "bun:test"; import * as z from "zod/mini"; import { u53 } from "./integers.ts"; import type { ReferenceInstance, RelativeBroadcast } from "./path.ts"; -import { checkRenditions, DuplicateRendition, encode, RootSchema, UnsupportedVersion, VERSION } from "./root.ts"; +import { + checkRenditions, + DuplicateRendition, + encode, + type Root, + RootSchema, + skipped, + UnsupportedVersion, + VERSION, +} from "./root.ts"; import { track } from "./track.ts"; // The base catalog carries the media sections (`video`/`audio`) and the data track sections @@ -312,21 +321,93 @@ test("a supported catalog version is read", () => { } }); -// Only a field an older reader would misread raises the version. -test("the catalog version is needed only for misread fields", () => { +// Only a field an older reader would misread raises an entry's version, and no moq-hang-04 field +// raises the root's. +test("an entry version is needed only for misread fields", () => { const audio = { ...opus, warmup: 80 }; const root = (hd: object) => - RootSchema.parse({ video: { renditions: { hd } }, audio: { renditions: { en: audio } } }); + RootSchema.parse({ + video: { renditions: { hd } }, + audio: { renditions: { en: audio } }, + include: { extra: { broadcast: "../extra" } }, + }); + const versions = (value: Root) => { + expect(value.version).toBeUndefined(); + const entry = (map: Record | undefined, id: string) => + (map?.[id] as { version?: number } | undefined)?.version; + return { + hd: entry(value.video?.renditions, "hd"), + en: entry(value.audio?.renditions, "en"), + extra: entry(value.include, "extra"), + }; + }; + const none = { hd: undefined, en: undefined, extra: undefined }; - expect(encode(root(avc)).version).toBeUndefined(); - expect(encode(root({ ...avc, track: "hd" })).version).toBeUndefined(); - expect(encode(root({ ...avc, track: "video" })).version).toBe(4); + expect(versions(encode(root(avc)))).toEqual(none); + expect(versions(encode(root({ ...avc, track: "hd" })))).toEqual(none); + expect(versions(encode(root({ ...avc, track: "video" })))).toEqual({ ...none, hd: 4 }); // moq-hang-04 defines no video `warmup`, so it is dropped as an unknown field. - expect(encode(root({ ...avc, warmup: 500 })).version).toBeUndefined(); + expect(versions(encode(root({ ...avc, warmup: 500 })))).toEqual(none); + expect(JSON.stringify(encode(root({ ...avc, track: "video" })))).toContain('"hd":{"version":4,'); + const data = RootSchema.parse({ json: { tracks: { chat: { mode: "stream", track: "chat.json" } } } }); - expect(encode(data).version).toBe(4); + expect((encode(data).json?.tracks.chat as { version?: number } | undefined)?.version).toBe(4); + // A carried version is recomputed, never trusted. - expect(encode({ ...root(avc), version: 4 }).version).toBeUndefined(); + const carried = { + ...root(avc), + version: 4, + json: { tracks: { chat: { mode: "stream", version: 4 } } }, + } as Root; + expect(JSON.stringify(encode(carried))).not.toContain("version"); +}); + +// An entry a newer draft defines is skipped and reported, even one this reader would call +// malformed, while the rest of the catalog plays. +test("a newer entry is skipped", () => { + const catalog = { + video: { renditions: { compat: avc, next: { version: 5, codec: 42 } } }, + audio: { renditions: { next: { version: 6 } } }, + text: { renditions: { next: { version: 5 } } }, + json: { tracks: { next: { version: 5 } } }, + binary: { tracks: { next: { version: 5, mode: [] } } }, + include: { next: { version: 5, broadcast: 7 } }, + }; + const parsed = RootSchema.parse(catalog); + expect(Object.keys(parsed.video?.renditions ?? {})).toEqual(["compat"]); + expect(parsed.audio?.renditions).toEqual({}); + expect(parsed.include).toEqual({}); + expect(skipped(parsed)).toEqual({ + version: 6, + video: { next: 5 }, + audio: { next: 6 }, + text: { next: 5 }, + json: { next: 5 }, + binary: { next: 5 }, + include: { next: 5 }, + }); + + // Never written, so a republish lists only what this reader read. + expect(skipped(RootSchema.parse(JSON.parse(JSON.stringify(encode(parsed)))))).toBeUndefined(); + + // The root version still refuses the whole catalog. + expect(() => RootSchema.parse({ ...catalog, version: 5 })).toThrow(UnsupportedVersion); +}); + +test("a supported entry version is read, and a malformed one refuses the catalog", () => { + for (const version of [0, 3, VERSION]) { + const parsed = RootSchema.parse({ video: { renditions: { hd: { ...avc, version } } } }); + expect(Object.keys(parsed.video?.renditions ?? {})).toEqual(["hd"]); + expect(skipped(parsed)).toBeUndefined(); + } + for (const version of ["5", -1, 4.5, null, []]) { + expect(() => RootSchema.parse({ json: { tracks: { chat: { mode: "stream", version } } } })).toThrow( + z.core.$ZodError, + ); + } + // The entry version is not kept as an extension field. + const data = RootSchema.parse({ json: { tracks: { chat: { mode: "stream", version: 4 } } } }); + expect(data.json?.tracks.chat).toEqual({ mode: "stream" }); }); test("shared stats and echo discovery round trips without changing old catalogs", async () => { diff --git a/js/hang/src/catalog/root.ts b/js/hang/src/catalog/root.ts index 7f9cc628178..7aec67165d0 100644 --- a/js/hang/src/catalog/root.ts +++ b/js/hang/src/catalog/root.ts @@ -11,33 +11,19 @@ import { IncludeSchema } from "./include.ts"; import { JsonSchema } from "./json.ts"; import type { RelativeBroadcast } from "./path.ts"; import { PRIORITY } from "./priority.ts"; -import { renditions } from "./section.ts"; +import { renditions, SKIPPED } from "./section.ts"; import { StatsSchema } from "./stats.ts"; import { TextSchema } from "./text.ts"; import { TimelineSchema } from "./timeline.ts"; import { track } from "./track.ts"; +import { UnsupportedVersion, VERSION, VersionSchema } from "./version.ts"; import { VideoSchema } from "./video.ts"; -/** The newest moq-hang draft this package reads; a catalog whose `version` is higher is refused. */ -export const VERSION = 4; - -/** A catalog needs a newer moq-hang draft than this reader implements. */ -export class UnsupportedVersion extends Error { - /** The catalog version that was read. */ - readonly version: number; - - constructor(version: number) { - super(`unsupported catalog version ${version}: upgrade to read it`); - this.name = "UnsupportedVersion"; - this.version = version; - } -} +export { UnsupportedVersion, VERSION } from "./version.ts"; // Thrown rather than reported as an issue, so it surfaces as itself and before any section, which // the newer draft may have reshaped. -const VersionSchema = z.number().check( - z.int(), - z.nonnegative(), +const RootVersionSchema = VersionSchema.check( z.refine((version) => { if (Number.isInteger(version) && version > VERSION) throw new UnsupportedVersion(version); return true; @@ -61,12 +47,14 @@ const VersionSchema = z.number().check( * present, or parsing refuses the whole catalog, the same as Rust. * * The root `version` is the oldest moq-hang draft that reads the catalog correctly, absent while - * that is 3. Parsing throws {@link UnsupportedVersion} when it is above {@link VERSION}; a - * publisher sets it with {@link encode}. + * that is 3, and parsing throws {@link UnsupportedVersion} when it is above {@link VERSION}. Each + * entry (rendition, data track, include) carries its own `version` the same way, and parsing skips + * an entry whose `version` is above {@link VERSION}; {@link skipped} reports it. A publisher writes + * the entry versions with {@link encode}. */ export const RootSchema = z.looseObject({ // First, so it is checked before any section. - version: z.optional(VersionSchema), + version: z.optional(RootVersionSchema), video: z.optional(VideoSchema), audio: z.optional(AudioSchema), // The broadcast's timeline, omitted when it holds nothing. @@ -82,22 +70,69 @@ export const RootSchema = z.looseObject({ /** The root catalog object: the media sections, `sync`, the data track sections, plus any app extensions. */ export type Root = z.infer; +/** The catalog entries a reader skipped because a newer moq-hang draft defines them. */ +export interface Skipped { + /** The draft a reader needs to read every skipped entry. */ + version: number; + /** Skipped video renditions, mapping each ID to its `version`. */ + video: Record; + /** Skipped audio renditions. */ + audio: Record; + /** Skipped text renditions. */ + text: Record; + /** Skipped JSON tracks. */ + json: Record; + /** Skipped binary tracks. */ + binary: Record; + /** Skipped includes. */ + include: Record; +} + /** - * The oldest moq-hang draft that reads `root` correctly, or undefined while that is 3. + * The entries parsing `root` skipped because a newer moq-hang draft defines them, or undefined if + * it read them all. The rest of the catalog reads as if they were absent, so a player plays what + * it can and may tell its user to upgrade for the rest. * - * Only a field an older reader would misread raises it; one it would merely ignore does not. + * Reads what {@link RootSchema} recorded on each parsed map, so pass the parsed value itself, not + * a copy. Mirrors Rust's `Catalog::skipped`. */ -function minVersion(root: Root): number | undefined { +export function skipped(root: Root): Skipped | undefined { + const of = (map: object | undefined) => (map && SKIPPED.get(map)) ?? {}; + const sections = { + video: of(root.video?.renditions), + audio: of(root.audio?.renditions), + text: of(root.text?.renditions), + json: of(root.json?.tracks), + binary: of(root.binary?.tracks), + include: of(root.include), + }; + const versions = Object.values(sections).flatMap((section) => Object.values(section)); + if (versions.length === 0) return undefined; + return { version: Math.max(...versions), ...sections }; +} + +/** + * The oldest moq-hang draft that reads an entry correctly given its ID, or undefined while that is + * 3. Only a field an older reader would misread raises it; one it would merely ignore does not. + */ +function entryVersion(id: string, entry: { track?: string }): number | undefined { // moq-hang-04: a reader that ignores `track` subscribes to the ID, a different track. - const renamed = [ - root.video?.renditions, - root.audio?.renditions, - root.text?.renditions, - root.json?.tracks, - root.binary?.tracks, - ].some((entries) => Object.entries(entries ?? {}).some(([id, config]) => track(id, config) !== id)); + if (track(id, entry) !== id) return 4; + return undefined; +} - return renamed ? 4 : undefined; +/** Rewrite a map's entries with their computed `version` first, dropping any they carried. */ +function versioned( + entries: Record, + version: (id: string, entry: T) => number | undefined, +): Record { + return Object.fromEntries( + Object.entries(entries).map(([id, entry]) => { + const { version: _, ...rest } = entry as T & { version?: unknown }; + const computed = version(id, entry); + return [id, computed === undefined ? rest : { version: computed, ...rest }]; + }), + ) as Record; } /** A catalog update used one rendition ID for both a video and an audio rendition. */ @@ -121,9 +156,11 @@ export function checkRenditions(root: Root): Root { } /** - * The catalog as a publisher writes it: refused as every reader refuses it, with the root - * `version` computed rather than carried, so an edit can't claim less than the catalog uses, and an - * empty `sync` left off the wire. +/** + * The catalog as a publisher writes it: refused as every reader refuses it, with each entry's + * `version` computed rather than carried, so an edit can't claim less than an entry uses, and an + * empty `sync` left off the wire. No moq-hang-04 field reshapes the root, so the root `version` is + * never written. * * Throws {@link DuplicateRendition}. Mirrors Rust's catalog serializer. */ @@ -132,8 +169,12 @@ export function encode(root: Root): Root { const value = { ...root }; delete value.version; if (value.sync && value.sync.clock === undefined && value.sync.interval === undefined) delete value.sync; - const version = minVersion(root); - if (version !== undefined) value.version = version; + if (value.video) value.video = { ...value.video, renditions: versioned(value.video.renditions, entryVersion) }; + if (value.audio) value.audio = { ...value.audio, renditions: versioned(value.audio.renditions, entryVersion) }; + if (value.text) value.text = { ...value.text, renditions: versioned(value.text.renditions, entryVersion) }; + if (value.json) value.json = { ...value.json, tracks: versioned(value.json.tracks, entryVersion) }; + if (value.binary) value.binary = { ...value.binary, tracks: versioned(value.binary.tracks, entryVersion) }; + if (value.include) value.include = versioned(value.include, () => undefined); return value; } diff --git a/js/hang/src/catalog/section.ts b/js/hang/src/catalog/section.ts index c1c4005e72f..ed469cf0c7f 100644 --- a/js/hang/src/catalog/section.ts +++ b/js/hang/src/catalog/section.ts @@ -1,13 +1,18 @@ import * as z from "zod/mini"; import { u53Schema } from "./integers.ts"; +import { VERSION, VersionSchema } from "./version.ts"; + +/** The entries each parsed map skipped, keyed by the map itself. Read through `skipped` in `root.ts`. */ +export const SKIPPED = new WeakMap>(); /** - * A catalog map keyed by ID (renditions, data tracks, includes), refusing the catalog if any - * entry is malformed. + * A catalog map keyed by ID (renditions, data tracks, includes), skipping an entry newer than this + * reader and refusing the catalog if any other entry is malformed. * - * Each entry must parse with `schema`; the issue names the entry. An unknown container - * or extension field is not malformed, so it never refuses the catalog. Mirrors the Rust - * `deserialize_entries`. + * An entry's `version` is read before the rest of it, since a newer draft may have reshaped the + * entry; one above {@link VERSION} is skipped and recorded in {@link SKIPPED}. Every other entry + * must parse with `schema`; the issue names the entry. An unknown container or extension field is + * not malformed, so it never refuses the catalog. Mirrors the Rust `deserialize_entries`. * * @param schema - one entry's schema. * @param kind - what an entry is, naming it in the issue (`rendition`, `include`). @@ -20,8 +25,29 @@ export function renditions(schema: T, kind = "rendition ), z.transform((raw, ctx) => { const kept: [string, z.infer][] = []; + const skipped: [string, number][] = []; for (const [id, value] of Object.entries(raw)) { - const result = schema.safeParse(value); + let entry = value; + if (typeof value === "object" && value !== null && Object.hasOwn(value, "version")) { + // Taken out rather than left to the entry: written versions are computed, never carried. + const { version, ...rest } = value as Record; + const checked = VersionSchema.safeParse(version); + if (!checked.success) { + ctx.issues.push({ + code: "custom", + message: `malformed ${kind} ${id}: ${checked.error.message}`, + input: value, + }); + continue; + } + if (checked.data > VERSION) { + skipped.push([id, checked.data]); + continue; + } + entry = rest; + } + + const result = schema.safeParse(entry); if (result.success) kept.push([id, result.data]); else ctx.issues.push({ @@ -31,7 +57,9 @@ export function renditions(schema: T, kind = "rendition }); } // fromEntries defines each key as its own property, so `__proto__` stays an ID. - return Object.fromEntries(kept) as Record>; + const map = Object.fromEntries(kept) as Record>; + if (skipped.length > 0) SKIPPED.set(map, Object.fromEntries(skipped)); + return map; }), ); } diff --git a/js/hang/src/catalog/version.ts b/js/hang/src/catalog/version.ts new file mode 100644 index 00000000000..d06b50af2c8 --- /dev/null +++ b/js/hang/src/catalog/version.ts @@ -0,0 +1,22 @@ +import * as z from "zod/mini"; + +/** + * The newest moq-hang draft this package reads. A catalog whose root `version` is higher is + * refused, and an entry whose `version` is higher is skipped. + */ +export const VERSION = 4; + +/** A catalog needs a newer moq-hang draft than this reader implements. */ +export class UnsupportedVersion extends Error { + /** The catalog version that was read. */ + readonly version: number; + + constructor(version: number) { + super(`unsupported catalog version ${version}: upgrade to read it`); + this.name = "UnsupportedVersion"; + this.version = version; + } +} + +/** A `version` member: the oldest moq-hang draft that reads what carries it, absent while that is 3. */ +export const VersionSchema = z.number().check(z.int(), z.nonnegative()); diff --git a/js/publish/src/catalog.test.ts b/js/publish/src/catalog.test.ts index c220dc0b6ed..6fd95477642 100644 --- a/js/publish/src/catalog.test.ts +++ b/js/publish/src/catalog.test.ts @@ -53,7 +53,7 @@ test("catalog producer refuses an ID naming both a video and an audio rendition" ).toThrow(Catalog.DuplicateRendition); }); -test("catalog producer computes the version from the fields it uses", async () => { +test("catalog producer computes each entry version from the fields it uses", async () => { const catalog = new CatalogProducer(); const effect = new Effect(); const track = new Track.Producer("catalog.json"); @@ -61,17 +61,19 @@ test("catalog producer computes the version from the fields it uses", async () = const consumer = new Json.Snapshot.Consumer({ track }); const video = { codec: "avc1.64001f", container: { kind: "legacy" as const } }; - // A caller's own version is replaced by the computed one. + // A caller's own version is replaced by the computed ones: the renamed rendition's, not the root's. catalog.mutate((c) => { c.video = { renditions: { hd: { ...video, track: "video" } } }; c.version = 3; }); - expect((await consumer.latest())?.value.version).toBe(4); + const renamed = (await consumer.latest())?.value; + expect(renamed).not.toHaveProperty("version"); + expect(renamed?.video?.renditions.hd).toHaveProperty("version", 4); catalog.mutate((c) => { c.video = { renditions: { hd: video } }; }); - expect((await consumer.latest())?.value).not.toHaveProperty("version"); + expect((await consumer.latest())?.value.video?.renditions.hd).not.toHaveProperty("version"); effect.close(); }); diff --git a/js/watch/src/broadcast.ts b/js/watch/src/broadcast.ts index f86aa9e62ac..245d914b3b7 100644 --- a/js/watch/src/broadcast.ts +++ b/js/watch/src/broadcast.ts @@ -581,7 +581,10 @@ export class Broadcast { accepted = catalog && Catalog.checkResolvable(Catalog.checkRenditions(Catalog.RootSchema.parse(catalog)), name); - if (accepted) status = "live"; + if (accepted) { + status = "live"; + warnSkipped(name, accepted); + } } catch (err) { if (err instanceof Catalog.UnsupportedVersion) status = "unsupported"; console.error("rejecting catalog", name, err); @@ -650,6 +653,7 @@ export class Broadcast { this.#raw.set(Catalog.checkResolvable(Catalog.checkRenditions(update), name), true); this.#progress.set("live"); + warnSkipped(name, update); } } catch (err) { if (err instanceof Catalog.UnsupportedVersion) status = "unsupported"; @@ -809,3 +813,9 @@ export class Broadcast { this.#children.clear(); } } + +// The rest of the catalog plays; an entry a newer draft defines only costs the viewer that entry. +function warnSkipped(name: Moq.Path.Valid, root: Catalog.Root) { + const skipped = Catalog.skipped(root); + if (skipped) console.warn("catalog entries need moq-hang draft", skipped.version, "to read", name, skipped); +} diff --git a/quest/m2/hang04/entry-version.md b/quest/m2/hang04/entry-version.md deleted file mode 100644 index af3d992e038..00000000000 --- a/quest/m2/hang04/entry-version.md +++ /dev/null @@ -1,76 +0,0 @@ -# [M] A player skips a catalog entry newer than it reads - -## Goal - -A hang catalog entry (a rendition, a data track, an include) can carry its -own `version`: the oldest moq-hang draft that reads that entry correctly. A -reader skips an entry whose `version` is above its own and plays the rest, -and can tell its user that something was skipped. The root `version` stays, -and still refuses the whole catalog, for a change that reshapes the root. -hang-04's one remaining trigger, a `track` that differs from the entry's ID, -moves from the root to the entry. `rs/hang`, `js/hang`, and the hang draft -agree. - -## Plan - -Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): - -- ✅ Skip per entry (rejected: keep the root gate and tell publishers never - to mix new-style and compatibility renditions in one catalog; keep as - is). Both hang-04 triggers are per-rendition features, so one such - rendition takes the whole catalog from an older reader, including the - compatibility rendition the draft tells publishers to add. - -Facts found by the audit: - -- A reader "MUST refuse a catalog whose `version` is above the draft it - implements" (the draft's Version section). `min_version` in - `rs/hang/src/catalog/root.rs` and `minVersion` in - `js/hang/src/catalog/root.ts` raise it to 4 for a renamed `track` or a - video `warmup`, both properties of one entry. -- [moq-dev/moq#5806](https://github.com/moq-dev/moq/pull/5806) saw this - cost and avoided it for `enabled` ("a live rendition toggle would flip - the whole catalog unreadable"). -- The draft already has the gentler tool: an unknown `container.kind`, - text `format`, or data `mode` ignores that entry alone. -- Published 0.21 readers check no `version`, so 4 protects nobody deployed - today. 0.22 is the first reader that checks, and the rule it ships is the - only forward-compatibility lever every later catalog change gets. - -Recommendations for the PR: - -- The entry member is named `version`, an integer, absent while it is 3. - Both serializers compute it from the entry, as the root's is computed - today, so a caller cannot claim less than the entry uses. -- A reader checks an entry's `version` before it validates the entry, as - `Probe` reads the root's before any section: a newer entry may have a - shape this reader would call malformed, and the malformed-rendition rule - refuses the whole catalog. -- A skipped entry is reported, not silent: the parsed catalog says which - IDs were skipped and the highest version among them, the per-entry twin - of `Error::UnsupportedVersion` and JS `UnsupportedVersion`, so a player - can say "upgrade to see everything". -- With video warmup out of hang-04 - ([moq-dev/moq#8960](https://github.com/moq-dev/moq/pull/8960)), the - renamed `track` is the only trigger, and nothing in hang-04 raises the - root `version`. Keep the root check and its tests: it is what a reshaped - root will use. -- An include is an entry too. Decide whether a skipped include is reported - the same way, and say so in the draft. -- A reference that an entry makes to a skipped entry (if any section can) - is the case to look for before settling the rule. - -Tests, in both languages and in the parity fixtures: a catalog holding a -compatibility rendition and a version-5 rendition reads as the -compatibility rendition alone and reports the skip; a version-5 entry that -would be malformed to this reader is skipped, not refused; a root -`version` of 5 still refuses; a duplicate `version` member in an entry is -refused as the root's is. - -Public API: additive on the parsed catalog (the skipped-entries report); -the computed root `version` changes for a catalog with a renamed `track`. -Wire: the hang-04 catalog JSON, unpublished. - -## Related - -- [Audio languages](/quest/m3/audio-lang.md) - a later rendition a 0.22 player should skip can be marked with this diff --git a/quest/m3/ffi-catalog-skipped.md b/quest/m3/ffi-catalog-skipped.md new file mode 100644 index 00000000000..0d2e62f814c --- /dev/null +++ b/quest/m3/ffi-catalog-skipped.md @@ -0,0 +1,35 @@ +# [M] Bindings report the catalog entries they skipped + +## Goal + +A native player built on a binding can tell its user that the catalog +listed renditions it skipped because a newer moq-hang draft defines them, +the way `@moq/watch` warns and `hang::Catalog::skipped` reports. `MoqCatalog` +in `rs/moq-ffi/src/media.rs` carries the skipped video and audio rendition +IDs with their versions, and every wrapper (Python, Go, Kotlin, Swift, Dart, +C, C++) exposes them under the same name. + +## Plan + +Today a binding gets a `MoqCatalog` built from `hang::Catalog`, so a +rendition a newer draft defines just vanishes: the root +`MoqError::UnsupportedCatalog` covers a reshaped root only. + +Recommendations: + +- One field, `skipped`, holding the video and audio maps of ID to + `version` (the only sections `MoqCatalog` exposes), plus the highest + version, mirroring `hang::catalog::Skipped`. Data tracks and includes + join it when `MoqCatalog` exposes those sections. +- `moq play` and the OBS source log a warning naming the version, as + `@moq/watch` does. + +Tests: the ffi test that a catalog with a compatibility rendition and a +version-5 rendition yields the compatibility one plus the report, and each +wrapper's smoke test reads the field. + +Public API: additive in moq-ffi and every wrapper. Wire: none. + +## Related + +- [hang-04 freezes a catalog worth keeping](/quest/m2/hang04/README.md) - the epic whose entry versions this exposes diff --git a/quest/m4/intra-refresh/catalog-warmup.md b/quest/m4/intra-refresh/catalog-warmup.md index 324320eb69b..2b0ec5fe973 100644 --- a/quest/m4/intra-refresh/catalog-warmup.md +++ b/quest/m4/intra-refresh/catalog-warmup.md @@ -28,8 +28,9 @@ rendition. It returns here, with the producers this epic adds. - The field comes back in the hang draft's next version, with the group rule that lets a video group start at a picture from which decoding converges. It raises the entry's `version`, not the root's (the - per-entry rule hang-04 ships, planned as `quest/m2/hang04/entry-version.md`), - so a player that cannot play it keeps the other renditions. + per-entry rule hang-04 ships, `Entry::version` in `rs/hang` and + `videoVersion` in `js/hang`), so a player that cannot play it keeps the + other renditions. - Audio `warmup` never left; reuse `moq_mux::container::Playout` and the JS consumer's `warmup` reach as they are. - The draft says which engines play it. The Firefox and Safari check in diff --git a/rs/hang/fixtures/catalog-parity.json b/rs/hang/fixtures/catalog-parity.json index 85e23881c36..fb575275caf 100644 --- a/rs/hang/fixtures/catalog-parity.json +++ b/rs/hang/fixtures/catalog-parity.json @@ -5914,5 +5914,197 @@ "com.example.text": null }, "video": ["ok"] + }, + { + "name": "a newer entry is skipped", + "catalog": { + "video": { + "renditions": { + "compat": { + "codec": "avc1.64001f" + }, + "next": { + "version": 5, + "codec": 42 + } + } + }, + "audio": { + "renditions": { + "next": { + "version": 6 + } + } + }, + "text": { + "renditions": { + "next": { + "version": 5 + } + } + }, + "json": { + "tracks": { + "next": { + "version": 5 + } + } + }, + "binary": { + "tracks": { + "next": { + "version": 5, + "mode": [] + } + } + }, + "include": { + "next": { + "version": 5, + "broadcast": 7 + } + } + }, + "video": ["compat"], + "skipped": { + "video": { + "next": 5 + }, + "audio": { + "next": 6 + }, + "text": { + "next": 5 + }, + "json": { + "next": 5 + }, + "binary": { + "next": 5 + }, + "include": { + "next": 5 + } + } + }, + { + "name": "a supported entry version is read", + "catalog": { + "video": { + "renditions": { + "zero": { + "version": 0, + "codec": "avc1.64001f" + }, + "four": { + "version": 4, + "codec": "avc1.64001f" + } + } + } + }, + "video": ["four", "zero"] + }, + { + "name": "a newer root version refuses despite entry versions", + "catalog": { + "version": 5, + "video": { + "renditions": { + "compat": { + "codec": "avc1.64001f" + }, + "next": { + "version": 5 + } + } + } + }, + "refused": true + }, + { + "name": "entry version \"5\" refuses the catalog", + "catalog": { + "video": { + "renditions": { + "compat": { + "codec": "avc1.64001f" + }, + "bad": { + "version": "5", + "codec": "avc1.64001f" + } + } + } + }, + "refused": true + }, + { + "name": "entry version -1 refuses the catalog", + "catalog": { + "video": { + "renditions": { + "compat": { + "codec": "avc1.64001f" + }, + "bad": { + "version": -1, + "codec": "avc1.64001f" + } + } + } + }, + "refused": true + }, + { + "name": "entry version 4.5 refuses the catalog", + "catalog": { + "video": { + "renditions": { + "compat": { + "codec": "avc1.64001f" + }, + "bad": { + "version": 4.5, + "codec": "avc1.64001f" + } + } + } + }, + "refused": true + }, + { + "name": "entry version null refuses the catalog", + "catalog": { + "video": { + "renditions": { + "compat": { + "codec": "avc1.64001f" + }, + "bad": { + "version": null, + "codec": "avc1.64001f" + } + } + } + }, + "refused": true + }, + { + "name": "entry version [] refuses the catalog", + "catalog": { + "video": { + "renditions": { + "compat": { + "codec": "avc1.64001f" + }, + "bad": { + "version": [], + "codec": "avc1.64001f" + } + } + } + }, + "refused": true } ] diff --git a/rs/hang/src/catalog/audio/mod.rs b/rs/hang/src/catalog/audio/mod.rs index 6a7fb6fc593..e78c229c751 100644 --- a/rs/hang/src/catalog/audio/mod.rs +++ b/rs/hang/src/catalog/audio/mod.rs @@ -36,7 +36,10 @@ pub struct Audio { /// We use a BTreeMap so keys are sorted alphabetically for *some* deterministic behavior. /// /// A malformed rendition refuses the whole catalog when decoding. - #[serde(deserialize_with = "crate::catalog::deserialize_entries")] + #[serde( + deserialize_with = "crate::catalog::deserialize_entries", + serialize_with = "crate::catalog::serialize_entries" + )] pub renditions: BTreeMap, } @@ -277,6 +280,10 @@ impl crate::catalog::Entry for AudioConfig { } Ok(()) } + + fn version(&self, id: &str) -> Option { + crate::catalog::renamed_version(self, id) + } } #[cfg(test)] diff --git a/rs/hang/src/catalog/binary.rs b/rs/hang/src/catalog/binary.rs index a9c3ae3875a..eac35108e0f 100644 --- a/rs/hang/src/catalog/binary.rs +++ b/rs/hang/src/catalog/binary.rs @@ -25,11 +25,22 @@ pub struct Binary { /// /// A map rather than an array so it works with JSON Merge Patch, and a `BTreeMap` so keys are /// sorted for *some* deterministic behavior. - #[serde(deserialize_with = "crate::catalog::deserialize_entries")] + #[serde( + deserialize_with = "crate::catalog::deserialize_entries", + serialize_with = "crate::catalog::serialize_entries" + )] pub tracks: BTreeMap, } -impl crate::catalog::Entry for BinaryConfig {} +impl crate::catalog::Entry for BinaryConfig { + fn version(&self, id: &str) -> Option { + crate::catalog::renamed_version(self, id) + } + + fn claims_version(&self) -> bool { + self.extra.contains_key("version") + } +} impl Binary { /// Insert a track config, returning an error if the name already exists. @@ -125,7 +136,8 @@ pub struct BinaryConfig { #[serde(default, skip_serializing_if = "crate::catalog::millis::no_delay")] pub delay: Option, - /// Fields this build doesn't recognize, kept so the entry round-trips. + /// Fields this build doesn't recognize, kept so the entry round-trips. Never `version`, which + /// is computed when the entry is written. /// /// A future [`Mode`] almost certainly comes with fields describing it, and /// preserving the discriminant without them would leave a relay republishing an entry nothing diff --git a/rs/hang/src/catalog/json.rs b/rs/hang/src/catalog/json.rs index 954dc5ad119..dfa194c3432 100644 --- a/rs/hang/src/catalog/json.rs +++ b/rs/hang/src/catalog/json.rs @@ -23,11 +23,22 @@ pub struct Json { /// /// A map rather than an array so it works with JSON Merge Patch, and a `BTreeMap` so keys are /// sorted for *some* deterministic behavior. - #[serde(deserialize_with = "crate::catalog::deserialize_entries")] + #[serde( + deserialize_with = "crate::catalog::deserialize_entries", + serialize_with = "crate::catalog::serialize_entries" + )] pub tracks: BTreeMap, } -impl crate::catalog::Entry for JsonConfig {} +impl crate::catalog::Entry for JsonConfig { + fn version(&self, id: &str) -> Option { + crate::catalog::renamed_version(self, id) + } + + fn claims_version(&self) -> bool { + self.extra.contains_key("version") + } +} impl Json { /// Insert a track config, returning an error if the name already exists. @@ -123,7 +134,8 @@ pub struct JsonConfig { #[serde(default, skip_serializing_if = "crate::catalog::millis::no_delay")] pub delay: Option, - /// Fields this build doesn't recognize, kept so the entry round-trips. + /// Fields this build doesn't recognize, kept so the entry round-trips. Never `version`, which + /// is computed when the entry is written. /// /// A future [`Mode`] almost certainly comes with fields describing it, and /// preserving the discriminant without them would leave a relay republishing an entry nothing diff --git a/rs/hang/src/catalog/mod.rs b/rs/hang/src/catalog/mod.rs index 50e3ad63932..6109638a380 100644 --- a/rs/hang/src/catalog/mod.rs +++ b/rs/hang/src/catalog/mod.rs @@ -20,6 +20,7 @@ mod mode; mod priority; mod reference; mod root; +mod skipped; mod stats; mod text; mod timeline; @@ -38,11 +39,16 @@ pub use mode::*; pub use priority::*; pub use reference::*; pub use root::*; +pub use skipped::Skipped; pub use stats::*; pub use text::*; pub use timeline::*; pub use video::*; +/// The newest moq-hang draft this crate reads. A catalog whose root `version` is higher is refused, +/// and an entry whose `version` is higher is skipped. +pub(crate) const VERSION: u64 = 4; + /// Serde default for a rendition's `enabled` field. pub(crate) fn enabled_default() -> bool { true @@ -122,18 +128,35 @@ impl<'de, T, U: serde_with::DeserializeAs<'de, T>> serde_with::DeserializeAs<'de } /// An entry of a catalog map keyed by ID (a rendition, data track, or include), checked as it -/// decodes. -pub(crate) trait Entry: serde::de::DeserializeOwned { +/// decodes and versioned as it encodes. +pub(crate) trait Entry: serde::de::DeserializeOwned + serde::Serialize { /// Refuse a field out of the range its type allows. fn check(&self) -> crate::Result<()> { Ok(()) } + + /// The oldest moq-hang draft that reads this entry correctly given its ID, or `None` while that + /// is 3. Written as the entry's `version`. + /// + /// Only a field an older reader would misread raises it; one it would merely ignore does not. + fn version(&self, _id: &str) -> Option { + None + } + + /// Whether the entry keeps an unrecognized member named `version`, which would sit beside the + /// computed one as a duplicate key. + fn claims_version(&self) -> bool { + false + } } -/// Decode a catalog map keyed by ID, refusing the catalog if any entry is malformed. +/// Decode a catalog map keyed by ID, skipping an entry newer than this reader and refusing the +/// catalog if any other entry is malformed. /// -/// Each entry must be an object whose fields are in range; the error names the entry. -/// An unknown container or extension field is not malformed, so it never refuses the catalog. +/// An entry's `version` is read before the rest of it, since a newer draft may have reshaped the +/// entry; one above [`VERSION`] is skipped, and [`Catalog::skipped`](crate::catalog::Catalog::skipped) +/// reports it. Every other entry must be an object whose fields are in range; the error names the +/// entry. An unknown container or extension field is not malformed, so it never refuses the catalog. pub(crate) fn deserialize_entries<'de, D, T>(deserializer: D) -> Result, D::Error> where D: serde::Deserializer<'de>, @@ -142,17 +165,59 @@ where use serde::Deserialize; let entries = std::collections::BTreeMap::::deserialize(deserializer)?; - let decode = |value: serde_json::Value| -> crate::Result { + let decode = |mut value: serde_json::Value| -> crate::Result> { + // Taken out rather than left to the entry: written versions are computed, never carried. + if let Some(version) = value.as_object_mut().and_then(|entry| entry.remove("version")) + && serde_json::from_value::(version)? > VERSION + { + return Ok(None); + } let config: T = deserialize_object(value)?; config.check()?; - Ok(config) + Ok(Some(config)) }; - entries - .into_iter() - .map(|(id, value)| match decode(value) { - Ok(config) => Ok((id, config)), - Err(err) => Err(serde::de::Error::custom(format!("malformed entry {id}: {err}"))), - }) - .collect() + let mut decoded = std::collections::BTreeMap::new(); + for (id, value) in entries { + match decode(value) { + Ok(Some(config)) => { + decoded.insert(id, config); + } + Ok(None) => {} + Err(err) => return Err(serde::de::Error::custom(format!("malformed entry {id}: {err}"))), + } + } + Ok(decoded) +} + +/// Encode a catalog map keyed by ID, writing each entry's computed `version` ahead of its fields. +pub(crate) fn serialize_entries( + entries: &std::collections::BTreeMap, + serializer: S, +) -> Result +where + S: serde::Serializer, + T: Entry, +{ + #[derive(serde::Serialize)] + struct Versioned<'a, T> { + #[serde(skip_serializing_if = "Option::is_none")] + version: Option, + #[serde(flatten)] + config: &'a T, + } + + if let Some(id) = entries + .iter() + .find_map(|(id, config)| config.claims_version().then_some(id)) + { + return Err(serde::ser::Error::custom(format!( + "catalog entry {id} must not carry a member `version`" + ))); + } + + serializer.collect_map(entries.iter().map(|(id, config)| { + let version = config.version(id); + (id, Versioned { version, config }) + })) } diff --git a/rs/hang/src/catalog/reference.rs b/rs/hang/src/catalog/reference.rs index 20a6bf40976..171f38352ed 100644 --- a/rs/hang/src/catalog/reference.rs +++ b/rs/hang/src/catalog/reference.rs @@ -36,3 +36,9 @@ macro_rules! reference { } reference!(VideoConfig, AudioConfig, TextConfig, JsonConfig, BinaryConfig); + +/// moq-hang-04 for a `track` other than the ID: a reader that ignores it subscribes to the ID, a +/// different track. +pub(crate) fn renamed_version(config: &impl Reference, id: &str) -> Option { + (config.track(id) != id).then_some(4) +} diff --git a/rs/hang/src/catalog/root.rs b/rs/hang/src/catalog/root.rs index b920170985d..908d563cd46 100644 --- a/rs/hang/src/catalog/root.rs +++ b/rs/hang/src/catalog/root.rs @@ -1,5 +1,6 @@ //! This module contains the structs and functions for the MoQ catalog format use crate::Result; +use crate::catalog::skipped::Probe; use crate::catalog::{Audio, Binary, Json, PRIORITY, Text, Video}; use serde::de::DeserializeOwned; use std::str::FromStr; @@ -84,16 +85,20 @@ pub struct Catalog { /// Application-defined root sections, flattened alongside the base catalog sections. /// - /// The root `version` is reserved: serializing computes it from the base sections, and fails if - /// the extension names a member `version`. + /// The root `version` is reserved: serializing fails if the extension names a member `version`. pub ext: E, -} -/// The newest moq-hang draft this crate reads; a catalog whose `version` is higher is refused. -const VERSION: u64 = 4; + /// The entries decoding skipped because a newer moq-hang draft defines them. + /// + /// Filled when a catalog is decoded and never written. + pub skipped: crate::catalog::Skipped, +} -/// The wire shape of [`Catalog`]: its sections plus the root `version`, the oldest moq-hang draft -/// that reads the catalog correctly. An absent `version` means 3, the draft before the field. +/// The wire shape of [`Catalog`]: its sections, without the root `version`. +/// +/// The root `version` is the oldest moq-hang draft that reads the catalog correctly, absent while +/// that is 3. [`Probe`] checks it before any section is decoded. No moq-hang-04 field reshapes the +/// root, so this crate never writes it; a field one entry uses raises that entry's `version`. #[serde_with::serde_as] #[serde_with::skip_serializing_none] #[derive(Serialize, Deserialize)] @@ -101,10 +106,6 @@ const VERSION: u64 = 4; #[serde(remote = "Catalog", rename_all = "camelCase")] #[serde(bound(serialize = "E: Serialize", deserialize = "E: DeserializeOwned + Default"))] struct Wire { - // Computed rather than stored, so a republished catalog never claims less than it uses. - #[serde(default, getter = "Catalog::min_version", deserialize_with = "deserialize_version")] - version: Option, - #[serde( default, skip_serializing_if = "Video::is_empty", @@ -159,16 +160,21 @@ struct Wire { #[serde( default, skip_serializing_if = "std::collections::BTreeMap::is_empty", - deserialize_with = "crate::catalog::deserialize_entries" + deserialize_with = "crate::catalog::deserialize_entries", + serialize_with = "crate::catalog::serialize_entries" )] include: std::collections::BTreeMap, #[serde(flatten, serialize_with = "serialize_ext")] ext: E, + + // Filled from `Probe` by `Catalog::from_value`. + #[serde(skip)] + skipped: crate::catalog::Skipped, } -/// Refuse an extension member named `version`: flattened beside the computed one, it would emit a -/// duplicate key that a reader resolves to whichever comes last. +/// Refuse an extension member named `version`: the root `version` is reserved for this +/// specification, and a reader would refuse a catalog whose extension claimed a newer draft. fn serialize_ext(ext: &E, serializer: S) -> std::result::Result { use serde::ser::Error; @@ -187,7 +193,6 @@ fn serialize_ext(ext: &E, serializer: S) -> impl From> for Catalog { fn from(wire: Wire) -> Self { let Wire { - version: _, video, audio, sync, @@ -199,6 +204,7 @@ impl From> for Catalog { echo, include, ext, + skipped, } = wire; Self { video, @@ -212,6 +218,7 @@ impl From> for Catalog { echo, include, ext, + skipped, } } } @@ -223,19 +230,81 @@ impl Serialize for Catalog { } impl<'de, E: DeserializeOwned + Default> Deserialize<'de> for Catalog { + /// Buffered, so every `version` is read before any section, which a newer draft may have + /// reshaped. An entry needing a newer draft is skipped and listed in [`skipped`](Self::skipped). fn deserialize>(deserializer: D) -> std::result::Result { - Wire::deserialize(deserializer) + Self::from_value(Strict::deserialize(deserializer)?.0).map_err(serde::de::Error::custom) } } -/// Refuse a `version` above [`VERSION`]: the newer draft changed something this reader would -/// misread, not merely added something it would miss. -fn deserialize_version<'de, D: serde::Deserializer<'de>>( - deserializer: D, -) -> std::result::Result, D::Error> { - let version = Some(u64::deserialize(deserializer)?); - check_version(version).map_err(serde::de::Error::custom)?; - Ok(version) +/// A JSON value that refuses an object repeating a member, which a [`Value`](serde_json::Value) +/// would silently collapse to its last. Without it, `{"version":5,"version":3}` would read as 3. +struct Strict(serde_json::Value); + +impl<'de> Deserialize<'de> for Strict { + fn deserialize>(deserializer: D) -> std::result::Result { + struct Visitor; + + impl<'de> serde::de::Visitor<'de> for Visitor { + type Value = serde_json::Value; + + fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { + f.write_str("any JSON value") + } + + fn visit_bool(self, v: bool) -> std::result::Result { + Ok(v.into()) + } + + fn visit_i64(self, v: i64) -> std::result::Result { + Ok(v.into()) + } + + fn visit_u64(self, v: u64) -> std::result::Result { + Ok(v.into()) + } + + fn visit_f64(self, v: f64) -> std::result::Result { + Ok(serde_json::Number::from_f64(v).map_or(serde_json::Value::Null, serde_json::Value::Number)) + } + + fn visit_str(self, v: &str) -> std::result::Result { + Ok(v.into()) + } + + fn visit_string(self, v: String) -> std::result::Result { + Ok(v.into()) + } + + fn visit_none(self) -> std::result::Result { + Ok(serde_json::Value::Null) + } + + fn visit_unit(self) -> std::result::Result { + Ok(serde_json::Value::Null) + } + + fn visit_seq>(self, mut seq: A) -> std::result::Result { + let mut items = Vec::new(); + while let Some(Strict(item)) = seq.next_element()? { + items.push(item); + } + Ok(items.into()) + } + + fn visit_map>(self, mut map: A) -> std::result::Result { + let mut object = serde_json::Map::new(); + while let Some((key, Strict(value))) = map.next_entry::()? { + if object.insert(key.clone(), value).is_some() { + return Err(serde::de::Error::custom(format!("duplicate member `{key}`"))); + } + } + Ok(object.into()) + } + } + + deserializer.deserialize_any(Visitor).map(Self) + } } impl Catalog<()> { @@ -290,26 +359,6 @@ impl Catalog { Ok(()) } - /// The oldest moq-hang draft that reads this catalog correctly, or `None` while that is 3. - /// - /// Only a field an older reader would misread raises it; one it would merely ignore does not. - fn min_version(&self) -> Option { - use crate::catalog::Reference; - - fn renamed<'a, C: Reference + 'a>(entries: impl IntoIterator) -> bool { - entries.into_iter().any(|(id, config)| config.track(id) != id) - } - - // moq-hang-04: a reader that ignores `track` subscribes to the ID, a different track. - let renamed = renamed(&self.video.renditions) - || renamed(&self.audio.renditions) - || renamed(&self.text.renditions) - || renamed(&self.json.tracks) - || renamed(&self.binary.tracks); - - renamed.then_some(4) - } - /// Copy the media sections into a catalog with no application extension. pub fn without_ext(&self) -> Catalog<()> { Catalog { @@ -352,10 +401,10 @@ impl Catalog { /// Fails with [`Error::UnsupportedVersion`](crate::Error::UnsupportedVersion) if the catalog /// needs a newer moq-hang draft than this crate reads. pub fn from_slice(v: &[u8]) -> Result { - // Decoded straight from the bytes rather than via a `Value`, which would keep only the - // last of two `version` members instead of refusing them. - check_version(serde_json::from_slice::(v)?.version)?; - Ok(serde_json::from_slice(v)?) + // Probed straight from the bytes first, so an unsupported root `version` is reported before + // any other fault; `Strict` then refuses a repeated member, which a `Value` would collapse. + serde_json::from_slice::(v)?.check()?; + Self::from_value(serde_json::from_slice::(v)?.0) } /// Parse a catalog from a reader. @@ -371,24 +420,19 @@ impl Catalog { /// Parse a catalog from a JSON value. /// /// Fails with [`Error::UnsupportedVersion`](crate::Error::UnsupportedVersion) if the catalog - /// needs a newer moq-hang draft than this crate reads. - pub(crate) fn from_value(value: serde_json::Value) -> Result { - check_version(value.get("version").and_then(serde_json::Value::as_u64))?; - Ok(serde_json::from_value(value)?) - } -} - -/// Just the root `version`, read before any section since the newer draft may have reshaped one. -#[derive(Deserialize)] -struct Probe { - #[serde(default)] - version: Option, -} - -fn check_version(version: Option) -> Result<()> { - match version { - Some(version) if version > VERSION => Err(crate::Error::UnsupportedVersion(version)), - _ => Ok(()), + /// needs a newer moq-hang draft than this crate reads. Every `version` is read before any + /// section, which the newer draft may have reshaped; an entry needing a newer draft is + /// skipped and reported in [`skipped`](Self::skipped). + pub(crate) fn from_value(mut value: serde_json::Value) -> Result { + let probe = Probe::deserialize(&value)?; + probe.check()?; + // Checked, so taken out of what an extension would otherwise receive. + if let Some(root) = value.as_object_mut() { + root.remove("version"); + } + let mut catalog: Self = Wire::deserialize(value)?; + catalog.skipped = probe.skipped; + Ok(catalog) } } @@ -435,10 +479,13 @@ mod test { binary: Vec, #[serde(default)] include: Vec, + #[serde(default)] + skipped: BTreeMap>, } /// The corpus `js/hang` also loads: both languages accept the same catalogs and keep the same - /// rendition, data track, and include IDs, so a divergence fails CI on whichever side drifts. + /// rendition, data track, and include IDs, and skip the same newer entries, 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(); @@ -473,6 +520,22 @@ mod test { case.name )); } + let skipped = &catalog.skipped; + let skipped: BTreeMap> = [ + ("video", &skipped.video), + ("audio", &skipped.audio), + ("text", &skipped.text), + ("json", &skipped.json), + ("binary", &skipped.binary), + ("include", &skipped.include), + ] + .into_iter() + .filter(|(_, ids)| !ids.is_empty()) + .map(|(section, ids)| (section.to_string(), ids.clone())) + .collect(); + if skipped != case.skipped { + failures.push(format!("{}: skipped {skipped:?}", case.name)); + } } } } @@ -1403,7 +1466,17 @@ mod test { let err = Catalog::<()>::from_str(json).unwrap_err(); assert!(err.to_string().contains("duplicate field `version`"), "{json}: {err}"); assert!(Catalog::<()>::from_reader(json.as_bytes()).is_err(), "{json}"); + // So does plain serde, at the root and in an entry. + assert!(serde_json::from_str::(json).is_err(), "{json}"); } + let entry = r#"{"video":{"renditions":{"hd":{"version":5,"version":3,"codec":"avc1.64001f"}}}}"#; + assert!(Catalog::<()>::from_str(entry).is_err(), "{entry}"); + assert!(serde_json::from_str::(entry).is_err(), "{entry}"); + + // Any repeated member, not only `version`. + let repeated = r#"{"video":{"renditions":{"hd":{"codec":"avc1.64001f","codec":"vp8"}}}}"#; + assert!(Catalog::<()>::from_str(repeated).is_err(), "{repeated}"); + assert!(serde_json::from_str::(repeated).is_err(), "{repeated}"); } #[test] @@ -1457,44 +1530,72 @@ mod test { assert_eq!(ok.to_json().unwrap(), r#"{"scte35":{}}"#); } - /// Only a field an older reader would misread raises the version; one it would merely ignore - /// leaves the catalog readable by moq-hang-03. + fn h264() -> VideoConfig { + let mut config = VideoConfig::new(H264 { + profile: 0x64, + constraints: 0x00, + level: 0x1f, + inline: false, + }); + config.container = Container::Legacy; + config + } + + /// Only a field an older reader would misread raises an entry's version; one it would merely + /// ignore leaves the entry readable by moq-hang-03. No moq-hang-04 field raises the root's. #[test] fn the_version_is_written_only_when_needed() { - let rendition = || { - let mut config = VideoConfig::new(H264 { - profile: 0x64, - constraints: 0x00, - level: 0x1f, - inline: false, - }); - config.container = Container::Legacy; - config + let versions = |catalog: &Catalog| { + let value = serde_json::to_value(catalog).unwrap(); + assert_eq!(value.get("version"), None, "the root version is never written"); + let mut versions = BTreeMap::new(); + for (section, map) in [ + ("video", "/video/renditions"), + ("audio", "/audio/renditions"), + ("json", "/json/tracks"), + ("include", "/include"), + ] { + for (id, entry) in value.pointer(map).and_then(|v| v.as_object()).into_iter().flatten() { + if let Some(version) = entry.get("version") { + versions.insert(format!("{section}.{id}"), version.as_u64().unwrap()); + } + } + } + versions }; - let version = |catalog: &Catalog| serde_json::to_value(catalog).unwrap().get("version").cloned(); let mut catalog = Catalog::<()>::default(); - catalog.video.renditions.insert("hd".into(), rendition()); + catalog.video.renditions.insert("hd".into(), h264()); let mut audio = AudioConfig::new(Opus, 48_000, 2); audio.warmup = Some(std::time::Duration::from_millis(80)); catalog.audio.renditions.insert("en".into(), audio); - assert_eq!(version(&catalog), None, "an older reader still plays audio warmup"); + catalog.include.insert( + "extra".into(), + crate::catalog::Include::new(moq_net::path::Relative::new("../extra").unwrap()), + ); + assert_eq!( + versions(&catalog), + BTreeMap::new(), + "an older reader still plays audio warmup" + ); // A `track` naming the ID is what an older reader subscribes to anyway. catalog.video.renditions.get_mut("hd").unwrap().track = Some("hd".into()); - assert_eq!(version(&catalog), None); + assert_eq!(versions(&catalog), BTreeMap::new()); catalog.video.renditions.get_mut("hd").unwrap().track = Some("video".into()); - assert_eq!(version(&catalog), Some(4.into())); + assert_eq!(versions(&catalog), BTreeMap::from([("video.hd".into(), 4)])); let json = catalog.to_json().unwrap(); - assert!(json.starts_with(r#"{"version":4,"#), "{json}"); + assert!(json.contains(r#""hd":{"version":4,"#), "{json}"); assert_eq!(Catalog::<()>::from_str(&json).unwrap(), catalog); - let mut data = Catalog::<()>::default(); let mut chat = JsonConfig::new(Mode::Stream); chat.track = Some("chat.json".into()); - data.json.insert("chat", chat).unwrap(); - assert_eq!(version(&data), Some(4.into())); + catalog.json.insert("chat", chat).unwrap(); + assert_eq!( + versions(&catalog), + BTreeMap::from([("video.hd".into(), 4), ("json.chat".into(), 4)]) + ); } /// moq-hang-04 defines `warmup` for audio only, so a video rendition's is an unknown field: read @@ -1510,11 +1611,117 @@ mod test { ); } - /// The version is computed, never carried: republishing a catalog that claimed more than it + /// Versions are computed, never carried: republishing a catalog that claimed more than it /// uses writes what it actually needs. #[test] fn a_republish_recomputes_the_version() { - let catalog = Catalog::<()>::from_str(r#"{"version":4}"#).unwrap(); - assert_eq!(catalog.to_json().unwrap(), "{}"); + let json = r#"{"version":4,"video":{"renditions":{"hd":{"version":4,"codec":"avc1.64001f"}}}, + "json":{"tracks":{"chat":{"version":4,"mode":"stream"}}}}"#; + let catalog = Catalog::<()>::from_str(json).unwrap(); + assert!( + catalog.json.tracks["chat"].extra.is_empty(), + "the entry version is not an extension" + ); + assert!(!catalog.to_json().unwrap().contains("version")); + } + + /// An entry a newer draft defines is skipped and reported, even one this reader would call + /// malformed, while the rest of the catalog plays. + #[test] + fn a_newer_entry_is_skipped() { + let json = r#"{ + "video": {"renditions": { + "compat": {"codec": "avc1.64001f"}, + "next": {"version": 5, "codec": 42} + }}, + "audio": {"renditions": {"next": {"version": 6}}}, + "text": {"renditions": {"next": {"version": 5}}}, + "json": {"tracks": {"next": {"version": 5}}}, + "binary": {"tracks": {"next": {"version": 5, "mode": []}}}, + "include": {"next": {"version": 5, "broadcast": 7}} + }"#; + + let check = |catalog: Catalog| { + assert_eq!(catalog.video.renditions.keys().collect::>(), ["compat"]); + assert!(catalog.audio.is_empty() && catalog.text.is_empty() && catalog.include.is_empty()); + assert!(catalog.json.is_empty() && catalog.binary.is_empty()); + + let next = |version| BTreeMap::from([("next".to_string(), version)]); + assert_eq!(catalog.skipped.video, next(5)); + assert_eq!(catalog.skipped.audio, next(6)); + assert_eq!(catalog.skipped.text, next(5)); + assert_eq!(catalog.skipped.json, next(5)); + assert_eq!(catalog.skipped.binary, next(5)); + assert_eq!(catalog.skipped.include, next(5)); + assert_eq!(catalog.skipped.version(), Some(6)); + + // Never written, so a republish lists only what this reader read. + let republished = Catalog::<()>::from_str(&catalog.to_json().unwrap()).unwrap(); + assert!(republished.skipped.is_empty()); + assert_eq!(republished.skipped.version(), None); + }; + check(Catalog::from_str(json).unwrap()); + check(serde_json::from_str(json).unwrap()); + + // The root version still refuses the whole catalog. + let root = json.replacen('{', r#"{"version":5,"#, 1); + assert!(matches!( + Catalog::<()>::from_str(&root), + Err(crate::Error::UnsupportedVersion(5)) + )); + + // Even when the newer draft reshaped an entry's own `version`, wherever the root's sits. + for entry in [r#"{"version":"new-shape"}"#, r#"{"version":5,"version":3}"#] { + for json in [ + format!(r#"{{"version":5,"video":{{"renditions":{{"hd":{entry}}}}}}}"#), + format!(r#"{{"video":{{"renditions":{{"hd":{entry}}}}},"version":5}}"#), + ] { + assert!( + matches!(Catalog::<()>::from_str(&json), Err(crate::Error::UnsupportedVersion(5))), + "{json}" + ); + } + } + } + + /// An entry readable by this draft is read whatever version it claims. + #[test] + fn a_supported_entry_version_is_read() { + for version in [0, 3, 4] { + let json = + format!(r#"{{"video":{{"renditions":{{"hd":{{"version":{version},"codec":"avc1.64001f"}}}}}}}}"#); + let catalog = Catalog::<()>::from_str(&json).unwrap(); + assert!(catalog.video.renditions.contains_key("hd"), "{json}"); + assert!(catalog.skipped.is_empty(), "{json}"); + } + } + + /// An entry's version is refused, with the catalog, when malformed or repeated, as the root's is: + /// otherwise a newer entry could slip past the check by also claiming an old version. + #[test] + fn a_malformed_entry_version_is_refused() { + for version in [r#""5""#, "-1", "4.5", "null", "[]"] { + let json = format!(r#"{{"json":{{"tracks":{{"chat":{{"version":{version},"mode":"stream"}}}}}}}}"#); + assert!(Catalog::<()>::from_str(&json).is_err(), "{json}"); + assert!(serde_json::from_str::(&json).is_err(), "{json}"); + } + + for versions in [r#""version":5,"version":3"#, r#""version":3,"version":3"#] { + let json = format!(r#"{{"video":{{"renditions":{{"hd":{{{versions},"codec":"avc1.64001f"}}}}}}}}"#); + let err = Catalog::<()>::from_str(&json).unwrap_err(); + assert!(err.to_string().contains("duplicate field `version`"), "{json}: {err}"); + assert!(Catalog::<()>::from_reader(json.as_bytes()).is_err(), "{json}"); + } + } + + /// A data track extension member named `version` would sit beside the computed one. + #[test] + fn an_entry_extension_version_is_refused() { + let mut catalog = Catalog::<()>::default(); + let mut chat = JsonConfig::new(Mode::Stream); + chat.extra.insert("version".into(), 3.into()); + catalog.json.insert("chat", chat).unwrap(); + let err = catalog.to_json().unwrap_err(); + assert!(err.to_string().contains("must not carry a member `version`"), "{err}"); } } diff --git a/rs/hang/src/catalog/skipped.rs b/rs/hang/src/catalog/skipped.rs new file mode 100644 index 00000000000..2e9ea454bcc --- /dev/null +++ b/rs/hang/src/catalog/skipped.rs @@ -0,0 +1,242 @@ +use std::collections::BTreeMap; + +use serde::de::{DeserializeSeed, Deserializer, Error as _, IgnoredAny, MapAccess, SeqAccess, Visitor}; + +use crate::catalog::VERSION; + +/// The catalog entries a reader skipped because a newer moq-hang draft defines them. +/// +/// Each section maps a skipped entry's ID to its `version`. The rest of the catalog reads as if +/// those entries were absent, so a player plays what it can and may tell its user to upgrade for +/// the rest. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +#[non_exhaustive] +pub struct Skipped { + /// Skipped video renditions. + pub video: BTreeMap, + /// Skipped audio renditions. + pub audio: BTreeMap, + /// Skipped text renditions. + pub text: BTreeMap, + /// Skipped JSON tracks. + pub json: BTreeMap, + /// Skipped binary tracks. + pub binary: BTreeMap, + /// Skipped includes. + pub include: BTreeMap, +} + +impl Skipped { + fn sections(&self) -> [&BTreeMap; 6] { + [ + &self.video, + &self.audio, + &self.text, + &self.json, + &self.binary, + &self.include, + ] + } + + /// Whether every entry was read. + pub fn is_empty(&self) -> bool { + self.sections().iter().all(|section| section.is_empty()) + } + + /// The draft a reader needs to read every skipped entry, or `None` if none was skipped. + pub fn version(&self) -> Option { + self.sections().into_iter().flat_map(BTreeMap::values).copied().max() + } +} + +/// What a reader checks before decoding any section: the root `version`, and which entries are too +/// new to read. +/// +/// Read straight from the bytes where it can, so a repeated `version` member is caught rather than +/// resolved to either copy. Nothing here refuses an entry before the root `version` is checked, +/// since a newer draft may have reshaped any section; every other shape is left to the catalog's +/// own decoding. +#[derive(Default)] +pub(crate) struct Probe { + pub version: Option, + pub skipped: Skipped, + /// An entry repeats its `version` member, which refuses the catalog once the root is read. + pub repeated: bool, +} + +impl Probe { + /// Refuse a root `version` above [`VERSION`], then an entry that repeats its `version`. + /// + /// A root `version` above this reader means the newer draft changed something it would + /// misread, not merely added something it would miss. + pub fn check(&self) -> crate::Result<()> { + match self.version { + Some(version) if version > VERSION => Err(crate::Error::UnsupportedVersion(version)), + _ if self.repeated => Err(crate::Error::Json( + "duplicate field `version` in a catalog entry".to_string(), + )), + _ => Ok(()), + } + } +} + +impl<'de> serde::Deserialize<'de> for Probe { + fn deserialize>(deserializer: D) -> Result { + Lenient(RootSeed).deserialize(deserializer) + } +} + +/// Reads one JSON object's members. +trait MapSeed { + type Value: Default; + fn visit<'de, A: MapAccess<'de>>(self, map: A) -> Result; +} + +/// Reads an object with its [`MapSeed`] and anything else as the seed's default. +struct Lenient(S); + +impl<'de, S: MapSeed> DeserializeSeed<'de> for Lenient { + type Value = S::Value; + + fn deserialize>(self, deserializer: D) -> Result { + deserializer.deserialize_any(self) + } +} + +impl<'de, S: MapSeed> Visitor<'de> for Lenient { + type Value = S::Value; + + fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { + f.write_str("any JSON value") + } + + fn visit_map>(self, map: A) -> Result { + self.0.visit(map) + } + + fn visit_seq>(self, mut seq: A) -> Result { + while seq.next_element::()?.is_some() {} + Ok(Default::default()) + } + + fn visit_bool(self, _: bool) -> Result { + Ok(Default::default()) + } + + fn visit_i64(self, _: i64) -> Result { + Ok(Default::default()) + } + + fn visit_u64(self, _: u64) -> Result { + Ok(Default::default()) + } + + fn visit_f64(self, _: f64) -> Result { + Ok(Default::default()) + } + + fn visit_str(self, _: &str) -> Result { + Ok(Default::default()) + } + + fn visit_unit(self) -> Result { + Ok(Default::default()) + } +} + +struct RootSeed; + +impl MapSeed for RootSeed { + type Value = Probe; + + fn visit<'de, A: MapAccess<'de>>(self, mut map: A) -> Result { + let mut probe = Probe::default(); + while let Some(key) = map.next_key::()? { + let skipped = &mut probe.skipped; + let repeated = &mut probe.repeated; + let (section, entries) = match key.as_str() { + "version" => { + if probe.version.is_some() { + return Err(A::Error::duplicate_field("version")); + } + probe.version = Some(map.next_value()?); + continue; + } + "video" => (&mut skipped.video, Some("renditions")), + "audio" => (&mut skipped.audio, Some("renditions")), + "text" => (&mut skipped.text, Some("renditions")), + "json" => (&mut skipped.json, Some("tracks")), + "binary" => (&mut skipped.binary, Some("tracks")), + "include" => (&mut skipped.include, None), + _ => { + map.next_value::()?; + continue; + } + }; + *section = match entries { + Some(key) => map.next_value_seed(Lenient(SectionSeed(key, repeated)))?, + None => map.next_value_seed(Lenient(EntriesSeed(repeated)))?, + }; + } + Ok(probe) + } +} + +/// A section holding its entries under one key (`renditions`, `tracks`). +struct SectionSeed<'a>(&'static str, &'a mut bool); + +impl MapSeed for SectionSeed<'_> { + type Value = BTreeMap; + + fn visit<'de, A: MapAccess<'de>>(self, mut map: A) -> Result { + let Self(entries, repeated) = self; + let mut skipped = BTreeMap::new(); + while let Some(key) = map.next_key::()? { + if key == entries { + skipped = map.next_value_seed(Lenient(EntriesSeed(&mut *repeated)))?; + } else { + map.next_value::()?; + } + } + Ok(skipped) + } +} + +/// A map of entries keyed by ID, yielding the ones newer than this reader. +struct EntriesSeed<'a>(&'a mut bool); + +impl MapSeed for EntriesSeed<'_> { + type Value = BTreeMap; + + fn visit<'de, A: MapAccess<'de>>(self, mut map: A) -> Result { + let mut skipped = BTreeMap::new(); + while let Some(id) = map.next_key::()? { + if let Some(version) = map.next_value_seed(Lenient(EntrySeed(&mut *self.0)))? + && version > VERSION + { + skipped.insert(id, version); + } + } + Ok(skipped) + } +} + +/// One entry, yielding its `version` when it is one. A malformed `version` is left to the entry's +/// own decoding, which refuses it once the root `version` has been checked. +struct EntrySeed<'a>(&'a mut bool); + +impl MapSeed for EntrySeed<'_> { + type Value = Option; + + fn visit<'de, A: MapAccess<'de>>(self, mut map: A) -> Result, A::Error> { + let mut version = None; + while let Some(key) = map.next_key::()? { + if key != "version" { + map.next_value::()?; + } else if version.replace(map.next_value::()?).is_some() { + *self.0 = true; + } + } + Ok(version.as_ref().and_then(serde_json::Value::as_u64)) + } +} diff --git a/rs/hang/src/catalog/text/mod.rs b/rs/hang/src/catalog/text/mod.rs index 32224310154..6357294bd30 100644 --- a/rs/hang/src/catalog/text/mod.rs +++ b/rs/hang/src/catalog/text/mod.rs @@ -28,11 +28,18 @@ pub struct Text { /// A map of track name to rendition configuration. /// This is not an array so it will work with JSON Merge Patch. /// We use a BTreeMap so keys are sorted alphabetically for *some* deterministic behavior. - #[serde(deserialize_with = "crate::catalog::deserialize_entries")] + #[serde( + deserialize_with = "crate::catalog::deserialize_entries", + serialize_with = "crate::catalog::serialize_entries" + )] pub renditions: BTreeMap, } -impl crate::catalog::Entry for TextConfig {} +impl crate::catalog::Entry for TextConfig { + fn version(&self, id: &str) -> Option { + crate::catalog::renamed_version(self, id) + } +} impl Text { /// Insert a track config, returning an error if the name already exists. diff --git a/rs/hang/src/catalog/video/mod.rs b/rs/hang/src/catalog/video/mod.rs index 6f14e180acd..278c5fd00b7 100644 --- a/rs/hang/src/catalog/video/mod.rs +++ b/rs/hang/src/catalog/video/mod.rs @@ -46,7 +46,10 @@ pub struct Video { /// We use a BTreeMap so keys are sorted alphabetically for *some* deterministic behavior. /// /// A malformed rendition refuses the whole catalog when decoding. - #[serde(deserialize_with = "crate::catalog::deserialize_entries")] + #[serde( + deserialize_with = "crate::catalog::deserialize_entries", + serialize_with = "crate::catalog::serialize_entries" + )] pub renditions: BTreeMap, /// Render the video at this size in pixels. @@ -441,6 +444,10 @@ impl crate::catalog::Entry for VideoConfig { } Ok(()) } + + fn version(&self, id: &str) -> Option { + crate::catalog::renamed_version(self, id) + } } fn is_zero(value: &i32) -> bool {