From fe568ee30a707c9a0e56122e46a7b835f9917371 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 16:10:16 -0700 Subject: [PATCH] feat(hang)!: add json and binary data tracks to the catalog Two new base catalog sections alongside video/audio/text for application data tracks: `json` (UTF-8 JSON frames) and `binary` (opaque bytes). Split by what a generic consumer can do without knowing the application: parse and re-serialize a JSON track, only copy a binary one. `mode` (snapshot|stream) is required with no default, since reading an append log as a latest-value document silently discards every payload but the last. `compression` is an explicit flag rather than the `.z` filename convention, which was never something a consumer could rely on. Adds the moq-binary crate and the @moq/binary package: opaque payloads over a track, the same two modes as moq-json without the JSON. A stream track is exactly one group, and a failed write closes the track rather than rolling a second one, so a gap is never presented as a complete log. moq_mux::{json,binary} mint the catalog entry alongside the track and retire it on drop, so a track is never advertised without a publisher behind it. BREAKING CHANGE: moq_mux::catalog::Catalog gains `json` and `binary` fields and is now #[non_exhaustive], so external struct-literal construction no longer compiles. Build one from Default::default(). Co-Authored-By: Claude Opus 5 --- Cargo.lock | 12 + Cargo.toml | 3 + bun.lock | 15 + doc/concept/layer/hang.md | 96 +++- drafts/draft-lcurley-moq-hang.md | 110 ++++- js/CLAUDE.md | 1 + js/binary/README.md | 13 + js/binary/package.json | 27 ++ js/binary/src/index.ts | 28 ++ js/binary/src/snapshot/consumer.ts | 81 ++++ js/binary/src/snapshot/index.ts | 18 + js/binary/src/snapshot/producer.ts | 70 +++ js/binary/src/snapshot/snapshot.test.ts | 140 ++++++ js/binary/src/stream/consumer.ts | 83 ++++ js/binary/src/stream/index.ts | 24 + js/binary/src/stream/producer.ts | 89 ++++ js/binary/src/stream/stream.test.ts | 108 +++++ js/binary/tsconfig.build.json | 7 + js/binary/tsconfig.json | 9 + js/hang/src/catalog/binary.ts | 50 +++ js/hang/src/catalog/compression.ts | 27 ++ js/hang/src/catalog/data.test.ts | 107 +++++ js/hang/src/catalog/index.ts | 9 +- js/hang/src/catalog/json.ts | 49 ++ js/hang/src/catalog/mode.ts | 28 ++ js/hang/src/catalog/root.test.ts | 5 +- js/hang/src/catalog/root.ts | 18 +- js/hang/src/catalog/section.ts | 34 ++ js/json/src/snapshot/encoder.ts | 37 +- js/json/src/snapshot/producer.ts | 8 +- js/json/src/snapshot/snapshot.test.ts | 79 +++- js/json/src/stream/codec.test.ts | 30 +- js/json/src/stream/consumer.ts | 41 +- js/json/src/stream/encoder.ts | 9 +- js/json/src/stream/index.ts | 2 +- js/json/src/stream/producer.ts | 55 ++- js/net/src/group.test.ts | 16 +- js/net/src/group.ts | 18 + package.json | 1 + rs/CLAUDE.md | 2 + rs/hang/src/catalog/binary.rs | 115 +++++ rs/hang/src/catalog/compression.rs | 63 +++ rs/hang/src/catalog/json.rs | 113 +++++ rs/hang/src/catalog/mod.rs | 48 +- rs/hang/src/catalog/mode.rs | 76 ++++ rs/hang/src/catalog/root.rs | 195 +++++++- rs/hang/src/catalog/text/mod.rs | 7 +- rs/moq-binary/Cargo.toml | 20 + rs/moq-binary/src/lib.rs | 53 +++ rs/moq-binary/src/snapshot/consumer.rs | 124 ++++++ rs/moq-binary/src/snapshot/mod.rs | 156 +++++++ rs/moq-binary/src/snapshot/producer.rs | 135 ++++++ rs/moq-binary/src/stream/consumer.rs | 108 +++++ rs/moq-binary/src/stream/mod.rs | 346 +++++++++++++++ rs/moq-binary/src/stream/producer.rs | 173 ++++++++ rs/moq-gst/tests/element.rs | 2 +- rs/moq-hls/src/export/mod.rs | 6 +- rs/moq-json/src/lib.rs | 9 + rs/moq-json/src/snapshot/encoder.rs | 28 ++ rs/moq-json/src/snapshot/mod.rs | 18 + rs/moq-json/src/snapshot/producer.rs | 8 + rs/moq-json/src/stream/consumer.rs | 34 +- rs/moq-json/src/stream/encoder.rs | 7 + rs/moq-json/src/stream/mod.rs | 67 ++- rs/moq-json/src/stream/producer.rs | 100 +++-- rs/moq-mux/Cargo.toml | 1 + rs/moq-mux/src/binary.rs | 419 +++++++++++++++++ rs/moq-mux/src/catalog/consumer.rs | 4 +- rs/moq-mux/src/catalog/entry.rs | 46 ++ rs/moq-mux/src/catalog/hang/consumer.rs | 41 +- rs/moq-mux/src/catalog/hang/ext.rs | 94 +++- rs/moq-mux/src/catalog/mod.rs | 2 + rs/moq-mux/src/catalog/producer.rs | 69 +++ rs/moq-mux/src/catalog/tracks.rs | 24 + rs/moq-mux/src/error.rs | 12 + rs/moq-mux/src/json.rs | 567 ++++++++++++++++++++++++ rs/moq-mux/src/lib.rs | 14 + rs/moq-mux/src/source.rs | 14 + 78 files changed, 4753 insertions(+), 124 deletions(-) create mode 100644 js/binary/README.md create mode 100644 js/binary/package.json create mode 100644 js/binary/src/index.ts create mode 100644 js/binary/src/snapshot/consumer.ts create mode 100644 js/binary/src/snapshot/index.ts create mode 100644 js/binary/src/snapshot/producer.ts create mode 100644 js/binary/src/snapshot/snapshot.test.ts create mode 100644 js/binary/src/stream/consumer.ts create mode 100644 js/binary/src/stream/index.ts create mode 100644 js/binary/src/stream/producer.ts create mode 100644 js/binary/src/stream/stream.test.ts create mode 100644 js/binary/tsconfig.build.json create mode 100644 js/binary/tsconfig.json create mode 100644 js/hang/src/catalog/binary.ts create mode 100644 js/hang/src/catalog/compression.ts create mode 100644 js/hang/src/catalog/data.test.ts create mode 100644 js/hang/src/catalog/json.ts create mode 100644 js/hang/src/catalog/mode.ts create mode 100644 js/hang/src/catalog/section.ts create mode 100644 rs/hang/src/catalog/binary.rs create mode 100644 rs/hang/src/catalog/compression.rs create mode 100644 rs/hang/src/catalog/json.rs create mode 100644 rs/hang/src/catalog/mode.rs create mode 100644 rs/moq-binary/Cargo.toml create mode 100644 rs/moq-binary/src/lib.rs create mode 100644 rs/moq-binary/src/snapshot/consumer.rs create mode 100644 rs/moq-binary/src/snapshot/mod.rs create mode 100644 rs/moq-binary/src/snapshot/producer.rs create mode 100644 rs/moq-binary/src/stream/consumer.rs create mode 100644 rs/moq-binary/src/stream/mod.rs create mode 100644 rs/moq-binary/src/stream/producer.rs create mode 100644 rs/moq-mux/src/binary.rs create mode 100644 rs/moq-mux/src/catalog/entry.rs create mode 100644 rs/moq-mux/src/json.rs diff --git a/Cargo.lock b/Cargo.lock index 60570d08450..255fd9fa5f4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4708,6 +4708,17 @@ dependencies = [ "usage-rs", ] +[[package]] +name = "moq-binary" +version = "0.1.0" +dependencies = [ + "bytes", + "kio 0.5.6", + "moq-flate", + "moq-net", + "thiserror 2.0.20", +] + [[package]] name = "moq-boy" version = "0.4.11" @@ -4883,6 +4894,7 @@ dependencies = [ "hang", "kio 0.5.6", "memchr", + "moq-binary", "moq-json", "moq-loc", "moq-msf", diff --git a/Cargo.toml b/Cargo.toml index 030375d7fc8..772721c7876 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -5,6 +5,7 @@ members = [ "rs/libmoq", "rs/moq-audio", "rs/moq-bench", + "rs/moq-binary", "rs/moq-boy", "rs/moq-cli", "rs/moq-ffi", @@ -39,6 +40,7 @@ default-members = [ "rs/moq-boy", "rs/moq-audio", "rs/moq-bench", + "rs/moq-binary", "rs/moq-cli", # "rs/moq-ffi", # requires Python/maturin # "rs/moq-gst", # requires GStreamer @@ -113,6 +115,7 @@ loom = { version = "0.7.2", features = ["futures"] } # `async` awaits the event channel instead of blocking a thread on it. mdns-sd = { version = "0.20", features = ["async"] } moq-audio = { version = "0.0.20", path = "rs/moq-audio" } +moq-binary = { version = "0.1.0", path = "rs/moq-binary" } moq-flate = { version = "0.1.1", path = "rs/moq-flate" } moq-hls = { version = "0.4.11", path = "rs/moq-hls", default-features = false } moq-json = { version = "0.3.6", path = "rs/moq-json" } diff --git a/bun.lock b/bun.lock index 5ad96b5e984..19a24d7826f 100644 --- a/bun.lock +++ b/bun.lock @@ -67,6 +67,19 @@ "yaml": "^2.9.0", }, }, + "js/binary": { + "name": "@moq/binary", + "version": "0.1.0", + "dependencies": { + "@moq/flate": "workspace:^", + "@moq/net": "workspace:^", + }, + "devDependencies": { + "@types/bun": "^1.3.14", + "rimraf": "^6.1.3", + "typescript": "7.0.2", + }, + }, "js/clock": { "name": "@moq/clock", "version": "0.1.0", @@ -577,6 +590,8 @@ "@libav.js/variant-opus-af": ["@libav.js/variant-opus-af@6.9.8", "", {}, "sha512-4v4kBOoNnmafubEiBof+ATtr7KcU2/kL+G2hXU61orvC4Lt5OViBXnHdUHCh5ZSQQSmx9nOFEgbYGGYTrBufXQ=="], + "@moq/binary": ["@moq/binary@workspace:js/binary"], + "@moq/boy": ["@moq/boy@workspace:js/moq-boy"], "@moq/clock": ["@moq/clock@workspace:js/clock"], diff --git a/doc/concept/layer/hang.md b/doc/concept/layer/hang.md index 22f40d0872b..49b6b0fe1d2 100644 --- a/doc/concept/layer/hang.md +++ b/doc/concept/layer/hang.md @@ -62,6 +62,9 @@ The compression is the group-scoped `deflate-raw` ([RFC 1951](https://www.rfc-ed To read the compressed track, opt in explicitly: pass `--catalog-format hangz` to `moq export`, `CatalogFormat::HangZ` in Rust, or `catalogFormat: "hangz"` to `@moq/watch`. The `.hang` broadcast suffix is unchanged: the compressed track is an extra track on the same broadcast, not a different broadcast name. +`catalog.json.z` and the `.timeline.z` tracks are always compressed and known by their role. +Everywhere else compression is declared, not guessed: a data track carries a `compression` field (see below), and the `.z` suffix on a track name is a naming convention a consumer must never read as a signal. + ### Audio [See the latest schema](https://github.com/moq-dev/moq/blob/main/js/hang/src/catalog/audio.ts). @@ -119,9 +122,96 @@ Both refuse a target no reference can name, since a path segment may itself be c `@moq/watch` resolves the reference automatically. In Rust, the `moq-mux` exporters do the same: they take a `Source::new(origin, path)`, and both the catalog broadcast and any referenced broadcast resolve through the origin over the same connection. +### Data tracks + +Not everything in a broadcast is media. A chat log, a telemetry feed, a thumbnail, a serialized game state: the catalog lists these in two sections alongside `video` and `audio`, split by what a generic consumer can do with the payload. + +```json +{ + "json": { + "tracks": { + "chat": { "mode": "stream", "compression": "deflate" }, + "status": { "mode": "snapshot" } + } + }, + "binary": { + "tracks": { + "thumbnail": { "mode": "snapshot", "mime": "image/jpeg" } + } + } +} +``` + +A `json` track's frames are UTF-8 JSON values, so a relay, a debugger, or an archiver can parse and re-serialize them without knowing the application. A `binary` track's frames are opaque bytes, which only the application can interpret. Each map is keyed by track name, and unlike the media sections these are not rendition sets: the entries are distinct tracks, not alternatives to choose between. A section is omitted entirely when it holds no tracks. + +`mode` is required and says how a track's groups compose its frames. There is no default, because reading an append log as a latest-value document silently discards every payload but the last: + +- `snapshot` is lossy. Each group is self-contained and supersedes the previous one, so a consumer reads only the newest and a publisher may drop older ones. A JSON track may follow a group's first frame with merge-patch deltas; a binary track writes one frame per group. +- `stream` is lossless in the sense that nothing supersedes anything else. One payload per frame, in order, all in a single group that is never rolled. A publisher that cannot write a payload closes the track, since a second group would present a gap as if it were a complete log. A consumer reads the one group the track carries and fails the read if a second appears, rather than yielding the remainder as though the log were continuous. Retention is still bounded by the group cache: a log longer than the cache holds evicts its earliest frames, and a consumer that falls behind or joins late then cannot read the log at all, since the read fails when it reaches the evicted prefix rather than silently resuming partway through. That is deliberate, because a partial log presented as a whole one is what this mode exists to prevent, and under compression the retained frames are undecodable anyway without the evicted prefix as context. Keep a stream track's log inside what its groups retain, and split anything unbounded across successive tracks. + +`compression` names the compression applied to the frames, or is absent when they are uncompressed. `deflate` is the same group-scoped `deflate-raw` the catalog uses. The remaining fields are optional and descriptive: `schema` (a JSON Schema URL) on a JSON track, `mime` on a binary one. Both kinds also accept the `broadcast` and `timeline` fields a media rendition takes. + +A consumer that does not recognize a track's `mode` or `compression` must ignore that track. It still round-trips verbatim, so a relay that reparses and republishes the catalog never corrupts a track it cannot read. + +#### Publishing and reading + +In Rust you create the track on the broadcast, as you would for a media track, and hand it to the catalog. The catalog writes the entry and drops it when the handle drops, so a track is never advertised without a publisher behind it. The catalog key is the track's own name, with no `.z` suffix even when compressed, since the entry's compression flag is what a consumer reads: + +```rust +let track = broadcast.create_track("chat", None)?; +let mut chat = catalog.json_stream::(track, json::Config::default().with_compression(true))?; +chat.append(&message)?; + +let track = broadcast.create_track("thumbnail", None)?; +let mut thumbnail = catalog.binary_snapshot(track, binary::Config::default().with_mime("image/jpeg"))?; +thumbnail.update(jpeg)?; +``` + +There is a producer type per mode (`json_snapshot` / `json_stream`, `binary_snapshot` / `binary_stream`) so `append` on a latest-value track does not compile. + +The read side names the track once. `catalog.json_track(name)` returns an entry pairing the name with its config, and the entry subscribes itself: + +```rust +let entry = catalog.json_track("chat").expect("no chat track"); +let mut chat = entry.subscribe::(&source).await?; +while let Some(message) = chat.next().await? { + // ... +} +``` + +The entry supplies the track's mode and compression, so a reader cannot pair the wrong ones with the track, and it resolves through a `Source`, so an entry pointing at a sibling broadcast is followed rather than read from the wrong place. + +There is one consumer type rather than one per mode. Both modes hand the caller the same thing, a sequence of values ending when the track does, so a reader writes one loop either way; what differs is loss semantics, and `consumer.mode()` answers that for the rare reader that can only work with one. Discovery is the same entries: `catalog.json_tracks()` and `catalog.binary_tracks()` enumerate them, since the catalog is the only thing that announces a data track. + +In the browser the pieces are the same, assembled by hand: read the entry from `catalog.json.tracks` (or `catalog.binary.tracks`), subscribe to the track by name, and hand it to `@moq/json` or `@moq/binary`. Two mappings to do yourself, since the packages take the mode and compression as code rather than as catalog values: + +```ts +const entry = catalog.json?.tracks.chat; +if (!entry || !Catalog.modeSupported(entry.mode)) return; +if (entry.compression !== undefined && !Catalog.compressionSupported(entry.compression)) return; + +const compression = entry.compression === "deflate"; + +// Honor a cross-broadcast reference the same way the Rust `Entry::subscribe` does; without this +// you would read an unrelated same-named track in the catalog's own broadcast. A catalog is +// untrusted input, so use `tryResolve`: it returns undefined when the reference escapes above the +// root, which the spec says to ignore rather than clamp onto some other valid broadcast. +let source = broadcast; +if (entry.broadcast !== undefined) { + const path = Path.tryResolve(catalogPath, entry.broadcast); + if (!path) return; + source = await connection.consume(path); +} +const track = source.subscribe("chat"); +const consumer = + entry.mode === "stream" ? new Json.Stream.Consumer(track, { compression }) : new Json.Snapshot.Consumer(track, { compression }); +``` + +`mode` picks the namespace (`Stream` or `Snapshot`), and `compression` is a boolean there while the catalog carries `"deflate"` or nothing. Check both against `modeSupported` / `compressionSupported` first and skip the track if either is unrecognized, rather than guessing. + ### Extensions -The base catalog carries only the media sections (`video` and `audio`). +The base catalog carries the media sections (`video` and `audio`) and the data track sections (`json` and `binary`). Applications add their own root sections (for example `scte35`) without modifying hang. The catalog is a JSON document published through the merge-patch snapshot helper (the `Snapshot` mode of `@moq/json` / `moq-json`), and an extension is just an extra top-level key: @@ -140,7 +230,9 @@ This keeps application-specific sections in the application layer while the base ### Custom tracks -A custom catalog section can carry its payload inline (for low-rate metadata), or it can reference a separate track in the same broadcast (for a stream of data, e.g. a `meta.json` track or an SCTE-35 event track). The relay treats such a track like any other; only the publisher and consumer give it meaning. +Reach for the `json` and `binary` sections above first: they name a track and say how to read it, so a generic consumer can find and decode one without application support. + +An application still needs its own catalog section when the metadata is not a track at all (a low-rate value carried inline in the catalog) or when it has to say something the data sections do not model. Such a section can reference a separate track in the same broadcast, which the relay treats like any other; only the publisher and consumer give it meaning. The `@moq/publish` and `@moq/watch` components publish and subscribe to these tracks generically, with no per-application support. Each exposes a low-level track hook, and the application uses `@moq/json` to encode the payload itself: diff --git a/drafts/draft-lcurley-moq-hang.md b/drafts/draft-lcurley-moq-hang.md index ffda90486f9..904d256335f 100644 --- a/drafts/draft-lcurley-moq-hang.md +++ b/drafts/draft-lcurley-moq-hang.md @@ -113,6 +113,8 @@ type Catalog = { "video": VideoSchema | undefined, "timeline": TimelineSchema | undefined, "text": TextSchema | undefined, + "json": JsonTracks | undefined, + "binary": BinaryTracks | undefined, // ... any custom fields ... } ~~~ @@ -120,10 +122,11 @@ type Catalog = { Additional fields MAY be added based on the application. The catalog SHOULD be mostly static, delegating any dynamic content to other tracks. -For example, a `"chat"` section should include the name of a chat track, not individual chat messages. +For example, a chat entry should name a chat track, not carry individual chat messages. 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, plus an optional timeline track ({{timeline}}) indexing their segments. +This specification defines audio, video, and text media tracks, plus an optional timeline track ({{timeline}}) indexing their segments and the application data tracks in {{data}}. ## Video A video track contains the necessary information to decode a video stream. @@ -321,6 +324,102 @@ For example: } ~~~ +## Data Tracks {#data} +Beyond media, a broadcast MAY publish application data tracks: a chat log, a telemetry feed, a thumbnail, a serialized state blob. +The catalog lists them in two sections, split by payload encoding: + +~~~ +type JsonTracks = { + "tracks": Map, +} + +type BinaryTracks = { + "tracks": Map, +} +~~~ + +A `json` track's frames are UTF-8 JSON values; a `binary` track's frames are opaque to everything but the application. +The split is by what a generic consumer can do without knowing the application: parse, inspect, and re-serialize a JSON track, but only copy a binary one. + +Each map is keyed by track name, so an entry's key is the name to subscribe to. +Unlike the media sections these are not rendition sets: entries are distinct tracks, not alternatives to choose between. +A publisher MUST omit a section that holds no tracks. + +A consumer discovers these tracks the same way it discovers media, by reading the catalog; nothing else in the broadcast announces them. + +### JSON {#json-tracks} +~~~ +type JsonSchema = { + "mode": Mode, + "compression": Compression | undefined, + "schema": string | undefined, + "broadcast": string | undefined, + "timeline": Timeline | undefined, +} +~~~ + +The `schema` field is an optional identifier for the shape of each value, typically the URL of a JSON Schema. +It is descriptive: a consumer that does not recognize it MUST still be able to read the track. + +### Binary {#binary-tracks} +~~~ +type BinarySchema = { + "mode": Mode, + "compression": Compression | undefined, + "mime": string | undefined, + "broadcast": string | undefined, + "timeline": Timeline | undefined, +} +~~~ + +The `mime` field is an optional media type ({{!RFC6838}}) for each payload, for example `image/jpeg`. +It is descriptive, the same as `schema` above. + +### mode {#field-mode} +~~~ +type Mode = "snapshot" | "stream" +~~~ + +The `mode` field says how a track's groups compose its frames into what a consumer sees. +It is REQUIRED and has no default: reading an append log as a latest-value document silently discards every payload but the last. +A consumer MUST ignore a track whose `mode` it does not recognize. + +A `snapshot` track is lossy. +Each group is self-contained and supersedes the previous one, so a consumer reads only the newest group and a publisher MAY drop older ones. +A group's first frame is a complete value. +A `json` track MAY follow it with JSON Merge Patch ({{!RFC7396}}) deltas applied in order; a `binary` track MUST write exactly one frame per group, since an opaque payload has no delta form. + +A `stream` track is lossless in the sense that nothing supersedes anything else. +It is a single group, never rolled, carrying one self-contained payload per frame, delivered in order. + +A publisher that cannot write a payload MUST close the track rather than continue the log in a second group. +A second group would present a gap as if it were a complete log; ending the track surfaces the failure instead, and a publisher with more to say opens a new track. + +A consumer MUST NOT skip to the newest group, since a later group does not supersede an earlier one the way a `snapshot` group does. +It reads the one group the track carries, and MUST fail the read if the track carries a second, since whatever would have completed the first group is gone and yielding the remainder would present that gap as a continuous log. +This is why a consumer takes groups in arrival order rather than by ascending sequence: groups are separate streams, so a second group MAY arrive with a lower sequence than the first, and skipping it would report a truncated log as a whole one. + +Retention is bounded, and this is the limit of "lossless". +A group's cache is finite, so a publisher that writes more than it holds evicts the log's earliest frames. +A consumer that has not kept up, or that subscribes later, then cannot read the log at all: the read fails once it reaches the evicted prefix, rather than silently resuming at whatever the cache still holds. +That is the intended behaviour, since a partial log presented as a whole one is exactly what this mode exists to prevent, and under compression ({{compression}}) the retained frames are undecodable anyway without the evicted prefix as context. +A publisher SHOULD therefore keep a `stream` track's log within what its groups retain, and split anything unbounded across successive tracks; a consumer that needs the whole log SHOULD subscribe before the publisher exceeds that. + +### compression {#field-compression} +~~~ +type Compression = "deflate" +~~~ + +The `compression` field names the compression applied to the track's frames. +If absent, the frames are uncompressed. +A consumer MUST ignore a track whose `compression` it does not recognize, since it cannot decode the frames. + +The `deflate` value is the group-scoped DEFLATE of {{compression}}. +A `snapshot` group covers a single value (plus any deltas), so its window spans that group alone; a `stream` group's frames compress against the earlier ones in the log. + +### broadcast and timeline {#data-shared} +The `broadcast` ({{field-broadcast}}) and `timeline` ({{field-timeline}}) fields carry the same meaning here as they do for a media rendition. + ## Binary Fields {#binary} A decoder config field carrying raw bytes, notably `description` (an `AllowSharedBufferSource` in WebCodecs), is carried in the catalog as a hex string ({{!RFC4648, Section 8}}). A publisher SHOULD emit lowercase hexadecimal characters and MUST NOT emit a `0x` prefix or any separators. @@ -427,7 +526,12 @@ Each frame is a Low Overhead Container frame {{!I-D.ietf-moq-loc}}: a property b # Compression {#compression} -Some metadata tracks are compressed, conventionally marked with a `.z` suffix on the track name. +Some metadata tracks are compressed. + +Compression is signalled per track, never inferred from the track's name. +A data track ({{data}}) declares it with the `compression` field ({{field-compression}}). +The two tracks this specification defines as always compressed, `catalog.json.z` ({{catalog}}) and the timeline track ({{timeline}}), are identified by their role instead. +The `.z` suffix on those names is a naming convention, and a consumer MUST NOT treat it as a signal. Each group is one raw DEFLATE stream ({{!RFC1951}}), sync-flushed at each frame boundary. Each frame is therefore a self-delimited, byte-aligned slice, while later frames compress against the earlier ones in the same group. diff --git a/js/CLAUDE.md b/js/CLAUDE.md index 4c5f175b076..27bd9f38854 100644 --- a/js/CLAUDE.md +++ b/js/CLAUDE.md @@ -19,6 +19,7 @@ Bun workspaces; members listed in the repo-root `package.json` (not in `js/`). D - `@moq/loc` (`loc/`): Low Overhead Container frame encoding. Thin layer on `@moq/net`. - `@moq/json` (`json/`): JSON over a track, in three namespaces. `Snapshot` is lossy latest-value (RFC 7396 merge-patch deltas; consumers only get the most recent value; the base `Snapshot.Producer`/`Snapshot.Consumer` that `@moq/hang`'s catalog extends); `Stream` is a lossless append-log (every record preserved in order); `Window` is an append-and-trim sequence that can restate a retained checkpoint when a group rolls. DEFLATE via `@moq/flate`. +- `@moq/binary` (`binary/`): opaque binary payloads over a track: the same two namespaces as `@moq/json`, without the JSON. `Snapshot` is lossy latest-value (one self-contained group per value); `Stream` is a lossless append-log (a single group, one payload per frame, sharing one DEFLATE window). Compression via `@moq/flate`, framed identically to `@moq/json` so the two agree on the wire. Mirror of `rs/moq-binary`. - `@moq/flate` (`flate/`): group-scoped DEFLATE primitive (only deps on `pako`). `Encoder`/`Decoder` turn a stream of payloads into self-delimited sync-flushed frames sharing one window; wire-interoperable with the Rust `moq-flate` crate. Used by `@moq/json`. - `@moq/msf` (`msf/`): MOQT Streaming Format catalog types (zod schemas). diff --git a/js/binary/README.md b/js/binary/README.md new file mode 100644 index 00000000000..732050ff57e --- /dev/null +++ b/js/binary/README.md @@ -0,0 +1,13 @@ +# @moq/binary + +Opaque binary payloads over MoQ tracks, in two modes: + +- `Snapshot`: **lossy**. One value updated over time; a consumer only gets the most recent one. +- `Stream`: **lossless**. An ordered append-log of self-contained payloads, nothing superseded. + +The bytes are opaque: this package frames them onto a track and optionally compresses them, and +never looks inside. For JSON documents reach for [`@moq/json`](../json) instead, which adds RFC 7396 +merge-patch deltas on top of the same two modes. + +Compression is [`@moq/flate`](../flate), the same group-scoped DEFLATE `@moq/json` uses, so the two +agree on the wire. Interoperable with the Rust `moq-binary` crate. diff --git a/js/binary/package.json b/js/binary/package.json new file mode 100644 index 00000000000..ac27c6f2f5e --- /dev/null +++ b/js/binary/package.json @@ -0,0 +1,27 @@ +{ + "name": "@moq/binary", + "type": "module", + "version": "0.1.0", + "description": "Binary publishing over MoQ tracks: latest-value snapshots, or append-log streams.", + "license": "(MIT OR Apache-2.0)", + "repository": "github:moq-dev/moq", + "sideEffects": false, + "exports": { + ".": "./src/index.ts" + }, + "scripts": { + "build": "rimraf dist && tsc -b tsconfig.build.json && bun ../common/package.ts", + "check": "tsc --noEmit", + "test": "bun test --only-failures", + "release": "bun ../common/release.ts" + }, + "dependencies": { + "@moq/flate": "workspace:^", + "@moq/net": "workspace:^" + }, + "devDependencies": { + "@types/bun": "^1.3.14", + "rimraf": "^6.1.3", + "typescript": "7.0.2" + } +} diff --git a/js/binary/src/index.ts b/js/binary/src/index.ts new file mode 100644 index 00000000000..da190f0f494 --- /dev/null +++ b/js/binary/src/index.ts @@ -0,0 +1,28 @@ +/** + * Opaque binary payloads over MoQ tracks, in two modes: + * + * - {@link Snapshot}: **lossy**. One value updated over time; a consumer only gets the most recent + * one. Older values are superseded and dropped. + * - {@link Stream}: **lossless**. An ordered append-log of self-contained payloads, delivered in + * order with nothing superseded. Bounded by the group cache: see {@link Stream} for what that + * costs a consumer that falls behind. + * + * Pick {@link Snapshot} when consumers care about "what is the value now" (a poster image, a + * serialized state blob) and {@link Stream} when they care about every payload (an event log, a + * sequence of samples). + * + * The bytes are opaque: this package frames them onto a track and optionally compresses them, and + * never looks inside. For JSON documents reach for `@moq/json` instead, which adds RFC 7396 + * merge-patch deltas on top of the same two modes. + * + * Compression is `@moq/flate`, the same group-scoped DEFLATE `@moq/json` uses, so the two agree on + * the wire: each group is one raw DEFLATE stream, sync-flushed at every frame boundary. A + * {@link Stream} therefore compresses each payload against the earlier ones in its group, while a + * {@link Snapshot} group holds a single self-contained value. Interoperable with the Rust + * `moq-binary` crate. + * + * @module + */ + +export * as Snapshot from "./snapshot/index.ts"; +export * as Stream from "./stream/index.ts"; diff --git a/js/binary/src/snapshot/consumer.ts b/js/binary/src/snapshot/consumer.ts new file mode 100644 index 00000000000..04bd84bd3ba --- /dev/null +++ b/js/binary/src/snapshot/consumer.ts @@ -0,0 +1,81 @@ +import { Decoder as Flate } from "@moq/flate"; +import * as Moq from "@moq/net"; + +/** Options for a {@link Consumer}. */ +export interface ConsumerConfig { + /** Whether the frames are `deflate-raw` compressed. Must match the producer. Defaults to `false`. */ + compression?: boolean; +} + +/** + * Consumes a binary value from a track, yielding the newest one. + * + * Jumps to the newest group and reads the value out of it, so a late joiner starts at the current + * value rather than replaying superseded ones. Interoperable with the Rust + * `moq_binary::snapshot::Consumer`, which collapses the same backlog. + */ +export class Consumer { + #track: Moq.Track.Ordered; + #decompress: boolean; + + // The group the current window belongs to, so a boundary restarts it. + #group?: number; + // The DEFLATE window for the current group, present while decompressing. A snapshot group is + // normally one frame, but the window is per group either way. + #flate?: Flate; + + constructor(track: Moq.Track.Subscriber, config: ConsumerConfig = {}) { + this.#track = track.ordered(); + this.#decompress = config.compression ?? false; + } + + /** + * Get the next value, or `undefined` once the track ends. + * + * Every group is a complete value, so any older group is already superseded. Raising the read + * floor to the newest sequence before each read does two things: it discards a backlog instead + * of decoding every superseded value in turn, and it abandons a group a newer one has + * superseded rather than waiting out its close. A snapshot reader's latency therefore never + * grows with the queue, and never depends on a stale group's FIN arriving. + * + * This consumer owns its subscriber's read cursor, which is what lets it discard the backlog. + */ + async next(): Promise { + for (;;) { + const latest = this.#track.latest(); + if (latest !== undefined) this.#track.startAt(latest); + + let next: Awaited>; + try { + next = await this.#track.readFrameSequence(); + } catch (err) { + // Falling behind a group's eviction window is recoverable: the next group carries a + // complete value of its own, so resync there rather than surfacing a partial read. + // Anything else is the track's terminal error, which every later read would throw + // again; swallowing it would spin here instead of telling the caller the + // subscription died. + if (!(err instanceof Moq.Group.Lagged)) throw err; + continue; + } + + if (!next) return undefined; + + // Each group is its own compressed stream, so a boundary starts a cold window. + if (next.group !== this.#group) { + this.#group = next.group; + this.#flate = this.#decompress ? new Flate() : undefined; + } + + return this.#flate ? this.#flate.frame(next.payload) : next.payload; + } + } + + /** Iterate over values until the track ends, each the newest at the time it is yielded. */ + async *[Symbol.asyncIterator](): AsyncIterator { + for (;;) { + const value = await this.next(); + if (value === undefined) return; + yield value; + } + } +} diff --git a/js/binary/src/snapshot/index.ts b/js/binary/src/snapshot/index.ts new file mode 100644 index 00000000000..d901d721ee4 --- /dev/null +++ b/js/binary/src/snapshot/index.ts @@ -0,0 +1,18 @@ +/** + * Lossy latest-value binary publishing over MoQ tracks. + * + * One opaque value updated over time, for consumers that only care about the current state (a + * poster image, a serialized state blob). This mode is **lossy** by design: a consumer yields only + * the most recent value. A late joiner (or a consumer that falls behind) jumps straight to the + * newest group, and older groups are dropped entirely. For an ordered log where every payload is + * preserved, use the `Stream` module instead. + * + * On the wire each value is one group holding one frame, so a group is self-contained and a + * consumer never needs an older one. With {@link ProducerConfig.compression} on, that frame is its + * own raw DEFLATE stream; there is no window to share across a single-frame group. + * + * @module + */ + +export { Consumer, type ConsumerConfig } from "./consumer.ts"; +export { Producer, type ProducerConfig } from "./producer.ts"; diff --git a/js/binary/src/snapshot/producer.ts b/js/binary/src/snapshot/producer.ts new file mode 100644 index 00000000000..4fcf5e26983 --- /dev/null +++ b/js/binary/src/snapshot/producer.ts @@ -0,0 +1,70 @@ +import { DEFAULT_MAX_FRAME_SIZE, Encoder as Flate } from "@moq/flate"; +import * as Moq from "@moq/net"; +import { Time } from "@moq/net"; + +/** Options for a {@link Producer}. */ +export interface ProducerConfig { + /** + * Compress each value as its own raw DEFLATE stream. + * + * A snapshot group holds a single self-contained value, so there is no window to share: each + * value is compressed alone. A {@link Consumer} reading the frames must set the same flag. + * Defaults to `false`. + */ + compression?: boolean; +} + +/** + * Publishes a binary value to a track, one value per group. + * + * Each {@link update} rolls a new group holding the whole value, so a consumer only ever needs the + * newest group and older ones are dropped. For a log where every payload survives, use the `Stream` + * module. + */ +export class Producer { + #track: Moq.Track.Producer; + #compress: boolean; + + /** Wrap a track to publish a binary value into it. */ + constructor(track: Moq.Track.Producer, config: ProducerConfig = {}) { + this.#track = track; + this.#compress = config.compression ?? false; + } + + /** + * Publish a new value, superseding the previous one. + * + * Unlike `@moq/json`, an identical value is republished rather than skipped: comparing two + * opaque blobs costs a full scan, and only the caller knows whether its bytes changed. + */ + update(payload: Uint8Array): void { + // Consumers all decode with `@moq/flate`'s default cap, so publishing past it would advertise + // a value that always fails to read. Rejected before anything is published; unlike a stream + // this is not terminal, since the previous value still stands and the next update supersedes. + if (this.#compress && payload.byteLength > DEFAULT_MAX_FRAME_SIZE) { + throw new Error(`payload larger than the decoder's ${DEFAULT_MAX_FRAME_SIZE} byte limit`); + } + + // One frame per group, so the window spans a single value and starts cold every time. + const encoded = this.#compress ? new Flate().frame(payload) : payload; + + // Check before opening a group. `appendGroup` publishes immediately, so letting `writeFrame` + // reject the frame would leave an empty newest group behind: a snapshot consumer jumps to the + // newest, so the previous value would be lost even though this update threw. + if (encoded.byteLength > Moq.Group.MAX_GROUP_CACHE_BYTES) throw new Moq.Group.FrameTooLarge(); + + const group = this.#track.appendGroup(); + try { + group.writeFrame({ payload: encoded, timestamp: Time.Timestamp.now() }); + } finally { + // The group is already visible on the track, so leaving it open on a failed write would + // strand a subscriber that advanced into it with nothing to read and no end. + group.close(); + } + } + + /** Finish the track. */ + finish(): void { + this.#track.close(); + } +} diff --git a/js/binary/src/snapshot/snapshot.test.ts b/js/binary/src/snapshot/snapshot.test.ts new file mode 100644 index 00000000000..706fb5bc0f2 --- /dev/null +++ b/js/binary/src/snapshot/snapshot.test.ts @@ -0,0 +1,140 @@ +import { expect, test } from "bun:test"; +import { Time, Track } from "@moq/net"; +import { Consumer, Producer } from "./index.ts"; + +const bytes = (...values: number[]) => new Uint8Array(values); + +// Walking a finished track's groups inspects a complete timeline, so request a replay window +// instead of the transport's live-edge default, which skips every superseded group. +const REPLAY_LATENCY = 30_000; + +// Drain every value currently available from a fresh consumer over the (finished) track. +async function drain(track: Track.Subscriber, compression: boolean): Promise { + const consumer = new Consumer(track, { compression }); + const out: Uint8Array[] = []; + for (;;) { + const value = await consumer.next(); + if (value === undefined) break; + out.push(value); + } + return out; +} + +test("one single-frame group per update", async () => { + const track = new Track.Producer("test"); + const producer = new Producer(track); + producer.update(bytes(1)); + producer.update(bytes(2)); + producer.finish(); + + // Two updates => two self-contained groups, so a consumer never needs an older one: a reader + // that arrives after both discards the superseded first group instead of replaying it. + expect(await drain(track.subscribe(), false)).toEqual([bytes(2)]); + + const subscriber = track.subscribe({ maxAge: REPLAY_LATENCY }).ordered(); + const counts: number[] = []; + for (;;) { + const group = await subscriber.nextGroup(); + if (!group) break; + let frames = 0; + while ((await group.readFrame()) !== undefined) frames++; + counts.push(frames); + } + expect(counts).toEqual([1, 1]); +}); + +test("a live consumer sees each update", async () => { + const track = new Track.Producer("test"); + const producer = new Producer(track); + const consumer = new Consumer(track.subscribe()); + + for (let n = 0; n < 3; n++) { + producer.update(bytes(n)); + expect(await consumer.next()).toEqual(bytes(n)); + } + producer.finish(); +}); + +test("compressed roundtrip", async () => { + const track = new Track.Producer("test"); + const producer = new Producer(track, { compression: true }); + const payload = new TextEncoder().encode("the quick brown fox".repeat(64)); + producer.update(payload); + producer.finish(); + + expect(await drain(track.subscribe(), true)).toEqual([payload]); +}); + +test("compression shrinks the frame on the wire", async () => { + // A consumer that ignored the catalog's compression flag would read this raw and get garbage, + // which is why the flag has to be carried rather than guessed. + const track = new Track.Producer("test"); + const producer = new Producer(track, { compression: true }); + const payload = new TextEncoder().encode("the quick brown fox".repeat(64)); + producer.update(payload); + producer.finish(); + + const group = await track.subscribe().ordered().nextGroup(); + const frame = await group?.readFrame(); + expect(frame?.payload.byteLength).toBeLessThan(payload.byteLength / 4); +}); + +test("a finished track ends the consumer", async () => { + const track = new Track.Producer("test"); + const producer = new Producer(track); + producer.update(bytes(7)); + producer.finish(); + + const consumer = new Consumer(track.subscribe()); + expect(await consumer.next()).toEqual(bytes(7)); + expect(await consumer.next()).toBeUndefined(); +}); + +test("a backlog collapses to the newest value", async () => { + // A consumer that fell behind (or joined late) must not replay every superseded value: its + // latency would grow with the backlog, and each older group is already superseded by design. + const track = new Track.Producer("test"); + const producer = new Producer(track); + const consumer = new Consumer(track.subscribe()); + + for (let n = 0; n < 10; n++) producer.update(bytes(n)); + producer.finish(); + + expect(await consumer.next()).toEqual(bytes(9)); + expect(await consumer.next()).toBeUndefined(); +}); + +test("a newer group preempts an open one", async () => { + // A group whose close is delayed must not park the reader while a newer value is available. + // Snapshot mode exists to deliver the current value, not to wait out a stale group's FIN, and + // groups ride independent QUIC streams so a newer one can land first. + const track = new Track.Producer("test"); + const consumer = new Consumer(track.subscribe()); + + const stale = track.appendGroup(); + stale.writeFrame({ payload: bytes(1), timestamp: Time.Timestamp.now() }); + expect(await consumer.next()).toEqual(bytes(1)); + + // A complete newer value arrives while the previous group is still open. + const fresh = track.appendGroup(); + fresh.writeFrame({ payload: bytes(2), timestamp: Time.Timestamp.now() }); + fresh.close(); + + expect(await consumer.next()).toEqual(bytes(2)); + + stale.close(); + track.close(); +}); + +test("an aborted track surfaces its error instead of spinning", async () => { + // Every read after an abort throws the same terminal error, so swallowing it as if it were a + // recoverable Lagged would loop forever on a rejected promise rather than telling the caller + // the subscription died. + const track = new Track.Producer("test"); + const consumer = new Consumer(track.subscribe()); + + const boom = new Error("subscription aborted"); + track.close(boom); + + await expect(consumer.next()).rejects.toThrow("subscription aborted"); +}); diff --git a/js/binary/src/stream/consumer.ts b/js/binary/src/stream/consumer.ts new file mode 100644 index 00000000000..192601817cb --- /dev/null +++ b/js/binary/src/stream/consumer.ts @@ -0,0 +1,83 @@ +import { Decoder as Flate } from "@moq/flate"; +import type * as Moq from "@moq/net"; + +/** Options for a {@link Consumer}. */ +export interface ConsumerConfig { + /** Whether the frames are `deflate-raw` compressed. Must match the producer. Defaults to `false`. */ + compression?: boolean; +} + +/** + * Thrown by a stream read when the track carried a second group, which a lossless log cannot do. + * + * A stream is a single group by construction: a publisher that cannot write a payload ends the + * track rather than rolling. A second group therefore means whatever would have completed the + * first is gone, so the read reports it instead of handing back the remainder as a continuous log. + * + * Mirrors the Rust `moq_binary::Error::Rolled`. + */ +export class Rolled extends Error { + constructor() { + super("rolled: the stream carried a second group, so records are missing"); + this.name = "Rolled"; + } +} + +/** + * Consumes an ordered log of binary payloads from a track, yielding every one in order. + * + * The log is a single group. That is what makes the mode lossless: rolling to a second group means + * the payloads that would have completed the first are gone, so a publisher that cannot write ends + * the track instead. A second group is therefore a broken publisher, and reading it would present + * a gap as a continuous log, so it throws {@link Rolled} rather than yielding the remainder. + */ +export class Consumer { + #track: Moq.Track.Subscriber; + #decompress: boolean; + + #group?: Moq.Group.Consumer; + // Whether the log's one group has been taken, so a second is a rolled log rather than the first. + #taken = false; + // The DEFLATE window for the group, present while decompressing. + #flate?: Flate; + + constructor(track: Moq.Track.Subscriber, config: ConsumerConfig = {}) { + this.#track = track; + this.#decompress = config.compression ?? false; + } + + /** Get the next payload, or `undefined` once the track ends. */ + async next(): Promise { + for (;;) { + if (!this.#group) { + // Arrival order rather than sequence order, because there is only ever one group to + // take and a second one has to be seen whatever its sequence. The monotonic + // `nextGroup` would drop a late lower sequence, which is the very loss this reports. + this.#group = await this.#track.recvGroup(); + if (!this.#group) return undefined; + if (this.#taken) throw new Rolled(); + this.#taken = true; + this.#flate = this.#decompress ? new Flate() : undefined; + } + + const frame = await this.#group.readFrame(); + if (frame === undefined) { + // The log's one group is exhausted. Keep reading the track so a clean end still + // reports the log as complete, and so a second group is caught as Rolled. + this.#group = undefined; + continue; + } + + return this.#flate ? this.#flate.frame(frame.payload) : frame.payload; + } + } + + /** Iterate over every payload in order, until the track ends. */ + async *[Symbol.asyncIterator](): AsyncIterator { + for (;;) { + const value = await this.next(); + if (value === undefined) return; + yield value; + } + } +} diff --git a/js/binary/src/stream/index.ts b/js/binary/src/stream/index.ts new file mode 100644 index 00000000000..e60a5ecaeb4 --- /dev/null +++ b/js/binary/src/stream/index.ts @@ -0,0 +1,24 @@ +/** + * Lossless append-log binary publishing over MoQ tracks. + * + * An ordered log of opaque payloads, for consumers that care about every one (an event log, a + * sequence of samples). Nothing is ever superseded: a consumer yields each payload in the order it + * was appended. For a latest-value document, use the `Snapshot` module instead. + * + * Retention is bounded, which is the limit of "lossless" here. The group's cache is finite, so a + * log longer than it holds evicts its earliest frames, and a consumer that falls behind or + * subscribes late then fails its read with `Lagged` rather than silently resuming partway through: + * a partial log presented as a whole one is what this mode exists to prevent. Keep a log inside + * what the group retains, and split anything unbounded across successive tracks. + * + * On the wire the log rides a **single group** that is never rolled, one payload per frame. A + * payload that cannot be written ends the track rather than opening a second group: a log missing a + * record is not lossless, and a gap dressed up as a complete log is worse than a visible failure. + * With {@link ProducerConfig.compression} on, that one group is one DEFLATE window, so each payload + * compresses against the earlier ones and a run of similar payloads shrinks sharply. + * + * @module + */ + +export { Consumer, type ConsumerConfig, Rolled } from "./consumer.ts"; +export { Producer, type ProducerConfig } from "./producer.ts"; diff --git a/js/binary/src/stream/producer.ts b/js/binary/src/stream/producer.ts new file mode 100644 index 00000000000..defe73f5edc --- /dev/null +++ b/js/binary/src/stream/producer.ts @@ -0,0 +1,89 @@ +import { DEFAULT_MAX_FRAME_SIZE, Encoder as Flate } from "@moq/flate"; +import type * as Moq from "@moq/net"; +import { Time } from "@moq/net"; + +/** Options for a {@link Producer}. */ +export interface ProducerConfig { + /** + * Compress the group as one sync-flushed `deflate-raw` stream, so each payload reuses the + * earlier ones as context. A {@link Consumer} reading the frames must set the same flag. + * Defaults to `false`. + */ + compression?: boolean; +} + +/** + * Publishes an ordered log of binary payloads to a track, one payload per frame in a single group. + */ +export class Producer { + #track: Moq.Track.Producer; + #compress: boolean; + + // The DEFLATE window for the whole log, present while compressing. + #flate?: Flate; + // The single group carrying the whole log, opened on the first append and never rolled. + #group?: Moq.Group.Producer; + + /** Wrap a track to publish a payload log into it. */ + constructor(track: Moq.Track.Producer, config: ProducerConfig = {}) { + this.#track = track; + this.#compress = config.compression ?? false; + this.#flate = this.#compress ? new Flate() : undefined; + } + + /** + * Append one payload to the log. + * + * A payload that cannot be written ends the track: a log missing a record is not the lossless + * log this mode promises, so the failure is surfaced rather than papered over with a second + * group. The group is aborted rather than closed cleanly, so a consumer sees the failure + * instead of a log that merely looks complete. Every later append fails on the closed track. + */ + append(payload: Uint8Array): void { + // A payload no consumer could decode is as terminal as one the track rejects: consumers all + // decode with `@moq/flate`'s default cap, so this would publish a record none of them could + // read. Ends the track like any other lost record, and aborts the group the same way the + // write path below does: an earlier append may already have opened one, and leaving the two + // paths to tear down differently only invites a reader to wonder which is authoritative. + if (this.#flate && payload.byteLength > DEFAULT_MAX_FRAME_SIZE) { + const err = new Error(`payload larger than the decoder's ${DEFAULT_MAX_FRAME_SIZE} byte limit`); + this.#group?.close(err); + this.#group = undefined; + this.#track.close(err); + throw err; + } + + // Open the group before compressing: a failure here must not leave the window ahead of a + // consumer that never received the frame. + this.#group ??= this.#track.appendGroup(); + + const encoded = this.#flate ? this.#flate.frame(payload) : payload; + + try { + this.#group.writeFrame({ payload: encoded, timestamp: Time.Timestamp.now() }); + } catch (err) { + // The payload never reached the wire, so the log has a hole in it, which is not the + // lossless log this mode promises. Continuing into a second group would hand consumers a + // gap dressed up as a complete log, so end the track and let the caller start a new one. + // + // Abort rather than closing cleanly: a clean close reads as `undefined`, exactly what a + // completed log looks like, so a consumer could not tell a truncated log from a whole one. + // Both halves are needed. The track reaches a reader that has not pulled the group yet, + // since aborting only the group drops it from the cache and that reader still sees a clean + // end. The group reaches a reader already inside it, which keeps its own handle and would + // otherwise get a generic error when ours is dropped. + const abort = err instanceof Error ? err : new Error(String(err)); + this.#group?.close(abort); + this.#group = undefined; + this.#track.close(abort); + throw err; + } + } + + /** Finish the track, closing the group. */ + finish(): void { + this.#group?.close(); + this.#group = undefined; + this.#track.close(); + } +} diff --git a/js/binary/src/stream/stream.test.ts b/js/binary/src/stream/stream.test.ts new file mode 100644 index 00000000000..c6ddd91dbdd --- /dev/null +++ b/js/binary/src/stream/stream.test.ts @@ -0,0 +1,108 @@ +import { expect, test } from "bun:test"; +import { DEFAULT_MAX_FRAME_SIZE } from "@moq/flate"; +import { Time, Track } from "@moq/net"; +import { Consumer, Producer, Rolled } from "./index.ts"; + +// Ask for a replay window, so the superseded first group is delivered rather than skipped by the +// subscriber's default max-age budget. A rolled log is exactly the case where both groups matter. +const REPLAY_LATENCY = 30_000; + +const payloads = (count: number) => Array.from({ length: count }, (_, n) => new Uint8Array(8).fill(n)); + +// Drain every payload currently available from a fresh consumer over the (finished) track. +async function drain(track: Track.Subscriber, compression: boolean): Promise { + const consumer = new Consumer(track, { compression }); + const out: Uint8Array[] = []; + for (;;) { + const value = await consumer.next(); + if (value === undefined) break; + out.push(value); + } + return out; +} + +test("every payload survives in order", async () => { + const track = new Track.Producer("test"); + const producer = new Producer(track); + const expected = payloads(5); + for (const payload of expected) producer.append(payload); + producer.finish(); + + expect(await drain(track.subscribe(), false)).toEqual(expected); +}); + +test("compressed roundtrip in order", async () => { + const track = new Track.Producer("test"); + const producer = new Producer(track, { compression: true }); + const expected = payloads(20); + for (const payload of expected) producer.append(payload); + producer.finish(); + + expect(await drain(track.subscribe(), true)).toEqual(expected); +}); + +test("the whole log rides one group, never rolled", async () => { + const track = new Track.Producer("test"); + const producer = new Producer(track, { compression: true }); + for (const payload of payloads(50)) producer.append(payload); + producer.finish(); + + const subscriber = track.subscribe().ordered(); + expect((await subscriber.nextGroup())?.sequence).toBe(0); + expect(await subscriber.nextGroup()).toBeUndefined(); +}); + +test("the shared window shrinks repetitive payloads", async () => { + const track = new Track.Producer("test"); + const producer = new Producer(track, { compression: true }); + const payload = new TextEncoder().encode("the quick brown fox".repeat(16)); + for (let n = 0; n < 8; n++) producer.append(payload); + producer.finish(); + + const group = await track.subscribe().ordered().nextGroup(); + const sizes: number[] = []; + for (;;) { + const frame = await group?.readFrame(); + if (frame === undefined) break; + sizes.push(frame.payload.byteLength); + } + + expect(sizes.length).toBe(8); + expect(sizes[sizes.length - 1]).toBeLessThan(sizes[0] ?? 0); +}); + +test("a second group is a rolled log, not a continuation", async () => { + // A stream is one group. A publisher that rolls lost whatever would have completed the first, + // so the read reports that rather than handing back the remainder as a continuous log. + // Written by hand because this producer never rolls. + const track = new Track.Producer("test"); + for (const pair of [payloads(2), payloads(2)]) { + const group = track.appendGroup(); + for (const payload of pair) group.writeFrame({ payload, timestamp: Time.Timestamp.now() }); + group.close(); + } + track.close(); + + const consumer = new Consumer(track.subscribe({ maxAge: REPLAY_LATENCY })); + expect(await consumer.next()).toBeDefined(); + expect(await consumer.next()).toBeDefined(); + await expect(consumer.next()).rejects.toThrow(Rolled); +}); + +test("an undecodable payload ends the log for a reader already inside the group", async () => { + // The decoder-limit check ends the track like any other lost record, and by then an earlier + // append may already have opened the group. A reader that pulled that group has to see the + // failure rather than park on a group nothing will ever finish. + const track = new Track.Producer("test"); + const producer = new Producer(track, { compression: true }); + producer.append(payloads(1)[0]); + + const consumer = new Consumer(track.subscribe(), { compression: true }); + expect(await consumer.next()).toBeDefined(); + + const oversized = new Uint8Array(DEFAULT_MAX_FRAME_SIZE + 1); + expect(() => producer.append(oversized)).toThrow("limit"); + + // Surfaces the terminal error rather than hanging on the still-open group. + await expect(consumer.next()).rejects.toThrow("limit"); +}); diff --git a/js/binary/tsconfig.build.json b/js/binary/tsconfig.build.json new file mode 100644 index 00000000000..b0d79fdc2cb --- /dev/null +++ b/js/binary/tsconfig.build.json @@ -0,0 +1,7 @@ +{ + // Build-only variant of tsconfig.json that keeps tests out of dist/, so they + // are neither published nor discovered by `bun test` at the package root. + // `tsc --noEmit` still uses tsconfig.json, so tests stay type-checked. + "extends": "./tsconfig.json", + "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"] +} diff --git a/js/binary/tsconfig.json b/js/binary/tsconfig.json new file mode 100644 index 00000000000..bb55d7c43fc --- /dev/null +++ b/js/binary/tsconfig.json @@ -0,0 +1,9 @@ +{ + "extends": "../tsconfig.json", + "compilerOptions": { + "outDir": "dist", + "rootDir": "./src", + "types": ["bun"] + }, + "include": ["src"] +} diff --git a/js/hang/src/catalog/binary.ts b/js/hang/src/catalog/binary.ts new file mode 100644 index 00000000000..24ff7754f21 --- /dev/null +++ b/js/hang/src/catalog/binary.ts @@ -0,0 +1,50 @@ +import * as z from "zod/mini"; +import { CompressionSchema } from "./compression"; +import { ModeSchema } from "./mode"; +import { RelativeBroadcastSchema } from "./path"; +import { TimelineSchema } from "./timeline"; + +/** + * Schema for a single binary track: application data published as opaque payloads. + * + * The entry says how to read the track, so a consumer needs the track name and nothing else about + * the application. Prefer a {@link JsonConfig} track when the payloads are JSON, so a generic + * consumer can read them. + * + * A *loose* object: fields this build doesn't recognize pass through untouched, so an entry using + * a future mode or compression round-trips rather than losing the fields that describe it. + */ +export const BinaryConfigSchema = z.looseObject({ + // Optional reference to another broadcast that publishes this track, expressed + // relative to the broadcast that served this catalog (e.g. "./source"). + // If unset, the track lives in the same broadcast as the catalog. + broadcast: z.optional(RelativeBroadcastSchema), + + // Whether the track is a latest-value blob or an append log. Always stated. + mode: ModeSchema, + + // The compression applied to each frame, or absent when they are written through untouched. + compression: z.optional(CompressionSchema), + + // An optional media type for each payload (e.g. "image/jpeg"). Purely descriptive: + // a consumer that doesn't recognize it can still read the track. + mime: z.optional(z.string()), + + // The companion timeline track indexing this track's groups, if the publisher offers one. + timeline: z.optional(TimelineSchema), +}); + +/** + * Schema for the catalog `binary` section: a map of track name to config. + * + * Not a rendition set: entries are distinct tracks, not alternatives to choose between. The map + * key is the track name to subscribe to. + */ +export const BinarySchema = z.object({ + tracks: z.record(z.string(), BinaryConfigSchema), +}); + +/** The catalog binary section: data tracks keyed by track name. */ +export type Binary = z.infer; +/** How to read one binary track. */ +export type BinaryConfig = z.infer; diff --git a/js/hang/src/catalog/compression.ts b/js/hang/src/catalog/compression.ts new file mode 100644 index 00000000000..b93428a4fc6 --- /dev/null +++ b/js/hang/src/catalog/compression.ts @@ -0,0 +1,27 @@ +import * as z from "zod/mini"; + +/** The compression algorithms this build knows how to decode. */ +export type KnownCompression = "deflate"; + +/** + * The compression applied to a data track's frames, or absent when they are uncompressed. + * + * `"deflate"` is group-scoped raw DEFLATE (RFC 1951), sync-flushed at each frame boundary: every + * frame is self-delimited while later frames compress against the earlier ones in the same group. + * + * A track's catalog entry declares this explicitly. The `.z` suffix seen on some track names is a + * naming convention, not a signal: never infer compression from a track's name. + * + * Typed as a plain string so an unrecognized algorithm survives a reparse-and-republish verbatim. + * Narrow it with {@link compressionSupported} before reading the track, and ignore the track + * otherwise, since its frames cannot be decoded. + */ +export const CompressionSchema = z.string(); + +/** The compression applied to a data track's frames. See {@link CompressionSchema}. */ +export type Compression = z.infer; + +/** Whether this build knows how to decode frames compressed with `compression`. */ +export function compressionSupported(compression: Compression): compression is KnownCompression { + return compression === "deflate"; +} diff --git a/js/hang/src/catalog/data.test.ts b/js/hang/src/catalog/data.test.ts new file mode 100644 index 00000000000..6089bca9cd8 --- /dev/null +++ b/js/hang/src/catalog/data.test.ts @@ -0,0 +1,107 @@ +import { expect, test } from "bun:test"; +import { compressionSupported } from "./compression.ts"; +import { modeSupported } from "./mode.ts"; +import { RootSchema } from "./root.ts"; + +// The `json` and `binary` sections list application data tracks. Each entry says how to read the +// track, so a consumer needs the track name and nothing else about the application. + +const catalog = { + json: { + tracks: { + chat: { mode: "stream", compression: "deflate", schema: "https://example.com/chat.schema.json" }, + status: { broadcast: "./source", mode: "snapshot" }, + }, + }, + binary: { + tracks: { + thumbnail: { mode: "snapshot", mime: "image/jpeg" }, + }, + }, +}; + +test("data tracks parse with their mode and compression", () => { + const parsed = RootSchema.parse(catalog); + + expect(parsed.json?.tracks.chat?.mode).toBe("stream"); + expect(parsed.json?.tracks.chat?.compression).toBe("deflate"); + expect(parsed.json?.tracks.chat?.schema).toBe("https://example.com/chat.schema.json"); + + expect(parsed.json?.tracks.status?.mode).toBe("snapshot"); + // Normalized like Rust PathRelative, the same as a media rendition's reference. + expect(parsed.json?.tracks.status?.broadcast).toBe("source"); + expect(parsed.json?.tracks.status?.compression).toBeUndefined(); + + expect(parsed.binary?.tracks.thumbnail?.mode).toBe("snapshot"); + expect(parsed.binary?.tracks.thumbnail?.mime).toBe("image/jpeg"); +}); + +test("a media-only catalog leaves the data sections undefined", () => { + const parsed = RootSchema.parse({ video: { renditions: {} }, audio: { renditions: {} } }); + expect(parsed.json).toBeUndefined(); + expect(parsed.binary).toBeUndefined(); +}); + +test("a track without a mode is rejected", () => { + // There is no safe default: reading a stream as a snapshot silently drops every record but the + // last, so a mode-less entry is malformed rather than assumed. + expect(() => RootSchema.parse({ json: { tracks: { chat: { compression: "deflate" } } } })).toThrow(); +}); + +test("an unrecognized mode or compression survives verbatim", () => { + // A relay reparses and republishes the catalog, so a track it cannot read must round-trip + // rather than be corrupted. It just has to be skipped, not dropped. + const parsed = RootSchema.parse({ + json: { tracks: { future: { mode: "windowed", compression: "zstd" } } }, + }); + + const future = parsed.json?.tracks.future; + expect(future?.mode).toBe("windowed"); + expect(future?.compression).toBe("zstd"); + expect(modeSupported(future?.mode ?? "")).toBe(false); + expect(compressionSupported(future?.compression ?? "")).toBe(false); +}); + +test("the known modes and compressions are recognized", () => { + expect(modeSupported("snapshot")).toBe(true); + expect(modeSupported("stream")).toBe(true); + expect(compressionSupported("deflate")).toBe(true); +}); + +test("fields belonging to an unrecognized mode survive a round trip", () => { + // Preserving the mode string alone is not enough: a future mode comes with fields describing it, + // and a relay that reparsed and republished would otherwise strip them, leaving an entry nothing + // can act on. Same guarantee the container schema gives an unknown container. + const parsed = RootSchema.parse({ + json: { tracks: { future: { mode: "windowed", window: 10 } } }, + binary: { tracks: { future: { mode: "windowed", chunk: "4k" } } }, + }); + + expect(parsed.json?.tracks.future).toMatchObject({ mode: "windowed", window: 10 }); + expect(parsed.binary?.tracks.future).toMatchObject({ mode: "windowed", chunk: "4k" }); +}); + +test("a foreign data section does not fail the catalog", () => { + // A section name is only reserved from the version that defines it, and `json` and `binary` are + // generic enough that an application could already be using one. Dropping the section we can't + // read keeps video and audio playable, instead of failing the whole catalog over that key. + for (const section of ["json", "binary"] as const) { + const parsed = RootSchema.parse({ video: { renditions: {} }, [section]: { messages: "chat" } }); + expect(parsed[section]).toBeUndefined(); + expect(parsed.video).toBeDefined(); + } +}); + +test("a foreign section with a non-object tracks value does not fail the catalog", () => { + // The gate is the map's *shape*, not just its presence: an application section that happens to + // carry its own `tracks` scalar is still someone else's key. Rust's `deserialize_section` gates + // on `is_object`, so recognizing this as ours would make the two parsers disagree and take the + // media sections down over a key we never owned. + for (const section of ["json", "binary"] as const) { + for (const tracks of [null, 3, "chat", [], true]) { + const parsed = RootSchema.parse({ video: { renditions: {} }, [section]: { tracks } }); + expect(parsed[section]).toBeUndefined(); + expect(parsed.video).toBeDefined(); + } + } +}); diff --git a/js/hang/src/catalog/index.ts b/js/hang/src/catalog/index.ts index 9ff5712d07a..909fe924a89 100644 --- a/js/hang/src/catalog/index.ts +++ b/js/hang/src/catalog/index.ts @@ -1,15 +1,20 @@ /** - * JSON catalog schema and types describing a broadcast's tracks for WebCodecs: - * audio/video decoder configs, container format, and rendition layout. + * JSON catalog schema and types describing a broadcast's tracks: audio/video decoder configs for + * WebCodecs, container format, and rendition layout, plus the `json` and `binary` sections listing + * application data tracks that aren't media. * * @module */ export * from "./audio"; +export * from "./binary"; +export * from "./compression"; export * from "./container"; export * from "./format"; export * from "./hex"; export * from "./integers"; +export * from "./json"; +export * from "./mode"; export * from "./path"; export * from "./priority"; export * from "./root"; diff --git a/js/hang/src/catalog/json.ts b/js/hang/src/catalog/json.ts new file mode 100644 index 00000000000..c97ab21bfd8 --- /dev/null +++ b/js/hang/src/catalog/json.ts @@ -0,0 +1,49 @@ +import * as z from "zod/mini"; +import { CompressionSchema } from "./compression"; +import { ModeSchema } from "./mode"; +import { RelativeBroadcastSchema } from "./path"; +import { TimelineSchema } from "./timeline"; + +/** + * Schema for a single JSON track: application data published as a live JSON document or log. + * + * The entry says how to read the track, so a consumer needs the track name and nothing else about + * the application. + * + * A *loose* object: fields this build doesn't recognize pass through untouched, so an entry using + * a future mode or compression round-trips rather than losing the fields that describe it. + */ +export const JsonConfigSchema = z.looseObject({ + // Optional reference to another broadcast that publishes this track, expressed + // relative to the broadcast that served this catalog (e.g. "./source"). + // If unset, the track lives in the same broadcast as the catalog. + broadcast: z.optional(RelativeBroadcastSchema), + + // Whether the track is a latest-value document or an append log. Always stated. + mode: ModeSchema, + + // The compression applied to each frame, or absent when they are plaintext. + compression: z.optional(CompressionSchema), + + // An optional identifier for the shape of each value, typically a JSON Schema URL. + // Purely descriptive: a consumer that doesn't recognize it can still read the track. + schema: z.optional(z.string()), + + // The companion timeline track indexing this track's groups, if the publisher offers one. + timeline: z.optional(TimelineSchema), +}); + +/** + * Schema for the catalog `json` section: a map of track name to config. + * + * Not a rendition set: entries are distinct tracks, not alternatives to choose between. The map + * key is the track name to subscribe to. + */ +export const JsonSchema = z.object({ + tracks: z.record(z.string(), JsonConfigSchema), +}); + +/** The catalog JSON section: data tracks keyed by track name. */ +export type Json = z.infer; +/** How to read one JSON track. */ +export type JsonConfig = z.infer; diff --git a/js/hang/src/catalog/mode.ts b/js/hang/src/catalog/mode.ts new file mode 100644 index 00000000000..3acc8628450 --- /dev/null +++ b/js/hang/src/catalog/mode.ts @@ -0,0 +1,28 @@ +import * as z from "zod/mini"; + +/** The modes this build knows how to read. */ +export type KnownMode = "snapshot" | "stream"; + +/** + * How a data track's groups carry its payloads. + * + * - `"snapshot"`: lossy. Each group is self-contained and supersedes the previous one, so a + * consumer reads only the newest. A JSON track may follow a group's first frame with RFC 7396 + * merge-patch deltas; a binary track writes one frame per group. + * - `"stream"`: lossless. A single group, never rolled, one payload per frame in order. + * + * Always stated by the publisher: there is no default, because reading an append log as a + * latest-value document silently discards every payload but the last. + * + * Typed as a plain string so an unrecognized mode survives a reparse-and-republish verbatim. + * Narrow it with {@link modeSupported} before reading the track, and ignore the track otherwise. + */ +export const ModeSchema = z.string(); + +/** How a data track's groups carry its payloads. See {@link ModeSchema}. */ +export type Mode = z.infer; + +/** Whether this build knows how to read a track published in `mode`. */ +export function modeSupported(mode: Mode): mode is KnownMode { + return mode === "snapshot" || mode === "stream"; +} diff --git a/js/hang/src/catalog/root.test.ts b/js/hang/src/catalog/root.test.ts index 4e555cdcb87..f1883efc26b 100644 --- a/js/hang/src/catalog/root.test.ts +++ b/js/hang/src/catalog/root.test.ts @@ -2,8 +2,9 @@ import { expect, test } from "bun:test"; import * as z from "zod/mini"; import { RootSchema } from "./root.ts"; -// The base catalog is generic: only `video`/`audio`. Applications add their own root sections -// (e.g. `scte35`) without modifying hang, relying on the loose schema to pass them through. +// The base catalog carries the media sections (`video`/`audio`) and the data track sections +// (`json`/`binary`). Applications add their own root sections (e.g. `scte35`) without modifying +// hang, relying on the loose schema to pass them through. test("base catalog preserves unknown sections", () => { const extended = { video: { renditions: {} }, scte35: { spliceId: 42 } }; diff --git a/js/hang/src/catalog/root.ts b/js/hang/src/catalog/root.ts index 22d469cfeaa..60d80ef2fb3 100644 --- a/js/hang/src/catalog/root.ts +++ b/js/hang/src/catalog/root.ts @@ -1,12 +1,19 @@ import * as z from "zod/mini"; import { AudioSchema } from "./audio"; +import { BinarySchema } from "./binary"; +import { JsonSchema } from "./json"; +import { section } from "./section"; import { TextSchema } from "./text"; import { TimelineSchema } from "./timeline"; import { VideoSchema } from "./video"; /** - * The root catalog: the base media sections every hang broadcast carries. + * The root catalog: the base sections every hang broadcast carries. + * + * The media sections are `video`, `audio`, and `text`, alongside the broadcast's `timeline`; + * `json` and `binary` list application data tracks that aren't media. A section is omitted when + * it holds no tracks. * * 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 @@ -22,7 +29,14 @@ export const RootSchema = z.looseObject({ // before this existed must not fail to parse: fall back to `undefined` (dropping the section) // rather than rejecting the whole catalog, so video/audio still play. text: z.catch(z.optional(TextSchema), undefined), + // Lenient for the same reason as `text` above: `json` and `binary` are generic enough keys that + // an application could have been carrying its own before these sections were reserved. Narrower + // than `text`'s blanket catch, though, because these entries have a required field: a value that + // IS a section but carries a mode-less track still fails, rather than silently dropping every + // data track. See `section`. + json: section(JsonSchema, "tracks"), + binary: section(BinarySchema, "tracks"), }); -/** The root catalog object, with optional media and timeline sections plus any app extensions. */ +/** The root catalog object: the media and timeline sections, the data track sections, plus any app extensions. */ export type Root = z.infer; diff --git a/js/hang/src/catalog/section.ts b/js/hang/src/catalog/section.ts new file mode 100644 index 00000000000..29511413ebe --- /dev/null +++ b/js/hang/src/catalog/section.ts @@ -0,0 +1,34 @@ +import * as z from "zod/mini"; + +/** + * Wrap a catalog section so a value that isn't one decodes as absent rather than failing the + * whole catalog. + * + * A section name is only reserved from the version that defines it, so an application may already + * be carrying its own key under that name. Dropping the one key we can't read keeps the rest of + * the catalog readable, instead of taking video and audio down with it. + * + * The fallback is deliberately narrow: only a value whose `map` key is missing or not an object is + * treated as someone else's. A value that *is* a section but carries a malformed entry still fails, + * since swallowing that would hide a publisher bug (a data track with no `mode`) behind the silence + * that exists to protect an unrelated key. Mirrors the Rust `deserialize_section`, which recognizes + * the section only when the map is an object. + * + * @param schema - the section's own schema, applied when the value looks like a section. + * @param map - the key holding the section's map of tracks (`tracks`, `renditions`). + */ +export function section(schema: T, map: string) { + return z.optional( + z.union([ + schema, + z.pipe( + z.custom((value) => { + if (typeof value !== "object" || value === null || !(map in value)) return true; + const inner = (value as Record)[map]; + return typeof inner !== "object" || inner === null || Array.isArray(inner); + }), + z.transform(() => undefined), + ), + ]), + ); +} diff --git a/js/json/src/snapshot/encoder.ts b/js/json/src/snapshot/encoder.ts index c4c348bb3d6..246f35f878a 100644 --- a/js/json/src/snapshot/encoder.ts +++ b/js/json/src/snapshot/encoder.ts @@ -1,4 +1,5 @@ -import { Encoder as Flate } from "@moq/flate"; +import { DEFAULT_MAX_FRAME_SIZE, Encoder as Flate } from "@moq/flate"; +import { Group } from "@moq/net"; import type * as z from "zod/mini"; import { deepEqual, diff } from "../diff.ts"; @@ -206,10 +207,22 @@ export class Encoder { // Rust encoder, which completes every fallible step before mutating state. if (delta) { const payload = this.#frame(delta); - this.#last = json; - this.#deltaBytes += payload.length; - this.#groupFrames += 1; - return this.#pend({ payload, keyframe: false }); + + // A delta is only readable while the group still holds the snapshot it applies to, and the + // group cache evicts from the front. Admitting a patch that pushes the group past that + // budget would drop frame 0, leaving a late subscriber with a base-less group (`Lagged`) + // instead of the current value, so fall through to a fresh snapshot instead. + // + // Measured on the encoded payload rather than the plaintext: a sync-flushed DEFLATE frame + // can come out slightly larger than its input, so the plaintext is not an upper bound. + // Compressing first advances the window, but `#snapshot` opens a fresh one, so an + // over-budget delta costs only the wasted compression. + if (this.#snapshotLen + this.#deltaBytes + payload.length <= Group.MAX_GROUP_CACHE_BYTES) { + this.#last = json; + this.#deltaBytes += payload.length; + this.#groupFrames += 1; + return this.#pend({ payload, keyframe: false }); + } } const payload = this.#snapshot(new TextEncoder().encode(text)); @@ -262,9 +275,20 @@ export class Encoder { return new TextEncoder().encode(JSON.stringify(result.patch)); } + // Reject plaintext the consumer's decoder could never reproduce. Every consumer decodes with + // `@moq/flate`'s default output cap, so a frame past it would be unreadable however small it + // compresses to. Checked before anything is published or the window advances. + #checkDecodable(frame: Uint8Array): void { + if (this.#compress && frame.byteLength > DEFAULT_MAX_FRAME_SIZE) { + throw new Error(`value larger than the decoder's ${DEFAULT_MAX_FRAME_SIZE} byte limit`); + } + } + // Encode a group's snapshot (frame 0), returning its payload. On the compressed path this opens a // fresh stream (cold window), so the snapshot and its deltas share one DEFLATE window. #snapshot(frame: Uint8Array): Uint8Array { + this.#checkDecodable(frame); + // Build the window locally and install it only once framing succeeds. Assigning it first would // leave a throw with a cold window in place, no resync pending, and the old group counters // intact, so the next delta would compress against a window the decoder cannot follow. This is @@ -283,6 +307,9 @@ export class Encoder { // Compress a frame into the current group's window, or pass it through when uncompressed. #frame(frame: Uint8Array): Uint8Array { + // A delta is worse than a snapshot here: there is no keyframe after it to resynchronize on, + // so one the consumer cannot decode makes the rest of the group unreadable. + this.#checkDecodable(frame); return this.#flate ? this.#flate.frame(frame) : frame; } } diff --git a/js/json/src/snapshot/producer.ts b/js/json/src/snapshot/producer.ts index 9afe66fffc4..dd8f14676b9 100644 --- a/js/json/src/snapshot/producer.ts +++ b/js/json/src/snapshot/producer.ts @@ -1,4 +1,4 @@ -import type * as Moq from "@moq/net"; +import * as Moq from "@moq/net"; import { Time } from "@moq/net"; import { type Config, DEFAULT_DELTA_RATIO, type Encoded, Encoder } from "./encoder.ts"; @@ -66,6 +66,12 @@ export class Producer { } #write(encoded: Encoded): void { + // Check before touching a group. A keyframe closes the previous group and publishes its + // replacement before the frame is written, so discovering the limit inside `writeFrame` would + // leave an empty newest group behind: a snapshot consumer jumps to the newest, so the last + // good value would vanish even though this update reported an error. + if (encoded.payload.byteLength > Moq.Group.MAX_GROUP_CACHE_BYTES) throw new Moq.Group.FrameTooLarge(); + if (encoded.keyframe) { // The previous group is complete; no more frames will be appended to it. Drop the handle // before opening the next one, so a failure below doesn't leave a closed group behind. diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 9516604956d..bd3b3e1e368 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -1,5 +1,5 @@ import { expect, test } from "bun:test"; -import { Track } from "@moq/net"; +import { Group, Track } from "@moq/net"; import { Consumer } from "./consumer.ts"; import { Producer } from "./producer.ts"; @@ -312,3 +312,80 @@ test("frame cap rolls snapshot", async () => { expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }).ordered())).toEqual([256, 1]); }); + +test("a rejected update leaves the previous value readable", async () => { + // A keyframe closes the previous group and publishes its replacement before writing, so + // rejecting the frame inside writeFrame would supersede the last good value with an empty group. + // A snapshot consumer jumps to the newest, so that value would vanish on a failed update. + const track = new Track.Producer("test"); + const producer = new Producer({ track, deltaRatio: 0 }); + producer.update({ keep: true }); + + // Serializes past the group cache limit, so the frame cannot be published. + const oversized = { big: "x".repeat(Group.MAX_GROUP_CACHE_BYTES + 1) }; + expect(() => producer.update(oversized)).toThrow(Group.FrameTooLarge); + producer.finish(); + + // A reader arriving now still finds the last good value, not an empty superseding group. + expect(await drain(track.subscribe())).toEqual([{ keep: true }]); +}); + +test("a delta that would evict the snapshot rolls a new one instead", async () => { + // A delta is only readable while its group still holds the snapshot it applies to, and the group + // cache evicts from the front. A patch that pushes the group past the cache would drop frame 0, + // leaving a late subscriber with a base-less group instead of the current value. Mirrors the + // cumulative check in the Rust encoder. + // + // The value is replaced rather than grown, so each snapshot fits the cache on its own while the + // snapshot plus the patch that rewrites it does not. + const half = Math.floor(Group.MAX_GROUP_CACHE_BYTES * 0.6); + const track = new Track.Producer("test"); + const producer = new Producer({ track }); + + producer.update({ v: "x".repeat(half) }); + producer.update({ v: "y".repeat(half) }); + producer.finish(); + + // Two groups, a self-contained snapshot each, rather than one whose frame 0 was evicted. + const subscriber = track.subscribe({ maxAge: REPLAY_LATENCY }).ordered(); + expect((await subscriber.nextGroup())?.sequence).toBe(0); + expect((await subscriber.nextGroup())?.sequence).toBe(1); + expect(await subscriber.nextGroup()).toBeUndefined(); + + // The newest value is readable with no earlier frame to apply it to. + const values = await drain(track.subscribe({ maxAge: REPLAY_LATENCY })); + expect(values[values.length - 1]).toEqual({ v: "y".repeat(half) }); +}); + +test("a compressed delta is gated on its encoded size, not its plaintext", async () => { + // A sync-flushed DEFLATE frame can come out larger than its input, so the plaintext is not an + // upper bound on what lands in the group. A snapshot that fills the cache to within a few bytes + // plus a tiny patch that compresses to more than it measures would otherwise slip through the + // gate and evict frame 0. + const track = new Track.Producer("test"); + const producer = new Producer({ track, compression: true }); + + // Highly repetitive, so the compressed snapshot lands just under the cap. + producer.update({ v: "x".repeat(Group.MAX_GROUP_CACHE_BYTES) }); + producer.update({ v: "x".repeat(Group.MAX_GROUP_CACHE_BYTES), q: "a" }); + producer.finish(); + + // Whatever the split, no group may exceed the cache, and the newest value must be readable. + const subscriber = track.subscribe({ maxAge: REPLAY_LATENCY }).ordered(); + for (;;) { + const group = await subscriber.nextGroup(); + if (!group) break; + let bytes = 0; + for (;;) { + const frame = await group.readFrame(); + if (!frame) break; + bytes += frame.payload.byteLength; + } + expect(bytes).toBeLessThanOrEqual(Group.MAX_GROUP_CACHE_BYTES); + } + + const consumer = new Consumer(track.subscribe({ maxAge: REPLAY_LATENCY }), { compression: true }); + const values: Value[] = []; + for await (const value of consumer) values.push(value); + expect(values[values.length - 1]).toEqual({ v: "x".repeat(Group.MAX_GROUP_CACHE_BYTES), q: "a" }); +}); diff --git a/js/json/src/stream/codec.test.ts b/js/json/src/stream/codec.test.ts index a80ce2d0f15..7812f51aa13 100644 --- a/js/json/src/stream/codec.test.ts +++ b/js/json/src/stream/codec.test.ts @@ -1,5 +1,5 @@ import { expect, test } from "bun:test"; -import { Track } from "@moq/net"; +import { Group, Track } from "@moq/net"; import { Decoder } from "./decoder.ts"; import { Encoder } from "./encoder.ts"; import { Producer } from "./producer.ts"; @@ -101,7 +101,7 @@ test("a record JSON cannot represent is rejected", () => { // A record the encoder rejects must not have published a group first: a live consumer would advance // into it and wait there even though nothing was ever appended. -test("a rejected record does not open a group", async () => { +test("a rejected record ends the track without opening a group", async () => { const track = new Track.Producer("test"); const subscriber = track.subscribe().ordered(); const producer = new Producer(track); @@ -109,8 +109,11 @@ test("a rejected record does not open a group", async () => { expect(() => producer.append(undefined)).toThrow("not representable as JSON"); // Nothing was appended, so the log has no group for a consumer to enter and wait in. - producer.finish(); - expect(await subscriber.nextGroup()).toBeUndefined(); + expect(subscriber.latest()).toBeUndefined(); + + // And the log is missing a record, so the track ends rather than staying writable: a later + // append would present that gap as a complete log. Matches the Rust producer. + await expect(subscriber.nextGroup()).rejects.toThrow("not representable as JSON"); }); // The same stale-commit hazard the snapshot encoder has: acknowledging a superseded record must not @@ -160,3 +163,22 @@ test("a rejected record leaves the producer able to retry", () => { // encoder having latched itself shut. expect(() => producer.append({ n: 2 })).not.toThrow("compression desynchronized"); }); + +test("a failed write on the very first record still ends the track", async () => { + // The first append opens group 0 and then fails its write, which is as terminal as any later + // one: the group is live, so leaving the track writable would let a second group present the + // missing record as a complete log, and leave a consumer waiting in the empty group 0. + const track = new Track.Producer("test"); + const subscriber = track.subscribe().ordered(); + const producer = new Producer(track); + + // Serializes past the group cache limit, so `appendGroup` succeeds and `writeFrame` rejects it. + const oversized = "x".repeat(Group.MAX_GROUP_CACHE_BYTES + 1); + expect(() => producer.append(oversized)).toThrow(Group.FrameTooLarge); + + // The consumer is handed the group that was already published, and reading it surfaces the + // abort. Without ending the track that group stays open and empty, so this read hangs instead. + const group = await subscriber.nextGroup(); + expect(group).toBeDefined(); + await expect(group?.readFrame()).rejects.toThrow(Group.FrameTooLarge); +}); diff --git a/js/json/src/stream/consumer.ts b/js/json/src/stream/consumer.ts index de752805d5d..fceebe97040 100644 --- a/js/json/src/stream/consumer.ts +++ b/js/json/src/stream/consumer.ts @@ -2,21 +2,42 @@ import type * as Moq from "@moq/net"; import { type ConsumerConfig, Decoder } from "./decoder.ts"; +/** + * Thrown by a stream read when the track carried a second group, which a lossless log cannot do. + * + * A stream is a single group by construction: a publisher that cannot write a record ends the + * track rather than rolling. A second group therefore means whatever would have completed the + * first is gone, so the read reports it instead of handing back the remainder as a continuous log. + * + * Mirrors the Rust `moq_json::Error::Rolled`. + */ +export class Rolled extends Error { + constructor() { + super("rolled: the stream carried a second group, so records are missing"); + this.name = "Rolled"; + } +} + /** * Consumes an ordered log of JSON records from a track, yielding every record in order. * - * A {@link Decoder} that owns its track. The log rides a single group, so this reads that group's - * frames in order; one record per frame. When something else already owns the track, use the - * {@link Decoder} directly. + * A {@link Decoder} that owns its track, reading one record per frame. The log is a single group, + * which is what makes the mode lossless: rolling to a second group means the records that would + * have completed the first are gone, so a {@link Producer} that cannot write ends the track + * instead. A second group is therefore a broken publisher, and reading it would present a gap as a + * continuous log, so it throws {@link Rolled} rather than yielding the remainder. When something + * else already owns the track, use the {@link Decoder} directly. */ export class Consumer { - #track: Moq.Track.Ordered; + #track: Moq.Track.Subscriber; #decoder: Decoder; #group?: Moq.Group.Consumer; + // Whether the log's one group has been taken, so a second is a rolled log rather than the first. + #taken = false; constructor(track: Moq.Track.Subscriber, config: ConsumerConfig = {}) { - this.#track = track.ordered(); + this.#track = track; this.#decoder = new Decoder(config); } @@ -24,15 +45,21 @@ export class Consumer { async next(): Promise { for (;;) { if (!this.#group) { - this.#group = await this.#track.nextGroup(); + // Arrival order rather than sequence order, because there is only ever one group to + // take and a second one has to be seen whatever its sequence. The monotonic + // `nextGroup` would drop a late lower sequence, which is the very loss this reports. + this.#group = await this.#track.recvGroup(); if (!this.#group) return undefined; + if (this.#taken) throw new Rolled(); + this.#taken = true; // Each group is its own compressed stream, so the window starts cold. this.#decoder.reset(); } const frame = await this.#group.readFrame(); if (frame === undefined) { - // The group is finished; the log rides just this one, so the stream ends. + // The log's one group is exhausted. Keep reading the track so a clean end still + // reports the log as complete, and so a second group is caught as Rolled. this.#group = undefined; continue; } diff --git a/js/json/src/stream/encoder.ts b/js/json/src/stream/encoder.ts index 56f0afbfcf5..cdce1e38973 100644 --- a/js/json/src/stream/encoder.ts +++ b/js/json/src/stream/encoder.ts @@ -1,4 +1,4 @@ -import { Encoder as Flate } from "@moq/flate"; +import { DEFAULT_MAX_FRAME_SIZE, Encoder as Flate } from "@moq/flate"; /** Options shared by an {@link Encoder} and the {@link Producer} that wraps one. */ export interface ProducerConfig { @@ -99,6 +99,13 @@ export class Encoder { } const bytes = new TextEncoder().encode(text); + + // Every consumer decodes with `@moq/flate`'s default output cap, so a record past it would be + // unreadable however small it compresses to. Reject it here, where the caller still learns + // why, rather than publishing something only the producer can read. + if (this.#compress && bytes.byteLength > DEFAULT_MAX_FRAME_SIZE) { + throw new Error(`record larger than the decoder's ${DEFAULT_MAX_FRAME_SIZE} byte limit`); + } const payload = this.#flate ? this.#flate.frame(bytes) : bytes; this.#pending = true; diff --git a/js/json/src/stream/index.ts b/js/json/src/stream/index.ts index 4cf822de108..6fe8f4fb2e6 100644 --- a/js/json/src/stream/index.ts +++ b/js/json/src/stream/index.ts @@ -17,7 +17,7 @@ * @module */ -export { Consumer } from "./consumer.ts"; +export { Consumer, Rolled } from "./consumer.ts"; export { type ConsumerConfig, Decoder } from "./decoder.ts"; export { Encoder, type Pending, type ProducerConfig } from "./encoder.ts"; export { Producer } from "./producer.ts"; diff --git a/js/json/src/stream/producer.ts b/js/json/src/stream/producer.ts index adc712549a0..b7b6738edfa 100644 --- a/js/json/src/stream/producer.ts +++ b/js/json/src/stream/producer.ts @@ -1,7 +1,7 @@ import type * as Moq from "@moq/net"; import { Time } from "@moq/net"; -import { Encoder, type ProducerConfig } from "./encoder.ts"; +import { Encoder, type Pending, type ProducerConfig } from "./encoder.ts"; /** * Publishes an ordered log of JSON records to a track, one record per frame in a single group. @@ -22,29 +22,66 @@ export class Producer { this.#encoder = new Encoder(config); } - /** Append one record to the log. */ + /** + * Append one record to the log. + * + * A record that cannot be written ends the track: a log missing a record is not the lossless log + * this mode promises, so the failure is surfaced rather than papered over with a second group. + * The track is aborted rather than closed cleanly, so a consumer sees the failure instead of a + * log that merely looks complete. + */ append(value: T): void { // Encode first, so a value that can't be serialized doesn't publish an empty group that // subscribers would advance into and wait on. Opening the group afterwards is safe because // the record stays uncommitted until the write lands. - const record = this.#encoder.encode(value); + let record: Pending; + try { + record = this.#encoder.encode(value); + } catch (err) { + // A record that can't be encoded is as lost as one the group rejects: the log is missing it + // either way. Nothing was published, so this only has to end the track. + this.#abort(err); + throw err; + } + // Split the two failures: what decides whether this is terminal is whether a group is live by + // the time the write fails, not whether one was already open when the append started. The + // first append opens group 0 and can then fail its write, which is just as terminal. try { this.#group ??= this.#track.appendGroup(); + } catch (err) { + // Nothing was published, so a later append may still open a fresh group whose decoder + // starts cold. The record never landed, so the window still has to reset, or the desync + // latch answers the next append before the track does. + this.#encoder.reset(); + throw err; + } + + try { this.#group.writeFrame({ payload: record.payload, timestamp: Time.Timestamp.now() }); } catch (err) { - // The group is already visible on the track, so leaving it open would strand a subscriber - // that advanced into it. Closing it is also the group roll that recovery needs, so reset the - // encoder to finish it: the record never landed, and without the reset a compressed encoder - // refuses every later one even though the fresh group could carry it. - this.#group?.close(); - this.#group = undefined; + // The group is live, so the record is a hole in the log and a second group would hand + // consumers that gap dressed up as a complete log. this.#encoder.reset(); + this.#abort(err); throw err; } + record.commit(); } + // End the track with an error, so a consumer sees the failure rather than a clean end. + #abort(err: unknown): void { + const abort = err instanceof Error ? err : new Error(String(err)); + + // Close the group with the same error first. A consumer that already pulled it holds its own + // handle, which the track's close no longer reaches, so dropping ours would leave a reader + // sitting in the group with a generic error instead of the failure that ended the log. + this.#group?.close(abort); + this.#group = undefined; + this.#track.close(abort); + } + /** Finish the track, closing the group. */ finish(): void { this.#group?.close(); diff --git a/js/net/src/group.test.ts b/js/net/src/group.test.ts index d4860ae2fbf..baecf0ad8cb 100644 --- a/js/net/src/group.test.ts +++ b/js/net/src/group.test.ts @@ -1,5 +1,5 @@ import { expect, test } from "bun:test"; -import { Lagged, MAX_GROUP_CACHE_BYTES, MAX_GROUP_FRAMES, Producer } from "./group.ts"; +import { FrameTooLarge, Lagged, MAX_GROUP_CACHE_BYTES, MAX_GROUP_FRAMES, Producer } from "./group.ts"; import { Timestamp } from "./time.ts"; const dec = new TextDecoder(); @@ -189,3 +189,17 @@ test("buffered frames are still readable after the group closes", async () => { expect(await consumer.readString()).toBe("a"); expect(await consumer.readFrame()).toBeUndefined(); }); + +test("a frame larger than the cache is rejected rather than silently dropped", () => { + // Appending it would evict it in the same call, so a silent success would report a write that + // nothing can ever read. Rust rejects the same frame up front with `Error::FrameTooLarge`. + const producer = new Producer(0); + const oversized = new Uint8Array(MAX_GROUP_CACHE_BYTES + 1); + + expect(() => producer.writeFrame({ payload: oversized, timestamp: Timestamp.now() })).toThrow(FrameTooLarge); + + // Nothing was appended, so the group is still empty rather than holding a phantom frame. + const consumer = producer.consume(); + producer.close(); + expect(consumer.tryReadFrame()).toBeUndefined(); +}); diff --git a/js/net/src/group.ts b/js/net/src/group.ts index 7f761d9f96b..c871ec71387 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -46,6 +46,19 @@ export class Lagged extends Error { } } +/** + * Thrown by a frame write when the frame is larger than a group can cache, so appending it would + * evict it immediately and drop the write. + * + * Mirrors the Rust `Error::FrameTooLarge`, which rejects the same frame before touching any state. + */ +export class FrameTooLarge extends Error { + constructor() { + super("frame too large: larger than a group can cache"); + this.name = "FrameTooLarge"; + } +} + /** Reactive backing state shared by the group producer and one consumer. */ class GroupState { readonly sequence: number; @@ -185,6 +198,11 @@ export class Producer { /** Writes a frame to the group. */ writeFrame(frame: Frame) { + // A frame past the cache cap would be evicted by the very append that added it, so accepting + // it would report success for a write nothing can ever read. Rust rejects it up front with + // `Error::FrameTooLarge`; do the same rather than silently dropping it. + if (frame.payload.byteLength > MAX_GROUP_CACHE_BYTES) throw new FrameTooLarge(); + appendFrame(this.#state, frame); if (this.#mirrors) { diff --git a/package.json b/package.json index a71133bc24a..a01cca3b876 100644 --- a/package.json +++ b/package.json @@ -30,6 +30,7 @@ "js/clock", "js/token", "js/flate", + "js/binary", "js/json", "js/hang", "js/loc", diff --git a/rs/CLAUDE.md b/rs/CLAUDE.md index eb8d4eebb0e..0b3680110c1 100644 --- a/rs/CLAUDE.md +++ b/rs/CLAUDE.md @@ -22,6 +22,7 @@ Layered roughly transport -> container/format -> media -> apps/bindings. - `moq-loc` (lib): LOC (Low Overhead Container) wire frame codec. Top-level `encode`/`decode` + `Frame`. QUIC varints, property KVPs. - `moq-msf` (lib): IETF MSF/CMSF catalog types (`Catalog`, `Track`, `Packaging`, `Role`). serde JSON. Alternative to hang's catalog. - `moq-json` (lib): generic JSON publishing over a track. `snapshot` is lossy latest-value (RFC 7396 merge-patch deltas; consumers only get the most recent value; `Producer`/`Consumer`, `Guard` RAII edit); `stream` is a lossless append-log (every record preserved in order); `window` is an ordered retained range with push/pop/skip events and group checkpoints. DEFLATE via `moq-flate`. +- `moq-binary` (lib): opaque binary payloads over a track: the same two modes as `moq-json`, without the JSON. `snapshot` is lossy latest-value (one self-contained group per value); `stream` is a lossless append-log (a single group, one payload per frame, sharing one DEFLATE window). Compression via `moq-flate`, framed identically to moq-json so the two agree on the wire. - `moq-flate` (lib): group-scoped DEFLATE primitive (no moq deps). `Encoder`/`Decoder` turn a stream of payloads into self-delimited sync-flushed frames sharing one window (RFC 7692 marker trick), so similar frames compress against the earlier ones. Used by `moq-json`; reusable by any framed stream. - `moq-stats` (lib): stats publishing and consumption over `moq-net` + `moq-json`. `Producer` drains a `moq_net::stats::Registry` on an interval into per-node JSON tracks (plain `.json` plus compressed `.json.z` siblings); `Consumer` yields typed `TrafficFrame`/`SessionsFrame` off one stats broadcast; `parse_node_path` + track-name helpers cover the announce/track naming scheme. The relay's stats surface is this crate. @@ -114,6 +115,7 @@ Negotiation: `version::NEGOTIATED` lists SETUP-negotiated versions in preference - **Use typed time units**: never represent a duration or timestamp as an untyped numeric value such as `f64` seconds or `u64` milliseconds. Use `std::time::Duration`, `moq_net::Timestamp`, or another type that carries the unit. When a serialized format requires a numeric value, convert at that boundary with `serde_with` where possible. - **Retry loops use capped backoff with jitter** (root Retries has the policy). For a local loop, escalate a `Duration` toward a `const MAX`, jitter each wait (`delay.mul_f64(0.5 + rand::rng().random::() / 2.0)`), and keep its budget next to the delay. Reuse an existing operation-specific retry abstraction when one owns the sequence already. - **Prefer `kio` over tokio sync primitives**: reach for `kio::Producer`/`Consumer` (and the `poll_*` plumbing) instead of `tokio::sync` channels or `watch`. A `tokio::sync::watch` (or a channel) carrying a single value is a code smell. `kio` ties into the runtime-free `poll_*` model and avoids a hard runtime dependency. +- **Don't hand-roll `Serialize`/`Deserialize`.** A manual impl is a second copy of the type's wire shape that drifts from the fields it mirrors, and it is almost never needed. Derive it, and reach for `serde_with` for anything the derive can't express: a string-valued enum that must round-trip an unrecognized value is `derive_more::Display` + `FromStr` plus `#[serde_as(as = "DisplayFromStr")]` on the field (`catalog::Mode`, `catalog::TextFormat`), and a numeric wire field that should be a typed duration is `DurationMilliSeconds`. Write the impl by hand only when the wire shape genuinely isn't a function of the fields, and say why in a comment. - **Errors**: `thiserror` with `#[from]` for libraries, `anyhow` (with `.context("...")`, not `.map_err(|_| anyhow!())`) for binaries. Always `#[non_exhaustive]` on public error enums (e.g. `moq-net/src/error.rs`, `moq-ffi/src/error.rs`, `moq-loc/src/lib.rs`). **Never put a dependency's error type in a public variant** unless the crate is also re-exported (`moq-hls` re-exports `reqwest`, `moq-mux` re-exports `mp4_atom`, `moq-tokio` re-exports `rustls`). Otherwise a major bump of that dependency is a silent semver break for us and forces every consumer onto the same version. Store the message instead and keep a hand-written `From` so `?` still works: `moq-tokio/src/error.rs` has the `message` helper (which flattens the `source()` chain) and the `from_message!` macro the backend modules use. When callers act on something inside the foreign error, read it at conversion time and keep it as a field of its own (`quinn::Error::Client { message, status }`), not by matching the stored error later. - **Config + TOML merge**: parse Usage defaults and environment first, recursively overlay the TOML value, then call `update_from` so only explicit CLI flags win. Precedence is `CLI > TOML > env > defaults`. This works without typing every field as `Option`: `update_from` fills a declared default or an env value only where the standing value is still *empty*, and a plain value always reads as present. **Emptiness is a property of the type, and two shapes are not safe.** A bare `bool` reads empty when it is `false`, and a `Vec` reads empty when it has no items, so either one is refilled from the environment (or a declared default) over whatever the file said. Type every merged boolean as `Option` and resolve the default in code (`stats::StatsConfig::enabled`, `web::WebConfig::resolved_ws`, `websocket::Config::resolved_enabled`). Bare `Vec` fields carry the same latent bug and predate the Usage migration; see moq-dev/moq#3051 rather than materializing more of them. Everything else can be a bare field. See `moq-relay/src/config.rs` and its regression tests (`cli_does_not_clobber_toml_*`, `env_does_not_clobber_toml_booleans`); add such a test for any new flag. - **Config structs**: derive `usage::Cli`, `Serialize`, and `Deserialize` with `#[serde(deny_unknown_fields, default)]`; declare flags with `#[usage(long, env = "MOQ_...")]`, flatten nested configs with `#[usage(flatten)]`, and use an `.init()`/`.load()` method to produce the live object. See the `#[non_exhaustive]` conventions below for whether the struct gets the attribute and/or a builder. diff --git a/rs/hang/src/catalog/binary.rs b/rs/hang/src/catalog/binary.rs new file mode 100644 index 00000000000..0ab44d2bea0 --- /dev/null +++ b/rs/hang/src/catalog/binary.rs @@ -0,0 +1,115 @@ +use std::collections::{BTreeMap, btree_map}; + +use serde::{Deserialize, Serialize}; + +use crate::catalog::{Compression, Mode, Timeline}; + +/// The binary tracks a broadcast publishes, keyed by track name. +/// +/// Each frame is an opaque blob: a thumbnail, a serialized state snapshot, a sequence of samples in +/// some application format. Each entry says how to read the track ([`mode`](BinaryConfig::mode) and +/// [`compression`](BinaryConfig::compression)) without a consumer having to know the application. +/// Use [`Json`](crate::catalog::Json) instead when the payloads are JSON, so a generic consumer can +/// read them. +/// +/// Marked `#[non_exhaustive]` so additional optional fields can be added without bumping the major +/// version. External callers start from [`Binary::default`] and fill in what they need +/// ([`insert`](Self::insert)); struct-literal construction is not available outside this crate. +#[serde_with::skip_serializing_none] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct Binary { + /// A map of track name to configuration. + /// + /// A map rather than an array so it works with JSON Merge Patch, and a `BTreeMap` so keys are + /// sorted for *some* deterministic behavior. + pub tracks: BTreeMap, +} + +impl crate::catalog::Section for Binary { + const MAP: &'static str = "tracks"; +} + +impl Binary { + /// Insert a track config, returning an error if the name already exists. + pub fn insert(&mut self, name: &str, config: BinaryConfig) -> crate::Result<()> { + let btree_map::Entry::Vacant(entry) = self.tracks.entry(name.to_string()) else { + return Err(crate::Error::Duplicate(name.to_string())); + }; + entry.insert(config); + Ok(()) + } + + /// Remove the track from the catalog and return its configuration if found. + pub fn remove(&mut self, name: &str) -> Option { + self.tracks.remove(name) + } + + /// Whether there are no binary tracks, in which case the section is left off the wire. + pub fn is_empty(&self) -> bool { + self.tracks.is_empty() + } +} + +/// How to read one binary track. +/// +/// Each frame is an opaque payload; [`mode`](Self::mode) says how the track's groups compose those +/// frames into what a consumer sees. +/// +/// Marked `#[non_exhaustive]` so additional optional fields can be added without bumping the major +/// version. External callers build one with [`BinaryConfig::new`] and assign the optional fields +/// they need; struct-literal construction is not available outside this crate. +#[serde_with::serde_as] +#[serde_with::skip_serializing_none] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct BinaryConfig { + /// Optional reference to another broadcast that publishes this track, expressed relative to the + /// broadcast that served this catalog (e.g. `./source`). If unset, the track lives in the same + /// broadcast as the catalog. + #[serde(default)] + pub broadcast: Option, + + /// Whether the track is a latest-value blob or an append log. Always stated: see [`Mode`]. + #[serde_as(as = "serde_with::DisplayFromStr")] + pub mode: Mode, + + /// The compression applied to each frame, or `None` when they are written through untouched. + #[serde(default)] + #[serde_as(as = "Option")] + pub compression: Option, + + /// An optional media type for each payload (e.g. `image/jpeg`). Purely descriptive: a consumer + /// that doesn't recognize it can still read the track. + #[serde(default)] + pub mime: Option, + + /// The companion timeline track indexing this track's groups, if the publisher offers one. + #[serde(default)] + pub timeline: Option, + + /// Fields this build doesn't recognize, kept so the entry round-trips. + /// + /// A future [`Mode`] or [`Compression`] almost certainly comes with fields describing it, and + /// preserving the discriminant without them would leave a relay republishing an entry nothing + /// can act on. Same reason [`Container`](crate::catalog::Container) keeps an unknown container + /// verbatim. + #[serde(flatten)] + pub extra: serde_json::Map, +} + +impl BinaryConfig { + /// A config for a track read in `mode`, uncompressed and with no optional fields set. + pub fn new(mode: Mode) -> Self { + Self { + broadcast: None, + mode, + compression: None, + mime: None, + timeline: None, + extra: Default::default(), + } + } +} diff --git a/rs/hang/src/catalog/compression.rs b/rs/hang/src/catalog/compression.rs new file mode 100644 index 00000000000..ccb2181f481 --- /dev/null +++ b/rs/hang/src/catalog/compression.rs @@ -0,0 +1,63 @@ +use crate::Error; + +use derive_more::Display; +use std::str::FromStr; + +/// The compression applied to a metadata track's frames. +/// +/// A track's catalog entry declares this explicitly; the conventional `.z` suffix on a track name +/// is a naming convention, not a signal a consumer may rely on. An absent field (`None` on the +/// config) means the frames are uncompressed. +#[derive(Debug, Clone, PartialEq, Eq, Display)] +#[non_exhaustive] +pub enum Compression { + /// Group-scoped raw DEFLATE ([RFC 1951](https://www.rfc-editor.org/rfc/rfc1951.html)), + /// sync-flushed at each frame boundary so every frame is self-delimited while later frames + /// compress against the earlier ones in the same group. + #[display("deflate")] + Deflate, + + /// A compression this build does not recognize, preserved verbatim. + /// + /// A consumer MUST ignore the track, since its frames cannot be decoded. + #[display("{_0}")] + Unknown(String), +} + +impl FromStr for Compression { + type Err = Error; + + fn from_str(s: &str) -> Result { + Ok(match s { + "deflate" => Self::Deflate, + _ => Self::Unknown(s.to_string()), + }) + } +} + +#[cfg(test)] +mod test { + use super::*; + + #[test] + fn deflate_roundtrip() { + let mut config = crate::catalog::JsonConfig::new(crate::catalog::Mode::Stream); + config.compression = Some(Compression::Deflate); + let encoded = serde_json::to_value(&config).unwrap(); + assert_eq!(encoded["compression"], serde_json::json!("deflate")); + assert_eq!( + serde_json::from_value::(encoded) + .unwrap() + .compression, + Some(Compression::Deflate) + ); + } + + #[test] + fn unknown_roundtrip() { + let wire = serde_json::json!({ "mode": "stream", "compression": "zstd" }); + let config: crate::catalog::JsonConfig = serde_json::from_value(wire.clone()).unwrap(); + assert_eq!(config.compression, Some(Compression::Unknown("zstd".to_string()))); + assert_eq!(serde_json::to_value(&config).unwrap(), wire); + } +} diff --git a/rs/hang/src/catalog/json.rs b/rs/hang/src/catalog/json.rs new file mode 100644 index 00000000000..5029f99dce0 --- /dev/null +++ b/rs/hang/src/catalog/json.rs @@ -0,0 +1,113 @@ +use std::collections::{BTreeMap, btree_map}; + +use serde::{Deserialize, Serialize}; + +use crate::catalog::{Compression, Mode, Timeline}; + +/// The JSON tracks a broadcast publishes, keyed by track name. +/// +/// These are application data tracks, not media: a chat log, a telemetry feed, a status document. +/// Each entry says how to read the track ([`mode`](JsonConfig::mode) and +/// [`compression`](JsonConfig::compression)) without a consumer having to know the application. +/// +/// Marked `#[non_exhaustive]` so additional optional fields can be added without bumping the major +/// version. External callers start from [`Json::default`] and fill in what they need +/// ([`insert`](Self::insert)); struct-literal construction is not available outside this crate. +#[serde_with::skip_serializing_none] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct Json { + /// A map of track name to configuration. + /// + /// A map rather than an array so it works with JSON Merge Patch, and a `BTreeMap` so keys are + /// sorted for *some* deterministic behavior. + pub tracks: BTreeMap, +} + +impl crate::catalog::Section for Json { + const MAP: &'static str = "tracks"; +} + +impl Json { + /// Insert a track config, returning an error if the name already exists. + pub fn insert(&mut self, name: &str, config: JsonConfig) -> crate::Result<()> { + let btree_map::Entry::Vacant(entry) = self.tracks.entry(name.to_string()) else { + return Err(crate::Error::Duplicate(name.to_string())); + }; + entry.insert(config); + Ok(()) + } + + /// Remove the track from the catalog and return its configuration if found. + pub fn remove(&mut self, name: &str) -> Option { + self.tracks.remove(name) + } + + /// Whether there are no JSON tracks, in which case the section is left off the wire. + pub fn is_empty(&self) -> bool { + self.tracks.is_empty() + } +} + +/// How to read one JSON track. +/// +/// Each frame is a UTF-8 JSON value; [`mode`](Self::mode) says how the track's groups compose +/// those frames into the value a consumer sees. +/// +/// Marked `#[non_exhaustive]` so additional optional fields can be added without bumping the major +/// version. External callers build one with [`JsonConfig::new`] and assign the optional fields they +/// need; struct-literal construction is not available outside this crate. +#[serde_with::serde_as] +#[serde_with::skip_serializing_none] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct JsonConfig { + /// Optional reference to another broadcast that publishes this track, expressed relative to the + /// broadcast that served this catalog (e.g. `./source`). If unset, the track lives in the same + /// broadcast as the catalog. + #[serde(default)] + pub broadcast: Option, + + /// Whether the track is a latest-value document or an append log. Always stated: see [`Mode`]. + #[serde_as(as = "serde_with::DisplayFromStr")] + pub mode: Mode, + + /// The compression applied to each frame, or `None` when they are plaintext. + #[serde(default)] + #[serde_as(as = "Option")] + pub compression: Option, + + /// An optional identifier for the shape of each value, typically a JSON Schema URL. Purely + /// descriptive: a consumer that doesn't recognize it can still read the track. + #[serde(default)] + pub schema: Option, + + /// The companion timeline track indexing this track's groups, if the publisher offers one. + #[serde(default)] + pub timeline: Option, + + /// Fields this build doesn't recognize, kept so the entry round-trips. + /// + /// A future [`Mode`] or [`Compression`] almost certainly comes with fields describing it, and + /// preserving the discriminant without them would leave a relay republishing an entry nothing + /// can act on. Same reason [`Container`](crate::catalog::Container) keeps an unknown container + /// verbatim. + #[serde(flatten)] + pub extra: serde_json::Map, +} + +impl JsonConfig { + /// A config for a track read in `mode`, uncompressed and with no optional fields set. + pub fn new(mode: Mode) -> Self { + Self { + broadcast: None, + mode, + compression: None, + schema: None, + timeline: None, + extra: Default::default(), + } + } +} diff --git a/rs/hang/src/catalog/mod.rs b/rs/hang/src/catalog/mod.rs index 614f05b25f7..2aa56bbbdcf 100644 --- a/rs/hang/src/catalog/mod.rs +++ b/rs/hang/src/catalog/mod.rs @@ -1,12 +1,17 @@ -//! The catalog describes available media tracks and codecs. +//! The catalog describes the tracks a broadcast publishes. //! //! This is a JSON blob that can be live updated like any other track in MoQ. //! It describes the available audio and video tracks, including codec information, -//! resolution, bitrates, and other metadata. +//! resolution, bitrates, and other metadata, plus the `json` and `binary` sections +//! listing the data tracks that aren't media. mod audio; +mod binary; +mod compression; mod container; mod hex; +mod json; +mod mode; mod priority; mod root; mod text; @@ -14,9 +19,48 @@ mod timeline; mod video; pub use audio::*; +pub use binary::*; +pub use compression::*; pub use container::*; +pub use json::*; +pub use mode::*; pub use priority::*; pub use root::*; pub use text::*; pub use timeline::*; pub use video::*; + +/// A catalog section: a map of track name to config, published under one well-known root key. +/// +/// The associated [`MAP`](Self::MAP) is what tells a real section apart from an application's own +/// value under the same name. See [`deserialize_section`]. +pub trait Section: Default + serde::de::DeserializeOwned { + /// The key holding the section's map of tracks. + const MAP: &'static str; +} + +/// Decode a catalog section, falling back to an empty one when the value isn't a section at all. +/// +/// A section name is only reserved from the version that defines it, so an application may already +/// be carrying its own key under that name (through [`Extra`](crate::catalog::Catalog), or in a +/// catalog this build has never seen). Dropping the one key we can't read keeps the rest of the +/// catalog readable, rather than failing the whole document and taking video and audio down with it. +/// +/// The fallback is deliberately narrow: only a value with no [`Section::MAP`] is treated as someone +/// else's. A value that *is* a section but carries a malformed entry still fails, since swallowing +/// that would hide a publisher bug (a data track with no `mode`) behind the silence that exists to +/// protect an unrelated key. +pub fn deserialize_section<'de, D, T>(deserializer: D) -> Result +where + D: serde::Deserializer<'de>, + T: Section, +{ + use serde::Deserialize; + let value = serde_json::Value::deserialize(deserializer)?; + + if !value.get(T::MAP).is_some_and(serde_json::Value::is_object) { + return Ok(T::default()); + } + + serde_json::from_value(value).map_err(serde::de::Error::custom) +} diff --git a/rs/hang/src/catalog/mode.rs b/rs/hang/src/catalog/mode.rs new file mode 100644 index 00000000000..8f597cda4c6 --- /dev/null +++ b/rs/hang/src/catalog/mode.rs @@ -0,0 +1,76 @@ +use crate::Error; + +use derive_more::Display; +use std::str::FromStr; + +/// How a metadata track's groups carry its payloads. +/// +/// The two modes are equally primary and there is no safe default: reading an append log as a +/// latest-value document silently drops every record but the last. So a +/// [`JsonConfig`](crate::catalog::JsonConfig) or [`BinaryConfig`](crate::catalog::BinaryConfig) +/// always states its mode, and a consumer that doesn't recognize the value +/// ([`Unknown`](Self::Unknown)) must ignore the track rather than guess. +#[derive(Debug, Clone, PartialEq, Eq, Display)] +#[non_exhaustive] +pub enum Mode { + /// Lossy latest-value: each group carries one complete payload and supersedes the previous + /// group, so a consumer reads only the newest. + /// + /// JSON tracks may follow the first frame of a group with + /// [RFC 7396](https://www.rfc-editor.org/rfc/rfc7396.html) merge-patch deltas; binary tracks + /// carry a single frame per group. + #[display("snapshot")] + Snapshot, + + /// Lossless append log: a single group that is never rolled, one payload per frame, delivered + /// in order with nothing superseded. + #[display("stream")] + Stream, + + /// A mode this build does not recognize, preserved verbatim. + /// + /// A consumer MUST ignore the track: it cannot know whether skipping to the newest group + /// would lose records. + #[display("{_0}")] + Unknown(String), +} + +impl FromStr for Mode { + type Err = Error; + + fn from_str(s: &str) -> Result { + Ok(match s { + "snapshot" => Self::Snapshot, + "stream" => Self::Stream, + _ => Self::Unknown(s.to_string()), + }) + } +} + +#[cfg(test)] +mod test { + use super::*; + + #[test] + fn known_roundtrip() { + for (mode, json) in [(Mode::Snapshot, r#""snapshot""#), (Mode::Stream, r#""stream""#)] { + let config = crate::catalog::JsonConfig::new(mode.clone()); + let encoded = serde_json::to_value(&config).unwrap(); + assert_eq!(encoded["mode"].to_string(), json); + assert_eq!( + serde_json::from_value::(encoded) + .unwrap() + .mode, + mode + ); + } + } + + #[test] + fn unknown_roundtrip() { + let wire = serde_json::json!({ "mode": "future" }); + let config: crate::catalog::JsonConfig = serde_json::from_value(wire.clone()).unwrap(); + assert_eq!(config.mode, Mode::Unknown("future".to_string())); + assert_eq!(serde_json::to_value(&config).unwrap(), wire); + } +} diff --git a/rs/hang/src/catalog/root.rs b/rs/hang/src/catalog/root.rs index 0cec425877f..da3b44594ce 100644 --- a/rs/hang/src/catalog/root.rs +++ b/rs/hang/src/catalog/root.rs @@ -1,12 +1,13 @@ //! This module contains the structs and functions for the MoQ catalog format use crate::Result; -use crate::catalog::{Audio, PRIORITY, Text, Video}; +use crate::catalog::{Audio, Binary, Json, PRIORITY, Text, Video}; use serde::{Deserialize, Serialize}; /// A catalog track, created by a broadcaster to describe the tracks available in a broadcast. /// -/// The base catalog carries the media sections (`video`, `audio`, `text`) and the optional shared -/// `timeline`. Applications extend it with their own root sections (e.g. `scte35`) by flattening +/// The base catalog carries the media sections (`video`, `audio`, `text`), the optional shared +/// `timeline`, and the data sections (`json`, `binary`) for application tracks that aren't media. +/// Applications extend it with their own root sections (e.g. `scte35`) by flattening /// this struct into their own with `#[serde(flatten)]`. The catalog does not deny unknown fields, /// so a base consumer ignores the extra sections and an extended catalog stays wire-compatible. /// See the `extension_roundtrip` test. @@ -54,6 +55,32 @@ pub struct Catalog { deserialize_with = "crate::catalog::deserialize_text" )] pub text: Text, + + /// JSON tracks: application data published as live JSON documents or logs. + /// + /// Omitted from the wire when empty, so a media-only catalog is unchanged. + /// + /// A `json` value that isn't a data-track section decodes as empty rather than failing the + /// catalog, the same as [`text`](Self::text): `json` is a generic enough key that an + /// application could have been carrying its own before this one was reserved, and losing the + /// tracks we can't read beats losing the whole catalog. + #[serde( + default, + skip_serializing_if = "Json::is_empty", + deserialize_with = "crate::catalog::deserialize_section" + )] + pub json: Json, + + /// Binary tracks: application data published as opaque payloads. + /// + /// Omitted from the wire when empty, so a media-only catalog is unchanged. Decoded leniently + /// for the same reason as [`json`](Self::json). + #[serde( + default, + skip_serializing_if = "Binary::is_empty", + deserialize_with = "crate::catalog::deserialize_section" + )] + pub binary: Binary, } impl Catalog { @@ -123,7 +150,9 @@ impl Catalog { mod test { use std::collections::BTreeMap; - use crate::catalog::{AudioCodec::Opus, AudioConfig, Container, H264, VideoConfig}; + use crate::catalog::{ + AudioCodec::Opus, AudioConfig, BinaryConfig, Compression, Container, H264, JsonConfig, Mode, VideoConfig, + }; use super::*; @@ -488,6 +517,164 @@ mod test { ); } + /// A section name is only reserved from the version that defines it, and `json` and `binary` are + /// generic enough that an application could already be using one. Dropping the section we can't + /// read keeps video and audio playable, instead of failing the whole catalog over that key. + #[test] + fn a_foreign_data_section_does_not_fail_the_catalog() { + for section in ["json", "binary"] { + let wire = format!(r#"{{"video":{{"renditions":{{}}}},"{section}":{{"messages":"chat"}}}}"#); + let catalog = + Catalog::from_str(&wire).unwrap_or_else(|err| panic!("{section} took the catalog down: {err}")); + assert!(catalog.json.is_empty(), "{section}"); + assert!(catalog.binary.is_empty(), "{section}"); + } + } + + /// The counterpart to the above: the fallback covers someone else's key, not our own bugs. A + /// value that *is* a data section still has to decode, or a mode-less track would silently cost + /// a publisher every data track it advertised. + #[test] + fn a_malformed_data_section_still_fails() { + for section in ["json", "binary"] { + let wire = format!(r#"{{"{section}":{{"tracks":{{"chat":{{"compression":"deflate"}}}}}}}}"#); + assert!( + Catalog::from_str(&wire).is_err(), + "a mode-less {section} track decoded instead of failing" + ); + } + } + + #[test] + fn data_sections_stay_off_the_wire_when_empty() { + // A media-only catalog must serialize exactly as it did before the data sections existed, + // or every existing publisher's bytes change. + let output = Catalog::default().to_json().expect("failed to encode"); + assert_eq!(output, r#"{"video":{"renditions":{}},"audio":{"renditions":{}}}"#); + } + + #[test] + fn data_tracks_roundtrip() { + let mut encoded = r#"{ + "video": {"renditions": {}}, + "audio": {"renditions": {}}, + "json": { + "tracks": { + "chat": { + "mode": "stream", + "compression": "deflate", + "schema": "https://example.com/chat.schema.json" + }, + "status": { + "broadcast": "source", + "mode": "snapshot" + } + } + }, + "binary": { + "tracks": { + "thumbnail": { + "mode": "snapshot", + "mime": "image/jpeg" + } + } + } + }"# + .to_string(); + encoded.retain(|c| !c.is_whitespace()); + + let mut chat = JsonConfig::new(Mode::Stream); + chat.compression = Some(Compression::Deflate); + chat.schema = Some("https://example.com/chat.schema.json".to_string()); + + let mut status = JsonConfig::new(Mode::Snapshot); + status.broadcast = Some(moq_net::PathRelativeOwned::new("source")); + + let mut thumbnail = BinaryConfig::new(Mode::Snapshot); + thumbnail.mime = Some("image/jpeg".to_string()); + + let mut catalog = Catalog::default(); + catalog.json.insert("chat", chat).unwrap(); + catalog.json.insert("status", status).unwrap(); + catalog.binary.insert("thumbnail", thumbnail).unwrap(); + + let decoded = Catalog::from_str(&encoded).expect("failed to decode"); + assert_eq!(decoded, catalog, "decode mismatch"); + + let output = catalog.to_json().expect("failed to encode"); + assert_eq!(output, encoded, "encode mismatch"); + } + + /// A track using a future mode or compression must survive a reparse-and-republish intact, so a + /// relay doesn't corrupt what it can't read. Its siblings stay readable. + #[test] + fn unknown_mode_and_compression_keep_siblings() { + let encoded = r#"{ + "json": { + "tracks": { + "future": {"mode": "windowed", "compression": "zstd"}, + "known": {"mode": "stream", "compression": "deflate"} + } + } + }"#; + + let parsed = Catalog::from_str(encoded).expect("failed to decode"); + + let known = parsed.json.tracks.get("known").expect("missing track"); + assert_eq!(known.mode, Mode::Stream); + assert_eq!(known.compression, Some(Compression::Deflate)); + + let future = parsed.json.tracks.get("future").expect("missing track"); + assert_eq!(future.mode, Mode::Unknown("windowed".to_string())); + assert_eq!(future.compression, Some(Compression::Unknown("zstd".to_string()))); + + let output = parsed.to_json().expect("failed to encode"); + assert!( + output.contains(r#""mode":"windowed""#), + "unknown mode dropped: {output}" + ); + let reparsed = Catalog::from_str(&output).expect("failed to re-decode"); + assert_eq!(parsed, reparsed, "re-encoded catalog did not round-trip"); + } + + /// Preserving the mode string alone is not enough: a future mode comes with fields describing + /// it, and a relay that reparsed and republished would otherwise strip them, leaving an entry + /// nothing can act on. + #[test] + fn unknown_mode_fields_round_trip() { + let encoded = r#"{"json":{"tracks":{"future":{"mode":"windowed","window":10}}}}"#; + + let parsed = Catalog::from_str(encoded).expect("failed to decode"); + let future = parsed.json.tracks.get("future").expect("missing track"); + assert_eq!(future.mode, Mode::Unknown("windowed".to_string())); + assert_eq!(future.extra.get("window"), Some(&serde_json::json!(10))); + + let output = parsed.to_json().expect("failed to encode"); + assert!(output.contains(r#""window":10"#), "unknown fields dropped: {output}"); + assert_eq!(Catalog::from_str(&output).expect("re-decode"), parsed); + } + + /// There is no safe default: reading a stream as a snapshot silently drops every record but the + /// last, so an entry without a mode is malformed rather than assumed. + #[test] + fn a_track_without_a_mode_is_rejected() { + Catalog::from_str(r#"{"json":{"tracks":{"chat":{"compression":"deflate"}}}}"#) + .expect_err("a mode-less track must not decode"); + } + + #[test] + fn duplicate_data_track_names_are_rejected() { + let mut catalog = Catalog::default(); + catalog.json.insert("chat", JsonConfig::new(Mode::Stream)).unwrap(); + assert!(matches!( + catalog.json.insert("chat", JsonConfig::new(Mode::Snapshot)), + Err(crate::Error::Duplicate(_)) + )); + + // The two sections are separate namespaces on the wire, so the same name in each is fine. + catalog.binary.insert("chat", BinaryConfig::new(Mode::Stream)).unwrap(); + } + #[test] fn extension_roundtrip() { // An application extends the catalog with its own root section by flattening Catalog. diff --git a/rs/hang/src/catalog/text/mod.rs b/rs/hang/src/catalog/text/mod.rs index 231909d1c58..87e53b3ca3a 100644 --- a/rs/hang/src/catalog/text/mod.rs +++ b/rs/hang/src/catalog/text/mod.rs @@ -43,8 +43,11 @@ pub fn deserialize_text<'de, D>(deserializer: D) -> Result where D: serde::Deserializer<'de>, { - let value = serde_json::Value::deserialize(deserializer)?; - Ok(serde_json::from_value(value).unwrap_or_default()) + crate::catalog::deserialize_section(deserializer) +} + +impl crate::catalog::Section for Text { + const MAP: &'static str = "renditions"; } impl Text { diff --git a/rs/moq-binary/Cargo.toml b/rs/moq-binary/Cargo.toml new file mode 100644 index 00000000000..05fc4cf0b7d --- /dev/null +++ b/rs/moq-binary/Cargo.toml @@ -0,0 +1,20 @@ +[package] +name = "moq-binary" +description = "Binary publishing over MoQ tracks: latest-value snapshots, or append-log streams." +authors = ["Luke Curley "] +repository = "https://github.com/moq-dev/moq" +license = "MIT OR Apache-2.0" + +version = "0.1.0" +edition = "2024" +rust-version.workspace = true + +keywords = ["quic", "http3", "webtransport", "binary", "live"] +categories = ["multimedia", "network-programming", "web-programming"] + +[dependencies] +bytes = { workspace = true } +kio = { workspace = true } +moq-flate = { workspace = true } +moq-net = { workspace = true } +thiserror = { workspace = true } diff --git a/rs/moq-binary/src/lib.rs b/rs/moq-binary/src/lib.rs new file mode 100644 index 00000000000..570448dab0f --- /dev/null +++ b/rs/moq-binary/src/lib.rs @@ -0,0 +1,53 @@ +//! Opaque binary payloads over [`moq-net`](moq_net) tracks, in two modes: +//! +//! - [`snapshot`]: **lossy**. One value updated over time; a consumer only gets the most recent +//! one. Older values are superseded and dropped. +//! - [`stream`]: **lossless**. An ordered append-log of self-contained payloads, delivered in order +//! with nothing superseded. Bounded by the group cache: see [`stream`] for what that costs a +//! consumer that falls behind. +//! +//! Pick [`snapshot`] when consumers care about "what is the value now" (a poster image, a +//! serialized state blob) and [`stream`] when they care about every payload (an event log, a +//! sequence of samples). +//! +//! The bytes are opaque: this crate frames them onto a track and optionally compresses them, and +//! never looks inside. For JSON documents reach for [`moq-json`](https://docs.rs/moq-json) instead, +//! which adds RFC 7396 merge-patch deltas on top of the same two modes. +//! +//! Compression is [`moq-flate`](moq_flate), the same group-scoped DEFLATE moq-json uses, so the two +//! agree on the wire: each group is one raw DEFLATE stream, sync-flushed at every frame boundary. A +//! [`stream`] therefore compresses each payload against the earlier ones in its group, while a +//! [`snapshot`] group holds a single self-contained value. + +// The browser transport is `!Send`, so on wasm the shared state behind these `Arc`s is +// too and clippy suggests `Rc`. The same code is genuinely cross-thread on native, so +// `Arc` stays and the lint is unactionable here. +#![cfg_attr(target_arch = "wasm32", allow(clippy::arc_with_non_send_sync))] + +pub mod snapshot; +pub mod stream; + +/// Errors produced while publishing or consuming binary payloads. +#[derive(thiserror::Error, Debug, Clone)] +#[non_exhaustive] +pub enum Error { + /// An error from the underlying track. + #[error(transparent)] + Net(#[from] moq_net::Error), + + /// A compressed frame could not be decoded (malformed, truncated, or oversized). + #[error(transparent)] + Flate(#[from] moq_flate::Error), + + /// A [`stream`] track carried a second group, which a lossless log cannot do. + /// + /// A stream is a single group by construction: a publisher that cannot write a payload ends + /// the track rather than rolling. A second group therefore means the records that would have + /// completed the first one are gone, so the read fails instead of presenting the remainder as + /// a continuous log. + #[error("stream rolled to a second group")] + Rolled, +} + +/// A [`Result`](std::result::Result) using this crate's [`Error`]. +pub type Result = std::result::Result; diff --git a/rs/moq-binary/src/snapshot/consumer.rs b/rs/moq-binary/src/snapshot/consumer.rs new file mode 100644 index 00000000000..7e0e99a2ff7 --- /dev/null +++ b/rs/moq-binary/src/snapshot/consumer.rs @@ -0,0 +1,124 @@ +//! Consuming a binary value from a track. + +use std::task::Poll; + +use bytes::Bytes; + +use crate::Result; + +/// Configuration for a [`Consumer`]. +/// +/// Build from [`Default`] and override fields (the struct is `#[non_exhaustive]`, so new options +/// stay additive). +#[derive(Debug, Clone, Default)] +#[non_exhaustive] +pub struct ConsumerConfig { + /// Whether the frames are DEFLATE-compressed. Must match the producer's + /// [`ProducerConfig::compression`](super::ProducerConfig::compression). Defaults to `false`. + pub compression: bool, +} + +impl ConsumerConfig { + /// Set [`compression`](Self::compression) (a builder, since the struct is `#[non_exhaustive]`). + pub fn with_compression(mut self, compression: bool) -> Self { + self.compression = compression; + self + } +} + +/// Consumes a binary value from a track, yielding the newest one. +/// +/// Jumps to the newest group and reads the value out of it, so a late joiner starts at the current +/// value rather than replaying superseded ones. +pub struct Consumer { + track: moq_net::track::Ordered, + group: Option, + /// The DEFLATE decoder for the current group, `Some` while decompressing. A snapshot group is + /// normally one frame, but the window is per group either way. + flate: Option, + compression: bool, +} + +impl Consumer { + /// Create a consumer reading from the given track subscriber. + /// + /// Set [`ConsumerConfig::compression`] to read a track written by a producer with + /// [`ProducerConfig::compression`](super::ProducerConfig::compression) on. + pub fn new(track: moq_net::track::Subscriber, config: ConsumerConfig) -> Self { + Self { + track: track.ordered(), + group: None, + flate: None, + compression: config.compression, + } + } + + /// Get the next value, or `None` once the track ends. + pub async fn next(&mut self) -> Result> { + kio::wait(|waiter| self.poll_next(waiter)).await + } + + /// Poll for the next value, without blocking. + /// + /// Jumps to the newest group and drains everything buffered in it, yielding only the last value: + /// the earlier ones are already superseded, so a consumer that has fallen behind catches up to + /// the head in a single step. A compressed group's frames are still decoded in order, since they + /// share one window; only the yield is skipped. Switching to a newer group discards the older one. + pub fn poll_next(&mut self, waiter: &kio::Waiter) -> Poll>> { + // Drain to the newest group, starting a cold window whenever we switch. + let track_finished = loop { + match self.track.poll_next_group(waiter)? { + Poll::Ready(Some(group)) => { + self.group = Some(group); + self.flate = self.compression.then(moq_flate::Decoder::new); + } + Poll::Ready(None) => break true, + Poll::Pending => break false, + } + }; + + // Decode every frame currently buffered in the group, keeping only the last. + // `poll_read_frame` returns an owned `Poll`, so the borrow of `self.group` ends before the + // match arms, leaving `decode` (and clearing the group) free to take `&mut self`. + let mut latest = None; + let mut group_pending = false; + while let Some(group) = &mut self.group { + match group.poll_read_frame(waiter)? { + Poll::Ready(Some(frame)) => latest = Some(self.decode(&frame.payload)?), + // The current group is exhausted; wait for a newer one. + Poll::Ready(None) => { + self.group = None; + break; + } + // The group is still open but has nothing buffered yet. + Poll::Pending => { + group_pending = true; + break; + } + } + } + + if let Some(payload) = latest { + return Poll::Ready(Ok(Some(payload))); + } + + // An open group may still deliver frames even after the track finishes (it was appended before + // the finish), so wait on it rather than ending the stream. + if group_pending { + return Poll::Pending; + } + + match track_finished { + true => Poll::Ready(Ok(None)), + false => Poll::Pending, + } + } + + /// Decompress one frame, if the track is compressed. + fn decode(&mut self, payload: &Bytes) -> Result { + Ok(match self.flate.as_mut() { + Some(flate) => flate.frame(payload)?, + None => payload.clone(), + }) + } +} diff --git a/rs/moq-binary/src/snapshot/mod.rs b/rs/moq-binary/src/snapshot/mod.rs new file mode 100644 index 00000000000..f9f172b5df7 --- /dev/null +++ b/rs/moq-binary/src/snapshot/mod.rs @@ -0,0 +1,156 @@ +//! Lossy latest-value binary publishing over [`moq-net`](moq_net) tracks. +//! +//! One opaque value updated over time, for consumers that only care about the current state (a +//! poster image, a serialized state blob). This mode is **lossy** by design: a consumer yields only +//! the most recent value. A late joiner (or a consumer that falls behind) jumps straight to the +//! newest group, and older groups are dropped entirely. For an ordered log where every payload is +//! preserved, use [`stream`](crate::stream) instead. +//! +//! On the wire each value is one group holding one frame, so a group is self-contained and a +//! consumer never needs an older one. With [`ProducerConfig::compression`] on, that frame is its own +//! raw DEFLATE stream; there is no window to share across a single-frame group. + +mod consumer; +mod producer; + +pub use consumer::{Consumer, ConsumerConfig}; +pub use producer::{Producer, ProducerConfig}; + +#[cfg(test)] +mod test { + use std::task::Poll; + + use bytes::Bytes; + + use super::*; + + fn producer(compression: bool) -> (Producer, moq_net::track::Subscriber) { + let track = moq_net::broadcast::Info::new() + .produce() + .create_track("test", None) + .unwrap(); + let consumer = track.subscribe(None); + ( + Producer::new(track, ProducerConfig::default().with_compression(compression)), + consumer, + ) + } + + fn consumer(track: moq_net::track::Subscriber, compression: bool) -> Consumer { + Consumer::new(track, ConsumerConfig::default().with_compression(compression)) + } + + /// Drain every value currently available without blocking. + fn drain(mut consumer: Consumer) -> Vec { + let waiter = kio::Waiter::noop(); + let mut out = Vec::new(); + while let Poll::Ready(Ok(Some(payload))) = consumer.poll_next(&waiter) { + out.push(payload); + } + out + } + + #[test] + fn one_group_per_update() { + let (mut producer, track) = producer(false); + producer.update(&b"first"[..]).unwrap(); + producer.update(&b"second"[..]).unwrap(); + producer.finish().unwrap(); + + // Two updates => two groups. A consumer that joins after both only sees the latest. + assert_eq!(track.latest(), Some(1)); + assert_eq!(drain(consumer(track, false)), vec![Bytes::from_static(b"second")]); + } + + #[test] + fn live_consumer_sees_each_update() { + let (mut producer, track) = producer(false); + let mut consumer = consumer(track, false); + let waiter = kio::Waiter::noop(); + + for n in 0..3u8 { + producer.update(vec![n]).unwrap(); + match consumer.poll_next(&waiter) { + Poll::Ready(Ok(Some(payload))) => assert_eq!(&payload[..], &[n]), + other => panic!("expected value, got {other:?}"), + } + } + } + + #[test] + fn compressed_roundtrip() { + let (mut producer, track) = producer(true); + let payload = Bytes::from(b"the quick brown fox".repeat(64)); + producer.update(payload.clone()).unwrap(); + producer.finish().unwrap(); + + assert_eq!(drain(consumer(track, true)), vec![payload]); + } + + /// The compressed frame on the wire is much smaller than the value it carries, so a consumer + /// that ignored the flag would read garbage rather than the payload. + #[test] + fn compression_shrinks_the_frame() { + let (mut producer, track) = producer(true); + let payload = Bytes::from(b"the quick brown fox".repeat(64)); + producer.update(payload.clone()).unwrap(); + producer.finish().unwrap(); + + // Read the raw frame, bypassing the consumer's decompression. + let waiter = kio::Waiter::noop(); + let Poll::Ready(Ok(Some(mut group))) = track.ordered().poll_next_group(&waiter) else { + panic!("expected a group"); + }; + let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) else { + panic!("expected a frame"); + }; + assert!( + frame.payload.len() < payload.len() / 4, + "compressed frame {} should be far below the raw {}", + frame.payload.len(), + payload.len() + ); + } + + /// `append_group` publishes immediately, so rejecting the frame inside `write_frame` would leave + /// an empty newest group behind. A snapshot consumer jumps to the newest, so the previous value + /// would vanish even though the update reported an error. + #[test] + fn a_rejected_update_leaves_the_previous_value_readable() { + let (mut producer, track) = producer(false); + producer.update(&b"keep"[..]).unwrap(); + + let oversized = Bytes::from(vec![0u8; moq_net::group::MAX_CACHE_BYTES as usize + 1]); + assert!(producer.update(oversized).is_err()); + producer.finish().unwrap(); + + // A reader arriving now still finds the last good value, not an empty superseding group. + assert_eq!(drain(consumer(track, false)), vec![Bytes::from_static(b"keep")]); + } + + /// `finish` closes the underlying track, so a later update fails rather than being silently + /// accepted, and that holds for every clone since they share one track. + #[test] + fn updating_after_finish_fails_on_every_clone() { + let (mut producer, _track) = producer(false); + let mut clone = producer.clone(); + + producer.update(&b"first"[..]).unwrap(); + producer.finish().unwrap(); + + assert!(producer.update(&b"late"[..]).is_err()); + assert!(clone.update(&b"late"[..]).is_err()); + } + + #[test] + fn a_finished_track_ends_the_consumer() { + let (mut producer, track) = producer(false); + producer.update(&b"only"[..]).unwrap(); + producer.finish().unwrap(); + + let mut consumer = consumer(track, false); + let waiter = kio::Waiter::noop(); + assert!(matches!(consumer.poll_next(&waiter), Poll::Ready(Ok(Some(_))))); + assert!(matches!(consumer.poll_next(&waiter), Poll::Ready(Ok(None)))); + } +} diff --git a/rs/moq-binary/src/snapshot/producer.rs b/rs/moq-binary/src/snapshot/producer.rs new file mode 100644 index 00000000000..583ff3c6392 --- /dev/null +++ b/rs/moq-binary/src/snapshot/producer.rs @@ -0,0 +1,135 @@ +//! Publishing a binary value over a track. + +use std::sync::{Arc, Mutex}; + +use bytes::Bytes; + +use crate::Result; + +/// Configuration for a [`Producer`]. +/// +/// Build from [`Default`] and override fields (the struct is `#[non_exhaustive]`, so new options +/// stay additive). +#[derive(Debug, Clone, Default)] +#[non_exhaustive] +pub struct ProducerConfig { + /// Compress each value as its own raw DEFLATE stream. + /// + /// A snapshot group holds a single self-contained value, so there is no window to share: each + /// value is compressed alone. `false` (the default) writes the bytes through untouched. A + /// [`Consumer`](super::Consumer) must set + /// [`ConsumerConfig::compression`](super::ConsumerConfig::compression) to match. + pub compression: bool, +} + +impl ProducerConfig { + /// Set [`compression`](Self::compression) (a builder, since the struct is `#[non_exhaustive]`). + pub fn with_compression(mut self, compression: bool) -> Self { + self.compression = compression; + self + } +} + +/// Publishes a binary value over a track, one value per group. +/// +/// Each [`update`](Self::update) rolls a new group holding the whole value, so a consumer only ever +/// needs the newest group and older ones are dropped. For a log where every payload survives, use +/// [`stream`](crate::stream) instead. +/// +/// Cheaply clonable: clones share one underlying track, like other MoQ producers. +#[derive(Clone)] +pub struct Producer { + inner: Arc>, +} + +impl Producer { + /// Create a producer that publishes to the given track. + pub fn new(track: moq_net::track::Producer, config: ProducerConfig) -> Self { + Self { + inner: Arc::new(Mutex::new(Inner { + track, + compression: config.compression, + })), + } + } + + /// Create a subscriber for the underlying track. + pub fn consume(&self) -> moq_net::track::Subscriber { + self.inner.lock().unwrap().track.subscribe(None) + } + + /// Whether any consumer for the underlying track currently exists. + /// + /// The demand signal for a producer serving on request: an unused track is cached state nobody is + /// watching, safe to drop and recreate on the next request. + pub fn is_used(&self) -> bool { + self.inner + .lock() + .unwrap() + .track + .poll_unused(&kio::Waiter::noop()) + .is_pending() + } + + /// Publish a new value, superseding the previous one. + /// + /// Unlike [`moq-json`](https://docs.rs/moq-json), an identical value is republished rather than + /// skipped: comparing two opaque blobs costs a full scan, and only the caller knows whether its + /// bytes changed. + pub fn update(&mut self, payload: impl Into) -> Result<()> { + self.inner.lock().unwrap().update(payload.into()) + } + + /// Finish the track. + pub fn finish(&mut self) -> Result<()> { + self.inner.lock().unwrap().finish() + } +} + +/// Shared publishing state behind [`Producer`]'s `Arc`. +struct Inner { + track: moq_net::track::Producer, + compression: bool, +} + +impl Inner { + fn update(&mut self, payload: Bytes) -> Result<()> { + // One frame per group, so the window spans a single value and starts cold every time. + let payload = match self.compression { + true => { + // Compression can take a large value under the group's frame limit, but every consumer + // decodes with moq-flate's default output cap, so publishing past it would advertise a + // value that always fails to read. Reject it here instead. + if payload.len() as u64 > moq_flate::DEFAULT_MAX_FRAME_SIZE { + return Err(moq_flate::Error::TooLarge(moq_flate::DEFAULT_MAX_FRAME_SIZE).into()); + } + moq_flate::Encoder::new().frame(&payload) + } + false => payload, + }; + + // Check before opening a group. `append_group` publishes immediately, so discovering the limit + // inside `write_frame` would leave an empty newest group behind: a snapshot consumer jumps to + // the newest, so the previous value would be lost even though this update reported an error. + if payload.len() as u64 > moq_net::group::MAX_CACHE_BYTES { + return Err(moq_net::Error::FrameTooLarge.into()); + } + + let mut group = self.track.append_group()?; + if let Err(err) = group.write_frame(moq_net::Timestamp::now(), payload) { + // `append_group` already published this group, and a rejected frame (too large) doesn't + // close the track. Dropping the handle does NOT close the group, so leaving it would strand + // any subscriber that advanced into it with nothing to read and no end. + let _ = group.finish(); + return Err(err.into()); + } + + group.finish()?; + Ok(()) + } + + fn finish(&mut self) -> Result<()> { + self.track.finish()?; + Ok(()) + } +} diff --git a/rs/moq-binary/src/stream/consumer.rs b/rs/moq-binary/src/stream/consumer.rs new file mode 100644 index 00000000000..eaae520670f --- /dev/null +++ b/rs/moq-binary/src/stream/consumer.rs @@ -0,0 +1,108 @@ +//! Consuming an ordered log of binary payloads from a track. + +use std::task::Poll; + +use bytes::Bytes; + +use crate::Result; + +/// Configuration for a [`Consumer`]. +/// +/// Build from [`Default`] and override fields (the struct is `#[non_exhaustive]`, so new options +/// stay additive). +#[derive(Debug, Clone, Default)] +#[non_exhaustive] +pub struct ConsumerConfig { + /// Whether the frames are DEFLATE-compressed. Must match the producer's + /// [`ProducerConfig::compression`](super::ProducerConfig::compression). Defaults to `false`. + pub compression: bool, +} + +impl ConsumerConfig { + /// Set [`compression`](Self::compression) (a builder, since the struct is `#[non_exhaustive]`). + pub fn with_compression(mut self, compression: bool) -> Self { + self.compression = compression; + self + } +} + +/// Consumes an ordered log of binary payloads from a track, yielding every one. +/// +/// The log is a single group. That is what makes the mode lossless: rolling to a second group +/// means the records that would have completed the first are gone, so a publisher that cannot +/// write ends the track instead. A second group is therefore a broken publisher, and reading it +/// would present a gap as a continuous log, so it fails with +/// [`Error::Rolled`](crate::Error::Rolled) rather than yielding the remainder. +pub struct Consumer { + track: moq_net::track::Subscriber, + group: Option, + /// Whether the log's one group has been taken, so a second is a rolled log rather than the first. + taken: bool, + /// The DEFLATE decoder for the group, `Some` while decompressing. + flate: Option, + compression: bool, +} + +impl Consumer { + /// Create a consumer reading from the given track subscriber. + /// + /// Set [`ConsumerConfig::compression`] to read a track written by a producer with + /// [`ProducerConfig::compression`](super::ProducerConfig::compression) on. + pub fn new(track: moq_net::track::Subscriber, config: ConsumerConfig) -> Self { + Self { + track, + group: None, + taken: false, + flate: None, + compression: config.compression, + } + } + + /// Get the next payload, or `None` once the track ends. + pub async fn next(&mut self) -> Result> { + kio::wait(|waiter| self.poll_next(waiter)).await + } + + /// Poll for the next payload, without blocking. + pub fn poll_next(&mut self, waiter: &kio::Waiter) -> Poll>> { + loop { + let Some(group) = &mut self.group else { + // Arrival order rather than sequence order, because there is only ever one group to + // take and a second one has to be seen whatever its sequence. The monotonic + // `poll_next_group` would drop a late lower sequence, which is the very loss this + // has to report. + match self.track.poll_recv_group(waiter)? { + Poll::Ready(Some(group)) => { + if self.taken { + return Poll::Ready(Err(crate::Error::Rolled)); + } + self.taken = true; + self.flate = self.compression.then(moq_flate::Decoder::new); + self.group = Some(group); + continue; + } + Poll::Ready(None) => return Poll::Ready(Ok(None)), + Poll::Pending => return Poll::Pending, + } + }; + + match group.poll_read_frame(waiter)? { + Poll::Ready(Some(frame)) => return Poll::Ready(self.decode(&frame.payload).map(Some)), + Poll::Ready(None) => { + // The log's one group is exhausted. Keep polling the track so a clean end still + // reports the log as complete, and so a second group is caught as `Rolled`. + self.group = None; + } + Poll::Pending => return Poll::Pending, + } + } + } + + /// Decompress one frame, if the track is compressed. + fn decode(&mut self, payload: &Bytes) -> Result { + Ok(match self.flate.as_mut() { + Some(flate) => flate.frame(payload)?, + None => payload.clone(), + }) + } +} diff --git a/rs/moq-binary/src/stream/mod.rs b/rs/moq-binary/src/stream/mod.rs new file mode 100644 index 00000000000..2d4823f6ff7 --- /dev/null +++ b/rs/moq-binary/src/stream/mod.rs @@ -0,0 +1,346 @@ +//! Lossless append-log binary publishing over [`moq-net`](moq_net) tracks. +//! +//! An ordered log of opaque payloads, for consumers that care about every one (an event log, a +//! sequence of samples). Nothing is ever superseded: a consumer yields each payload in the order it +//! was appended. For a latest-value document, use [`snapshot`](crate::snapshot) instead. +//! +//! Retention is bounded, which is the limit of "lossless" here. The group's cache is finite, so a +//! log longer than it holds evicts its earliest frames, and a consumer that falls behind or +//! subscribes late then fails its read ([`moq_net::Error::Lagged`]) rather than silently resuming +//! partway through: a partial log presented as a whole one is what this mode exists to prevent. +//! Keep a log inside what the group retains, and split anything unbounded across successive tracks. +//! +//! On the wire the log is a single group that is never rolled, one payload per frame. A payload +//! that cannot be written ends the track rather than opening a second group: a log missing a record +//! is not lossless, and a gap dressed up as a complete log is worse than a visible failure. With +//! [`ProducerConfig::compression`] on, that one group is one sync-flushed DEFLATE stream, so each +//! payload compresses against the earlier ones and a run of similar payloads shrinks sharply. + +mod consumer; +mod producer; + +pub use consumer::{Consumer, ConsumerConfig}; +pub use producer::{Producer, ProducerConfig}; + +#[cfg(test)] +mod test { + use std::task::Poll; + + use bytes::Bytes; + + use super::*; + + fn producer(compression: bool) -> (Producer, moq_net::track::Subscriber) { + let track = moq_net::broadcast::Info::new() + .produce() + .create_track("test", None) + .unwrap(); + let consumer = track.subscribe(None); + ( + Producer::new(track, ProducerConfig::default().with_compression(compression)), + consumer, + ) + } + + /// Drain every payload currently available without blocking. + fn drain(track: moq_net::track::Subscriber, compression: bool) -> Vec { + let mut consumer = Consumer::new(track, ConsumerConfig::default().with_compression(compression)); + let waiter = kio::Waiter::noop(); + let mut out = Vec::new(); + while let Poll::Ready(Ok(Some(payload))) = consumer.poll_next(&waiter) { + out.push(payload); + } + out + } + + fn payloads(count: u8) -> Vec { + (0..count).map(|n| Bytes::from(vec![n; 16])).collect() + } + + #[test] + fn every_payload_survives_in_order() { + let (mut producer, track) = producer(false); + let expected = payloads(5); + for payload in &expected { + producer.append(payload.clone()).unwrap(); + } + producer.finish().unwrap(); + + // One group holds the whole log, unlike snapshot's group-per-value. + assert_eq!(track.latest(), Some(0)); + assert_eq!(drain(track, false), expected); + } + + #[test] + fn compressed_roundtrip_in_order() { + let (mut producer, track) = producer(true); + let expected = payloads(20); + for payload in &expected { + producer.append(payload.clone()).unwrap(); + } + producer.finish().unwrap(); + + assert_eq!(drain(track, true), expected); + } + + /// The window spans the whole group, so a repeated payload costs almost nothing after the first. + #[test] + fn the_shared_window_shrinks_repetitive_payloads() { + let (mut producer, track) = producer(true); + let payload = Bytes::from(b"the quick brown fox".repeat(16)); + for _ in 0..8 { + producer.append(payload.clone()).unwrap(); + } + producer.finish().unwrap(); + + let waiter = kio::Waiter::noop(); + let Poll::Ready(Ok(Some(mut group))) = track.ordered().poll_next_group(&waiter) else { + panic!("expected a group"); + }; + + let mut sizes = Vec::new(); + while let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) { + sizes.push(frame.payload.len()); + } + + assert_eq!(sizes.len(), 8); + assert!( + *sizes.last().unwrap() < sizes[0], + "windowed frame {} should be below the first {}", + sizes.last().unwrap(), + sizes[0] + ); + } + + /// Clones share one track and one window, so two owners interleave into a single ordered log. + #[test] + fn clones_append_into_one_log() { + let (mut producer, track) = producer(true); + let mut clone = producer.clone(); + + producer.append(&b"a"[..]).unwrap(); + clone.append(&b"b"[..]).unwrap(); + producer.append(&b"c"[..]).unwrap(); + producer.finish().unwrap(); + + assert_eq!( + drain(track, true), + vec![ + Bytes::from_static(b"a"), + Bytes::from_static(b"b"), + Bytes::from_static(b"c") + ] + ); + } + + /// A track whose timescale is extreme enough that converting a wall-clock timestamp into it + /// overflows, so `write_frame` rejects every frame. That stands in for any post-`append_group` + /// write failure (the real one is a frame over moq-net's 32 MB per-group cache) without + /// allocating 32 MB to provoke it. Borrowed from moq-json's stream tests. + fn rejecting_track() -> moq_net::track::Producer { + let mut info = moq_net::track::Info::default(); + info.timescale = moq_net::Timescale::new((1u64 << 62) - 1).unwrap(); + + moq_net::broadcast::Info::new() + .produce() + .create_track("test", Some(info)) + .unwrap() + } + + /// A failed write must reach the consumer, not just the caller. A clean close drains a reader to + /// `None`, which is exactly what a completed log looks like, so a truncated log would be + /// indistinguishable from a whole one. + #[test] + fn a_failed_write_aborts_the_track() { + let track = rejecting_track(); + let mut subscriber = track.subscribe(None); + let mut producer = Producer::new(track, ProducerConfig::default()); + + assert!(producer.append(&b"rejected"[..]).is_err()); + + // Aborting the group alone is not enough: the group is dropped from the cache and the reader + // still sees a clean end, which is exactly what a completed log looks like. + let waiter = kio::Waiter::noop(); + assert!( + matches!(subscriber.poll_recv_group(&waiter), Poll::Ready(Err(_))), + "a truncated log must surface an error rather than read as a completed one" + ); + } + + /// A record the consumer could never decode is as lost as one the track rejects, so it takes the + /// track with it rather than leaving a live log missing a record. Guards the guard: an early + /// return here would bypass the terminal path and let a later append continue the gap. + #[test] + fn an_undecodable_record_ends_the_track() { + let track = moq_net::broadcast::Info::new() + .produce() + .create_track("test", None) + .unwrap(); + let mut subscriber = track.subscribe(None); + let mut producer = Producer::new(track, ProducerConfig::default().with_compression(true)); + + let oversized = Bytes::from(vec![0u8; moq_flate::DEFAULT_MAX_FRAME_SIZE as usize + 1]); + assert!(matches!( + producer.append(oversized), + Err(crate::Error::Flate(moq_flate::Error::TooLarge(_))) + )); + + // Nothing was published, and the track is terminal rather than merely skipping the record. + let waiter = kio::Waiter::noop(); + assert!(matches!(subscriber.poll_recv_group(&waiter), Poll::Ready(Err(_)))); + assert!(producer.append(&b"after"[..]).is_err()); + } + + /// A reader already inside the group keeps its own handle, which `track::Producer::abort` + /// deliberately leaves independent. So the group has to carry the same error, or that reader is + /// told the producer went away rather than why the log stopped. + #[test] + fn a_reader_inside_the_group_sees_the_real_error() { + let track = moq_net::broadcast::Info::new() + .produce() + .create_track("test", None) + .unwrap(); + let mut subscriber = track.subscribe(None); + let mut producer = Producer::new(track, ProducerConfig::default()); + + producer.append(&b"first"[..]).unwrap(); + + // Pull the group, the way a live reader would, so we hold a handle of our own. + let waiter = kio::Waiter::noop(); + let Poll::Ready(Ok(Some(mut group))) = subscriber.poll_recv_group(&waiter) else { + panic!("the group was published, so a subscriber sees it"); + }; + assert!(matches!(group.poll_read_frame(&waiter), Poll::Ready(Ok(Some(_))))); + + // A payload the group cannot hold, so the write fails and ends the log. + let oversized = Bytes::from(vec![0u8; moq_net::group::MAX_CACHE_BYTES as usize + 1]); + assert!(producer.append(oversized).is_err()); + + match group.poll_read_frame(&waiter) { + Poll::Ready(Err(err)) => assert!( + matches!(err, moq_net::Error::FrameTooLarge), + "the reader should see the write's own error, got {err:?}" + ), + other => panic!("expected the write error, got {other:?}"), + } + } + + /// These tests walk a finished multi-group track, so they need a subscriber that tolerates a + /// backlog. The default budget is [`Duration::ZERO`], which abandons any group a newer one has + /// already superseded. + fn replaying() -> moq_net::track::Subscription { + moq_net::track::Subscription::default().with_max_age(std::time::Duration::from_secs(30)) + } + + /// The track ends with the group, so nothing opens a second one and splits the log. + #[test] + fn a_failed_write_ends_the_track() { + let track = rejecting_track(); + let mut producer = Producer::new(track, ProducerConfig::default()); + + assert!(producer.append(&b"rejected"[..]).is_err()); + assert!( + producer.append(&b"again"[..]).is_err(), + "a second append must fail on the closed track rather than open another group" + ); + } + + /// A stream is one group. A publisher that rolls to a second one lost whatever would have + /// completed the first, so the read reports that rather than handing back the remainder as a + /// continuous log. Written by hand because this producer never rolls. + #[test] + fn a_second_group_is_a_rolled_log() { + let mut track = moq_net::broadcast::Info::new() + .produce() + .create_track("test", None) + .unwrap(); + let subscriber = track.subscribe(replaying()); + + for pair in payloads(4).chunks(2) { + // Each group is its own DEFLATE stream, which is what a recovery roll would produce. + let mut flate = moq_flate::Encoder::new(); + let mut group = track.append_group().unwrap(); + for payload in pair { + group + .write_frame(moq_net::Timestamp::now(), flate.frame(payload)) + .unwrap(); + } + group.finish().unwrap(); + } + track.finish().unwrap(); + + let mut consumer = Consumer::new(subscriber, ConsumerConfig::default().with_compression(true)); + let waiter = kio::Waiter::noop(); + + // The log's one group reads normally. + assert!(matches!(consumer.poll_next(&waiter), Poll::Ready(Ok(Some(_))))); + assert!(matches!(consumer.poll_next(&waiter), Poll::Ready(Ok(Some(_))))); + + // The second group is a gap, not a continuation. + assert!(matches!( + consumer.poll_next(&waiter), + Poll::Ready(Err(crate::Error::Rolled)) + )); + } + + /// Groups are separate QUIC streams, so a second one can land before the first. Reading in + /// arrival order is what catches that: the monotonic `next_group` would skip the late lower + /// sequence and end the log cleanly, reporting a truncated log as a whole one. + #[test] + fn a_late_lower_group_is_still_reported() { + let mut track = moq_net::broadcast::Info::new() + .produce() + .create_track("test", None) + .unwrap(); + let subscriber = track.subscribe(replaying()); + + // Publish sequence 1 before sequence 0, the way reordering delivers them. + for sequence in [1u64, 0] { + let mut flate = moq_flate::Encoder::new(); + let mut group = track.create_group(moq_net::group::Info { sequence }).unwrap(); + group + .write_frame(moq_net::Timestamp::now(), flate.frame(&[sequence as u8; 8])) + .unwrap(); + group.finish().unwrap(); + } + track.finish().unwrap(); + + let mut consumer = Consumer::new(subscriber, ConsumerConfig::default().with_compression(true)); + let waiter = kio::Waiter::noop(); + + assert!(matches!( + consumer.poll_next(&waiter), + Poll::Ready(Ok(Some(payload))) if payload == vec![1u8; 8] + )); + assert!(matches!( + consumer.poll_next(&waiter), + Poll::Ready(Err(crate::Error::Rolled)) + )); + } + + /// `finish` closes the underlying track, so a later append fails rather than being silently + /// accepted, and that holds for every clone since they share one track. + #[test] + fn appending_after_finish_fails_on_every_clone() { + let (mut producer, _track) = producer(false); + let mut clone = producer.clone(); + + producer.append(&b"first"[..]).unwrap(); + producer.finish().unwrap(); + + assert!(producer.append(&b"late"[..]).is_err()); + assert!(clone.append(&b"late"[..]).is_err()); + } + + #[test] + fn a_finished_track_ends_the_consumer() { + let (mut producer, track) = producer(false); + producer.append(&b"only"[..]).unwrap(); + producer.finish().unwrap(); + + let mut consumer = Consumer::new(track, ConsumerConfig::default()); + let waiter = kio::Waiter::noop(); + assert!(matches!(consumer.poll_next(&waiter), Poll::Ready(Ok(Some(_))))); + assert!(matches!(consumer.poll_next(&waiter), Poll::Ready(Ok(None)))); + } +} diff --git a/rs/moq-binary/src/stream/producer.rs b/rs/moq-binary/src/stream/producer.rs new file mode 100644 index 00000000000..9df4a6d779d --- /dev/null +++ b/rs/moq-binary/src/stream/producer.rs @@ -0,0 +1,173 @@ +//! Publishing an ordered log of binary payloads over a track. + +use std::sync::{Arc, Mutex}; + +use bytes::Bytes; + +use crate::Result; + +/// Configuration for a [`Producer`]. +/// +/// Build from [`Default`] and override fields (the struct is `#[non_exhaustive]`, so new options +/// stay additive). +#[derive(Debug, Clone, Default)] +#[non_exhaustive] +pub struct ProducerConfig { + /// Compress the group as one sync-flushed DEFLATE stream, so each payload reuses the earlier + /// ones as context. + /// + /// `false` (the default) writes the bytes through untouched. A [`Consumer`](super::Consumer) + /// must set [`ConsumerConfig::compression`](super::ConsumerConfig::compression) to match. + pub compression: bool, +} + +impl ProducerConfig { + /// Set [`compression`](Self::compression) (a builder, since the struct is `#[non_exhaustive]`). + pub fn with_compression(mut self, compression: bool) -> Self { + self.compression = compression; + self + } +} + +/// Publishes an ordered log of binary payloads over a track, one payload per frame in a single +/// group. +/// +/// Cheaply clonable: clones share one underlying track and publishing state, so multiple owners +/// append into a single ordered log. +#[derive(Clone)] +pub struct Producer { + inner: Arc>, +} + +impl Producer { + /// Create a producer that publishes to the given track. + pub fn new(track: moq_net::track::Producer, config: ProducerConfig) -> Self { + Self { + inner: Arc::new(Mutex::new(Inner { + track, + group: None, + flate: config.compression.then(moq_flate::Encoder::new), + })), + } + } + + /// Create a subscriber for the underlying track. + /// + /// Still hands one back once a failed write has ended the log: the subscriber surfaces the abort + /// on its first read, which is what tells a late reader the log is truncated. + pub fn consume(&self) -> moq_net::track::Subscriber { + self.inner.lock().unwrap().track.subscribe(None) + } + + /// Whether any consumer for the underlying track currently exists. + /// + /// The demand signal for a producer serving on request: an unused track is cached state nobody is + /// watching, safe to drop and recreate on the next request. + pub fn is_used(&self) -> bool { + self.inner + .lock() + .unwrap() + .track + .poll_unused(&kio::Waiter::noop()) + .is_pending() + } + + /// Append one payload to the log. + /// + /// A payload that cannot be written ends the track: a log missing a record is not the lossless + /// log this mode promises, so the failure is surfaced rather than papered over with a second + /// group. The group is aborted rather than closed cleanly, so a consumer sees the failure + /// instead of a log that merely looks complete. Every later append fails on the closed track. + pub fn append(&mut self, payload: impl Into) -> Result<()> { + self.inner.lock().unwrap().append(payload.into()) + } + + /// Finish the track, closing the group. + pub fn finish(&mut self) -> Result<()> { + self.inner.lock().unwrap().finish() + } +} + +/// Shared publishing state behind [`Producer`]'s `Arc`. +struct Inner { + track: moq_net::track::Producer, + + /// Opened on the first append and never rolled. + group: Option, + + /// The DEFLATE encoder, one window for the whole group, `Some` while compressing. + flate: Option, +} + +impl Inner { + fn append(&mut self, payload: Bytes) -> Result<()> { + // A payload no consumer could decode is as terminal as one the track rejects: the log is + // missing a record either way, and carrying on would present that gap as a complete log. + // Checked before the group is opened, so nothing is published, and routed through the same + // abort so a reader sees the failure rather than a clean end. + if self.flate.is_some() && payload.len() as u64 > moq_flate::DEFAULT_MAX_FRAME_SIZE { + self.abort(moq_net::Error::FrameTooLarge); + return Err(moq_flate::Error::TooLarge(moq_flate::DEFAULT_MAX_FRAME_SIZE).into()); + } + + // Open the group before compressing: a failure here must not leave the window ahead of a + // consumer that never received the frame. + if self.group.is_none() { + self.group = Some(self.track.append_group()?); + } + + let payload = match self.flate.as_mut() { + Some(flate) => flate.frame(&payload), + None => payload, + }; + + let group = self.group.as_mut().expect("a group is open"); + let Err(err) = group.write_frame(moq_net::Timestamp::now(), payload) else { + return Ok(()); + }; + + // The payload never reached the wire, so the log has a hole in it, which is not the lossless + // log this mode promises. Continuing into a second group would hand consumers a gap dressed up + // as a complete log, so end the track and let the caller start a new one. This is also what + // keeps "a stream is one group" a real invariant rather than the usual case. + // + // Abort the track rather than finishing it: a clean close drains a consumer to `None`, which + // is exactly what a completed log looks like, so a truncated log would be indistinguishable + // from a whole one. Aborting the *track* is what a subscriber observes; aborting only the + // group drops it from the cache and the consumer still reads a clean end. + self.abort(err.clone()); + + Err(err.into()) + } + + /// End the track with an error, so a consumer sees the failure rather than a clean end. + fn abort(&mut self, err: moq_net::Error) { + // Abort the group with the same error first. `track::Producer::abort` deliberately leaves an + // already-pulled `group::Consumer` independent, so dropping our handle would hand a reader + // sitting in the group a generic `Dropped` instead of the failure that ended the log. + if let Some(group) = self.group.take() { + let _ = group.abort(err.clone()); + } + + // Abort through a clone, since aborting consumes a handle and the state is shared. Keeping + // ours means `consume` still hands back a subscriber, which is how a reader learns the log + // ended badly rather than cleanly. + let _ = self.track.clone().abort(err); + } + + fn finish(&mut self) -> Result<()> { + // Finalize both independently rather than short-circuiting on the group. Returning early + // would leave the track open with `group` already taken, so a later append would open a + // second group, and (with compression) write into it from a window the consumer never + // received. That is exactly the split log ending the track exists to prevent. + let group = match self.group.take() { + Some(mut group) => group.finish(), + None => Ok(()), + }; + let track = self.track.finish(); + + group?; + track?; + Ok(()) + } +} diff --git a/rs/moq-gst/tests/element.rs b/rs/moq-gst/tests/element.rs index 1be99cca106..db0fa50d4a1 100644 --- a/rs/moq-gst/tests/element.rs +++ b/rs/moq-gst/tests/element.rs @@ -1034,7 +1034,7 @@ fn a_pad_requested_from_the_eos_notify_is_refused() { } // A write that the producer rejects is the failure the property exists for. A frame past -// MAX_GROUP_CACHE is the deterministic way to cause one: moq-net refuses it before reserving a group. +// MAX_CACHE_BYTES is the deterministic way to cause one: moq-net refuses it before reserving a group. #[test] fn a_rejected_write_moves_the_pad_to_error() { init(); diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index a59050c82f2..3cfb155b751 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -984,10 +984,8 @@ mod tests { let mut segments = rendition.segments(); // The catalog drops the rendition: its cursor must run dry rather than park. - let empty = moq_mux::catalog::hang::Catalog { - timeline: Some(hang::catalog::Timeline::new(hang::timeline::DEFAULT_NAME)), - ..Default::default() - }; + let mut empty = moq_mux::catalog::hang::Catalog::default(); + empty.timeline = Some(hang::catalog::Timeline::new(hang::timeline::DEFAULT_NAME)); renditions.sync(&upstream, &empty); let ended = tokio::time::timeout(Duration::from_secs(5), segments.next()) .await diff --git a/rs/moq-json/src/lib.rs b/rs/moq-json/src/lib.rs index 8215b5ca53e..f107147f451 100644 --- a/rs/moq-json/src/lib.rs +++ b/rs/moq-json/src/lib.rs @@ -57,6 +57,15 @@ pub enum Error { /// calling [`stream::Encoder::reset`]. #[error("compression desynchronized: a frame was encoded but never written")] Desync, + + /// A [`stream`] track carried a second group, which a lossless log cannot do. + /// + /// A stream is a single group by construction: a publisher that cannot write a record ends the + /// track rather than rolling. A second group therefore means the records that would have + /// completed the first one are gone, so the read fails instead of presenting the remainder as + /// a continuous log. + #[error("stream rolled to a second group")] + Rolled, } impl From for Error { diff --git a/rs/moq-json/src/snapshot/encoder.rs b/rs/moq-json/src/snapshot/encoder.rs index ef4a971d88d..30930c1955d 100644 --- a/rs/moq-json/src/snapshot/encoder.rs +++ b/rs/moq-json/src/snapshot/encoder.rs @@ -280,10 +280,31 @@ impl Encoder { // Compress into the per-group window only now, for a frame we are committed to emitting. let bytes = serde_json::to_vec(&patch)?; + + // Same cap as a snapshot, on the patch's plaintext: a delta that decompresses past the + // consumer's limit makes the whole group unreadable, since there is no keyframe after it to + // resynchronize on. Rejecting here leaves the encoder to reset and the group as it was. + if self.config.compression && bytes.len() as u64 > moq_flate::DEFAULT_MAX_FRAME_SIZE { + return Err(moq_flate::Error::TooLarge(moq_flate::DEFAULT_MAX_FRAME_SIZE).into()); + } let payload = match self.flate.as_mut() { Some(flate) => flate.frame(&bytes), None => Bytes::from(bytes), }; + + // A delta is only readable while the group still holds the snapshot it applies to, and the + // group cache evicts from the front. Admitting a patch that pushes the group past that budget + // would drop frame 0, leaving a late subscriber with a base-less group (`Lagged`) instead of + // the current value. Roll a fresh snapshot instead, which is cheap next to losing the value. + // + // Measured on the encoded payload rather than the plaintext: a sync-flushed DEFLATE frame can + // come out slightly larger than its input, so the plaintext is not an upper bound. Compressing + // first advances the window, but [`Self::snapshot`] opens a fresh one, so an over-budget delta + // costs only the wasted compression. + if self.snapshot_len + self.delta_bytes + payload.len() as u64 > moq_net::group::MAX_CACHE_BYTES { + return self.snapshot(value).map(Some); + } + self.delta_bytes += payload.len() as u64; self.group_frames += 1; @@ -317,6 +338,13 @@ impl Encoder { // keeping the wire bytes identical to serializing `T` straight to a frame. let snapshot = serde_json::to_vec(value)?; + // Every consumer decodes with moq-flate's default output cap, so a value past it would be + // unreadable however small it compresses to. Reject it before anything is published, so the + // previously published value stands rather than being superseded by one nothing can read. + if self.config.compression && snapshot.len() as u64 > moq_flate::DEFAULT_MAX_FRAME_SIZE { + return Err(moq_flate::Error::TooLarge(moq_flate::DEFAULT_MAX_FRAME_SIZE).into()); + } + // Read the baseline back out of those same bytes rather than serializing `value` a second // time, so the baseline IS the emitted snapshot by construction. A `Serialize` impl reading a // clock or interior mutable state would otherwise seed the baseline with a value no consumer diff --git a/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index e2b78e17988..5beb2f58625 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -201,6 +201,24 @@ mod test { } } + /// `write_snapshot` closes the previous group and publishes a new one before writing the frame, + /// so rejecting an oversize frame inside `write_frame` would leave an empty newest group behind. + /// A snapshot consumer jumps to the newest, so the last good value would vanish on a failed + /// update. + #[test] + fn a_rejected_update_leaves_the_previous_value_readable() { + let (mut producer, track) = producer(cfg(0)); + producer.update(&json!({ "keep": true })).unwrap(); + + // Serializes past the group cache limit, so the frame cannot be published. + let oversized = json!({ "big": "x".repeat(moq_net::group::MAX_CACHE_BYTES as usize + 1) }); + assert!(producer.update(&oversized).is_err()); + producer.finish().unwrap(); + + // A reader arriving now still finds the last good value, not an empty superseding group. + assert_eq!(drain(track), vec![json!({ "keep": true })]); + } + #[test] fn unchanged_value_writes_nothing() { let (mut producer, track) = producer(ProducerConfig::default()); diff --git a/rs/moq-json/src/snapshot/producer.rs b/rs/moq-json/src/snapshot/producer.rs index a058276c2e4..2fd7381d60f 100644 --- a/rs/moq-json/src/snapshot/producer.rs +++ b/rs/moq-json/src/snapshot/producer.rs @@ -265,6 +265,14 @@ impl Track { /// Write one encoded frame, rolling a group when it's a snapshot. fn write(&mut self, encoded: &Encoded) -> Result<()> { + // Check before touching a group. `write_snapshot` closes the previous group and publishes a + // new one before the frame is written, so discovering the limit inside `write_frame` would + // leave an empty newest group behind: a snapshot consumer jumps to the newest, so the previous + // value would be lost even though this update reported an error. + if encoded.payload.len() as u64 > moq_net::group::MAX_CACHE_BYTES { + return Err(moq_net::Error::FrameTooLarge.into()); + } + match encoded.keyframe { true => self.write_snapshot(encoded.payload.clone()), false => self.write_delta(encoded.payload.clone()), diff --git a/rs/moq-json/src/stream/consumer.rs b/rs/moq-json/src/stream/consumer.rs index fcfc4caf5b4..a65041fd8d4 100644 --- a/rs/moq-json/src/stream/consumer.rs +++ b/rs/moq-json/src/stream/consumer.rs @@ -9,14 +9,18 @@ use crate::Result; /// Consumes an ordered log of JSON records from a track, yielding every record in order. /// -/// A [`Decoder`] that owns its track: it reads one record per frame, in order, and starts the -/// decoder on a cold window at each group boundary. A [`Producer`](super::Producer) writes the whole -/// log into one group, but a publisher that rolls its own (the way an -/// [`Encoder`](super::Encoder) desync is cleared) is read here too. When something else already owns -/// the track, use the [`Decoder`] directly. +/// A [`Decoder`] that owns its track: it reads one record per frame, in order. The log is a single +/// group, which is what makes the mode lossless: rolling to a second group means the records that +/// would have completed the first are gone, so a [`Producer`](super::Producer) that cannot write +/// ends the track instead. A second group is therefore a broken publisher, and reading it would +/// present a gap as a continuous log, so it fails with [`Error::Rolled`](crate::Error::Rolled) +/// rather than yielding the remainder. When something else already owns the track, use the +/// [`Decoder`] directly. pub struct Consumer { - track: moq_net::track::Ordered, + track: moq_net::track::Subscriber, group: Option, + /// Whether the log's one group has been taken, so a second is a rolled log rather than the first. + taken: bool, decoder: Decoder, } @@ -27,8 +31,9 @@ impl Consumer { /// [`ProducerConfig::compression`](super::ProducerConfig::compression) on. pub fn new(track: moq_net::track::Subscriber, config: ConsumerConfig) -> Self { Self { - track: track.ordered(), + track, group: None, + taken: false, decoder: Decoder::new(config), } } @@ -45,9 +50,16 @@ impl Consumer { pub fn poll_next(&mut self, waiter: &kio::Waiter) -> Poll>> { loop { let Some(group) = &mut self.group else { - match self.track.poll_next_group(waiter)? { + // Arrival order rather than sequence order, because there is only ever one group to + // take and a second one has to be seen whatever its sequence. The monotonic + // `poll_next_group` would drop a late lower sequence, which is the very loss this + // has to report. + match self.track.poll_recv_group(waiter)? { Poll::Ready(Some(group)) => { - // Each group is its own compressed stream, so the window starts cold. + if self.taken { + return Poll::Ready(Err(crate::Error::Rolled)); + } + self.taken = true; self.decoder.reset(); self.group = Some(group); continue; @@ -60,8 +72,8 @@ impl Consumer { match group.poll_read_frame(waiter)? { Poll::Ready(Some(frame)) => return Poll::Ready(Ok(Some(self.decoder.decode(&frame.payload)?))), Poll::Ready(None) => { - // This group is exhausted. Clear it and poll for a later one, which starts its own - // window; the stream ends only when the track does. + // The log's one group is exhausted. Keep polling the track so a clean end still + // reports the log as complete, and so a second group is caught as `Rolled`. self.group = None; } Poll::Pending => return Poll::Pending, diff --git a/rs/moq-json/src/stream/encoder.rs b/rs/moq-json/src/stream/encoder.rs index b65f85ace0e..a1a891c7618 100644 --- a/rs/moq-json/src/stream/encoder.rs +++ b/rs/moq-json/src/stream/encoder.rs @@ -132,6 +132,13 @@ impl Encoder { } let bytes = serde_json::to_vec(value)?; + + // Every consumer decodes with moq-flate's default output cap, so a record past it would be + // unreadable however small it compresses to. Reject it here, where the caller still learns + // why, rather than publishing something only the producer can read. + if self.compression && bytes.len() as u64 > moq_flate::DEFAULT_MAX_FRAME_SIZE { + return Err(moq_flate::Error::TooLarge(moq_flate::DEFAULT_MAX_FRAME_SIZE).into()); + } let payload = match self.flate.as_mut() { Some(flate) => flate.frame(&bytes), None => Bytes::from(bytes), diff --git a/rs/moq-json/src/stream/mod.rs b/rs/moq-json/src/stream/mod.rs index 54d3f4eb099..6fa412631cd 100644 --- a/rs/moq-json/src/stream/mod.rs +++ b/rs/moq-json/src/stream/mod.rs @@ -12,6 +12,10 @@ //! the source (e.g. the timeline's segment cadence); a consumer that finds a gap can fetch or //! extrapolate. //! +//! A record that cannot be encoded or written therefore ends the track rather than continuing in a +//! second group: a log missing a record is not lossless, and a gap dressed up as a complete log is +//! worse than a visible failure. A publisher with more to say opens a new track. +//! //! That single group is what bounds the log's history. moq-net caps a group's cached bytes, and a //! consumer always starts at frame 0, so once the log outgrows that budget and the earliest frames //! are evicted a new consumer fails with [`moq_net::Error::Lagged`] rather than reading a partial @@ -152,7 +156,8 @@ mod test { } /// A record the encoder rejects must not have published a group first: a live consumer would - /// advance into it and wait there even though nothing was ever appended. + /// advance into it and wait there even though nothing was ever appended. It still ends the + /// track, since the log is missing the record either way. #[test] fn a_rejected_record_does_not_open_a_group() { // A map with non-string keys can't be represented as JSON, so serialization fails. @@ -160,7 +165,7 @@ mod test { .produce() .create_track("test", None) .unwrap(); - let subscriber = track.subscribe(None); + let mut subscriber = track.subscribe(None); let mut producer = Producer::>::new(track, ProducerConfig::default()); let mut bad = std::collections::BTreeMap::new(); @@ -168,6 +173,12 @@ mod test { assert!(producer.append(&bad).is_err()); assert_eq!(subscriber.latest(), None, "a rejected record opened a group"); + + let waiter = kio::Waiter::noop(); + assert!( + matches!(subscriber.poll_recv_group(&waiter), Poll::Ready(Err(_))), + "the log is missing a record, so the track must end rather than stay writable" + ); } /// A track whose timescale is extreme enough that converting a wall-clock timestamp into it @@ -184,42 +195,60 @@ mod test { .unwrap() } - /// Same as the snapshot case: the log's group is published by `open`, so a record the track - /// rejects must not leave it open with nothing in it. + /// A failed write must reach the consumer, not just the caller. A clean close drains a reader to + /// `None`, which is exactly what a completed log looks like, so a truncated log would be + /// indistinguishable from a whole one. #[test] - fn a_rejected_record_does_not_strand_an_empty_group() { + fn a_failed_write_aborts_the_track() { let track = rejecting_track(); - let mut subscriber = track.subscribe(None).ordered(); + let mut subscriber = track.subscribe(None); let mut producer = Producer::::new(track, ProducerConfig::default()); - assert!(producer.append(&json!({ "n": 1 })).is_err()); + assert!(matches!(producer.append(&json!({ "n": 1 })), Err(crate::Error::Net(_)))); let waiter = kio::Waiter::noop(); - let Poll::Ready(Ok(Some(mut group))) = subscriber.poll_next_group(&waiter) else { - panic!("the group was published, so a subscriber sees it"); - }; assert!( - matches!(group.poll_read_frame(&waiter), Poll::Ready(Ok(None))), - "the empty group must be closed, not left open for a subscriber to wait in" + matches!(subscriber.poll_recv_group(&waiter), Poll::Ready(Err(_))), + "a truncated log must surface an error rather than read as a completed one" ); } - /// Closing the rejected group is only half the recovery. The record that never landed desyncs a - /// compressed encoder, so without a matching reset every later append fails with - /// [`Error::Desync`](crate::Error::Desync) before it can use the fresh group that closing prepared. + /// The track ends with the group, so nothing opens a second one and splits the log. The retry + /// reports the ended track rather than the [`Error::Desync`](crate::Error::Desync) the dropped + /// record left on the encoder, which says nothing about why the log stopped. #[test] - fn a_rejected_record_leaves_the_encoder_able_to_retry() { + fn a_failed_write_ends_the_track() { let track = rejecting_track(); let mut producer = Producer::::new(track, ProducerConfig::default().with_compression(true)); assert!(matches!(producer.append(&json!({ "n": 1 })), Err(crate::Error::Net(_)))); - // The retry fails on the same track, but it has to fail for the same reason: a desync here - // would mean the producer had latched itself shut instead of starting a new group. + // The retry reports the abort rather than the `Error::Desync` the dropped record left on the + // encoder, which says nothing about why the log stopped. assert!( matches!(producer.append(&json!({ "n": 2 })), Err(crate::Error::Net(_))), - "the encoder latched a desync instead of retrying into a fresh group" + "a second append must fail on the ended track rather than open another group" ); + + // A subscriber taken after the abort still exists; it surfaces the failure on its first read, + // which is how a late reader learns the log is truncated. + let waiter = kio::Waiter::noop(); + assert!(matches!( + producer.consume().poll_recv_group(&waiter), + Poll::Ready(Err(_)) + )); + } + + /// A completed log is still readable, so finishing must not end the track the way an abort does. + /// The append that follows fails on the closed track without turning it into a failure. + #[test] + fn appending_after_finish_fails_without_aborting() { + let (mut producer, _track) = producer(compressed()); + producer.append(&json!({ "n": 0 })).unwrap(); + producer.finish().unwrap(); + + assert!(producer.append(&json!({ "n": 1 })).is_err()); + assert_eq!(drain(consumer(producer.consume(), true)), vec![json!({ "n": 0 })]); } #[test] diff --git a/rs/moq-json/src/stream/producer.rs b/rs/moq-json/src/stream/producer.rs index b8b31667d5e..f5a54e8cbc5 100644 --- a/rs/moq-json/src/stream/producer.rs +++ b/rs/moq-json/src/stream/producer.rs @@ -31,6 +31,9 @@ impl Clone for Producer { impl Producer { /// Create a subscriber for the underlying track. + /// + /// Still hands one back once a failed write has ended the log: the subscriber surfaces the abort + /// on its first read, which is what tells a late reader the log is truncated. pub fn consume(&self) -> moq_net::track::Subscriber { self.inner.lock().unwrap().track.inner.subscribe(None) } @@ -52,6 +55,12 @@ impl Producer { } /// Append one record to the log. + /// + /// Any failure ends the track. A log missing a record is not the lossless log a stream promises, + /// and that holds whether the group rejected the record or it never encoded at all, so the + /// failure is surfaced rather than papered over with a second group. The track is aborted rather + /// than closed cleanly, so a consumer sees the failure instead of a log that merely looks + /// complete. Every later append fails on the ended track. pub fn append(&mut self, value: &T) -> Result<()> { self.inner.lock().unwrap().append(value) } @@ -80,21 +89,44 @@ impl Inner { // Encode first, so a value that can't be serialized doesn't publish an empty group that // subscribers would advance into and wait on. Opening the group afterwards is safe because // `record` guards the window: any failure below drops it uncommitted. - let record = encoder.encode(value)?; + let record = match encoder.encode(value) { + Ok(record) => record, + Err(err) => { + // A record that can't be encoded is as lost as one the group rejects: the log is + // missing it either way, and carrying on would present that gap as a complete log. + // Nothing was published, so this only has to end the track. + track.abort(moq_net::Error::Cancel); + return Err(err); + } + }; - let result = match track.open() { + let opened = track.open(); + let published = opened.is_ok(); + let result = match opened { Ok(()) => track.write(record.payload()), Err(err) => Err(err), }; if let Err(err) = result { - // The record never reached the wire, so dropping it desyncs a compressed encoder. `Track` - // has already closed the group it published, which is the group roll that recovery needs; - // reset the encoder to finish it, or the desync latch refuses every later record even - // though the fresh group could carry one. + // The record never reached the wire either way, so the window is ahead of every consumer + // and has to be reset. Without this the desync latch answers the next append before the + // track does, masking the real reason the log stopped. drop(record); encoder.reset(); - return Err(err); + + // What differs is whether a consumer could have seen the group. A write failure means the + // group is already live, so the record is a hole in the log, and a second group would hand + // consumers that gap dressed up as a complete log. End the track, which is what keeps "a + // stream is one group" a real invariant rather than the usual case. + // + // An `open` failure published nothing (it only runs when there is no group), so a later + // append opens a fresh group whose decoder starts cold. That path also catches an append + // onto a track already ended this way, which keeps reporting the error it was aborted with. + if published { + track.abort(err.clone()); + } + + return Err(err.into()); } record.commit(); @@ -102,20 +134,21 @@ impl Inner { } fn finish(&mut self) -> Result<()> { - self.track.finish() + Ok(self.track.finish()?) } } /// The track half of [`Inner`]: the single group carrying the whole log. struct Track { inner: moq_net::track::Producer, - // Opened on the first append and never rolled. + + /// Opened on the first append and never rolled. group: Option, } impl Track { /// Open the log's group if it isn't already. - fn open(&mut self) -> Result<()> { + fn open(&mut self) -> std::result::Result<(), moq_net::Error> { if self.group.is_none() { self.group = Some(self.inner.append_group()?); } @@ -123,26 +156,43 @@ impl Track { } /// Append one encoded record to the log's group. - fn write(&mut self, payload: &bytes::Bytes) -> Result<()> { + fn write(&mut self, payload: &bytes::Bytes) -> std::result::Result<(), moq_net::Error> { let group = self.group.as_mut().expect("a group is open"); - let Err(err) = group.write_frame(moq_net::Timestamp::now(), payload.clone()) else { - return Ok(()); - }; + group.write_frame(moq_net::Timestamp::now(), payload.clone()) + } - // The group is already published and dropping the handle does not close it, so a subscriber - // that advanced into it would wait there with nothing to read. Close it and let a later append - // open a fresh one, which is what a caller recovering from the desync has to do anyway. - if let Some(mut group) = self.group.take() { - let _ = group.finish(); + /// End the track with an error, so a consumer sees the failure rather than a clean end. + /// + /// Aborting the *track* is what a subscriber observes. Aborting only the group drops it from the + /// cache and the consumer still reads a clean end, which is exactly what a completed log looks + /// like, so a truncated log would be indistinguishable from a whole one. + fn abort(&mut self, err: moq_net::Error) { + // Abort the group with the same error first. `track::Producer::abort` deliberately leaves an + // already-pulled `group::Consumer` independent, so dropping our handle would hand a reader + // sitting in the group a generic `Dropped` instead of the failure that ended the log. + if let Some(group) = self.group.take() { + let _ = group.abort(err.clone()); } - Err(err.into()) + + // Abort through a clone, since aborting consumes a handle and the state is shared. Keeping + // ours means `consume` still hands back a subscriber, which is how a reader learns the log + // ended badly rather than cleanly. + let _ = self.inner.clone().abort(err); } - fn finish(&mut self) -> Result<()> { - if let Some(mut group) = self.group.take() { - group.finish()?; - } - self.inner.finish()?; + fn finish(&mut self) -> std::result::Result<(), moq_net::Error> { + // Finalize both independently rather than short-circuiting on the group. Returning early + // would leave the track open with `group` already taken, so a later append would open a + // second group, and (with compression) write into it from a window the consumer never + // received. That is exactly the split log ending the track exists to prevent. + let group = match self.group.take() { + Some(mut group) => group.finish(), + None => Ok(()), + }; + let track = self.inner.finish(); + + group?; + track?; Ok(()) } } diff --git a/rs/moq-mux/Cargo.toml b/rs/moq-mux/Cargo.toml index ee78861f29e..16662ce8f53 100644 --- a/rs/moq-mux/Cargo.toml +++ b/rs/moq-mux/Cargo.toml @@ -20,6 +20,7 @@ h264-parser = { version = "0.4.0" } hang = { workspace = true } kio = { workspace = true } memchr = "2" +moq-binary = { workspace = true } moq-json = { workspace = true } moq-loc = { workspace = true } moq-msf = { workspace = true } diff --git a/rs/moq-mux/src/binary.rs b/rs/moq-mux/src/binary.rs new file mode 100644 index 00000000000..9317823d29a --- /dev/null +++ b/rs/moq-mux/src/binary.rs @@ -0,0 +1,419 @@ +//! Binary track publish/subscribe. +//! +//! A binary track is application data a broadcast publishes as opaque payloads: a thumbnail, a +//! serialized state blob, a sequence of samples in some application format. The catalog entry +//! ([`hang::catalog::BinaryConfig`]) says how to read it, so a consumer needs the track name and +//! nothing else about the application. Reach for [`json`](crate::json) instead when the payloads +//! are JSON, so a generic consumer can read them. +//! +//! The write and read sides are shaped differently on purpose. A publisher knows its mode at +//! compile time, so [`Snapshot`] and [`Stream`] are distinct types and `append`-on-a-snapshot can't +//! be written. A consumer only learns the mode from the catalog, so there is one [`Consumer`] that +//! reads either; it exposes [`mode`](Consumer::mode) for a reader that needs to know. +//! +//! Mint a producer from the catalog: +//! +//! ```no_run +//! # fn example( +//! # broadcast: &mut moq_net::broadcast::Producer, +//! # catalog: &moq_mux::catalog::Producer, +//! # jpeg: bytes::Bytes, +//! # ) -> moq_mux::Result<()> { +//! let track = broadcast.create_track("thumbnail", None)?; +//! let config = moq_mux::binary::Config::default().with_mime("image/jpeg"); +//! let mut thumbnail = catalog.binary_snapshot(track, config)?; +//! thumbnail.update(jpeg)?; +//! # Ok(()) +//! # } +//! ``` +//! +//! The catalog entry is written when the producer is created and removed when it drops, so a track +//! is never advertised without a publisher behind it. +//! +//! Read one back off the catalog, naming it once: +//! +//! ```no_run +//! # async fn example( +//! # source: &moq_mux::Source, +//! # catalog: &moq_mux::catalog::hang::Catalog, +//! # ) -> moq_mux::Result<()> { +//! let entry = catalog.binary_track("thumbnail").expect("no thumbnail track"); +//! let mut thumbnail = entry.subscribe(source).await?; +//! while let Some(jpeg) = thumbnail.next().await? { +//! // ... +//! } +//! # Ok(()) +//! # } +//! ``` + +use bytes::Bytes; + +use hang::catalog::{BinaryConfig, Compression, Mode}; + +use crate::catalog::Rendition; +use crate::catalog::hang::CatalogExt; + +/// Everything a binary track declares about itself, beyond its mode and name. +/// +/// Start from [`default`](Default::default) and chain the setters. The mode is not in here: it is +/// fixed by which producer you create. +#[derive(Debug, Clone, Default)] +#[non_exhaustive] +pub struct Config { + /// DEFLATE-compress the track's frames, advertised as + /// [`Compression::Deflate`]. + /// + /// The catalog flag is what a consumer reads, so the track name needs no `.z` suffix. + pub compression: bool, + + /// An optional media type for each payload (e.g. `image/jpeg`). + pub mime: Option, +} + +impl Config { + /// Set [`compression`](Self::compression) (a builder, since the struct is `#[non_exhaustive]`). + pub fn with_compression(mut self, compression: bool) -> Self { + self.compression = compression; + self + } + + /// Set [`mime`](Self::mime) (a builder, since the struct is `#[non_exhaustive]`). + pub fn with_mime(mut self, mime: impl Into) -> Self { + self.mime = Some(mime.into()); + self + } + + /// The catalog entry describing a track published under this config in `mode`. + pub(crate) fn entry(&self, mode: Mode) -> BinaryConfig { + let mut entry = BinaryConfig::new(mode); + entry.compression = self.compression.then_some(Compression::Deflate); + entry.mime = self.mime.clone(); + entry + } +} + +/// Publishes a latest-value binary track, advertised in the catalog for as long as this handle +/// lives. +/// +/// Every [`update`](Self::update) supersedes the last, so a consumer reads only the newest payload. +/// For a log where every payload survives, use [`Stream`]. +pub struct Snapshot { + inner: moq_binary::snapshot::Producer, + rendition: Rendition, +} + +impl Snapshot { + pub(crate) fn new( + track: moq_net::track::Producer, + mut rendition: Rendition, + config: &Config, + ) -> Self { + let inner = moq_binary::snapshot::Producer::new( + track, + moq_binary::snapshot::ProducerConfig::default().with_compression(config.compression), + ); + rendition.set(config.entry(Mode::Snapshot)); + Self { inner, rendition } + } + + /// The track name, which is also the catalog key. + pub fn name(&self) -> &str { + self.rendition.name() + } + + /// Create a subscriber for the underlying track. + pub fn consume(&self) -> moq_net::track::Subscriber { + self.inner.consume() + } + + /// Publish a new payload, superseding the previous one. + pub fn update(&mut self, payload: impl Into) -> crate::Result<()> { + Ok(self.inner.update(payload)?) + } + + /// Finish the track and retire its catalog entry. + /// + /// Consumes the handle, so a write after finishing cannot be expressed. Leaving the entry + /// advertising a closed track would only mislead a consumer that subscribed afterwards, so + /// dropping the handle without finishing retires the entry too. + pub fn finish(mut self) -> crate::Result<()> { + Ok(self.inner.finish()?) + } +} + +/// Publishes an append-log binary track, advertised in the catalog for as long as this handle lives. +/// +/// Every [`append`](Self::append) is preserved and delivered in order. For a latest-value payload, +/// use [`Snapshot`]. +pub struct Stream { + inner: moq_binary::stream::Producer, + name: String, + + /// Cleared when a terminal failure ends the track, which retires the catalog entry with it. An + /// entry advertising a track that can no longer accept records only misleads a consumer that + /// discovers it afterwards. + rendition: Option>, +} + +impl Stream { + pub(crate) fn new( + track: moq_net::track::Producer, + mut rendition: Rendition, + config: &Config, + ) -> Self { + let inner = moq_binary::stream::Producer::new( + track, + moq_binary::stream::ProducerConfig::default().with_compression(config.compression), + ); + rendition.set(config.entry(Mode::Stream)); + Self { + inner, + name: rendition.name().to_string(), + rendition: Some(rendition), + } + } + + /// The track name, which is also the catalog key. + pub fn name(&self) -> &str { + &self.name + } + + /// Create a subscriber for the underlying track. + /// + /// Still hands one back once a failed write has ended the log: the subscriber surfaces the abort + /// on its first read. + pub fn consume(&self) -> moq_net::track::Subscriber { + self.inner.consume() + } + + /// Append one payload to the log. + /// + /// A payload that cannot be written ends the track (see + /// [`moq_binary::stream::Producer::append`]) and retires the catalog entry with it. + pub fn append(&mut self, payload: impl Into) -> crate::Result<()> { + let Err(err) = self.inner.append(payload) else { + return Ok(()); + }; + + // The inner producer has already closed the track. Dropping the rendition retires the catalog + // entry too: waiting for the handle to drop would keep advertising a track that can no longer + // accept records, so a consumer discovering it now would subscribe to an already-ended log. + self.rendition = None; + + Err(err.into()) + } + + /// Finish the track and retire its catalog entry. + /// + /// Consumes the handle, so a write after finishing cannot be expressed. Leaving the entry + /// advertising a closed track would only mislead a consumer that subscribed afterwards, so + /// dropping the handle without finishing retires the entry too. + pub fn finish(mut self) -> crate::Result<()> { + Ok(self.inner.finish()?) + } +} + +/// Reads a binary track, in whichever mode its catalog entry declares. +/// +/// One type rather than one per mode: both modes hand the caller the same thing, a sequence of +/// payloads ending when the track does, so a reader writes one loop either way. What differs is +/// loss semantics, and that is a property to ask about ([`mode`](Self::mode)) rather than a fork +/// every caller pays for. A reader that genuinely requires losslessness checks the mode and bails. +pub struct Consumer { + inner: Inner, + mode: Mode, +} + +/// Which moq-binary consumer is doing the reading. Private: the caller sees one `Consumer`. +enum Inner { + Snapshot(moq_binary::snapshot::Consumer), + Stream(moq_binary::stream::Consumer), +} + +impl Consumer { + /// Read an already-subscribed track as its catalog entry declares. + /// + /// The escape hatch for a caller that resolved the subscription itself. Prefer + /// [`Entry::subscribe`](crate::catalog::Entry::subscribe), which resolves the track (including a + /// cross-broadcast [`broadcast`](BinaryConfig::broadcast) reference) from the catalog for you. + /// + /// Errors if the entry declares a mode or compression this build doesn't implement, which is a + /// track a consumer must skip rather than guess at. + pub fn from_track(track: moq_net::track::Subscriber, config: &BinaryConfig) -> crate::Result { + let compression = crate::compression(config.compression.as_ref())?; + + let inner = match &config.mode { + Mode::Snapshot => Inner::Snapshot(moq_binary::snapshot::Consumer::new( + track, + moq_binary::snapshot::ConsumerConfig::default().with_compression(compression), + )), + Mode::Stream => Inner::Stream(moq_binary::stream::Consumer::new( + track, + moq_binary::stream::ConsumerConfig::default().with_compression(compression), + )), + other => return Err(crate::Error::UnsupportedMode(other.to_string())), + }; + + Ok(Self { + inner, + mode: config.mode.clone(), + }) + } + + /// The mode the publisher chose. + /// + /// [`Mode::Snapshot`] is lossy: intermediate payloads are superseded and only the newest is + /// yielded. [`Mode::Stream`] preserves every payload. Check this when the application can only + /// work with one of them. + pub fn mode(&self) -> &Mode { + &self.mode + } + + /// Get the next payload, or `None` once the track ends. + pub async fn next(&mut self) -> crate::Result> { + kio::wait(|waiter| self.poll_next(waiter)).await + } + + /// Poll for the next payload, without blocking. + pub fn poll_next(&mut self, waiter: &kio::Waiter) -> std::task::Poll>> { + let result = match &mut self.inner { + Inner::Snapshot(consumer) => consumer.poll_next(waiter), + Inner::Stream(consumer) => consumer.poll_next(waiter), + }; + + match result { + std::task::Poll::Ready(value) => std::task::Poll::Ready(value.map_err(Into::into)), + std::task::Poll::Pending => std::task::Poll::Pending, + } + } +} + +impl crate::catalog::Entry<'_, BinaryConfig> { + /// Subscribe to this track and read it as the entry declares. + /// + /// Resolves the track through `source`, so an entry whose [`broadcast`](BinaryConfig::broadcast) + /// field names a sibling broadcast is followed rather than silently read from the catalog's own. + /// + /// Errors if the entry declares a mode or compression this build doesn't implement. + pub async fn subscribe(&self, source: &crate::Source) -> crate::Result { + let track = source + .subscribe_track(self.config().broadcast.as_ref(), self.name()) + .await?; + Consumer::from_track(track, self.config()) + } +} + +#[cfg(test)] +mod test { + use std::task::Poll; + + use super::*; + + fn catalog() -> (moq_net::broadcast::Producer, crate::catalog::Producer) { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = crate::catalog::Producer::new(&mut broadcast).unwrap(); + (broadcast, catalog) + } + + /// Create the moq-net track a data producer publishes on, as a caller does for a media track. + fn track(broadcast: &mut moq_net::broadcast::Producer, name: &str) -> moq_net::track::Producer { + broadcast.create_track(name, None).unwrap() + } + + fn entry(catalog: &crate::catalog::Producer, name: &str) -> BinaryConfig { + catalog + .snapshot() + .binary + .tracks + .get(name) + .expect("missing catalog entry") + .clone() + } + + /// Drain every payload a consumer currently has, without blocking. + /// + /// One loop whichever mode the publisher chose, which is the point of the single `Consumer`. + fn drain(mut consumer: Consumer) -> Vec { + let waiter = kio::Waiter::noop(); + let mut out = Vec::new(); + while let Poll::Ready(Ok(Some(payload))) = consumer.poll_next(&waiter) { + out.push(payload); + } + out + } + + #[test] + fn a_stream_track_roundtrips() { + let (mut broadcast, catalog) = catalog(); + let mut samples = catalog + .binary_stream( + track(&mut broadcast, "samples"), + Config::default().with_compression(true), + ) + .unwrap(); + + let track = samples.consume(); + let expected: Vec = (0..3u8).map(|n| Bytes::from(vec![n; 8])).collect(); + for payload in &expected { + samples.append(payload.clone()).unwrap(); + } + // `finish` retires the entry, so read both off the live track first. + let entry = entry(&catalog, "samples"); + samples.finish().unwrap(); + + let consumer = Consumer::from_track(track, &entry).unwrap(); + assert_eq!(consumer.mode(), &Mode::Stream); + assert_eq!(drain(consumer), expected); + } + + #[test] + fn a_snapshot_track_roundtrips() { + let (mut broadcast, catalog) = catalog(); + let mut thumbnail = catalog + .binary_snapshot( + track(&mut broadcast, "thumbnail"), + Config::default().with_mime("image/jpeg"), + ) + .unwrap(); + + let track = thumbnail.consume(); + thumbnail.update(&b"old"[..]).unwrap(); + thumbnail.update(&b"new"[..]).unwrap(); + let entry = entry(&catalog, "thumbnail"); + thumbnail.finish().unwrap(); + assert_eq!(entry.mode, Mode::Snapshot); + assert_eq!(entry.compression, None); + assert_eq!(entry.mime.as_deref(), Some("image/jpeg")); + + let consumer = Consumer::from_track(track, &entry).unwrap(); + assert_eq!(drain(consumer), vec![Bytes::from_static(b"new")]); + } + + #[test] + fn dropping_the_producer_retires_the_entry() { + let (mut broadcast, catalog) = catalog(); + let thumbnail = catalog + .binary_snapshot(track(&mut broadcast, "thumbnail"), Config::default()) + .unwrap(); + assert!(catalog.snapshot().binary.tracks.contains_key("thumbnail")); + + drop(thumbnail); + assert!( + !catalog.snapshot().binary.tracks.contains_key("thumbnail"), + "a track with no publisher must not stay advertised" + ); + } + + /// The two catalog sections are separate namespaces, so a JSON and a binary track may share a + /// name there. The broadcast's track names are one namespace, though, so the caller's + /// `create_track` is what refuses the second publisher. + #[test] + fn a_name_taken_by_another_track_is_refused() { + let (mut broadcast, catalog) = catalog(); + let _first = catalog + .binary_snapshot(track(&mut broadcast, "data"), Config::default()) + .unwrap(); + + assert!(broadcast.create_track("data", None).is_err()); + } +} diff --git a/rs/moq-mux/src/catalog/consumer.rs b/rs/moq-mux/src/catalog/consumer.rs index 340c41c18be..c64a46ce711 100644 --- a/rs/moq-mux/src/catalog/consumer.rs +++ b/rs/moq-mux/src/catalog/consumer.rs @@ -59,7 +59,7 @@ impl Stream for Consumer { match self { Self::Hang(c) => c.poll_next(waiter), Self::Msf(c) => { - // MSF carries only the media sections, so the extension defaults. + // MSF carries only the media sections, so the data sections and the extension default. let media = match ready!(c.poll_next(waiter)) { Ok(media) => media, Err(err) => return Poll::Ready(Err(err)), @@ -69,6 +69,8 @@ impl Stream for Consumer { audio: m.audio, timeline: m.timeline, text: m.text, + json: hang::catalog::Json::default(), + binary: hang::catalog::Binary::default(), ext: E::default(), }))) } diff --git a/rs/moq-mux/src/catalog/entry.rs b/rs/moq-mux/src/catalog/entry.rs new file mode 100644 index 00000000000..2b8a646e13c --- /dev/null +++ b/rs/moq-mux/src/catalog/entry.rs @@ -0,0 +1,46 @@ +//! A borrowed catalog entry: a track's name paired with the config describing it. + +use std::ops::Deref; + +/// One entry in a catalog section: the track's name and the config describing it. +/// +/// A catalog section is a map, so reading one out hands you a key and a value that have to be kept +/// together: the name says what to subscribe to, the config says how to read it. Pairing them means +/// a caller can't accidentally subscribe to one track with another's config, and it only has to +/// name the track once. +/// +/// Get one from [`Catalog`](super::hang::Catalog), by name or by iterating a section. It derefs to +/// the config, so the config's fields are reachable directly (`entry.mode`, `entry.compression`). +/// +/// The entry is what a consumer is built from: see +/// [`json::Consumer`](crate::json::Consumer) and [`binary::Consumer`](crate::binary::Consumer), +/// each of which adds a `subscribe` to the entry types it can read. +#[derive(Clone, Copy, Debug)] +pub struct Entry<'a, C> { + name: &'a str, + config: &'a C, +} + +impl<'a, C> Entry<'a, C> { + pub(crate) fn new(name: &'a str, config: &'a C) -> Self { + Self { name, config } + } + + /// The track name, which is the key this entry is stored under. + pub fn name(&self) -> &'a str { + self.name + } + + /// The config describing how to read the track. + pub fn config(&self) -> &'a C { + self.config + } +} + +impl Deref for Entry<'_, C> { + type Target = C; + + fn deref(&self) -> &C { + self.config + } +} diff --git a/rs/moq-mux/src/catalog/hang/consumer.rs b/rs/moq-mux/src/catalog/hang/consumer.rs index 43df7be9eb3..2f3c86c060d 100644 --- a/rs/moq-mux/src/catalog/hang/consumer.rs +++ b/rs/moq-mux/src/catalog/hang/consumer.rs @@ -79,19 +79,23 @@ impl From for Consumer { } } -/// Reject the catalog if any rendition's `broadcast` reference walks above the root. +/// Reject the catalog if any track's `broadcast` reference walks above the root. /// -/// Every section carrying renditions must be chained here; a section left out silently -/// exempts its renditions from the containment check. +/// Every section carrying a `broadcast` reference must be chained here; a section left out +/// silently exempts its tracks from the containment check. fn check_resolvable(base: &PathOwned, catalog: &Catalog) -> Result<()> { let video = catalog.video.renditions.iter(); let audio = catalog.audio.renditions.iter(); let text = catalog.text.renditions.iter(); + let json = catalog.json.tracks.iter(); + let binary = catalog.binary.tracks.iter(); for (rendition, rel) in video .map(|(name, config)| (name, config.broadcast.as_ref())) .chain(audio.map(|(name, config)| (name, config.broadcast.as_ref()))) .chain(text.map(|(name, config)| (name, config.broadcast.as_ref()))) + .chain(json.map(|(name, config)| (name, config.broadcast.as_ref()))) + .chain(binary.map(|(name, config)| (name, config.broadcast.as_ref()))) { let Some(rel) = rel.filter(|rel| !rel.is_empty()) else { continue; @@ -329,6 +333,37 @@ mod test { } } + /// Data tracks carry a `broadcast` reference like any rendition, so the containment check + /// covers them too. Without this the catalog is accepted and the escape surfaces much later, + /// when the entry is subscribed. + #[tokio::test] + async fn rejects_a_catalog_whose_data_broadcast_escapes_the_root() { + for section in ["json", "binary"] { + let mut published = Catalog::<()>::default(); + published.audio.renditions.insert("here".to_string(), opus()); + + let escaping = moq_net::PathRelative::new("../../../elsewhere").into_owned(); + match section { + "json" => { + let mut config = hang::catalog::JsonConfig::new(hang::catalog::Mode::Stream); + config.broadcast = Some(escaping); + published.json.tracks.insert("chat".to_string(), config); + } + _ => { + let mut config = hang::catalog::BinaryConfig::new(hang::catalog::Mode::Stream); + config.broadcast = Some(escaping); + published.binary.tracks.insert("blobs".to_string(), config); + } + } + + match publish_catalog(published) { + Err(crate::Error::EscapingBroadcast(reported)) => assert_eq!(reported, "../../../elsewhere"), + Err(err) => panic!("wrong error for {section}: {err:?}"), + Ok(_) => panic!("an escaping {section} reference should reject the catalog"), + } + } + } + #[test] fn waits_for_pending_catalog_group_payload() { let mut track = track_producer(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()); diff --git a/rs/moq-mux/src/catalog/hang/ext.rs b/rs/moq-mux/src/catalog/hang/ext.rs index 86eaa1a3e2e..9eac1bdb588 100644 --- a/rs/moq-mux/src/catalog/hang/ext.rs +++ b/rs/moq-mux/src/catalog/hang/ext.rs @@ -39,8 +39,8 @@ impl CatalogExt for () {} /// cross. Publish/consume a [`Catalog`] and use [`set`](Self::set)/[`get`](Self::get). /// The default extension stays `()` (unknown sections dropped); opt into `Extra` explicitly. /// -/// `video`, `audio`, `text`, and `timeline` are reserved for the base sections, so -/// [`set`](Self::set) rejects them to keep the wire JSON free of duplicate keys. +/// `video`, `audio`, `text`, `timeline`, `json`, and `binary` are reserved for the base sections, +/// so [`set`](Self::set) rejects them to keep the wire JSON free of duplicate keys. #[derive(Serialize, Deserialize, Clone, Default, Debug, PartialEq)] #[serde(transparent)] pub struct Extra(serde_json::Map); @@ -69,10 +69,13 @@ impl Extra { } /// Set (or replace) a section. Errors if `name` collides with a reserved base - /// section (`video`/`audio`/`text`/`timeline`). + /// section (`video`/`audio`/`text`/`timeline`/`json`/`binary`). pub fn set(&mut self, name: impl Into, value: serde_json::Value) -> crate::Result<()> { let name = name.into(); - if matches!(name.as_str(), "video" | "audio" | "text" | "timeline") { + if matches!( + name.as_str(), + "video" | "audio" | "text" | "timeline" | "json" | "binary" + ) { return Err(crate::Error::ReservedSection(name)); } self.0.insert(name, value); @@ -85,16 +88,21 @@ impl Extra { } } -/// The base media sections plus an application extension `E` (defaulting to `()` for none), -/// serialized as a flat union: the `video`/`audio`/`text` media sections, shared `timeline`, and -/// extension sections share one JSON object on the wire. +/// The base sections plus an application extension `E` (defaulting to `()` for none), serialized +/// as a flat union: the `video`/`audio`/`text` media sections, the shared `timeline`, the +/// `json`/`binary` data sections, and the extension's sections share one JSON object on the wire. /// -/// The base sections are direct fields (`catalog.video`), and the catalog derefs to the extension -/// so its sections are reachable directly too (`catalog.scte35`, or `catalog.ext.scte35` -/// explicitly). A consumer reading a different extension (or none) ignores sections it doesn't -/// know. +/// The data sections (`json`/`binary`) carry application tracks that aren't media. Every base +/// section is a direct field (`catalog.video`), and the catalog derefs to the extension so its +/// sections are reachable directly too (`catalog.scte35`, or `catalog.ext.scte35` explicitly). A +/// consumer reading a different extension (or none) ignores sections it doesn't know. +/// +/// Marked `#[non_exhaustive]` so a future base section can be added without breaking callers, which +/// is what [`hang::catalog::Catalog`] already does. Build one with +/// [`default`](Default::default) and set the fields you need. #[derive(Serialize, Deserialize, Clone, Default, Debug, PartialEq)] #[serde(bound(serialize = "E: Serialize", deserialize = "E: DeserializeOwned"))] +#[non_exhaustive] pub struct Catalog { #[serde(default)] pub video: hang::catalog::Video, @@ -118,12 +126,76 @@ pub struct Catalog { )] pub text: hang::catalog::Text, + /// JSON tracks: application data published as live JSON documents or logs. Omitted from the + /// wire when empty, so a media-only catalog is unchanged. + /// + /// Decoded leniently for the same reason as [`text`](Self::text): `json` is a generic enough + /// key that an application could have been carrying its own through [`Extra`] before this one + /// was reserved. + #[serde( + default, + skip_serializing_if = "hang::catalog::Json::is_empty", + deserialize_with = "hang::catalog::deserialize_section" + )] + pub json: hang::catalog::Json, + + /// Binary tracks: application data published as opaque payloads. Omitted from the wire when + /// empty, so a media-only catalog is unchanged. Decoded leniently for the same reason as + /// [`json`](Self::json). + #[serde( + default, + skip_serializing_if = "hang::catalog::Binary::is_empty", + deserialize_with = "hang::catalog::deserialize_section" + )] + pub binary: hang::catalog::Binary, + #[serde(flatten)] pub ext: E, } impl Catalog { + /// The JSON track named `name`, or `None` if the catalog doesn't list one. + /// + /// The returned [`Entry`](crate::catalog::Entry) carries the name along with the config, so + /// reading the track is one call that can't mismatch the two: + /// `catalog.json_track("chat")?.subscribe::(&source).await?`. + pub fn json_track(&self, name: &str) -> Option> { + let (name, config) = self.json.tracks.get_key_value(name)?; + Some(crate::catalog::Entry::new(name, config)) + } + + /// Every JSON track the catalog lists, in name order. + /// + /// This is the discovery path: the catalog is the only thing that announces a data track, so a + /// consumer finds them by walking this. + pub fn json_tracks(&self) -> impl Iterator> { + self.json + .tracks + .iter() + .map(|(name, config)| crate::catalog::Entry::new(name, config)) + } + + /// The binary track named `name`, or `None` if the catalog doesn't list one. + /// + /// See [`json_track`](Self::json_track). + pub fn binary_track(&self, name: &str) -> Option> { + let (name, config) = self.binary.tracks.get_key_value(name)?; + Some(crate::catalog::Entry::new(name, config)) + } + + /// Every binary track the catalog lists, in name order. + /// + /// See [`json_tracks`](Self::json_tracks). + pub fn binary_tracks(&self) -> impl Iterator> { + self.binary + .tracks + .iter() + .map(|(name, config)| crate::catalog::Entry::new(name, config)) + } + /// The base catalog carrying just the media sections, used to derive the MSF track. + /// + /// MSF describes media only, so the data sections are deliberately left out. pub(crate) fn media(&self) -> hang::Catalog { let mut catalog = hang::Catalog::default(); catalog.video = self.video.clone(); diff --git a/rs/moq-mux/src/catalog/mod.rs b/rs/moq-mux/src/catalog/mod.rs index 6bb4c57fd29..f7aa6584b4d 100644 --- a/rs/moq-mux/src/catalog/mod.rs +++ b/rs/moq-mux/src/catalog/mod.rs @@ -24,6 +24,7 @@ pub mod hang; pub mod msf; mod consumer; +mod entry; mod estimate; mod format; mod producer; @@ -32,6 +33,7 @@ mod stream; mod tracks; pub use consumer::Consumer; +pub use entry::Entry; pub use estimate::{Estimate, Estimator}; pub use format::*; pub use producer::{Config, Guard, Producer}; diff --git a/rs/moq-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index 50be530e4bf..1e7bd5fb5d3 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -461,6 +461,75 @@ impl Producer { self.timeline.clone() } + /// Publish `track` as a latest-value JSON track, advertising it in the catalog. + /// + /// The caller creates the track on the broadcast, as it does for a media track + /// ([`media_producer`](Self::media_producer)); this writes its catalog entry and removes the + /// entry when the returned handle drops. The catalog key is [`track.name()`](moq_net::track::Producer::name) + /// verbatim, with no `.z` suffix even when compressed, since the entry's compression flag is + /// what a consumer reads. + /// + /// Errors if the catalog already carries an entry under that name, for example one seeded + /// through [`Config::with_catalog`] or one pointing at a sibling broadcast. + pub fn json_snapshot( + &self, + track: moq_net::track::Producer, + config: crate::json::Config, + ) -> crate::Result> { + let rendition = self.data_entry(track.name())?; + Ok(crate::json::Snapshot::new(track, rendition, &config)) + } + + /// Publish `track` as an append-log JSON track, advertising it in the catalog. + /// + /// See [`json_snapshot`](Self::json_snapshot) for the lifecycle; this differs only in that every + /// record is preserved rather than superseded. + pub fn json_stream( + &self, + track: moq_net::track::Producer, + config: crate::json::Config, + ) -> crate::Result> { + let rendition = self.data_entry(track.name())?; + Ok(crate::json::Stream::new(track, rendition, &config)) + } + + /// Publish `track` as a latest-value binary track, advertising it in the catalog. + /// + /// See [`json_snapshot`](Self::json_snapshot) for the lifecycle; this differs only in that the + /// payloads are opaque bytes. + pub fn binary_snapshot( + &self, + track: moq_net::track::Producer, + config: crate::binary::Config, + ) -> crate::Result> { + let rendition = self.data_entry(track.name())?; + Ok(crate::binary::Snapshot::new(track, rendition, &config)) + } + + /// Publish `track` as an append-log binary track, advertising it in the catalog. + /// + /// See [`json_snapshot`](Self::json_snapshot) for the lifecycle; this differs only in that the + /// payloads are opaque bytes and every one is preserved rather than superseded. + pub fn binary_stream( + &self, + track: moq_net::track::Producer, + config: crate::binary::Config, + ) -> crate::Result> { + let rendition = self.data_entry(track.name())?; + Ok(crate::binary::Stream::new(track, rendition, &config)) + } + + /// Reserve the catalog entry a data producer owns, keyed by its track name. + /// + /// The rendition is reserved but not yet set, so the caller fills it in with the config for the + /// mode it is about to publish. Reserving is what rejects a name the catalog already carries, + /// including an entry with no local track behind it (seeded through + /// [`Config::with_catalog`], or pointing at a sibling broadcast), which publishing over would + /// silently replace and then retire when this handle drops. + fn data_entry>(&self, name: &str) -> crate::Result> { + self.reserve().init(name) + } + /// Create a consumer for this catalog, receiving updates as they're published. pub fn consume(&self) -> Result, moq_net::Error> { Ok(Consumer::new(self.outputs.hang.consume())) diff --git a/rs/moq-mux/src/catalog/tracks.rs b/rs/moq-mux/src/catalog/tracks.rs index b2f736b1152..635bdc75835 100644 --- a/rs/moq-mux/src/catalog/tracks.rs +++ b/rs/moq-mux/src/catalog/tracks.rs @@ -82,6 +82,30 @@ pub trait RenditionConfig: Sized + 'static { fn set_estimate(&mut self, _estimate: Estimate) {} } +impl RenditionConfig for hang::catalog::JsonConfig { + fn insert(self, catalog: &mut Catalog, name: &str) { + catalog.json.tracks.insert(name.to_string(), self); + } + fn get_mut<'a>(catalog: &'a mut Catalog, name: &str) -> Option<&'a mut Self> { + catalog.json.tracks.get_mut(name) + } + fn remove(catalog: &mut Catalog, name: &str) { + catalog.json.tracks.remove(name); + } +} + +impl RenditionConfig for hang::catalog::BinaryConfig { + fn insert(self, catalog: &mut Catalog, name: &str) { + catalog.binary.tracks.insert(name.to_string(), self); + } + fn get_mut<'a>(catalog: &'a mut Catalog, name: &str) -> Option<&'a mut Self> { + catalog.binary.tracks.get_mut(name) + } + fn remove(catalog: &mut Catalog, name: &str) { + catalog.binary.tracks.remove(name); + } +} + /// Caller-provided catalog fields for a video track: a starting point for what the importer detects. /// /// Every field is optional and fills only a gap the stream leaves; a value the stream reveals (the diff --git a/rs/moq-mux/src/error.rs b/rs/moq-mux/src/error.rs index 865b17dda86..8c3d2ed029b 100644 --- a/rs/moq-mux/src/error.rs +++ b/rs/moq-mux/src/error.rs @@ -36,6 +36,18 @@ pub enum Error { #[error("json: {0}")] Json(#[from] moq_json::Error), + /// Error publishing or consuming binary payloads over a track. + #[error("binary: {0}")] + Binary(#[from] moq_binary::Error), + + /// A catalog entry declares a track mode this build does not implement. + #[error("unsupported track mode: {0}")] + UnsupportedMode(String), + + /// A catalog entry declares a compression this build does not implement. + #[error("unsupported track compression: {0}")] + UnsupportedCompression(String), + /// Error parsing or building CMAF moof+mdat fragments. #[error("cmaf: {0}")] Cmaf(#[from] crate::container::fmp4::Error), diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs new file mode 100644 index 00000000000..038c17d52ca --- /dev/null +++ b/rs/moq-mux/src/json.rs @@ -0,0 +1,567 @@ +//! JSON track publish/subscribe. +//! +//! A JSON track is application data a broadcast publishes alongside its media: a chat log, a +//! telemetry feed, a status document. The catalog entry +//! ([`hang::catalog::JsonConfig`]) says how to read it, so a consumer needs the track name and +//! nothing else about the application. +//! +//! The write and read sides are shaped differently on purpose. A publisher knows its mode at +//! compile time, so [`Snapshot`] and [`Stream`] are distinct types and `append`-on-a-snapshot can't +//! be written. A consumer only learns the mode from the catalog, so there is one [`Consumer`] that +//! reads either; it exposes [`mode`](Consumer::mode) for a reader that needs to know. +//! +//! Mint a producer from the catalog: +//! +//! ```no_run +//! # use serde::{Deserialize, Serialize}; +//! # #[derive(Serialize, Deserialize)] +//! # struct Message { text: String } +//! # fn example( +//! # broadcast: &mut moq_net::broadcast::Producer, +//! # catalog: &moq_mux::catalog::Producer, +//! # ) -> moq_mux::Result<()> { +//! let track = broadcast.create_track("chat", None)?; +//! let config = moq_mux::json::Config::default().with_compression(true); +//! let mut chat = catalog.json_stream::(track, config)?; +//! chat.append(&Message { text: "hello".to_string() })?; +//! # Ok(()) +//! # } +//! ``` +//! +//! The catalog entry is written when the producer is created and removed when it drops, so a track +//! is never advertised without a publisher behind it. +//! +//! Read one back off the catalog, naming it once: +//! +//! ```no_run +//! # use serde::{Deserialize, Serialize}; +//! # #[derive(Serialize, Deserialize)] +//! # struct Message { text: String } +//! # async fn example( +//! # source: &moq_mux::Source, +//! # catalog: &moq_mux::catalog::hang::Catalog, +//! # ) -> moq_mux::Result<()> { +//! let entry = catalog.json_track("chat").expect("no chat track"); +//! let mut chat = entry.subscribe::(source).await?; +//! while let Some(message) = chat.next().await? { +//! // ... +//! } +//! # Ok(()) +//! # } +//! ``` + +use serde::Serialize; +use serde::de::DeserializeOwned; + +use hang::catalog::{Compression, JsonConfig, Mode}; + +use crate::catalog::Rendition; +use crate::catalog::hang::CatalogExt; + +/// Everything a JSON track declares about itself, beyond its mode and name. +/// +/// Start from [`default`](Default::default) and chain the setters. The mode is not in here: it is +/// fixed by which producer you create. +#[derive(Debug, Clone, Default)] +#[non_exhaustive] +pub struct Config { + /// DEFLATE-compress the track's frames, advertised as + /// [`Compression::Deflate`]. + /// + /// The catalog flag is what a consumer reads, so the track name needs no `.z` suffix. + pub compression: bool, + + /// An optional identifier for the shape of each value, typically a JSON Schema URL. + pub schema: Option, +} + +impl Config { + /// Set [`compression`](Self::compression) (a builder, since the struct is `#[non_exhaustive]`). + pub fn with_compression(mut self, compression: bool) -> Self { + self.compression = compression; + self + } + + /// Set [`schema`](Self::schema) (a builder, since the struct is `#[non_exhaustive]`). + pub fn with_schema(mut self, schema: impl Into) -> Self { + self.schema = Some(schema.into()); + self + } + + /// The catalog entry describing a track published under this config in `mode`. + pub(crate) fn entry(&self, mode: Mode) -> JsonConfig { + let mut entry = JsonConfig::new(mode); + entry.compression = self.compression.then_some(Compression::Deflate); + entry.schema = self.schema.clone(); + entry + } +} + +/// Publishes a latest-value JSON track, advertised in the catalog for as long as this handle lives. +/// +/// Every [`update`](Self::update) supersedes the last, so a consumer reads only the newest value. +/// For a log where every record survives, use [`Stream`]. +pub struct Snapshot { + inner: moq_json::snapshot::Producer, + rendition: Rendition, +} + +impl Snapshot { + pub(crate) fn new( + track: moq_net::track::Producer, + mut rendition: Rendition, + config: &Config, + ) -> Self { + let inner = moq_json::snapshot::Producer::new( + track, + moq_json::snapshot::ProducerConfig::default().with_compression(config.compression), + ); + rendition.set(config.entry(Mode::Snapshot)); + Self { inner, rendition } + } + + /// The track name, which is also the catalog key. + pub fn name(&self) -> &str { + self.rendition.name() + } + + /// Create a subscriber for the underlying track. + pub fn consume(&self) -> moq_net::track::Subscriber { + self.inner.consume() + } + + /// Publish a new value, superseding the previous one. + pub fn update(&mut self, value: &T) -> crate::Result<()> { + Ok(self.inner.update(value)?) + } + + /// Finish the track and retire its catalog entry. + /// + /// Consumes the handle, so a write after finishing cannot be expressed. Leaving the entry + /// advertising a closed track would only mislead a consumer that subscribed afterwards, so + /// dropping the handle without finishing retires the entry too. + pub fn finish(mut self) -> crate::Result<()> { + Ok(self.inner.finish()?) + } +} + +/// Publishes an append-log JSON track, advertised in the catalog for as long as this handle lives. +/// +/// Every [`append`](Self::append) is preserved and delivered in order. For a latest-value document, +/// use [`Snapshot`]. +pub struct Stream { + inner: moq_json::stream::Producer, + name: String, + + /// Cleared when a terminal failure ends the track, which retires the catalog entry with it. An + /// entry advertising a track that can no longer accept records only misleads a consumer that + /// discovers it afterwards. + rendition: Option>, +} + +impl Stream { + pub(crate) fn new( + track: moq_net::track::Producer, + mut rendition: Rendition, + config: &Config, + ) -> Self { + let inner = moq_json::stream::Producer::new( + track, + moq_json::stream::ProducerConfig::default().with_compression(config.compression), + ); + rendition.set(config.entry(Mode::Stream)); + Self { + inner, + name: rendition.name().to_string(), + rendition: Some(rendition), + } + } + + /// The track name, which is also the catalog key. + pub fn name(&self) -> &str { + &self.name + } + + /// Create a subscriber for the underlying track. + /// + /// Still hands one back once a failed write has ended the log: the subscriber surfaces the abort + /// on its first read. + pub fn consume(&self) -> moq_net::track::Subscriber { + self.inner.consume() + } + + /// Append one record to the log. + /// + /// Any failure ends the track (see [`moq_json::stream::Producer::append`]) and retires the + /// catalog entry with it. + pub fn append(&mut self, value: &T) -> crate::Result<()> { + let Err(err) = self.inner.append(value) else { + return Ok(()); + }; + + // The inner producer has already ended the track. Dropping the rendition retires the catalog + // entry: waiting for the handle to drop would keep advertising a track that can no longer + // accept records, so a consumer discovering it now would subscribe to an already-ended log. + self.rendition = None; + + Err(err.into()) + } + + /// Finish the track and retire its catalog entry. + /// + /// Consumes the handle, so a write after finishing cannot be expressed. Leaving the entry + /// advertising a closed track would only mislead a consumer that subscribed afterwards, so + /// dropping the handle without finishing retires the entry too. + pub fn finish(mut self) -> crate::Result<()> { + Ok(self.inner.finish()?) + } +} + +/// Reads a JSON track, in whichever mode its catalog entry declares. +/// +/// One type rather than one per mode: both modes hand the caller the same thing, a sequence of `T` +/// ending when the track does, so a reader writes one loop either way. What differs is loss +/// semantics, and that is a property to ask about ([`mode`](Self::mode)) rather than a fork every +/// caller pays for. A reader that genuinely requires losslessness checks the mode and bails. +pub struct Consumer { + inner: Inner, + mode: Mode, +} + +/// Which moq-json consumer is doing the reading. Private: the caller sees one `Consumer`. +enum Inner { + Snapshot(moq_json::snapshot::Consumer), + Stream(moq_json::stream::Consumer), +} + +impl Consumer { + /// Read an already-subscribed track as its catalog entry declares. + /// + /// The escape hatch for a caller that resolved the subscription itself. Prefer + /// [`Entry::subscribe`](crate::catalog::Entry::subscribe), which resolves the track (including a + /// cross-broadcast [`broadcast`](JsonConfig::broadcast) reference) from the catalog for you. + /// + /// Errors if the entry declares a mode or compression this build doesn't implement, which is a + /// track a consumer must skip rather than guess at. + pub fn from_track(track: moq_net::track::Subscriber, config: &JsonConfig) -> crate::Result { + let compression = crate::compression(config.compression.as_ref())?; + + let inner = match &config.mode { + Mode::Snapshot => Inner::Snapshot(moq_json::snapshot::Consumer::new( + track, + moq_json::snapshot::ConsumerConfig::default().with_compression(compression), + )), + Mode::Stream => Inner::Stream(moq_json::stream::Consumer::new( + track, + moq_json::stream::ConsumerConfig::default().with_compression(compression), + )), + other => return Err(crate::Error::UnsupportedMode(other.to_string())), + }; + + Ok(Self { + inner, + mode: config.mode.clone(), + }) + } + + /// The mode the publisher chose. + /// + /// [`Mode::Snapshot`] is lossy: intermediate values are superseded and only the newest is + /// yielded. [`Mode::Stream`] preserves every record. Check this when the application can only + /// work with one of them. + pub fn mode(&self) -> &Mode { + &self.mode + } + + /// Get the next value, or `None` once the track ends. + pub async fn next(&mut self) -> crate::Result> { + kio::wait(|waiter| self.poll_next(waiter)).await + } + + /// Poll for the next value, without blocking. + pub fn poll_next(&mut self, waiter: &kio::Waiter) -> std::task::Poll>> { + let result = match &mut self.inner { + Inner::Snapshot(consumer) => consumer.poll_next(waiter), + Inner::Stream(consumer) => consumer.poll_next(waiter), + }; + + match result { + std::task::Poll::Ready(value) => std::task::Poll::Ready(value.map_err(Into::into)), + std::task::Poll::Pending => std::task::Poll::Pending, + } + } +} + +impl crate::catalog::Entry<'_, JsonConfig> { + /// Subscribe to this track and read it as the entry declares. + /// + /// Resolves the track through `source`, so an entry whose [`broadcast`](JsonConfig::broadcast) + /// field names a sibling broadcast is followed rather than silently read from the catalog's own. + /// + /// Errors if the entry declares a mode or compression this build doesn't implement. + pub async fn subscribe(&self, source: &crate::Source) -> crate::Result> { + let track = source + .subscribe_track(self.config().broadcast.as_ref(), self.name()) + .await?; + Consumer::from_track(track, self.config()) + } +} + +#[cfg(test)] +mod test { + use std::task::Poll; + + use serde_json::{Value, json}; + + use super::*; + + fn catalog() -> (moq_net::broadcast::Producer, crate::catalog::Producer) { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = crate::catalog::Producer::new(&mut broadcast).unwrap(); + (broadcast, catalog) + } + + /// Create the moq-net track a data producer publishes on, as a caller does for a media track. + fn track(broadcast: &mut moq_net::broadcast::Producer, name: &str) -> moq_net::track::Producer { + broadcast.create_track(name, None).unwrap() + } + + fn entry(catalog: &crate::catalog::Producer, name: &str) -> JsonConfig { + catalog + .snapshot() + .json + .tracks + .get(name) + .expect("missing catalog entry") + .clone() + } + + /// Drain every value a consumer currently has, without blocking. + /// + /// One loop whichever mode the publisher chose, which is the point of the single `Consumer`. + fn drain(mut consumer: Consumer) -> Vec { + let waiter = kio::Waiter::noop(); + let mut out = Vec::new(); + while let Poll::Ready(Ok(Some(value))) = consumer.poll_next(&waiter) { + out.push(value); + } + out + } + + #[test] + fn a_stream_track_roundtrips() { + let (mut broadcast, catalog) = catalog(); + let mut chat = catalog + .json_stream::(track(&mut broadcast, "chat"), Config::default().with_compression(true)) + .unwrap(); + + let track = chat.consume(); + let expected: Vec = (0..3).map(|n| json!({ "n": n })).collect(); + for value in &expected { + chat.append(value).unwrap(); + } + // `finish` retires the entry, so read both off the live track first. + let entry = entry(&catalog, "chat"); + chat.finish().unwrap(); + + // The catalog is the only thing the reader is told; mode and compression come from it. + let consumer = Consumer::from_track(track, &entry).unwrap(); + assert_eq!(consumer.mode(), &Mode::Stream); + assert_eq!(drain(consumer), expected); + } + + #[test] + fn a_snapshot_track_roundtrips() { + let (mut broadcast, catalog) = catalog(); + let mut status = catalog + .json_snapshot::(track(&mut broadcast, "status"), Config::default()) + .unwrap(); + + let track = status.consume(); + status.update(&json!({ "live": false })).unwrap(); + status.update(&json!({ "live": true })).unwrap(); + let entry = entry(&catalog, "status"); + status.finish().unwrap(); + + // A late reader only sees the newest value, which is the point of snapshot mode. + let consumer = Consumer::from_track(track, &entry).unwrap(); + assert_eq!(consumer.mode(), &Mode::Snapshot); + assert_eq!(drain(consumer), vec![json!({ "live": true })]); + } + + #[test] + fn the_entry_describes_how_to_read_the_track() { + let (mut broadcast, catalog) = catalog(); + let _chat = catalog + .json_stream::( + track(&mut broadcast, "chat"), + Config::default() + .with_compression(true) + .with_schema("https://example.com/chat.schema.json"), + ) + .unwrap(); + + let entry = entry(&catalog, "chat"); + assert_eq!(entry.mode, Mode::Stream); + assert_eq!(entry.compression, Some(Compression::Deflate)); + assert_eq!(entry.schema.as_deref(), Some("https://example.com/chat.schema.json")); + // The flag is authoritative, so the track name carries no `.z` suffix. + assert_eq!(_chat.name(), "chat"); + } + + #[test] + fn dropping_the_producer_retires_the_entry() { + let (mut broadcast, catalog) = catalog(); + let chat = catalog + .json_stream::(track(&mut broadcast, "chat"), Config::default()) + .unwrap(); + assert!(catalog.snapshot().json.tracks.contains_key("chat")); + + drop(chat); + assert!( + !catalog.snapshot().json.tracks.contains_key("chat"), + "a track with no publisher must not stay advertised" + ); + } + + /// `finish` consumes the handle, so the entry goes with it: an entry advertising a closed track + /// only misleads a consumer that subscribes afterwards. + #[test] + fn finishing_retires_the_entry_too() { + let (mut broadcast, catalog) = catalog(); + let chat = catalog + .json_stream::(track(&mut broadcast, "chat"), Config::default()) + .unwrap(); + assert!(catalog.snapshot().json.tracks.contains_key("chat")); + + chat.finish().unwrap(); + assert!(!catalog.snapshot().json.tracks.contains_key("chat")); + } + + /// A catalog entry can exist with no local track behind it, e.g. one seeded at construction that + /// references a sibling broadcast. Publishing over that name would replace what the entry pointed + /// at and then retire it entirely on drop, so the name counts as taken. + #[test] + fn an_existing_catalog_entry_is_not_replaced() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + + let mut existing = JsonConfig::new(Mode::Snapshot); + existing.broadcast = Some(moq_net::PathRelativeOwned::new("source")); + + let mut seed = crate::catalog::hang::Catalog::<()>::default(); + seed.json.tracks.insert("chat".to_string(), existing.clone()); + let catalog = crate::catalog::Producer::with_catalog(&mut broadcast, seed).unwrap(); + + // Nothing local holds the track name, so `create_track` alone would have let this through. + assert!(matches!( + catalog.json_stream::(track(&mut broadcast, "chat"), Config::default()), + Err(crate::Error::Hang(hang::Error::Duplicate(_))) + )); + assert_eq!(catalog.snapshot().json.tracks.get("chat"), Some(&existing)); + } + + /// The catalog is the only thing that announces a data track, so walking it is the discovery + /// path. Each entry carries its own name, so nothing has to be threaded alongside it. + #[test] + fn the_catalog_enumerates_its_tracks() { + let (mut broadcast, catalog) = catalog(); + let _chat = catalog + .json_stream::(track(&mut broadcast, "chat"), Config::default()) + .unwrap(); + let _status = catalog + .json_snapshot::(track(&mut broadcast, "status"), Config::default()) + .unwrap(); + + let snapshot = catalog.snapshot(); + let found: Vec<(&str, &Mode)> = snapshot.json_tracks().map(|t| (t.name(), &t.config().mode)).collect(); + assert_eq!(found, vec![("chat", &Mode::Stream), ("status", &Mode::Snapshot)]); + + // A name the catalog doesn't list has no entry, rather than a config to misread. + assert!(snapshot.json_track("nope").is_none()); + + // The entry derefs to its config, so the fields read directly. + let chat = snapshot.json_track("chat").expect("missing entry"); + assert_eq!(chat.name(), "chat"); + assert_eq!(chat.mode, Mode::Stream); + } + + /// The whole read path: name the track once, and the entry resolves the subscription (through + /// `Source`, so a cross-broadcast reference is followed) and says how to decode it. + #[tokio::test] + async fn an_entry_subscribes_and_reads() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = crate::catalog::Producer::new(&mut broadcast).unwrap(); + let source = crate::source::announced(&broadcast.consume()); + + let mut chat = catalog + .json_stream::(track(&mut broadcast, "chat"), Config::default()) + .unwrap(); + chat.append(&json!({ "text": "hello" })).unwrap(); + + let snapshot = catalog.snapshot(); + let entry = snapshot.json_track("chat").expect("missing entry"); + let mut consumer = entry.subscribe::(&source).await.unwrap(); + chat.finish().unwrap(); + + assert_eq!(consumer.next().await.unwrap(), Some(json!({ "text": "hello" }))); + assert_eq!(consumer.next().await.unwrap(), None); + } + + /// A value that fails to serialize never reaches the track, but the log is missing it all the + /// same, so it is as terminal as a rejected write. The entry and the track have to agree: retiring + /// the entry while leaving the track writable would let a later valid record land somewhere no + /// consumer could discover. + #[test] + fn an_unserializable_record_ends_the_track_and_the_entry() { + struct Record(bool); + + impl Serialize for Record { + fn serialize(&self, serializer: S) -> Result { + match self.0 { + true => Err(serde::ser::Error::custom("cannot serialize")), + false => serializer.serialize_u8(0), + } + } + } + + let (mut broadcast, catalog) = catalog(); + let mut chat = catalog + .json_stream::(track(&mut broadcast, "chat"), Config::default()) + .unwrap(); + let mut track = chat.consume(); + + assert!(chat.append(&Record(true)).is_err()); + assert!(!catalog.snapshot().json.tracks.contains_key("chat")); + + assert!( + chat.append(&Record(false)).is_err(), + "a record after the failure would land on a track the retired entry no longer advertises" + ); + + let waiter = kio::Waiter::noop(); + assert!(matches!(track.poll_recv_group(&waiter), Poll::Ready(Err(_)))); + } + + /// A consumer that can't tell a log from a latest-value document would silently drop records, + /// so an unreadable entry is an error rather than a guess. + #[test] + fn an_unrecognized_mode_or_compression_is_refused() { + let track = moq_net::broadcast::Info::new() + .produce() + .create_track("chat", None) + .unwrap(); + + let mut config = JsonConfig::new(Mode::Unknown("windowed".to_string())); + assert!(matches!( + Consumer::::from_track(track.subscribe(None), &config), + Err(crate::Error::UnsupportedMode(_)) + )); + + config.mode = Mode::Stream; + config.compression = Some(Compression::Unknown("zstd".to_string())); + assert!(matches!( + Consumer::::from_track(track.subscribe(None), &config), + Err(crate::Error::UnsupportedCompression(_)) + )); + } +} diff --git a/rs/moq-mux/src/lib.rs b/rs/moq-mux/src/lib.rs index 511b76accb2..65a3a66d134 100644 --- a/rs/moq-mux/src/lib.rs +++ b/rs/moq-mux/src/lib.rs @@ -24,12 +24,14 @@ //! ranges that carry it on each track, so consumers can seek or build //! HLS/DASH playlists without downloading media. +pub mod binary; pub mod catalog; mod clock; pub mod codec; pub mod container; mod error; pub mod import; +pub mod json; mod pace; pub mod select; mod source; @@ -39,3 +41,15 @@ pub use clock::Clock; pub use error::*; pub use pace::Pacer; pub use source::Source; + +/// Translate a catalog entry's declared compression into the flag the codecs take. +/// +/// An unrecognized algorithm is an error rather than a fallback to plaintext: reading its frames +/// raw would hand the caller garbage. +pub(crate) fn compression(compression: Option<&hang::catalog::Compression>) -> Result { + match compression { + None => Ok(false), + Some(hang::catalog::Compression::Deflate) => Ok(true), + Some(other) => Err(Error::UnsupportedCompression(other.to_string())), + } +} diff --git a/rs/moq-mux/src/source.rs b/rs/moq-mux/src/source.rs index 7327201165f..1742fc8c587 100644 --- a/rs/moq-mux/src/source.rs +++ b/rs/moq-mux/src/source.rs @@ -126,6 +126,8 @@ impl Source { self.retain_valid_references("video", &mut catalog.video.renditions); self.retain_valid_references("audio", &mut catalog.audio.renditions); self.retain_valid_references("text", &mut catalog.text.renditions); + self.retain_valid_references("json", &mut catalog.json.tracks); + self.retain_valid_references("binary", &mut catalog.binary.tracks); } /// Remove media renditions whose broadcast reference escapes above the origin root. @@ -213,6 +215,18 @@ impl BroadcastConfig for hang::catalog::TextConfig { } } +impl BroadcastConfig for hang::catalog::JsonConfig { + fn broadcast(&self) -> Option<&moq_net::PathRelativeOwned> { + self.broadcast.as_ref() + } +} + +impl BroadcastConfig for hang::catalog::BinaryConfig { + fn broadcast(&self) -> Option<&moq_net::PathRelativeOwned> { + self.broadcast.as_ref() + } +} + /// Test helper: build an origin producer, spawning its driver on the ambient runtime. #[cfg(test)] pub(crate) fn produce_origin() -> moq_net::origin::Producer {