From 7e757347f3d77daef5e4f29e13cbb3dec4a213b3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 01:31:47 -0700 Subject: [PATCH 1/4] feat(json)!: Config means the same thing in json and binary Codec options are Config. The track-owning pair is producer::Config / consumer::Config in Rust and Producer.Config / Consumer.Config in JS. Compression is a shared enum instead of with_compression(bool). Co-Authored-By: grok-4.6 --- doc/.vitepress/config.ts | 4 ++ doc/lib/js/binary.md | 29 +++++++++ doc/lib/js/index.md | 3 +- doc/lib/js/json.md | 32 ++++++++++ doc/lib/rs/index.md | 3 +- doc/lib/rs/moq-binary.md | 32 ++++++++++ doc/lib/rs/moq-json.md | 30 +++++++++ js/binary/README.md | 6 +- js/binary/src/compression.ts | 15 +++++ js/binary/src/index.ts | 1 + js/binary/src/snapshot/consumer.ts | 19 +++--- js/binary/src/snapshot/index.ts | 6 +- js/binary/src/snapshot/producer.ts | 24 ++++--- js/binary/src/snapshot/snapshot.test.ts | 6 +- js/binary/src/stream/consumer.ts | 19 +++--- js/binary/src/stream/index.ts | 6 +- js/binary/src/stream/producer.ts | 24 ++++--- js/binary/src/stream/stream.test.ts | 12 ++-- js/binary/src/types.test.ts | 4 ++ js/json/README.md | 2 +- js/json/src/compression.ts | 15 +++++ js/json/src/index.ts | 1 + js/json/src/snapshot/codec.test.ts | 9 ++- js/json/src/snapshot/compression.test.ts | 20 +++--- js/json/src/snapshot/consumer.ts | 15 +++-- js/json/src/snapshot/decoder.ts | 10 ++- js/json/src/snapshot/encoder.ts | 9 +-- js/json/src/snapshot/index.ts | 7 ++- js/json/src/snapshot/producer.ts | 12 ++-- js/json/src/snapshot/snapshot.test.ts | 4 +- js/json/src/stream/codec.test.ts | 21 ++++--- js/json/src/stream/consumer.ts | 14 +++-- js/json/src/stream/decoder.ts | 11 ++-- js/json/src/stream/encoder.ts | 8 ++- js/json/src/stream/index.ts | 8 +-- js/json/src/stream/producer.ts | 12 ++-- js/json/src/stream/stream.test.ts | 10 +-- js/json/src/types.test.ts | 4 ++ js/publish/src/catalog.ts | 2 +- js/watch/src/broadcast.ts | 2 +- quest/m1/README.md | 1 - quest/m1/api-json-binary-config-names.md | 31 ---------- quest/m1/merge-dev.md | 1 - rs/libmoq/src/api.rs | 26 ++++++-- rs/libmoq/src/consume.rs | 4 +- rs/libmoq/src/publish.rs | 9 +-- rs/moq-binary/src/lib.rs | 18 ++++++ rs/moq-binary/src/snapshot/consumer.rs | 27 ++------ rs/moq-binary/src/snapshot/mod.rs | 63 +++++++++++++------ rs/moq-binary/src/snapshot/producer.rs | 28 +-------- rs/moq-binary/src/stream/consumer.rs | 27 ++------ rs/moq-binary/src/stream/mod.rs | 63 +++++++++++++------ rs/moq-binary/src/stream/producer.rs | 27 +------- rs/moq-boy/src/input.rs | 2 +- rs/moq-boy/src/status.rs | 2 +- rs/moq-ffi/src/json.rs | 45 ++++++++------ rs/moq-json/CHANGELOG.md | 3 + rs/moq-json/examples/telemetry.rs | 23 ++++--- rs/moq-json/src/lib.rs | 18 ++++++ rs/moq-json/src/snapshot/consumer.rs | 22 +++++-- rs/moq-json/src/snapshot/decoder.rs | 55 +++++++---------- rs/moq-json/src/snapshot/encoder.rs | 79 ++++++++++++------------ rs/moq-json/src/snapshot/mod.rs | 55 ++++++++++------- rs/moq-json/src/snapshot/producer.rs | 6 +- rs/moq-json/src/stream/consumer.rs | 9 +-- rs/moq-json/src/stream/decoder.rs | 67 ++++++++++---------- rs/moq-json/src/stream/encoder.rs | 26 +++----- rs/moq-json/src/stream/mod.rs | 55 ++++++++++------- rs/moq-json/src/stream/producer.rs | 6 +- rs/moq-json/src/window/encoder.rs | 2 +- rs/moq-mux/src/binary.rs | 40 +++++++----- rs/moq-mux/src/catalog/hang/consumer.rs | 6 +- rs/moq-mux/src/catalog/producer.rs | 4 +- rs/moq-mux/src/json.rs | 40 +++++++----- rs/moq-stats/src/aggregate.rs | 14 +++-- rs/moq-stats/src/consume.rs | 5 +- rs/moq-stats/src/produce.rs | 5 +- 77 files changed, 812 insertions(+), 573 deletions(-) create mode 100644 doc/lib/js/binary.md create mode 100644 doc/lib/js/json.md create mode 100644 doc/lib/rs/moq-binary.md create mode 100644 doc/lib/rs/moq-json.md create mode 100644 js/binary/src/compression.ts create mode 100644 js/json/src/compression.ts delete mode 100644 quest/m1/api-json-binary-config-names.md diff --git a/doc/.vitepress/config.ts b/doc/.vitepress/config.ts index 40e7471d566..717844df391 100644 --- a/doc/.vitepress/config.ts +++ b/doc/.vitepress/config.ts @@ -167,6 +167,8 @@ export default defineConfig({ { text: "moq-audio", link: "/lib/rs/moq-audio" }, { text: "moq-auth", link: "/lib/rs/moq-auth" }, { text: "moq-room", link: "/lib/rs/moq-room" }, + { text: "moq-json", link: "/lib/rs/moq-json" }, + { text: "moq-binary", link: "/lib/rs/moq-binary" }, ], }, { @@ -180,6 +182,8 @@ export default defineConfig({ { text: "@moq/room", link: "/lib/js/room" }, { text: "@moq/auth", link: "/lib/js/auth" }, { text: "@moq/signals", link: "/lib/js/signals" }, + { text: "@moq/json", link: "/lib/js/json" }, + { text: "@moq/binary", link: "/lib/js/binary" }, ], }, { text: "Swift", link: "/lib/swift/" }, diff --git a/doc/lib/js/binary.md b/doc/lib/js/binary.md new file mode 100644 index 00000000000..71a87298158 --- /dev/null +++ b/doc/lib/js/binary.md @@ -0,0 +1,29 @@ +--- +title: "@moq/binary" +description: Opaque binary payloads over MoQ tracks +--- + +# @moq/binary + +[![npm](https://img.shields.io/npm/v/@moq/binary)](https://www.npmjs.com/package/@moq/binary) + +Opaque payloads over [`@moq/net`](/lib/js/net) tracks, in two modes: + +- **Snapshot**: lossy latest-value, one payload per group. +- **Stream**: lossless append-log in a single group. + +The bytes are never inspected. Compression is [`@moq/flate`](https://www.npmjs.com/package/@moq/flate), +the same group-scoped DEFLATE `@moq/json` uses. + +`Config` is the codec options. `Producer.Config` / `Consumer.Config` add the +track. Compression is a shared `"none" | "deflate"` enum, not a boolean: both +sides set the same field. + +```ts +import { Snapshot } from "@moq/binary"; + +const producer = new Snapshot.Producer({ track, compression: "deflate" }); +producer.update(payload); +``` + +The Rust twin is [`moq-binary`](/lib/rs/moq-binary). diff --git a/doc/lib/js/index.md b/doc/lib/js/index.md index 29d9f6b0217..bf92b42f883 100644 --- a/doc/lib/js/index.md +++ b/doc/lib/js/index.md @@ -20,7 +20,8 @@ and WebAudio. `@moq/net` also runs in Node, Bun, and Deno. | [@moq/room](/lib/js/room) | Headless rooms: announce-derived roster, local publish, remote watch, and a chat track. | | [@moq/auth](/lib/js/auth) | Validate a relay's request, build its grant, and mint and verify relay JWTs. | | [@moq/signals](/lib/js/signals) | The reactive primitives every package exposes its state through. | -| [@moq/json](https://www.npmjs.com/package/@moq/json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. | +| [@moq/json](/lib/js/json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. | +| [@moq/binary](/lib/js/binary) | Opaque payloads over tracks: snapshots or append logs. | | [@moq/flate](https://www.npmjs.com/package/@moq/flate) | Group-scoped DEFLATE for any track. | | [@moq/loc](https://www.npmjs.com/package/@moq/loc), [@moq/msf](https://www.npmjs.com/package/@moq/msf) | The IETF LOC container and MSF catalog. | | [@moq/boy](https://www.npmjs.com/package/@moq/boy) | The [MoQ Boy](/bin/demo) player element. | diff --git a/doc/lib/js/json.md b/doc/lib/js/json.md new file mode 100644 index 00000000000..64c540e08f9 --- /dev/null +++ b/doc/lib/js/json.md @@ -0,0 +1,32 @@ +--- +title: "@moq/json" +description: JSON over MoQ tracks, as snapshots, streams, or a sliding window +--- + +# @moq/json + +[![npm](https://img.shields.io/npm/v/@moq/json)](https://www.npmjs.com/package/@moq/json) + +JSON over [`@moq/net`](/lib/js/net) tracks, in three modes: + +- **Snapshot**: lossy latest-value, with RFC 7396 merge-patch deltas. +- **Stream**: lossless append-log in a single group. +- **Window**: a bounded run of records a reader can join at any point. + +`Config` is the codec options. `Producer.Config` / `Consumer.Config` add the +track. Compression is a shared `"none" | "deflate"` enum, not a boolean: both +sides set the same field. + +```ts +import { Snapshot } from "@moq/json"; + +const producer = new Snapshot.Producer({ track, compression: "deflate" }); +producer.update({ hello: "world" }); + +const consumer = new Snapshot.Consumer({ track, compression: "deflate" }); +for await (const value of consumer) { + console.log(value); +} +``` + +The Rust twin is [`moq-json`](/lib/rs/moq-json). diff --git a/doc/lib/rs/index.md b/doc/lib/rs/index.md index c191b709ffb..7a25fb7b4be 100644 --- a/doc/lib/rs/index.md +++ b/doc/lib/rs/index.md @@ -22,7 +22,8 @@ The reference implementation. Every crate is on | [moq-transcode](https://docs.rs/moq-transcode) | Just-in-time rendition ladders, GPU-resident on NVIDIA. | | [moq-auth](/lib/rs/moq-auth) | The authorization contract: requests, grants, leases, the HTTP client, the reference server, and JWT keys, signing, and verification. | | [moq-room](/lib/rs/moq-room) | Headless rooms: announce-derived roster, token claims, and a chat track. | -| [moq-json](https://docs.rs/moq-json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. | +| [moq-json](/lib/rs/moq-json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. | +| [moq-binary](/lib/rs/moq-binary) | Opaque payloads over tracks: snapshots or append logs. | | [moq-e2ee](https://docs.rs/moq-e2ee) | End-to-end encryption of groups, datagrams, catalogs, and track names. | | [moq-flate](https://docs.rs/moq-flate) | Group-scoped DEFLATE for any track. | | [moq-loc](https://docs.rs/moq-loc), [moq-msf](https://docs.rs/moq-msf) | The IETF LOC container and MSF catalog. | diff --git a/doc/lib/rs/moq-binary.md b/doc/lib/rs/moq-binary.md new file mode 100644 index 00000000000..23fd5068623 --- /dev/null +++ b/doc/lib/rs/moq-binary.md @@ -0,0 +1,32 @@ +--- +title: moq-binary +description: Opaque binary payloads over MoQ tracks +--- + +# moq-binary + +[![crates.io](https://img.shields.io/crates/v/moq-binary)](https://crates.io/crates/moq-binary) +[![docs.rs](https://docs.rs/moq-binary/badge.svg)](https://docs.rs/moq-binary) + +Opaque payloads over [`moq-net`](/lib/rs/moq-net) tracks, in two modes: + +- **snapshot**: lossy latest-value, one payload per group. +- **stream**: lossless append-log in a single group. + +The bytes are never inspected. Compression is [`moq-flate`](https://docs.rs/moq-flate), +the same group-scoped DEFLATE `moq-json` uses. + +`Config` is the codec options. The track-owning pair is `producer::Config` / +`consumer::Config`. Compression is a shared `Compression` enum (`None` or +`Deflate`), not a bool: both sides set the same field. + +```rust +let mut config = moq_binary::snapshot::Config::default(); +config.compression = moq_binary::Compression::Deflate; + +let mut producer = moq_binary::snapshot::Producer::new(track, config); +producer.update(payload)?; +``` + +The TypeScript twin is [`@moq/binary`](/lib/js/binary). API: +[docs.rs/moq-binary](https://docs.rs/moq-binary). diff --git a/doc/lib/rs/moq-json.md b/doc/lib/rs/moq-json.md new file mode 100644 index 00000000000..0977265f8f7 --- /dev/null +++ b/doc/lib/rs/moq-json.md @@ -0,0 +1,30 @@ +--- +title: moq-json +description: JSON over MoQ tracks, as snapshots, streams, or a sliding window +--- + +# moq-json + +[![crates.io](https://img.shields.io/crates/v/moq-json)](https://crates.io/crates/moq-json) +[![docs.rs](https://docs.rs/moq-json/badge.svg)](https://docs.rs/moq-json) + +JSON over [`moq-net`](/lib/rs/moq-net) tracks, in three modes: + +- **snapshot**: lossy latest-value, with RFC 7396 merge-patch deltas. +- **stream**: lossless append-log in a single group. +- **window**: a bounded run of records a reader can join at any point. + +`Config` is the codec options. The track-owning pair is `producer::Config` / +`consumer::Config`. Compression is a shared `Compression` enum (`None` or +`Deflate`), not a bool: both sides set the same field. + +```rust +let mut config = moq_json::snapshot::Config::default(); +config.compression = moq_json::Compression::Deflate; + +let mut producer = moq_json::snapshot::Producer::new(track, config); +producer.update(&value)?; +``` + +The TypeScript twin is [`@moq/json`](/lib/js/json). API: +[docs.rs/moq-json](https://docs.rs/moq-json). diff --git a/js/binary/README.md b/js/binary/README.md index 732050ff57e..c3448e284b6 100644 --- a/js/binary/README.md +++ b/js/binary/README.md @@ -9,5 +9,7 @@ The bytes are opaque: this package frames them onto a track and optionally compr 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. +`Config` is the codec options (`compression: "none" | "deflate"`). `Producer.Config` / +`Consumer.Config` add the track. 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/src/compression.ts b/js/binary/src/compression.ts new file mode 100644 index 00000000000..bf2b36d4084 --- /dev/null +++ b/js/binary/src/compression.ts @@ -0,0 +1,15 @@ +/** How a binary track compresses its frames. `"none"` (the default) is uncompressed payloads. */ +export type Compression = "none" | "deflate"; + +/** Whether `compression` is group-scoped DEFLATE. */ +export function isDeflate(compression?: Compression): boolean { + switch (compression) { + case undefined: + case "none": + return false; + case "deflate": + return true; + default: + throw new Error(`unsupported compression: ${String(compression)}`); + } +} diff --git a/js/binary/src/index.ts b/js/binary/src/index.ts index da190f0f494..af19300fe12 100644 --- a/js/binary/src/index.ts +++ b/js/binary/src/index.ts @@ -24,5 +24,6 @@ * @module */ +export type { Compression } from "./compression.ts"; 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 index f3d641dd5bf..e1520d97172 100644 --- a/js/binary/src/snapshot/consumer.ts +++ b/js/binary/src/snapshot/consumer.ts @@ -1,14 +1,8 @@ import { Decoder as Flate } from "@moq/flate"; import * as Moq from "@moq/net"; -/** Snapshot consumer options, including the source track. */ -export interface ConsumerConfig { - /** Track to read values from. */ - track: Moq.Track.Subscriber; - - /** Whether the frames are `deflate-raw` compressed. Must match the producer. Defaults to `false`. */ - compression?: boolean; -} +import { isDeflate } from "../compression.ts"; +import type { Config as CodecConfig } from "./producer.ts"; /** * Consumes a binary value from a track, yielding the newest one. @@ -27,9 +21,9 @@ export class Consumer { // normally one frame, but the window is per group either way. #flate?: Flate; - constructor(config: ConsumerConfig) { + constructor(config: Consumer.Config) { this.#track = config.track.ordered(); - this.#decompress = config.compression ?? false; + this.#decompress = isDeflate(config.compression); } /** @@ -82,3 +76,8 @@ export class Consumer { } } } + +export namespace Consumer { + /** Snapshot consumer options, including the source track. */ + export type Config = CodecConfig & { track: Moq.Track.Subscriber }; +} diff --git a/js/binary/src/snapshot/index.ts b/js/binary/src/snapshot/index.ts index d901d721ee4..68fbf6165e4 100644 --- a/js/binary/src/snapshot/index.ts +++ b/js/binary/src/snapshot/index.ts @@ -8,11 +8,11 @@ * 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 + * consumer never needs an older one. With {@link Config.compression} `"deflate"`, 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"; +export { Consumer } from "./consumer.ts"; +export { type Config, Producer } from "./producer.ts"; diff --git a/js/binary/src/snapshot/producer.ts b/js/binary/src/snapshot/producer.ts index bebfa358ee4..1281e7f072e 100644 --- a/js/binary/src/snapshot/producer.ts +++ b/js/binary/src/snapshot/producer.ts @@ -2,19 +2,18 @@ import { DEFAULT_MAX_FRAME_SIZE, Encoder as Flate } from "@moq/flate"; import * as Moq from "@moq/net"; import { Time } from "@moq/net"; -/** Snapshot producer options, including the destination track. */ -export interface ProducerConfig { - /** Track that receives each value as its own group. */ - track: Moq.Track.Producer; +import { type Compression, isDeflate } from "../compression.ts"; +/** Codec options for a snapshot track. */ +export interface Config { /** * 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`. + * value is compressed alone. A {@link Consumer} reading the frames must set the same + * {@link compression}. Defaults to `"none"`. */ - compression?: boolean; + compression?: Compression; } /** @@ -29,9 +28,9 @@ export class Producer { #compress: boolean; /** Wrap a track to publish a binary value into it. */ - constructor(config: ProducerConfig) { + constructor(config: Producer.Config) { this.#track = config.track; - this.#compress = config.compression ?? false; + this.#compress = isDeflate(config.compression); } /** @@ -71,3 +70,10 @@ export class Producer { this.#track.close(); } } + +type Init = Config & { track: Moq.Track.Producer }; + +export namespace Producer { + /** Snapshot producer options, including the destination track. */ + export type Config = Init; +} diff --git a/js/binary/src/snapshot/snapshot.test.ts b/js/binary/src/snapshot/snapshot.test.ts index 8a7b434712e..b91e073b9a1 100644 --- a/js/binary/src/snapshot/snapshot.test.ts +++ b/js/binary/src/snapshot/snapshot.test.ts @@ -10,7 +10,7 @@ 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 consumer = new Consumer({ track, compression: compression ? "deflate" : "none" }); const out: Uint8Array[] = []; for (;;) { const value = await consumer.next(); @@ -57,7 +57,7 @@ test("a live consumer sees each update", async () => { test("compressed roundtrip", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, compression: true }); + const producer = new Producer({ track, compression: "deflate" }); const payload = new TextEncoder().encode("the quick brown fox".repeat(64)); producer.update(payload); producer.finish(); @@ -69,7 +69,7 @@ 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 producer = new Producer({ track, compression: "deflate" }); const payload = new TextEncoder().encode("the quick brown fox".repeat(64)); producer.update(payload); producer.finish(); diff --git a/js/binary/src/stream/consumer.ts b/js/binary/src/stream/consumer.ts index 530056a7744..47d9ee635d8 100644 --- a/js/binary/src/stream/consumer.ts +++ b/js/binary/src/stream/consumer.ts @@ -1,14 +1,8 @@ import { Decoder as Flate } from "@moq/flate"; import type * as Moq from "@moq/net"; -/** Stream consumer options, including the source track. */ -export interface ConsumerConfig { - /** Track to read payloads from. */ - track: Moq.Track.Subscriber; - - /** Whether the frames are `deflate-raw` compressed. Must match the producer. Defaults to `false`. */ - compression?: boolean; -} +import { isDeflate } from "../compression.ts"; +import type { Config as CodecConfig } from "./producer.ts"; /** * Thrown by a stream read when the track carried a second group, which a lossless log cannot do. @@ -55,9 +49,9 @@ export class Consumer { // The DEFLATE window for the group, present while decompressing. #flate?: Flate; - constructor(config: ConsumerConfig) { + constructor(config: Consumer.Config) { this.#track = config.track; - this.#decompress = config.compression ?? false; + this.#decompress = isDeflate(config.compression); } /** Get the next payload, or `undefined` once the track ends. */ @@ -145,3 +139,8 @@ export class Consumer { } } } + +export namespace Consumer { + /** Stream consumer options, including the source track. */ + export type Config = CodecConfig & { track: Moq.Track.Subscriber }; +} diff --git a/js/binary/src/stream/index.ts b/js/binary/src/stream/index.ts index e60a5ecaeb4..23272a845c5 100644 --- a/js/binary/src/stream/index.ts +++ b/js/binary/src/stream/index.ts @@ -14,11 +14,11 @@ * 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 + * With {@link Config.compression} `"deflate"`, 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"; +export { Consumer, Rolled } from "./consumer.ts"; +export { type Config, Producer } from "./producer.ts"; diff --git a/js/binary/src/stream/producer.ts b/js/binary/src/stream/producer.ts index be8cc37ea93..13f6768153c 100644 --- a/js/binary/src/stream/producer.ts +++ b/js/binary/src/stream/producer.ts @@ -2,17 +2,16 @@ import { DEFAULT_MAX_FRAME_SIZE, Encoder as Flate } from "@moq/flate"; import type * as Moq from "@moq/net"; import { Time } from "@moq/net"; -/** Stream producer options, including the destination track. */ -export interface ProducerConfig { - /** Track that receives the payload log. */ - track: Moq.Track.Producer; +import { type Compression, isDeflate } from "../compression.ts"; +/** Codec options for a stream track. */ +export interface Config { /** * 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`. + * earlier ones as context. A {@link Consumer} reading the frames must set the same + * {@link compression}. Defaults to `"none"`. */ - compression?: boolean; + compression?: Compression; } /** @@ -28,9 +27,9 @@ export class Producer { #group?: Moq.Group.Producer; /** Wrap a track to publish a payload log into it. */ - constructor(config: ProducerConfig) { + constructor(config: Producer.Config) { this.#track = config.track; - this.#compress = config.compression ?? false; + this.#compress = isDeflate(config.compression); this.#flate = this.#compress ? new Flate() : undefined; } @@ -90,3 +89,10 @@ export class Producer { this.#track.close(); } } + +type Init = Config & { track: Moq.Track.Producer }; + +export namespace Producer { + /** Stream producer options, including the destination track. */ + export type Config = Init; +} diff --git a/js/binary/src/stream/stream.test.ts b/js/binary/src/stream/stream.test.ts index 6480787e61d..6df02fdad4a 100644 --- a/js/binary/src/stream/stream.test.ts +++ b/js/binary/src/stream/stream.test.ts @@ -11,7 +11,7 @@ const payloads = (count: number) => Array.from({ length: count }, (_, n) => new // 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 consumer = new Consumer({ track, compression: compression ? "deflate" : "none" }); const out: Uint8Array[] = []; for (;;) { const value = await consumer.next(); @@ -33,7 +33,7 @@ test("every payload survives in order", async () => { test("compressed roundtrip in order", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, compression: true }); + const producer = new Producer({ track, compression: "deflate" }); const expected = payloads(20); for (const payload of expected) producer.append(payload); producer.finish(); @@ -43,7 +43,7 @@ test("compressed roundtrip in order", async () => { test("the whole log rides one group, never rolled", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, compression: true }); + const producer = new Producer({ track, compression: "deflate" }); for (const payload of payloads(50)) producer.append(payload); producer.finish(); @@ -54,7 +54,7 @@ test("the whole log rides one group, never rolled", async () => { test("the shared window shrinks repetitive payloads", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, compression: true }); + const producer = new Producer({ track, compression: "deflate" }); const payload = new TextEncoder().encode("the quick brown fox".repeat(16)); for (let n = 0; n < 8; n++) producer.append(payload); producer.finish(); @@ -134,10 +134,10 @@ test("an undecodable payload ends the log for a reader already inside the group" // 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 }); + const producer = new Producer({ track, compression: "deflate" }); producer.append(payloads(1)[0]); - const consumer = new Consumer({ track: track.subscribe(), compression: true }); + const consumer = new Consumer({ track: track.subscribe(), compression: "deflate" }); expect(await consumer.next()).toBeDefined(); const oversized = new Uint8Array(DEFAULT_MAX_FRAME_SIZE + 1); diff --git a/js/binary/src/types.test.ts b/js/binary/src/types.test.ts index 729b5183c48..65e7d58ddcb 100644 --- a/js/binary/src/types.test.ts +++ b/js/binary/src/types.test.ts @@ -36,6 +36,10 @@ test("object literals reject positional tracks and producer tracks on consumers" new Stream.Producer(new Track.Producer("test")); // @ts-expect-error a producer track is not a subscriber new Stream.Consumer({ track: new Track.Producer("test") }); + // @ts-expect-error compression is an enum, not a boolean + new Snapshot.Producer({ track: new Track.Producer("test"), compression: true }); + // @ts-expect-error compression is an enum, not a boolean + new Stream.Producer({ track: new Track.Producer("test"), compression: true }); }; expect(reject).toBeDefined(); }); diff --git a/js/json/README.md b/js/json/README.md index d7c6ed8f37f..82b225f821e 100644 --- a/js/json/README.md +++ b/js/json/README.md @@ -57,4 +57,4 @@ for await (const record of consumer) { } ``` -Both modes support optional group-scoped DEFLATE compression (`{ compression: true }` on both sides), interoperable with the Rust `moq-json` crate. +Both modes support optional group-scoped DEFLATE compression (`{ compression: "deflate" }` on both sides), interoperable with the Rust `moq-json` crate. `Config` is the codec options; `Producer.Config` / `Consumer.Config` add the track. diff --git a/js/json/src/compression.ts b/js/json/src/compression.ts new file mode 100644 index 00000000000..fdfbeee9059 --- /dev/null +++ b/js/json/src/compression.ts @@ -0,0 +1,15 @@ +/** How a JSON track compresses its frames. `"none"` (the default) is uncompressed JSON. */ +export type Compression = "none" | "deflate"; + +/** Whether `compression` is group-scoped DEFLATE. */ +export function isDeflate(compression?: Compression): boolean { + switch (compression) { + case undefined: + case "none": + return false; + case "deflate": + return true; + default: + throw new Error(`unsupported compression: ${String(compression)}`); + } +} diff --git a/js/json/src/index.ts b/js/json/src/index.ts index 4ed8d0d002c..c683dd1b820 100644 --- a/js/json/src/index.ts +++ b/js/json/src/index.ts @@ -21,6 +21,7 @@ * @module */ +export type { Compression } from "./compression.ts"; export { type Diff, deepEqual, diff, merge } from "./diff.ts"; export * as Snapshot from "./snapshot/index.ts"; export * as Stream from "./stream/index.ts"; diff --git a/js/json/src/snapshot/codec.test.ts b/js/json/src/snapshot/codec.test.ts index e856af71522..8367c252c25 100644 --- a/js/json/src/snapshot/codec.test.ts +++ b/js/json/src/snapshot/codec.test.ts @@ -127,14 +127,14 @@ test("compressed roundtrip", () => { { a: 1, b: 2 }, { a: 5, b: 2 }, ]; - expect(roundtrip({ compression: true }, values)).toEqual(values); + expect(roundtrip({ compression: "deflate" }, values)).toEqual(values); }); // The window is per group, so a keyframe mid-stream has to restart it on both sides. A decoder that // kept the old window here would fail to inflate the new group's snapshot. test("compressed roundtrip across a group boundary", () => { const values: Doc[] = Array.from({ length: 41 }, (_, n) => ({ n })); - const got = roundtrip({ deltaRatio: 2, compression: true }, values); + const got = roundtrip({ deltaRatio: 2, compression: "deflate" }, values); expect(got.at(-1)).toEqual({ n: 40 }); }); @@ -170,7 +170,10 @@ test("frames apply without materializing", () => { test("compressed deltas reuse the group window", () => { const phrase = "Media over QUIC delivers real-time latency at massive scale"; - const frames = encode({ deltaRatio: 100, compression: true }, [{ note: phrase }, { note: phrase, echo: phrase }]); + const frames = encode({ deltaRatio: 100, compression: "deflate" }, [ + { note: phrase }, + { note: phrase, echo: phrase }, + ]); // The raw patch repeats the whole phrase; compressed against the window it's a fraction. const raw = new TextEncoder().encode(JSON.stringify({ echo: phrase })).length; diff --git a/js/json/src/snapshot/compression.test.ts b/js/json/src/snapshot/compression.test.ts index 2053f630129..80935a07f5f 100644 --- a/js/json/src/snapshot/compression.test.ts +++ b/js/json/src/snapshot/compression.test.ts @@ -13,7 +13,7 @@ const REPLAY_LATENCY = 30_000; // Reconstruct every value a compressed consumer yields, in order. async function drainCompressed(track: Track.Subscriber): Promise { const out: Value[] = []; - for await (const value of new Consumer({ track, compression: true })) out.push(value); + for await (const value of new Consumer({ track, compression: "deflate" })) out.push(value); return out; } @@ -39,7 +39,7 @@ async function groupCount(track: Track.Ordered): Promise { test("compressed snapshot per group round-trips", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 0, compression: true }); + const producer = new Producer({ track, deltaRatio: 0, compression: "deflate" }); producer.update({ a: 1 }); producer.update({ a: 2 }); producer.finish(); @@ -52,8 +52,8 @@ test("compressed snapshot per group round-trips", async () => { test("compressed live consumer sees each update in order", async () => { // A live consumer reconstructs each update in order from the shared per-group stream. const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100, compression: true }); - const consumer = new Consumer({ track: track.subscribe(), compression: true }); + const producer = new Producer({ track, deltaRatio: 100, compression: "deflate" }); + const consumer = new Consumer({ track: track.subscribe(), compression: "deflate" }); for (let n = 1; n <= 5; n++) { producer.update({ a: n }); @@ -63,7 +63,7 @@ test("compressed live consumer sees each update in order", async () => { test("compressed deltas share one group and reconstruct", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100, compression: true }); + const producer = new Producer({ track, deltaRatio: 100, compression: "deflate" }); producer.update({ a: 1, b: 1 }); producer.update({ a: 1, b: 2 }); producer.update({ a: 5, b: 2 }); @@ -74,7 +74,7 @@ test("compressed deltas share one group and reconstruct", async () => { test("compressed late joiner reconstructs from snapshot + deltas", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100, compression: true }); + const producer = new Producer({ track, deltaRatio: 100, compression: "deflate" }); producer.update({ a: 1, b: 1 }); producer.update({ a: 1, b: 2 }); producer.update({ a: 5, b: 2 }); @@ -88,7 +88,7 @@ test("a group's snapshot decodes from a fresh decoder", async () => { // Frame 0 opens a cold window, so a brand-new decoder reconstructs it, which is what lets a late // joiner (or the Rust consumer) start mid-stream at any group boundary. const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 0, compression: true }); + const producer = new Producer({ track, deltaRatio: 0, compression: "deflate" }); producer.update({ hello: "world" }); producer.finish(); @@ -101,7 +101,7 @@ test("a group's snapshot decodes from a fresh decoder", async () => { test("compressed deltas reuse the window", async () => { // The shared per-group window is the point: a delta restating snapshot content shrinks sharply. const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100, compression: true }); + const producer = new Producer({ track, deltaRatio: 100, compression: "deflate" }); const phrase = "Media over QUIC delivers real-time latency at massive scale"; producer.update({ note: phrase }); producer.update({ note: phrase, echo: phrase }); @@ -123,7 +123,7 @@ test("compression shrinks a repetitive frame", async () => { const plain = new Track.Producer("plain"); new Producer({ track: plain, deltaRatio: 0 }).update(value); const compressed = new Track.Producer("compressed"); - new Producer({ track: compressed, deltaRatio: 0, compression: true }).update(value); + new Producer({ track: compressed, deltaRatio: 0, compression: "deflate" }).update(value); const plainLen = (await firstFrame(plain.subscribe().ordered())).length; const compressedLen = (await firstFrame(compressed.subscribe().ordered())).length; @@ -137,7 +137,7 @@ test("compressed deltas roll on the compressed budget", async () => { // compressed group boundary. Guards against the budget regressing to raw lengths. Two identical // producers (deterministic output) keep the group-count and reconstruction reads independent. const fill = (track: Track.Producer) => { - const producer = new Producer({ track, deltaRatio: 2, compression: true }); + const producer = new Producer({ track, deltaRatio: 2, compression: "deflate" }); for (let n = 0; n <= 40; n++) producer.update({ n }); producer.finish(); }; diff --git a/js/json/src/snapshot/consumer.ts b/js/json/src/snapshot/consumer.ts index 4f4456c0e9b..142b4ccd213 100644 --- a/js/json/src/snapshot/consumer.ts +++ b/js/json/src/snapshot/consumer.ts @@ -1,9 +1,7 @@ import type * as Moq from "@moq/net"; -import { type ConsumerConfig as CodecConfig, Decoder } from "./decoder.ts"; - -/** Snapshot consumer options, including the source track. */ -export type ConsumerConfig = CodecConfig & { track: Moq.Track.Subscriber }; +import { Decoder } from "./decoder.ts"; +import type { Config as CodecConfig } from "./encoder.ts"; /** * Consumes a JSON value from a track, reconstructing it from snapshots and deltas. @@ -21,7 +19,7 @@ export class Consumer { #group?: Moq.Group.Consumer; #framesRead = 0; - constructor(config: ConsumerConfig) { + constructor(config: Consumer.Config) { this.#track = config.track.ordered(); this.#decoder = new Decoder(config); } @@ -110,3 +108,10 @@ export class Consumer { this.#framesRead += 1; } } + +export namespace Consumer { + /** Snapshot consumer options, including the source track. */ + export type Config = Pick, "schema" | "compression"> & { + track: Moq.Track.Subscriber; + }; +} diff --git a/js/json/src/snapshot/decoder.ts b/js/json/src/snapshot/decoder.ts index 4c8109f1d2b..971ae2832fc 100644 --- a/js/json/src/snapshot/decoder.ts +++ b/js/json/src/snapshot/decoder.ts @@ -1,11 +1,9 @@ import { Decoder as Flate } from "@moq/flate"; +import { isDeflate } from "../compression.ts"; import { merge } from "../diff.ts"; import type { Config } from "./encoder.ts"; -/** Options for a {@link Decoder}: the knobs it actually reads. */ -export type ConsumerConfig = Pick, "schema" | "compression">; - /** * Reconstructs a JSON value from the snapshot and delta frames of a group. * @@ -19,7 +17,7 @@ export type ConsumerConfig = Pick, "schema" | "compression">; * that wants a value per frame just calls it every time. */ export class Decoder { - #schema?: ConsumerConfig["schema"]; + #schema?: Config["schema"]; // Whether frames are `deflate-raw` compressed. Must match the encoder's {@link Config.compression}. #decompress: boolean; @@ -28,9 +26,9 @@ export class Decoder { // The reconstructed value, `undefined` until the first snapshot. #current?: unknown; - constructor(config: ConsumerConfig = {}) { + constructor(config: Pick, "schema" | "compression"> = {}) { this.#schema = config.schema; - this.#decompress = config.compression ?? false; + this.#decompress = isDeflate(config.compression); } /** diff --git a/js/json/src/snapshot/encoder.ts b/js/json/src/snapshot/encoder.ts index 1373f0ee9b7..67ce5047b14 100644 --- a/js/json/src/snapshot/encoder.ts +++ b/js/json/src/snapshot/encoder.ts @@ -2,6 +2,7 @@ import { DEFAULT_MAX_FRAME_SIZE, Encoder as Flate } from "@moq/flate"; import { Group } from "@moq/net"; import type * as z from "@zod/mini"; +import { type Compression, isDeflate } from "../compression.ts"; import { deepEqual, diff } from "../diff.ts"; // Maximum frames (snapshot + deltas) in a single group before a new snapshot is forced. Kept @@ -38,9 +39,9 @@ export interface Config { // Compress each group as one sync-flushed `deflate-raw` (RFC 1951) stream, so deltas reuse the // snapshot as context and shrink sharply. Interoperable with the Rust `moq-json` producer. - // `false`/unset (the default) writes plaintext JSON frames. A {@link Decoder} reading them - // must set the same flag. - compression?: boolean; + // `"none"`/unset (the default) writes plaintext JSON frames. A {@link Decoder} reading them + // must set the same {@link compression}. + compression?: Compression; } /** One encoded frame, and the group boundary it implies. */ @@ -138,7 +139,7 @@ export class Encoder { constructor(config: Config = {}) { this.#config = config; - this.#compress = config.compression ?? false; + this.#compress = isDeflate(config.compression); } /** diff --git a/js/json/src/snapshot/index.ts b/js/json/src/snapshot/index.ts index 5efed741abd..8208ff4bb3f 100644 --- a/js/json/src/snapshot/index.ts +++ b/js/json/src/snapshot/index.ts @@ -17,7 +17,8 @@ * with a full snapshot, so the deltas already written stop being provisional without publishing an * empty group. * - * {@link Producer} and {@link Consumer} own a track: pass `{ track, ... }` and they manage the groups + * {@link Producer} and {@link Consumer} own a track: pass a {@link Producer.Config} / + * {@link Consumer.Config} (`{ track, ... }`) and they manage the groups * for you. {@link Encoder} and {@link Decoder} are the same logic without the track. The encoder turns * values into {@link Encoded} frame payloads and says where the group boundaries fall; the decoder * reconstructs a value from those payloads. Reach for them when something else is already in charge @@ -31,7 +32,7 @@ * @module */ -export { Consumer, type ConsumerConfig } from "./consumer.ts"; +export { Consumer } from "./consumer.ts"; export { Decoder } from "./decoder.ts"; export { type Config, type Encoded, Encoder, type Pending } from "./encoder.ts"; -export { Producer, type ProducerConfig } from "./producer.ts"; +export { Producer } from "./producer.ts"; diff --git a/js/json/src/snapshot/producer.ts b/js/json/src/snapshot/producer.ts index dd8f14676b9..b53590e877f 100644 --- a/js/json/src/snapshot/producer.ts +++ b/js/json/src/snapshot/producer.ts @@ -1,10 +1,7 @@ import * as Moq from "@moq/net"; import { Time } from "@moq/net"; -import { type Config, DEFAULT_DELTA_RATIO, type Encoded, Encoder } from "./encoder.ts"; - -/** Snapshot producer options, including the destination track. */ -export type ProducerConfig = Config & { track: Moq.Track.Producer }; +import { type Config as CodecConfig, DEFAULT_DELTA_RATIO, type Encoded, Encoder } from "./encoder.ts"; /** * Publishes a JSON value over a track, choosing snapshots and deltas automatically. @@ -24,7 +21,7 @@ export class Producer { // is closed the moment it's written and never held open. #deltas: boolean; - constructor(config: ProducerConfig) { + constructor(config: Producer.Config) { this.#track = config.track; this.#encoder = new Encoder(config); this.#initial = config.initial; @@ -153,3 +150,8 @@ export class Producer { this.#track.close(); } } + +export namespace Producer { + /** Snapshot producer options, including the destination track. */ + export type Config = CodecConfig & { track: Moq.Track.Producer }; +} diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 0b8a1c44311..3e2d64836f7 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -362,7 +362,7 @@ test("a compressed delta is gated on its encoded size, not its plaintext", async // 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 }); + const producer = new Producer({ track, compression: "deflate" }); // Highly repetitive, so the compressed snapshot lands just under the cap. producer.update({ v: "x".repeat(Group.MAX_GROUP_CACHE_BYTES) }); @@ -385,7 +385,7 @@ test("a compressed delta is gated on its encoded size, not its plaintext", async const consumer = new Consumer({ track: track.subscribe({ maxAge: REPLAY_LATENCY }), - compression: true, + compression: "deflate", }); const values: Value[] = []; for await (const value of consumer) values.push(value); diff --git a/js/json/src/stream/codec.test.ts b/js/json/src/stream/codec.test.ts index 009ca9d530a..f3539e0d3ee 100644 --- a/js/json/src/stream/codec.test.ts +++ b/js/json/src/stream/codec.test.ts @@ -7,8 +7,9 @@ import { Producer } from "./producer.ts"; type Rec = { n: number }; function roundtrip(compression: boolean, values: Rec[]): Rec[] { - const encoder = new Encoder({ compression }); - const decoder = new Decoder({ compression }); + const config = { compression: compression ? ("deflate" as const) : ("none" as const) }; + const encoder = new Encoder(config); + const decoder = new Decoder(config); return values.map((value) => { const record = encoder.encode(value); const decoded = decoder.decode(record.payload); @@ -28,7 +29,7 @@ test("compressed roundtrip in order", () => { }); test("the shared window shrinks repetitive records", () => { - const encoder = new Encoder<{ group: number; pts: number }>({ compression: true }); + const encoder = new Encoder<{ group: number; pts: number }>({ compression: "deflate" }); const sizes = Array.from({ length: 8 }, (_, n) => { const record = encoder.encode({ group: n, pts: n * 2_000 }); record.commit(); @@ -42,8 +43,8 @@ test("the shared window shrinks repetitive records", () => { // A caller that rolls a group has to restart both windows, or the new group's frames decode against // context the decoder on the other side never received. test("reset starts a cold window on both sides", () => { - const encoder = new Encoder({ compression: true }); - const decoder = new Decoder({ compression: true }); + const encoder = new Encoder({ compression: "deflate" }); + const decoder = new Decoder({ compression: "deflate" }); for (let n = 0; n < 4; n += 1) { const record = encoder.encode({ n }); @@ -63,7 +64,7 @@ test("reset starts a cold window on both sides", () => { // has no keyframe to resynchronize on. Continuing would emit frames nothing can decode, so the // encoder refuses until the caller rolls a new group and resets. test("an uncommitted compressed record stops the encoder", () => { - const encoder = new Encoder({ compression: true }); + const encoder = new Encoder({ compression: "deflate" }); encoder.encode({ n: 0 }).commit(); // This one fails to write, so the caller never commits it. @@ -74,7 +75,7 @@ test("an uncommitted compressed record stops the encoder", () => { // Rolling a new group gives the consumer a cold window too, so the reset clears it. encoder.reset(); const record = encoder.encode({ n: 2 }); - const decoder = new Decoder({ compression: true }); + const decoder = new Decoder({ compression: "deflate" }); expect(decoder.decode(record.payload)).toEqual({ n: 2 }); record.commit(); }); @@ -119,7 +120,7 @@ test("a rejected record ends the track without opening a group", async () => { // The same stale-commit hazard the snapshot encoder has: acknowledging a superseded record must not // clear the flag belonging to the newer one, or a desync goes undetected. test("a stale commit does not clear a newer pending record", () => { - const encoder = new Encoder({ compression: true }); + const encoder = new Encoder({ compression: "deflate" }); const first = encoder.encode({ n: 0 }); first.commit(); @@ -134,7 +135,7 @@ test("a stale commit does not clear a newer pending record", () => { // A record committed after the encoder has been reset must not acknowledge whatever is outstanding // now: the newer record belongs to a different group and window. test("a commit from before a reset does not acknowledge a newer record", () => { - const encoder = new Encoder({ compression: true }); + const encoder = new Encoder({ compression: "deflate" }); const stale = encoder.encode({ n: 0 }); // The caller rolled a new group and reset, then encoded into it. @@ -153,7 +154,7 @@ test("a commit from before a reset does not acknowledge a newer record", () => { // `a_rejected_record_leaves_the_encoder_able_to_retry`.) test("a rejected record leaves the producer able to retry", () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, compression: true }); + const producer = new Producer({ track, compression: "deflate" }); // Closing the track makes every write fail, standing in for any post-appendGroup rejection. track.close(); diff --git a/js/json/src/stream/consumer.ts b/js/json/src/stream/consumer.ts index 298d80ff967..d18edd26875 100644 --- a/js/json/src/stream/consumer.ts +++ b/js/json/src/stream/consumer.ts @@ -1,9 +1,6 @@ import type * as Moq from "@moq/net"; - -import { type ConsumerConfig as CodecConfig, Decoder } from "./decoder.ts"; - -/** Stream consumer options, including the source track. */ -export type ConsumerConfig = CodecConfig & { track: Moq.Track.Subscriber }; +import { Decoder } from "./decoder.ts"; +import type { Config as CodecConfig } from "./encoder.ts"; /** * Thrown by a stream read when the track carried a second group, which a lossless log cannot do. @@ -50,7 +47,7 @@ export class Consumer { // carries is taken, so a second group stays resolved here and every later read fails on it again. #pending?: Promise<{ group: Moq.Group.Consumer | undefined }>; - constructor(config: ConsumerConfig) { + constructor(config: Consumer.Config) { this.#track = config.track; this.#decoder = new Decoder(config); } @@ -140,3 +137,8 @@ export class Consumer { } } } + +export namespace Consumer { + /** Stream consumer options, including the source track. */ + export type Config = CodecConfig & { track: Moq.Track.Subscriber }; +} diff --git a/js/json/src/stream/decoder.ts b/js/json/src/stream/decoder.ts index 7c95fe18d6a..e7ca4cc72bd 100644 --- a/js/json/src/stream/decoder.ts +++ b/js/json/src/stream/decoder.ts @@ -1,10 +1,7 @@ import { Decoder as Flate } from "@moq/flate"; -/** Options for a {@link Decoder}. */ -export interface ConsumerConfig { - /** Whether the frames are `deflate-raw` compressed. Must match the encoder. Defaults to `false`. */ - compression?: boolean; -} +import { isDeflate } from "../compression.ts"; +import type { Config } from "./encoder.ts"; /** * Decodes JSON records from frame payloads, sharing one DEFLATE window across the log. @@ -18,8 +15,8 @@ export class Decoder { // The DEFLATE window for the whole log, present while decompressing. #flate?: Flate; - constructor(config: ConsumerConfig = {}) { - this.#decompress = config.compression ?? false; + constructor(config: Config = {}) { + this.#decompress = isDeflate(config.compression); this.#flate = this.#decompress ? new Flate() : undefined; } diff --git a/js/json/src/stream/encoder.ts b/js/json/src/stream/encoder.ts index c5e7fbaa667..b71f0cee7ca 100644 --- a/js/json/src/stream/encoder.ts +++ b/js/json/src/stream/encoder.ts @@ -1,13 +1,15 @@ import { DEFAULT_MAX_FRAME_SIZE, Encoder as Flate } from "@moq/flate"; +import { type Compression, isDeflate } from "../compression.ts"; + /** Options for an {@link Encoder}. */ export interface Config { /** * Compress the group as one sync-flushed `deflate-raw` stream, so each record reuses the earlier * ones as context and shrinks sharply. A {@link Decoder} reading the frames must set the same - * flag. Defaults to `false`. + * {@link compression}. Defaults to `"none"`. */ - compression?: boolean; + compression?: Compression; } /** @@ -60,7 +62,7 @@ export class Encoder { #generation = 0; constructor(config: Config = {}) { - this.#compress = config.compression ?? false; + this.#compress = isDeflate(config.compression); this.#flate = this.#compress ? new Flate() : undefined; } diff --git a/js/json/src/stream/index.ts b/js/json/src/stream/index.ts index 12d411ad826..1a2f8a00615 100644 --- a/js/json/src/stream/index.ts +++ b/js/json/src/stream/index.ts @@ -4,8 +4,8 @@ * records that preserves everything; every {@link Producer.append} writes one JSON object as one * frame, nothing is ever superseded, and a {@link Consumer} yields every record in order. * - * The whole log rides a **single group** that is never rolled: with {@link ProducerConfig.compression} - * on, that one group is one DEFLATE window, so every record compresses against the earlier ones. + * The whole log rides a **single group** that is never rolled: with {@link Config.compression} + * `"deflate"`, that one group is one DEFLATE window, so every record compresses against the earlier ones. * There is deliberately no group rolling (and so no catch-up machinery); a caller that wants to * bound the record rate throttles at the source. Interoperable on the wire with the Rust * `moq_json::stream`. @@ -18,7 +18,7 @@ * @module */ -export { Consumer, type ConsumerConfig, Rolled } from "./consumer.ts"; +export { Consumer, Rolled } from "./consumer.ts"; export { Decoder } from "./decoder.ts"; export { type Config, Encoder, type Pending } from "./encoder.ts"; -export { Producer, type ProducerConfig } from "./producer.ts"; +export { Producer } from "./producer.ts"; diff --git a/js/json/src/stream/producer.ts b/js/json/src/stream/producer.ts index 622df2cfdf5..30a6c7d65ce 100644 --- a/js/json/src/stream/producer.ts +++ b/js/json/src/stream/producer.ts @@ -1,10 +1,7 @@ import type * as Moq from "@moq/net"; import { Time } from "@moq/net"; -import { type Config, Encoder, type Pending } from "./encoder.ts"; - -/** Stream producer options, including the destination track. */ -export type ProducerConfig = Config & { track: Moq.Track.Producer }; +import { type Config as CodecConfig, Encoder, type Pending } from "./encoder.ts"; /** * Publishes an ordered log of JSON records to a track, one record per frame in a single group. @@ -20,7 +17,7 @@ export class Producer { #group?: Moq.Group.Producer; /** Wrap a track to publish a record log into it. */ - constructor(config: ProducerConfig) { + constructor(config: Producer.Config) { this.#track = config.track; this.#encoder = new Encoder(config); } @@ -92,3 +89,8 @@ export class Producer { this.#track.close(); } } + +export namespace Producer { + /** Stream producer options, including the destination track. */ + export type Config = CodecConfig & { track: Moq.Track.Producer }; +} diff --git a/js/json/src/stream/stream.test.ts b/js/json/src/stream/stream.test.ts index 0d6bf7a6c0e..c48bf5820d5 100644 --- a/js/json/src/stream/stream.test.ts +++ b/js/json/src/stream/stream.test.ts @@ -6,7 +6,7 @@ type Rec = { n: number }; // Drain every record 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 consumer = new Consumer({ track, compression: compression ? "deflate" : "none" }); const out: number[] = []; for (;;) { const record = await consumer.next(); @@ -27,7 +27,7 @@ test("plaintext roundtrip in order", async () => { test("compressed roundtrip in order", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, compression: true }); + const producer = new Producer({ track, compression: "deflate" }); for (let n = 0; n < 20; n++) producer.append({ n }); producer.finish(); @@ -36,7 +36,7 @@ test("compressed roundtrip in order", async () => { test("the whole log rides one group, never rolled", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, compression: true }); + const producer = new Producer({ track, compression: "deflate" }); for (let n = 0; n < 50; n++) producer.append({ n }); producer.finish(); @@ -52,12 +52,12 @@ test("records with embedded newlines round-trip (JSON escapes the newline)", asy // Each record is its own frame (one JSON object), and JSON.stringify escapes control characters, // so a string value containing a newline round-trips cleanly. const track = new Track.Producer("test"); - const producer = new Producer<{ s: string }>({ track, compression: true }); + const producer = new Producer<{ s: string }>({ track, compression: "deflate" }); const value = { s: "line1\nline2\ttab" }; for (let i = 0; i < 4; i++) producer.append(value); producer.finish(); - const consumer = new Consumer<{ s: string }>({ track: track.subscribe(), compression: true }); + const consumer = new Consumer<{ s: string }>({ track: track.subscribe(), compression: "deflate" }); const out: { s: string }[] = []; for (;;) { const record = await consumer.next(); diff --git a/js/json/src/types.test.ts b/js/json/src/types.test.ts index 74d0330eac9..93bd1a016db 100644 --- a/js/json/src/types.test.ts +++ b/js/json/src/types.test.ts @@ -73,6 +73,10 @@ test("object literals reject producer knobs and positional tracks", () => { new Stream.Encoder({ track: new Track.Producer("test") }); // @ts-expect-error Decoder does not take a track new Window.Decoder({ track }); + // @ts-expect-error compression is an enum, not a boolean + new Snapshot.Producer({ track: new Track.Producer("test"), compression: true }); + // @ts-expect-error compression is an enum, not a boolean + new Stream.Producer({ track: new Track.Producer("test"), compression: true }); }; expect(reject).toBeDefined(); }); diff --git a/js/publish/src/catalog.ts b/js/publish/src/catalog.ts index 99411674e3e..64b02a864c9 100644 --- a/js/publish/src/catalog.ts +++ b/js/publish/src/catalog.ts @@ -42,7 +42,7 @@ export class CatalogProducer { serve(track: Moq.Track.Producer, effect: Effect, opts?: { compression?: boolean }): void { const output = new Json.Snapshot.Producer({ track, - compression: opts?.compression, + compression: opts?.compression ? "deflate" : "none", deltaRatio: 0, }); output.update(this.#value); diff --git a/js/watch/src/broadcast.ts b/js/watch/src/broadcast.ts index 892eada2e80..2aeeca0b2ca 100644 --- a/js/watch/src/broadcast.ts +++ b/js/watch/src/broadcast.ts @@ -311,7 +311,7 @@ export class Broadcast { const consumer = new Json.Snapshot.Consumer({ track, schema: Catalog.RootSchema, - compression: format === "hangz", + compression: format === "hangz" ? "deflate" : "none", }); fetchNext = () => consumer.next(); } else { diff --git a/quest/m1/README.md b/quest/m1/README.md index 599a2afb3d8..277bc5ad18b 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -32,7 +32,6 @@ does not require it. - [Rate estimate names](/quest/m1/api-rate-estimate-names.md) - the send and receive estimates carry `estimated_*_rate` on the C ABI, every binding, and moqsink - [Announce names](/quest/m1/api-announce-names.md) - one name per announce, request, and origin config concept in Rust, JS, moq-ffi, and C - [moq-tokio names](/quest/m1/api-tokio-names.md) - moq-tokio's public names sit under their modules with no root compounds, adapter names, or forgettable close() -- [JSON config names](/quest/m1/api-json-binary-config-names.md) - `Config` means the codec options and `producer::Config` / `consumer::Config` the track pair in all four json and binary packages - [Anonymous rank](/quest/m1/anonymous-route-rank.md) - moq-net: a route through an anonymous hop ranks below every identified route at any cost, and hop 0 travels the chain to say so - [Cluster -01](/quest/m1/cluster-01/README.md) - rs/moq-net and js/net speak the revised cluster extension (HOP_ID, REQUEST_UPDATE repricing) and -01 is published - [Track demand](/quest/m1/libmoq-track-demand.md) - a C publisher sees used/unused per track and serves dynamic track and group requests, so an encoder runs only while someone watches diff --git a/quest/m1/api-json-binary-config-names.md b/quest/m1/api-json-binary-config-names.md deleted file mode 100644 index 0dc1c73995b..00000000000 --- a/quest/m1/api-json-binary-config-names.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] json and binary config names agree across languages - -## Goal - -`Config` means the same thing in `@moq/json`, `moq-json`, `@moq/binary`, and -`moq-binary`. Today `@moq/json` uses `Config` for the codec options and -`ProducerConfig` / `ConsumerConfig` for the track-owning options, while -`moq_json::stream::ProducerConfig` still means the codec options, and -`ConsumerConfig` is declared twice with different shapes inside one JS -module (`js/json/src/stream/{decoder,consumer}.ts`, same for `snapshot`). -`moq-binary` carries the `ProducerConfig` compound and a -`with_compression(bool)` builder that the producer and consumer sides must -keep in sync by hand. - -## Plan - -Codec options are `Config` on both sides; the track-owning pair is -`producer::Config` / `consumer::Config` under public submodules in Rust -(`rs/moq-json/src/{snapshot,stream}`, `rs/moq-binary/src/{snapshot,stream}`) -and `Producer.Config` / `Consumer.Config` in JS, one declaration each. -Replace `with_compression(bool)` with a `compression: Compression` field -whose enum both sides share, so a mismatch is unrepresentable. Update -`doc/lib` for the four packages. - -Public API: breaking on moq-json, @moq/json, moq-binary, and @moq/binary, -so on dev. Wire: none. - -## Related - -- [Merge dev](/quest/m1/merge-dev.md) - requires this so the published JSON packages do not carry two meanings of Config -- [JSON mutate](/quest/m2/json-mutate.md) - the additive twin of the same producer diff --git a/quest/m1/merge-dev.md b/quest/m1/merge-dev.md index 898d8290365..96f04ee9121 100644 --- a/quest/m1/merge-dev.md +++ b/quest/m1/merge-dev.md @@ -51,7 +51,6 @@ additive quest that builds on dev-only code start on main afterwards from - [Rate estimate names](/quest/m1/api-rate-estimate-names.md) - the estimates carry one name on the C ABI and every binding - [Announce names](/quest/m1/api-announce-names.md) - the announce and request surface releases under one name per concept - [moq-tokio names](/quest/m1/api-tokio-names.md) - moq-tokio's first release under this name has settled names -- [JSON config names](/quest/m1/api-json-binary-config-names.md) - the json and binary packages agree on Config - [Origin scope API](/quest/m1/api-origin-pattern-scopes.md) - typed scope grants preserve current prefixes and refuse unsupported patterns - [Cluster peer API](/quest/m1/api-cluster-peer-config.md) - typed peer configuration supports current symmetric policy - [Broadcast clock](/quest/m1/broadcast-clock.md) - the root clock replaces the published archive wall field on dev before release diff --git a/rs/libmoq/src/api.rs b/rs/libmoq/src/api.rs index 5d08f064fdb..b7e54812796 100644 --- a/rs/libmoq/src/api.rs +++ b/rs/libmoq/src/api.rs @@ -2301,9 +2301,13 @@ pub unsafe extern "C" fn moq_publish_json_snapshot( let broadcast = ffi::parse_id(broadcast)?; let name = unsafe { ffi::parse_str(name, name_len)? }; let config = unsafe { config.as_ref() }.ok_or(Error::InvalidPointer)?; - let mut producer = moq_json::snapshot::ProducerConfig::default(); + let mut producer = moq_json::snapshot::Config::default(); producer.delta_ratio = config.delta_ratio; - producer.compression = config.compression; + producer.compression = if config.compression { + moq_json::Compression::Deflate + } else { + moq_json::Compression::None + }; State::lock().publish.json_snapshot(broadcast, name, producer) }) } @@ -2355,7 +2359,10 @@ pub unsafe extern "C" fn moq_publish_json_stream( let broadcast = ffi::parse_id(broadcast)?; let name = unsafe { ffi::parse_str(name, name_len)? }; let config = unsafe { config.as_ref() }.ok_or(Error::InvalidPointer)?; - let producer = moq_json::stream::ProducerConfig::default().with_compression(config.compression); + let mut producer = moq_json::stream::Config::default(); + if config.compression { + producer.compression = moq_json::Compression::Deflate; + } State::lock().publish.json_stream(broadcast, name, producer) }) } @@ -2921,8 +2928,12 @@ pub unsafe extern "C" fn moq_consume_json_snapshot( let broadcast = ffi::parse_id(broadcast)?; let name = unsafe { ffi::parse_str(name, name_len)? }; let config = unsafe { config.as_ref() }.ok_or(Error::InvalidPointer)?; - let mut consumer = moq_json::snapshot::ConsumerConfig::default(); - consumer.compression = config.compression; + let mut consumer = moq_json::snapshot::consumer::Config::default(); + consumer.compression = if config.compression { + moq_json::Compression::Deflate + } else { + moq_json::Compression::None + }; let on_value = unsafe { ffi::OnStatus::new(user_data, on_value) }; State::lock().consume.json_snapshot(broadcast, name, consumer, on_value) }) @@ -2952,7 +2963,10 @@ pub unsafe extern "C" fn moq_consume_json_stream( let broadcast = ffi::parse_id(broadcast)?; let name = unsafe { ffi::parse_str(name, name_len)? }; let config = unsafe { config.as_ref() }.ok_or(Error::InvalidPointer)?; - let consumer = moq_json::stream::ConsumerConfig::default().with_compression(config.compression); + let mut consumer = moq_json::stream::Config::default(); + if config.compression { + consumer.compression = moq_json::Compression::Deflate; + } let on_value = unsafe { ffi::OnStatus::new(user_data, on_value) }; State::lock().consume.json_stream(broadcast, name, consumer, on_value) }) diff --git a/rs/libmoq/src/consume.rs b/rs/libmoq/src/consume.rs index f46494cc3c6..6dd890588a4 100644 --- a/rs/libmoq/src/consume.rs +++ b/rs/libmoq/src/consume.rs @@ -896,7 +896,7 @@ impl Consume { &mut self, broadcast: Id, name: &str, - config: moq_json::snapshot::ConsumerConfig, + config: moq_json::snapshot::consumer::Config, on_value: OnStatus, ) -> Result { let broadcast = self @@ -965,7 +965,7 @@ impl Consume { &mut self, broadcast: Id, name: &str, - config: moq_json::stream::ConsumerConfig, + config: moq_json::stream::Config, on_value: OnStatus, ) -> Result { let broadcast = self diff --git a/rs/libmoq/src/publish.rs b/rs/libmoq/src/publish.rs index 0315e6a74ed..857735f1f03 100644 --- a/rs/libmoq/src/publish.rs +++ b/rs/libmoq/src/publish.rs @@ -407,7 +407,7 @@ impl Publish { &mut self, broadcast: Id, name: &str, - config: moq_json::snapshot::ProducerConfig, + config: moq_json::snapshot::Config, ) -> Result { let broadcast = self.producer(broadcast)?; let track = broadcast.create_track(name, None)?; @@ -432,12 +432,7 @@ impl Publish { /// Create a JSON stream track (lossless append-log) on a broadcast. /// /// Every record appended via [`Self::json_stream_append`] is preserved and delivered in order. - pub fn json_stream( - &mut self, - broadcast: Id, - name: &str, - config: moq_json::stream::ProducerConfig, - ) -> Result { + pub fn json_stream(&mut self, broadcast: Id, name: &str, config: moq_json::stream::Config) -> Result { let broadcast = self.producer(broadcast)?; let track = broadcast.create_track(name, None)?; let producer = moq_json::stream::Producer::new(track, config); diff --git a/rs/moq-binary/src/lib.rs b/rs/moq-binary/src/lib.rs index 570448dab0f..27c94d503f2 100644 --- a/rs/moq-binary/src/lib.rs +++ b/rs/moq-binary/src/lib.rs @@ -27,6 +27,24 @@ pub mod snapshot; pub mod stream; +/// How a binary track compresses its frames. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub enum Compression { + /// Uncompressed payloads. + #[default] + None, + + /// Group-scoped raw DEFLATE, sync-flushed at each frame boundary. + Deflate, +} + +impl Compression { + /// Whether frames are DEFLATE-compressed. + pub const fn is_deflate(self) -> bool { + matches!(self, Self::Deflate) + } +} + /// Errors produced while publishing or consuming binary payloads. #[derive(thiserror::Error, Debug, Clone)] #[non_exhaustive] diff --git a/rs/moq-binary/src/snapshot/consumer.rs b/rs/moq-binary/src/snapshot/consumer.rs index 7e0e99a2ff7..79af98faef7 100644 --- a/rs/moq-binary/src/snapshot/consumer.rs +++ b/rs/moq-binary/src/snapshot/consumer.rs @@ -6,25 +6,7 @@ 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 - } -} +pub use super::Config; /// Consumes a binary value from a track, yielding the newest one. /// @@ -42,14 +24,13 @@ pub struct Consumer { 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 { + /// Set [`Config::compression`] to match the producer that wrote the track. + pub fn new(track: moq_net::track::Subscriber, config: Config) -> Self { Self { track: track.ordered(), group: None, flate: None, - compression: config.compression, + compression: config.compression.is_deflate(), } } diff --git a/rs/moq-binary/src/snapshot/mod.rs b/rs/moq-binary/src/snapshot/mod.rs index f9f172b5df7..d3d07d254b3 100644 --- a/rs/moq-binary/src/snapshot/mod.rs +++ b/rs/moq-binary/src/snapshot/mod.rs @@ -7,14 +7,32 @@ //! 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}; +//! consumer never needs an older one. With [`Config::compression`] set to +//! [`Compression::Deflate`], that frame is its own raw DEFLATE stream; +//! there is no window to share across a single-frame group. + +use crate::Compression; + +pub mod consumer; +pub mod producer; + +pub use consumer::Consumer; +pub use producer::Producer; + +/// Codec options for a snapshot track. +/// +/// Build from [`Default`] and override fields (the struct is `#[non_exhaustive]`, so new options +/// stay additive). +#[derive(Debug, Clone, Default)] +#[non_exhaustive] +pub struct Config { + /// 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. [`Compression::None`] (the default) writes the bytes through + /// untouched. A [`Consumer`] must set the same [`compression`](Self::compression). + pub compression: Compression, +} #[cfg(test)] mod test { @@ -24,20 +42,27 @@ mod test { use super::*; + fn cfg(compression: bool) -> Config { + Config { + compression: if compression { + Compression::Deflate + } else { + Compression::None + }, + } + } + 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, - ) + (Producer::new(track, cfg(compression)), consumer) } - fn consumer(track: moq_net::track::Subscriber, compression: bool) -> Consumer { - Consumer::new(track, ConsumerConfig::default().with_compression(compression)) + fn consume(track: moq_net::track::Subscriber, compression: bool) -> Consumer { + Consumer::new(track, cfg(compression)) } /// Drain every value currently available without blocking. @@ -59,13 +84,13 @@ mod test { // 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")]); + assert_eq!(drain(consume(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 mut consumer = consume(track, false); let waiter = kio::Waiter::noop(); for n in 0..3u8 { @@ -84,7 +109,7 @@ mod test { producer.update(payload.clone()).unwrap(); producer.finish().unwrap(); - assert_eq!(drain(consumer(track, true)), vec![payload]); + assert_eq!(drain(consume(track, true)), vec![payload]); } /// The compressed frame on the wire is much smaller than the value it carries, so a consumer @@ -125,7 +150,7 @@ mod test { 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")]); + assert_eq!(drain(consume(track, false)), vec![Bytes::from_static(b"keep")]); } /// `finish` closes the underlying track, so a later update fails rather than being silently @@ -148,7 +173,7 @@ mod test { producer.update(&b"only"[..]).unwrap(); producer.finish().unwrap(); - let mut consumer = consumer(track, false); + let mut consumer = consume(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 index 58518402cf9..1ba32935b61 100644 --- a/rs/moq-binary/src/snapshot/producer.rs +++ b/rs/moq-binary/src/snapshot/producer.rs @@ -6,29 +6,7 @@ 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 - } -} +pub use super::Config; /// Publishes a binary value over a track, one value per group. /// @@ -44,11 +22,11 @@ pub struct Producer { impl Producer { /// Create a producer that publishes to the given track. - pub fn new(track: moq_net::track::Producer, config: ProducerConfig) -> Self { + pub fn new(track: moq_net::track::Producer, config: Config) -> Self { Self { inner: Arc::new(Mutex::new(Inner { track, - compression: config.compression, + compression: config.compression.is_deflate(), })), } } diff --git a/rs/moq-binary/src/stream/consumer.rs b/rs/moq-binary/src/stream/consumer.rs index 4e56f1eb62f..049123b9079 100644 --- a/rs/moq-binary/src/stream/consumer.rs +++ b/rs/moq-binary/src/stream/consumer.rs @@ -6,25 +6,7 @@ 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 - } -} +pub use super::Config; /// Consumes an ordered log of binary payloads from a track, yielding every one. /// @@ -53,16 +35,15 @@ pub struct Consumer { 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 { + /// Set [`Config::compression`] to match the producer that wrote the track. + pub fn new(track: moq_net::track::Subscriber, config: Config) -> Self { Self { track, group: None, taken: false, rolled: false, flate: None, - compression: config.compression, + compression: config.compression.is_deflate(), } } diff --git a/rs/moq-binary/src/stream/mod.rs b/rs/moq-binary/src/stream/mod.rs index 389ab3135d9..79f5d151b79 100644 --- a/rs/moq-binary/src/stream/mod.rs +++ b/rs/moq-binary/src/stream/mod.rs @@ -13,14 +13,32 @@ //! 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 +//! [`Config::compression`] set to [`Compression::Deflate`], 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}; +use crate::Compression; + +pub mod consumer; +pub mod producer; + +pub use consumer::Consumer; +pub use producer::Producer; + +/// Codec options for a stream track. +/// +/// Build from [`Default`] and override fields (the struct is `#[non_exhaustive]`, so new options +/// stay additive). +#[derive(Debug, Clone, Default)] +#[non_exhaustive] +pub struct Config { + /// Compress the group as one sync-flushed DEFLATE stream, so each payload reuses the earlier + /// ones as context. + /// + /// [`Compression::None`] (the default) writes the bytes through untouched. A [`Consumer`] must + /// set the same [`compression`](Self::compression). + pub compression: Compression, +} #[cfg(test)] mod test { @@ -30,21 +48,28 @@ mod test { use super::*; + fn cfg(compression: bool) -> Config { + Config { + compression: if compression { + Compression::Deflate + } else { + Compression::None + }, + } + } + 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, - ) + (Producer::new(track, cfg(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 mut consumer = Consumer::new(track, cfg(compression)); let waiter = kio::Waiter::noop(); let mut out = Vec::new(); while let Poll::Ready(Ok(Some(payload))) = consumer.poll_next(&waiter) { @@ -154,7 +179,7 @@ mod 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()); + let mut producer = Producer::new(track, Config::default()); assert!(producer.append(&b"rejected"[..]).is_err()); @@ -177,7 +202,7 @@ mod test { .create_track("test", None) .unwrap(); let mut subscriber = track.subscribe(None); - let mut producer = Producer::new(track, ProducerConfig::default().with_compression(true)); + let mut producer = Producer::new(track, cfg(true)); assert!(producer.is_used()); let oversized = Bytes::from(vec![0u8; moq_flate::DEFAULT_MAX_FRAME_SIZE as usize + 1]); @@ -204,7 +229,7 @@ mod test { .create_track("test", None) .unwrap(); let mut subscriber = track.subscribe(None); - let mut producer = Producer::new(track, ProducerConfig::default()); + let mut producer = Producer::new(track, Config::default()); producer.append(&b"first"[..]).unwrap(); @@ -239,7 +264,7 @@ mod test { #[test] fn a_failed_write_ends_the_track() { let track = rejecting_track(); - let mut producer = Producer::new(track, ProducerConfig::default()); + let mut producer = Producer::new(track, Config::default()); assert!(producer.append(&b"rejected"[..]).is_err()); assert!( @@ -272,7 +297,7 @@ mod test { } track.finish().unwrap(); - let mut consumer = Consumer::new(subscriber, ConsumerConfig::default().with_compression(true)); + let mut consumer = Consumer::new(subscriber, cfg(true)); let waiter = kio::Waiter::noop(); // The log's one group reads normally. @@ -303,7 +328,7 @@ mod test { let mut second = track.append_group().unwrap(); second.write_frame(moq_net::Timestamp::now(), &b"second"[..]).unwrap(); - let mut consumer = Consumer::new(subscriber, ConsumerConfig::default()); + let mut consumer = Consumer::new(subscriber, Config::default()); let waiter = kio::Waiter::noop(); assert!(matches!( @@ -345,7 +370,7 @@ mod test { } track.finish().unwrap(); - let mut consumer = Consumer::new(subscriber, ConsumerConfig::default().with_compression(true)); + let mut consumer = Consumer::new(subscriber, cfg(true)); let waiter = kio::Waiter::noop(); assert!(matches!( @@ -378,7 +403,7 @@ mod test { producer.append(&b"only"[..]).unwrap(); producer.finish().unwrap(); - let mut consumer = Consumer::new(track, ConsumerConfig::default()); + let mut consumer = Consumer::new(track, Config::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 index 149baa07c58..a89a1808fbf 100644 --- a/rs/moq-binary/src/stream/producer.rs +++ b/rs/moq-binary/src/stream/producer.rs @@ -6,28 +6,7 @@ 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 - } -} +pub use super::Config; /// Publishes an ordered log of binary payloads over a track, one payload per frame in a single /// group. @@ -41,12 +20,12 @@ pub struct Producer { impl Producer { /// Create a producer that publishes to the given track. - pub fn new(track: moq_net::track::Producer, config: ProducerConfig) -> Self { + pub fn new(track: moq_net::track::Producer, config: Config) -> Self { Self { inner: Arc::new(Mutex::new(Inner { track, group: None, - flate: config.compression.then(moq_flate::Encoder::new), + flate: config.compression.is_deflate().then(moq_flate::Encoder::new), })), } } diff --git a/rs/moq-boy/src/input.rs b/rs/moq-boy/src/input.rs index 9ca17893dc0..83093f1f3da 100644 --- a/rs/moq-boy/src/input.rs +++ b/rs/moq-boy/src/input.rs @@ -108,7 +108,7 @@ async fn handle_viewer_commands( ) -> anyhow::Result<()> { let track = broadcast.track("command")?.subscribe(None).await?; let mut commands = - moq_json::snapshot::Consumer::::new(track, moq_json::snapshot::ConsumerConfig::default()); + moq_json::snapshot::Consumer::::new(track, moq_json::snapshot::consumer::Config::default()); loop { let command = match commands.next().await { diff --git a/rs/moq-boy/src/status.rs b/rs/moq-boy/src/status.rs index f09127307b9..4bb73576323 100644 --- a/rs/moq-boy/src/status.rs +++ b/rs/moq-boy/src/status.rs @@ -43,7 +43,7 @@ impl StatusPublisher { let producer = broadcast.create_track("status", None)?; Ok(Self { - producer: moq_json::snapshot::Producer::new(producer, moq_json::snapshot::ProducerConfig::default()), + producer: moq_json::snapshot::Producer::new(producer, moq_json::snapshot::Config::default()), }) } diff --git a/rs/moq-ffi/src/json.rs b/rs/moq-ffi/src/json.rs index 65f2e60ae01..d5445742ca0 100644 --- a/rs/moq-ffi/src/json.rs +++ b/rs/moq-ffi/src/json.rs @@ -31,19 +31,27 @@ pub struct MoqJsonSnapshotConfig { pub compression: bool, } -impl From for moq_json::snapshot::ProducerConfig { +fn compression(on: bool) -> moq_json::Compression { + if on { + moq_json::Compression::Deflate + } else { + moq_json::Compression::None + } +} + +impl From for moq_json::snapshot::Config { fn from(config: MoqJsonSnapshotConfig) -> Self { - let mut out = moq_json::snapshot::ProducerConfig::default(); + let mut out = moq_json::snapshot::Config::default(); out.delta_ratio = config.delta_ratio; - out.compression = config.compression; + out.compression = compression(config.compression); out } } -impl From for moq_json::snapshot::ConsumerConfig { +impl From for moq_json::snapshot::consumer::Config { fn from(config: MoqJsonSnapshotConfig) -> Self { - let mut out = moq_json::snapshot::ConsumerConfig::default(); - out.compression = config.compression; + let mut out = moq_json::snapshot::consumer::Config::default(); + out.compression = compression(config.compression); out } } @@ -58,15 +66,11 @@ pub struct MoqJsonStreamConfig { pub compression: bool, } -impl From for moq_json::stream::ProducerConfig { +impl From for moq_json::stream::Config { fn from(config: MoqJsonStreamConfig) -> Self { - moq_json::stream::ProducerConfig::default().with_compression(config.compression) - } -} - -impl From for moq_json::stream::ConsumerConfig { - fn from(config: MoqJsonStreamConfig) -> Self { - moq_json::stream::ConsumerConfig::default().with_compression(config.compression) + let mut out = moq_json::stream::Config::default(); + out.compression = compression(config.compression); + out } } @@ -77,11 +81,16 @@ mod tests { // each wrapper different behavior than the Rust API. #[test] fn record_defaults_match_moq_json() { - let snapshot = moq_json::snapshot::ProducerConfig::default(); + let snapshot = moq_json::snapshot::Config::default(); assert_eq!(snapshot.delta_ratio, 8, "update #[uniffi(default)] on delta_ratio"); - assert!(!snapshot.compression, "update #[uniffi(default)] on compression"); - assert!( - !moq_json::stream::ProducerConfig::default().compression, + assert_eq!( + snapshot.compression, + moq_json::Compression::None, + "update #[uniffi(default)] on compression" + ); + assert_eq!( + moq_json::stream::Config::default().compression, + moq_json::Compression::None, "update #[uniffi(default)] on MoqJsonStreamConfig::compression" ); } diff --git a/rs/moq-json/CHANGELOG.md b/rs/moq-json/CHANGELOG.md index e294748a80d..d534ea5f955 100644 --- a/rs/moq-json/CHANGELOG.md +++ b/rs/moq-json/CHANGELOG.md @@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- [**breaking**] Codec options are `Config` in snapshot and stream. Track-owning options are + `producer::Config` / `consumer::Config`. `compression` is a `Compression` enum (`None` / `Deflate`) + instead of a `bool`, and `with_compression` is gone. - [**breaking**] `snapshot::Producer::lock` is now `modify` and returns a `Result`, refusing a closed track. A guard that fails to publish on drop aborts the track with the error instead of logging a warning, so consumers and the next `modify` both see it. `Guard::commit` is unchanged and leaves diff --git a/rs/moq-json/examples/telemetry.rs b/rs/moq-json/examples/telemetry.rs index 7839a18c192..874b389165d 100644 --- a/rs/moq-json/examples/telemetry.rs +++ b/rs/moq-json/examples/telemetry.rs @@ -9,7 +9,8 @@ use std::task::Poll; -use moq_json::snapshot::{Consumer, ConsumerConfig, Producer, ProducerConfig}; +use moq_json::Compression; +use moq_json::snapshot::{self, Consumer, Producer}; use serde_json::{Value, json}; /// One second of telemetry for a fleet device: a big static core plus a few moving numbers. @@ -75,7 +76,7 @@ fn telemetry(tick: u64) -> Value { } /// Total wire bytes of every frame across every group for a full run under `config`. -fn wire_bytes(config: ProducerConfig, ticks: u64) -> usize { +fn wire_bytes(config: snapshot::Config, ticks: u64) -> usize { let track = moq_net::broadcast::Info::new() .produce() .create_track("telemetry", None) @@ -102,7 +103,7 @@ fn wire_bytes(config: ProducerConfig, ticks: u64) -> usize { /// Drive a producer and a live consumer in lockstep, asserting that EVERY tick reconstructs to the /// exact input value after decompression and delta application (not just the final one). -fn verify(producer_config: ProducerConfig, ticks: u64) { +fn verify(producer_config: snapshot::Config, ticks: u64) { let track = moq_net::broadcast::Info::new() .produce() .create_track("telemetry", None) @@ -110,7 +111,7 @@ fn verify(producer_config: ProducerConfig, ticks: u64) { let consumer = track.subscribe(None); let mut producer = Producer::::new(track, producer_config.clone()); - let mut consumer_config = ConsumerConfig::default(); + let mut consumer_config = snapshot::consumer::Config::default(); consumer_config.compression = producer_config.compression; let mut consumer = Consumer::::new(consumer, consumer_config); let waiter = kio::Waiter::noop(); @@ -140,7 +141,7 @@ fn verify(producer_config: ProducerConfig, ticks: u64) { /// /// Returns how many values the late joiner surfaced to the application: with backlog collapsing this /// is far below `ticks`, since stale intermediate reconstructions are applied internally but skipped. -fn verify_late_joiner(producer_config: ProducerConfig, ticks: u64) -> usize { +fn verify_late_joiner(producer_config: snapshot::Config, ticks: u64) -> usize { let track = moq_net::broadcast::Info::new() .produce() .create_track("telemetry", None) @@ -152,7 +153,7 @@ fn verify_late_joiner(producer_config: ProducerConfig, ticks: u64) -> usize { } producer.finish().unwrap(); - let mut consumer_config = ConsumerConfig::default(); + let mut consumer_config = snapshot::consumer::Config::default(); consumer_config.compression = producer_config.compression; let mut consumer = Consumer::::new(consumer, consumer_config); let waiter = kio::Waiter::noop(); @@ -170,10 +171,14 @@ fn verify_late_joiner(producer_config: ProducerConfig, ticks: u64) -> usize { yielded } -fn cfg(delta_ratio: u32, compression: bool) -> ProducerConfig { - let mut config = ProducerConfig::default(); +fn cfg(delta_ratio: u32, compression: bool) -> snapshot::Config { + let mut config = snapshot::Config::default(); config.delta_ratio = delta_ratio; - config.compression = compression; + config.compression = if compression { + Compression::Deflate + } else { + Compression::None + }; config } diff --git a/rs/moq-json/src/lib.rs b/rs/moq-json/src/lib.rs index f107147f451..a17fac6fa65 100644 --- a/rs/moq-json/src/lib.rs +++ b/rs/moq-json/src/lib.rs @@ -24,6 +24,24 @@ pub mod window; pub use crate::diff::{Diff, diff}; +/// How a JSON track compresses its frames. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub enum Compression { + /// Uncompressed JSON frames. + #[default] + None, + + /// Group-scoped raw DEFLATE, sync-flushed at each frame boundary. + Deflate, +} + +impl Compression { + /// Whether frames are DEFLATE-compressed. + pub const fn is_deflate(self) -> bool { + matches!(self, Self::Deflate) + } +} + /// Errors produced while publishing or consuming JSON. #[derive(thiserror::Error, Debug, Clone)] #[non_exhaustive] diff --git a/rs/moq-json/src/snapshot/consumer.rs b/rs/moq-json/src/snapshot/consumer.rs index 67b23ea0091..90f3267e785 100644 --- a/rs/moq-json/src/snapshot/consumer.rs +++ b/rs/moq-json/src/snapshot/consumer.rs @@ -4,8 +4,20 @@ use std::task::Poll; use serde::de::DeserializeOwned; -use super::{ConsumerConfig, Decoder}; -use crate::Result; +use super::Decoder; +use crate::{Compression, Result}; + +/// Track-owning options 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 Config { + /// How the frames are compressed. Must match the encoder's + /// [`Config::compression`](super::Config::compression). Defaults to [`Compression::None`]. + pub compression: Compression, +} /// Consumes a JSON value from a track, reconstructing it from snapshots and deltas. /// @@ -22,9 +34,9 @@ pub struct Consumer { 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 { + /// Set [`Config::compression`] to read a track written by a producer with the same + /// [`compression`](super::Config::compression). + pub fn new(track: moq_net::track::Subscriber, config: Config) -> Self { Self { track: track.ordered(), group: None, diff --git a/rs/moq-json/src/snapshot/decoder.rs b/rs/moq-json/src/snapshot/decoder.rs index d1546a2b65f..d76d28c42e2 100644 --- a/rs/moq-json/src/snapshot/decoder.rs +++ b/rs/moq-json/src/snapshot/decoder.rs @@ -5,28 +5,9 @@ use std::marker::PhantomData; use serde::de::DeserializeOwned; use serde_json::Value; +use super::consumer::Config; use crate::{Error, Result}; -/// Configuration for a [`Decoder`], and so for the [`Consumer`](super::Consumer) wrapping one. -/// -/// Build from [`Default`] and override fields (the struct is `#[non_exhaustive]`, so new options -/// stay additive), or chain the `with_*` setters. -#[derive(Debug, Clone, Default)] -#[non_exhaustive] -pub struct ConsumerConfig { - /// Whether the frames are DEFLATE-compressed. Must match the encoder'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 - } -} - /// Reconstructs a JSON value from the snapshot and delta frames of a group. /// /// The track-free core of [`Consumer`](super::Consumer), and the mirror of @@ -61,9 +42,9 @@ pub struct Decoder { impl Decoder { /// Create a decoder with no value, awaiting its first [`snapshot`](Self::snapshot). - pub fn new(config: ConsumerConfig) -> Self { + pub fn new(config: Config) -> Self { Self { - compression: config.compression, + compression: config.compression.is_deflate(), flate: None, current: None, _marker: PhantomData, @@ -136,16 +117,29 @@ impl Decoder { #[cfg(test)] mod test { - use super::super::{Encoder, ProducerConfig}; + use super::super::consumer::Config as ConsumerConfig; + use super::super::{Config, Encoder}; use super::*; - use serde_json::json; + use crate::Compression; + use serde_json::{Value, json}; + + fn consume(compression: Compression) -> ConsumerConfig { + ConsumerConfig { compression } + } + + fn deflate() -> Config { + Config { + compression: Compression::Deflate, + ..Default::default() + } + } /// Round-trip a sequence of values through an encoder and decoder, yielding the value the /// decoder reconstructs after each frame. - fn roundtrip(config: ProducerConfig, values: &[Value]) -> Vec { + fn roundtrip(config: Config, values: &[Value]) -> Vec { let compression = config.compression; let mut encoder = Encoder::::new(config); - let mut decoder = Decoder::::new(ConsumerConfig::default().with_compression(compression)); + let mut decoder = Decoder::::new(consume(compression)); let mut out = Vec::new(); for value in values { @@ -169,7 +163,7 @@ mod test { json!({ "a": 1, "b": 2 }), json!({ "a": 5, "b": 2 }), ]; - assert_eq!(roundtrip(ProducerConfig::default(), &values), values); + assert_eq!(roundtrip(Config::default(), &values), values); } #[test] @@ -179,8 +173,7 @@ mod test { json!({ "a": 1, "b": 2 }), json!({ "a": 5, "b": 2 }), ]; - let config = ProducerConfig::default().with_compression(true); - assert_eq!(roundtrip(config, &values), values); + assert_eq!(roundtrip(deflate(), &values), values); } /// The window is per group, so a keyframe mid-stream has to restart it on both sides. A decoder @@ -189,7 +182,7 @@ mod test { fn compressed_roundtrip_across_a_group_boundary() { // A tight ratio guarantees at least one roll partway through. let values: Vec = (0..=40).map(|n| json!({ "n": n })).collect(); - let config = ProducerConfig::default().with_delta_ratio(2).with_compression(true); + let config = deflate().with_delta_ratio(2); assert_eq!(roundtrip(config, &values).last().unwrap(), &json!({ "n": 40 })); } @@ -210,7 +203,7 @@ mod test { /// stale, and deserializing each one is exactly the cost the split exists to avoid. #[test] fn frames_apply_without_materializing() { - let mut encoder = Encoder::::new(ProducerConfig::default().with_delta_ratio(100)); + let mut encoder = Encoder::::new(Config::default().with_delta_ratio(100)); let mut decoder = Decoder::::new(ConsumerConfig::default()); for n in 0..=20 { diff --git a/rs/moq-json/src/snapshot/encoder.rs b/rs/moq-json/src/snapshot/encoder.rs index fd485f534de..fe35e8ef66a 100644 --- a/rs/moq-json/src/snapshot/encoder.rs +++ b/rs/moq-json/src/snapshot/encoder.rs @@ -6,7 +6,7 @@ use bytes::Bytes; use serde::Serialize; use serde_json::Value; -use crate::{Diff, Result, diff}; +use crate::{Compression, Diff, Result, diff}; /// Maximum frames (snapshot + deltas) in a single group before a new snapshot is forced. /// @@ -14,13 +14,13 @@ use crate::{Diff, Result, diff}; /// at frame 0 before the group is evicted. pub(super) const MAX_DELTA_FRAMES: usize = 256; -/// Configuration for an [`Encoder`], and so for the [`Producer`](super::Producer) wrapping one. +/// Codec options for an [`Encoder`], and so for the [`Producer`](super::Producer) wrapping one. /// /// Build from [`Default`] and override fields (the struct is `#[non_exhaustive]`, so new -/// options stay additive), or chain the `with_*` setters. +/// options stay additive), or chain [`with_delta_ratio`](Self::with_delta_ratio). #[derive(Debug, Clone)] #[non_exhaustive] -pub struct ProducerConfig { +pub struct Config { /// Controls how aggressively the encoder emits deltas (merge patches) instead of full snapshots. /// /// A ratio of `0` disables deltas: every change is encoded as a new snapshot. @@ -31,8 +31,8 @@ pub struct ProducerConfig { /// still lands before the group rolls. So `1` allows roughly one snapshot's worth of deltas before /// rolling, and a larger ratio tolerates more. /// - /// When [`compression`](Self::compression) is on, both sides of the comparison are measured on - /// the *compressed* frame sizes (the real wire cost). + /// When [`compression`](Self::compression) is [`Compression::Deflate`], both sides of the + /// comparison are measured on the *compressed* frame sizes (the real wire cost). /// /// Defaults to `8`. pub delta_ratio: u32, @@ -40,31 +40,25 @@ pub struct ProducerConfig { /// Compress each group as one sync-flushed DEFLATE stream, so deltas reuse the snapshot as /// context and shrink sharply. /// - /// `false` (the default) emits plaintext JSON frames, identical on the wire to an uncompressed - /// track. A [`Decoder`](super::Decoder) reading them must set - /// [`ConsumerConfig::compression`](super::ConsumerConfig::compression) to match. - pub compression: bool, + /// [`Compression::None`] (the default) emits plaintext JSON frames, identical on the wire to an + /// uncompressed track. A [`Decoder`](super::Decoder) reading them must set the same + /// [`compression`](Self::compression). + pub compression: Compression, } -impl ProducerConfig { +impl Config { /// Set [`delta_ratio`](Self::delta_ratio) (a builder, since the struct is `#[non_exhaustive]`). pub fn with_delta_ratio(mut self, delta_ratio: u32) -> Self { self.delta_ratio = delta_ratio; self } - - /// 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 - } } -impl Default for ProducerConfig { +impl Default for Config { fn default() -> Self { Self { delta_ratio: 8, - compression: false, + compression: Compression::None, } } } @@ -72,7 +66,7 @@ impl Default for ProducerConfig { /// One encoded frame, and the group boundary it implies. #[derive(Clone, Debug)] pub struct Encoded { - /// The frame payload, DEFLATE-compressed when [`ProducerConfig::compression`] is set. + /// The frame payload, DEFLATE-compressed when [`Config::compression`] is [`Compression::Deflate`]. pub payload: Bytes, /// Whether this frame is a full snapshot, which must open a new group. @@ -164,7 +158,7 @@ impl Drop for Pending<'_, T> { /// If the caller cuts a group for its own reasons (a `cut`, `seek`, or discontinuity), call /// [`reset`](Self::reset) directly so the next value opens the new group with a snapshot. pub struct Encoder { - config: ProducerConfig, + config: Config, /// The last encoded value, the baseline every delta is diffed against. `None` until the first /// snapshot, which is what makes that first [`update`](Self::update) a keyframe. @@ -195,7 +189,7 @@ pub struct Encoder { impl Encoder { /// Create an encoder with a cold baseline, so the first [`update`](Self::update) is a snapshot. - pub fn new(config: ProducerConfig) -> Self { + pub fn new(config: Config) -> Self { Self { config, last: None, @@ -284,7 +278,7 @@ impl Encoder { // 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 { + if self.config.compression.is_deflate() && 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() { @@ -341,7 +335,7 @@ impl Encoder { // 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 { + if self.config.compression.is_deflate() && snapshot.len() as u64 > moq_flate::DEFAULT_MAX_FRAME_SIZE { return Err(moq_flate::Error::TooLarge(moq_flate::DEFAULT_MAX_FRAME_SIZE).into()); } @@ -361,12 +355,12 @@ impl Encoder { // Open a fresh per-group encoder (cold window) and compress the snapshot as frame 0, recording // its wire size as the delta anchor. let (payload, flate) = match self.config.compression { - true => { + Compression::Deflate => { let mut flate = moq_flate::Encoder::new(); let payload = flate.frame(&snapshot); (payload, Some(flate)) } - false => (Bytes::from(snapshot), None), + Compression::None => (Bytes::from(snapshot), None), }; self.snapshot_len = payload.len() as u64; @@ -390,7 +384,7 @@ mod test { /// Encode a sequence of values, committing each frame, and return `(keyframe, payload_len)` per /// emitted frame. - fn encode(config: ProducerConfig, values: &[Value]) -> Vec<(bool, usize)> { + fn encode(config: Config, values: &[Value]) -> Vec<(bool, usize)> { let mut encoder = Encoder::::new(config); let mut out = Vec::new(); for value in values { @@ -415,21 +409,21 @@ mod test { #[test] fn first_update_is_a_keyframe() { - let frames = encode(ProducerConfig::default(), &[json!({ "a": 1 })]); + let frames = encode(Config::default(), &[json!({ "a": 1 })]); assert_eq!(frames.len(), 1); assert!(frames[0].0); } #[test] fn unchanged_value_encodes_nothing() { - let frames = encode(ProducerConfig::default(), &[json!({ "a": 1 }), json!({ "a": 1 })]); + let frames = encode(Config::default(), &[json!({ "a": 1 }), json!({ "a": 1 })]); assert_eq!(frames.len(), 1); } #[test] fn changes_ride_as_deltas() { let frames = encode( - ProducerConfig::default().with_delta_ratio(100), + Config::default().with_delta_ratio(100), &[ json!({ "a": 1, "b": 1 }), json!({ "a": 1, "b": 2 }), @@ -442,7 +436,7 @@ mod test { #[test] fn deltas_off_forces_a_keyframe_per_change() { let frames = encode( - ProducerConfig::default().with_delta_ratio(0), + Config::default().with_delta_ratio(0), &[json!({ "a": 1 }), json!({ "a": 2 })], ); assert_eq!(frames.iter().map(|f| f.0).collect::>(), vec![true, true]); @@ -454,7 +448,7 @@ mod test { #[test] fn a_null_field_forces_a_keyframe() { let frames = encode( - ProducerConfig::default().with_delta_ratio(100), + Config::default().with_delta_ratio(100), &[json!({ "a": 1, "b": 1 }), json!({ "a": 1, "b": null })], ); assert_eq!(frames.iter().map(|f| f.0).collect::>(), vec![true, true]); @@ -464,7 +458,7 @@ mod test { #[test] fn a_non_object_root_forces_a_keyframe() { let frames = encode( - ProducerConfig::default().with_delta_ratio(100), + Config::default().with_delta_ratio(100), &[json!({ "a": 1 }), json!([1, 2, 3])], ); assert_eq!(frames.iter().map(|f| f.0).collect::>(), vec![true, true]); @@ -473,7 +467,7 @@ mod test { #[test] fn frame_cap_forces_a_keyframe() { let values: Vec = (0..=MAX_DELTA_FRAMES).map(|n| json!({ "n": n })).collect(); - let frames = encode(ProducerConfig::default().with_delta_ratio(1_000_000), &values); + let frames = encode(Config::default().with_delta_ratio(1_000_000), &values); // The snapshot plus MAX_DELTA_FRAMES - 1 deltas fill the group, then the cap rolls it. assert_eq!(frames.len(), MAX_DELTA_FRAMES + 1); @@ -485,7 +479,7 @@ mod test { /// be a delta against a window and a baseline the new group never carried. #[test] fn reset_forces_the_next_update_to_be_a_keyframe() { - let mut encoder = Encoder::::new(ProducerConfig::default().with_delta_ratio(100)); + let mut encoder = Encoder::::new(Config::default().with_delta_ratio(100)); assert!(commit(&mut encoder, &json!({ "a": 1 })).unwrap().keyframe); assert!(!commit(&mut encoder, &json!({ "a": 2 })).unwrap().keyframe); @@ -498,7 +492,7 @@ mod test { /// and it has to resynchronize on its own: a caller cannot be relied on to remember. #[test] fn an_uncommitted_frame_resynchronizes_the_encoder() { - let mut encoder = Encoder::::new(ProducerConfig::default().with_delta_ratio(100)); + let mut encoder = Encoder::::new(Config::default().with_delta_ratio(100)); commit(&mut encoder, &json!({ "a": 1 })).unwrap(); // The caller wrote this one and said so, so the next value can still ride as a delta. @@ -522,7 +516,7 @@ mod test { /// already published and skip it as unchanged. #[test] fn an_uncommitted_first_frame_is_reencoded() { - let mut encoder = Encoder::::new(ProducerConfig::default()); + let mut encoder = Encoder::::new(Config::default()); drop(encoder.update(&json!({ "a": 1 })).unwrap().expect("a snapshot")); let retried = commit(&mut encoder, &json!({ "a": 1 })).expect("the same value, re-encoded"); @@ -533,7 +527,7 @@ mod test { /// open with a snapshot, so "unchanged" can't mean "write nothing" there. #[test] fn reset_republishes_an_unchanged_value() { - let mut encoder = Encoder::::new(ProducerConfig::default()); + let mut encoder = Encoder::::new(Config::default()); commit(&mut encoder, &json!({ "a": 1 })).unwrap(); encoder.reset(); @@ -548,7 +542,10 @@ mod test { fn compressed_deltas_reuse_the_group_window() { let phrase = "Media over QUIC delivers real-time latency at massive scale"; let frames = encode( - ProducerConfig::default().with_delta_ratio(100).with_compression(true), + Config { + delta_ratio: 100, + compression: Compression::Deflate, + }, &[json!({ "note": phrase }), json!({ "note": phrase, "echo": phrase })], ); @@ -585,7 +582,7 @@ mod test { #[test] fn a_snapshot_serializes_its_value_once() { let value = Ticking(std::cell::Cell::new(0)); - let mut encoder = Encoder::::new(ProducerConfig::default()); + let mut encoder = Encoder::::new(Config::default()); let payload = { let frame = encoder.update(&value).unwrap().expect("a snapshot"); let payload = frame.payload.clone(); @@ -602,7 +599,7 @@ mod test { #[test] fn value_tracks_the_baseline() { - let mut encoder = Encoder::::new(ProducerConfig::default().with_delta_ratio(100)); + let mut encoder = Encoder::::new(Config::default().with_delta_ratio(100)); assert_eq!(encoder.value(), None); commit(&mut encoder, &json!({ "a": 1, "b": 1 })); diff --git a/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index fb9367fde83..45098e7aaac 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -13,7 +13,7 @@ //! order. A consumer jumps to the newest group, reads the snapshot, and applies the deltas, so //! a late joiner never needs older groups. //! -//! Deltas are controlled by [`ProducerConfig::delta_ratio`]. A ratio of `0` disables them, so every +//! Deltas are controlled by [`Config::delta_ratio`]. A ratio of `0` disables them, so every //! change is a fresh snapshot group, matching a plain "one JSON blob per group" track. //! //! The encoder rolls a group on its own budget, but a caller can roll one for its own reasons with @@ -36,14 +36,14 @@ //! [`Pending`] the caller commits once the write succeeds. Dropping it uncommitted resynchronizes //! the encoder, which keeps a frame that never reached the wire from desyncing the stream. -mod consumer; +pub mod consumer; mod decoder; mod encoder; -mod producer; +pub mod producer; pub use consumer::Consumer; -pub use decoder::{ConsumerConfig, Decoder}; -pub use encoder::{Encoded, Encoder, Pending, ProducerConfig}; +pub use decoder::Decoder; +pub use encoder::{Config, Encoded, Encoder, Pending}; pub use producer::{Guard, Producer}; #[cfg(test)] @@ -55,23 +55,32 @@ mod test { use super::encoder::MAX_DELTA_FRAMES; use super::*; + use crate::Compression; /// An uncompressed config with the given delta ratio. - fn cfg(delta_ratio: u32) -> ProducerConfig { - ProducerConfig::default().with_delta_ratio(delta_ratio) + fn cfg(delta_ratio: u32) -> Config { + Config::default().with_delta_ratio(delta_ratio) } /// A DEFLATE-compressed config with the given delta ratio. - fn cfg_deflate(delta_ratio: u32) -> ProducerConfig { - cfg(delta_ratio).with_compression(true) + fn cfg_deflate(delta_ratio: u32) -> Config { + Config { + delta_ratio, + compression: Compression::Deflate, + } } /// A consumer reading compressed frames. fn deflate_consumer(track: moq_net::track::Subscriber) -> Consumer { - Consumer::new(track, ConsumerConfig::default().with_compression(true)) + Consumer::new( + track, + consumer::Config { + compression: Compression::Deflate, + }, + ) } - fn producer(config: ProducerConfig) -> (Producer, moq_net::track::Subscriber) { + fn producer(config: Config) -> (Producer, moq_net::track::Subscriber) { let track = moq_net::broadcast::Info::new() .produce() .create_track("test", None) @@ -82,7 +91,7 @@ mod test { /// Drain every value currently available from a plaintext consumer without blocking. fn drain(track: moq_net::track::Subscriber) -> Vec { - drain_with(Consumer::::new(track, ConsumerConfig::default())) + drain_with(Consumer::::new(track, consumer::Config::default())) } /// Drain every value currently available from an already-built consumer without blocking. @@ -188,8 +197,8 @@ mod test { #[test] fn live_consumer_sees_each_update() { - let (mut producer, track) = producer(ProducerConfig::default()); - let mut consumer = Consumer::::new(track, ConsumerConfig::default()); + let (mut producer, track) = producer(Config::default()); + let mut consumer = Consumer::::new(track, consumer::Config::default()); let waiter = kio::Waiter::noop(); for n in 1..=3 { @@ -221,7 +230,7 @@ mod test { #[test] fn unchanged_value_writes_nothing() { - let (mut producer, track) = producer(ProducerConfig::default()); + let (mut producer, track) = producer(Config::default()); producer.update(&json!({ "a": 1 })).unwrap(); producer.update(&json!({ "a": 1 })).unwrap(); producer.finish().unwrap(); @@ -332,7 +341,7 @@ mod test { .create_track("test", None) .unwrap(); let consumer = track.subscribe(None); - let mut producer = Producer::::new(track, ProducerConfig::default()); + let mut producer = Producer::::new(track, Config::default()); // First owner sets its field. producer.modify().unwrap().video = Some("v1".to_string()); @@ -345,7 +354,7 @@ mod test { producer.finish().unwrap(); - let mut consumer = Consumer::::new(consumer, ConsumerConfig::default()); + let mut consumer = Consumer::::new(consumer, consumer::Config::default()); let waiter = kio::Waiter::noop(); let mut last = None; while let Poll::Ready(Ok(Some(value))) = consumer.poll_next(&waiter) { @@ -455,7 +464,7 @@ mod test { } // Every frame is rejected, so each publish fails and the encoder resynchronizes. - let mut producer = Producer::::new(rejecting_track(), ProducerConfig::default()); + let mut producer = Producer::::new(rejecting_track(), Config::default()); let mut guard = producer.modify().unwrap(); guard.video = Some("v1".to_string()); @@ -551,7 +560,7 @@ mod test { // snapshot group (the gate overshoots the budget by one delta before rolling). let (mut producer, track) = producer(cfg(1)); let observer = producer.consume(); - let mut consumer = Consumer::::new(track, ConsumerConfig::default()); + let mut consumer = Consumer::::new(track, consumer::Config::default()); let waiter = kio::Waiter::noop(); producer.update(&json!({ "a": 1 })).unwrap(); // snapshot, group 0 @@ -586,7 +595,7 @@ mod test { let consumer_track = track.subscribe(None); track.finish().unwrap(); - let mut consumer = Consumer::::new(consumer_track, ConsumerConfig::default()); + let mut consumer = Consumer::::new(consumer_track, consumer::Config::default()); let waiter = kio::Waiter::noop(); // Track is finished but the open group is empty: pending, not end-of-stream. @@ -765,7 +774,7 @@ mod test { let (mut producer, track) = producer(cfg(0)); producer.update(&json!({ "inner": { "count": 300 } })).unwrap(); - let mut consumer = Consumer::::new(track, ConsumerConfig::default()); + let mut consumer = Consumer::::new(track, consumer::Config::default()); let Poll::Ready(Err(err)) = consumer.poll_next(&kio::Waiter::noop()) else { panic!("expected a deserialize error"); }; @@ -780,7 +789,7 @@ mod test { let (mut producer, track) = producer(cfg(0)); producer.update(&json!("not a map")).unwrap(); - let mut consumer = Consumer::>::new(track, ConsumerConfig::default()); + let mut consumer = Consumer::>::new(track, consumer::Config::default()); let Poll::Ready(Err(err)) = consumer.poll_next(&kio::Waiter::noop()) else { panic!("expected a deserialize error"); }; @@ -791,7 +800,7 @@ mod test { } /// Publish a single value and return the byte length of the resulting (frame 0) wire frame. - fn wire_frame_len(config: ProducerConfig, value: &Value) -> usize { + fn wire_frame_len(config: Config, value: &Value) -> usize { let (mut producer, track) = producer(config); producer.update(value).unwrap(); producer.finish().unwrap(); diff --git a/rs/moq-json/src/snapshot/producer.rs b/rs/moq-json/src/snapshot/producer.rs index 4b9c3d5c6bb..9e9168a7100 100644 --- a/rs/moq-json/src/snapshot/producer.rs +++ b/rs/moq-json/src/snapshot/producer.rs @@ -7,9 +7,11 @@ use std::sync::{Arc, Mutex, MutexGuard}; use serde::Serialize; use serde::de::DeserializeOwned; -use super::{Encoded, Encoder, ProducerConfig}; +use super::{Encoded, Encoder}; use crate::{Error, Result}; +pub use super::Config; + /// Take the shared publishing state, recovering if a prior guard panicked while holding it. /// /// A panic under this lock is an in-flight edit being unwound. That edit is discarded (see @@ -59,7 +61,7 @@ impl Producer { impl Producer { /// Create a producer that publishes to the given track. - pub fn new(track: moq_net::track::Producer, config: ProducerConfig) -> Self { + pub fn new(track: moq_net::track::Producer, config: Config) -> Self { Self { inner: Arc::new(Mutex::new(Inner { track: Track { diff --git a/rs/moq-json/src/stream/consumer.rs b/rs/moq-json/src/stream/consumer.rs index fb07bdcdd2e..d43f7aa1990 100644 --- a/rs/moq-json/src/stream/consumer.rs +++ b/rs/moq-json/src/stream/consumer.rs @@ -4,7 +4,9 @@ use std::task::Poll; use serde::de::DeserializeOwned; -use super::{ConsumerConfig, Decoder}; +use super::Decoder; + +pub use super::Config; use crate::Result; /// Consumes an ordered log of JSON records from a track, yielding every record in order. @@ -34,9 +36,8 @@ pub struct Consumer { 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 { + /// Set [`Config::compression`] to match the encoder that wrote the track. + pub fn new(track: moq_net::track::Subscriber, config: Config) -> Self { Self { track, group: None, diff --git a/rs/moq-json/src/stream/decoder.rs b/rs/moq-json/src/stream/decoder.rs index 33c144504ec..187353aea7a 100644 --- a/rs/moq-json/src/stream/decoder.rs +++ b/rs/moq-json/src/stream/decoder.rs @@ -4,28 +4,9 @@ use std::marker::PhantomData; use serde::de::DeserializeOwned; +use super::Config; use crate::Result; -/// Configuration for a [`Decoder`], and so for the [`Consumer`](super::Consumer) wrapping one. -/// -/// 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 encoder'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 - } -} - /// Decodes JSON records from frame payloads, sharing one DEFLATE window across the log. /// /// The track-free core of [`Consumer`](super::Consumer), and the mirror of @@ -41,10 +22,10 @@ pub struct Decoder { impl Decoder { /// Create a decoder with a cold window. - pub fn new(config: ConsumerConfig) -> Self { + pub fn new(config: Config) -> Self { Self { - flate: config.compression.then(moq_flate::Decoder::new), - compression: config.compression, + flate: config.compression.is_deflate().then(moq_flate::Decoder::new), + compression: config.compression.is_deflate(), _marker: PhantomData, } } @@ -67,14 +48,25 @@ impl Decoder { #[cfg(test)] mod test { - use super::super::{Encoder, ProducerConfig}; + use super::super::{Config, Encoder}; use super::*; + use crate::Compression; use serde_json::{Value, json}; + fn cfg(compression: bool) -> Config { + Config { + compression: if compression { + Compression::Deflate + } else { + Compression::None + }, + } + } + /// Round-trip a sequence of records through an encoder and decoder. fn roundtrip(compression: bool, values: &[Value]) -> Vec { - let mut encoder = Encoder::::new(ProducerConfig::default().with_compression(compression)); - let mut decoder = Decoder::::new(ConsumerConfig::default().with_compression(compression)); + let mut encoder = Encoder::::new(cfg(compression)); + let mut decoder = Decoder::::new(cfg(compression)); values .iter() @@ -101,7 +93,7 @@ mod test { #[test] fn the_shared_window_shrinks_repetitive_records() { - let mut encoder = Encoder::::new(ProducerConfig::default().with_compression(true)); + let mut encoder = Encoder::::new(cfg(true)); let sizes: Vec = (0..8) .map(|n| { let record = encoder.encode(&json!({ "group": n, "pts": n * 2_000 })).unwrap(); @@ -123,8 +115,8 @@ mod test { /// against context the decoder on the other side never received. #[test] fn reset_starts_a_cold_window_on_both_sides() { - let mut encoder = Encoder::::new(ProducerConfig::default().with_compression(true)); - let mut decoder = Decoder::::new(ConsumerConfig::default().with_compression(true)); + let mut encoder = Encoder::::new(cfg(true)); + let mut decoder = Decoder::::new(cfg(true)); for n in 0..4 { let record = encoder.encode(&json!({ "n": n })).unwrap(); @@ -143,16 +135,23 @@ mod test { #[cfg(test)] mod desync_test { - use super::super::{Encoder, ProducerConfig}; + use super::super::{Config, Encoder}; use super::*; + use crate::Compression; use serde_json::{Value, json}; + fn deflate() -> Config { + Config { + compression: Compression::Deflate, + } + } + /// A compressed record that never reached the wire leaves the window ahead of the consumer, and a /// log has no keyframe to resynchronize on. Continuing would emit frames nothing can decode, so /// the encoder refuses until the caller rolls a new group and resets. #[test] fn an_uncommitted_compressed_record_stops_the_encoder() { - let mut encoder = Encoder::::new(ProducerConfig::default().with_compression(true)); + let mut encoder = Encoder::::new(deflate()); encoder.encode(&json!({ "n": 0 })).unwrap().commit(); // This one fails to write, so the caller never commits it. @@ -163,7 +162,7 @@ mod desync_test { // Rolling a new group gives the consumer a cold window too, so the reset clears it. encoder.reset(); let record = encoder.encode(&json!({ "n": 2 })).unwrap(); - let mut decoder = Decoder::::new(ConsumerConfig::default().with_compression(true)); + let mut decoder = Decoder::::new(deflate()); assert_eq!(decoder.decode(record.payload()).unwrap(), json!({ "n": 2 })); record.commit(); } @@ -172,13 +171,13 @@ mod desync_test { /// rather than an undecodable stream, and the encoder keeps going. #[test] fn an_uncommitted_plaintext_record_does_not_stop_the_encoder() { - let mut encoder = Encoder::::new(ProducerConfig::default()); + let mut encoder = Encoder::::new(Config::default()); drop(encoder.encode(&json!({ "n": 0 })).unwrap()); let record = encoder .encode(&json!({ "n": 1 })) .expect("plaintext records are independent"); - let mut decoder = Decoder::::new(ConsumerConfig::default()); + let mut decoder = Decoder::::new(Config::default()); assert_eq!(decoder.decode(record.payload()).unwrap(), json!({ "n": 1 })); record.commit(); } diff --git a/rs/moq-json/src/stream/encoder.rs b/rs/moq-json/src/stream/encoder.rs index a1a891c7618..a1e6d94ec0f 100644 --- a/rs/moq-json/src/stream/encoder.rs +++ b/rs/moq-json/src/stream/encoder.rs @@ -5,29 +5,21 @@ use std::marker::PhantomData; use bytes::Bytes; use serde::Serialize; -use crate::{Error, Result}; +use crate::{Compression, Error, Result}; -/// Configuration for an [`Encoder`], and so for the [`Producer`](super::Producer) wrapping one. +/// Codec options for an [`Encoder`], and so for the [`Producer`](super::Producer) wrapping one. /// /// 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 { +pub struct Config { /// Compress the group as one sync-flushed DEFLATE stream, so each record reuses the earlier /// ones as context and shrinks sharply. /// - /// `false` (the default) emits plaintext JSON frames. A [`Decoder`](super::Decoder) reading them - /// 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 - } + /// [`Compression::None`] (the default) emits plaintext JSON frames. A [`Decoder`](super::Decoder) + /// reading them must set the same [`compression`](Self::compression). + pub compression: Compression, } /// An encoded record the caller has not yet acknowledged writing. @@ -93,10 +85,10 @@ pub struct Encoder { impl Encoder { /// Create an encoder with a cold window. - pub fn new(config: ProducerConfig) -> Self { + pub fn new(config: Config) -> Self { Self { - flate: config.compression.then(moq_flate::Encoder::new), - compression: config.compression, + flate: config.compression.is_deflate().then(moq_flate::Encoder::new), + compression: config.compression.is_deflate(), desynced: false, _marker: PhantomData, } diff --git a/rs/moq-json/src/stream/mod.rs b/rs/moq-json/src/stream/mod.rs index 8963a17bfc2..18fc2823638 100644 --- a/rs/moq-json/src/stream/mod.rs +++ b/rs/moq-json/src/stream/mod.rs @@ -5,7 +5,8 @@ //! JSON object as one frame, and a [`Consumer`] yields every record in order. //! //! The whole log rides a **single group** that is never rolled: with -//! [`ProducerConfig::compression`] on, that one group is one DEFLATE window, so every record +//! [`Config::compression`] set to [`crate::Compression::Deflate`], that one +//! group is one DEFLATE window, so every record //! compresses against all the earlier ones. There is deliberately no group rolling (and so no //! catch-up machinery): the only reason to roll would be moq-net's per-group frame cap, which //! isn't worth working around here. A caller that wants to bound the record rate throttles at @@ -29,14 +30,14 @@ //! without it, for when something else is already in charge of the track; they carry the shared //! DEFLATE window and nothing else, since a log has no group boundaries to report. -mod consumer; +pub mod consumer; mod decoder; mod encoder; -mod producer; +pub mod producer; pub use consumer::Consumer; -pub use decoder::{ConsumerConfig, Decoder}; -pub use encoder::{Encoder, Pending, ProducerConfig}; +pub use decoder::Decoder; +pub use encoder::{Config, Encoder, Pending}; pub use producer::Producer; #[cfg(test)] @@ -46,8 +47,9 @@ mod test { use serde_json::{Value, json}; use super::*; + use crate::Compression; - fn producer(config: ProducerConfig) -> (Producer, moq_net::track::Subscriber) { + fn producer(config: Config) -> (Producer, moq_net::track::Subscriber) { let track = moq_net::broadcast::Info::new() .produce() .create_track("test", None) @@ -56,12 +58,23 @@ mod test { (Producer::new(track, config), consumer) } - fn compressed() -> ProducerConfig { - ProducerConfig::default().with_compression(true) + fn compressed() -> Config { + Config { + compression: Compression::Deflate, + } } - fn consumer(track: moq_net::track::Subscriber, compression: bool) -> Consumer { - Consumer::new(track, ConsumerConfig::default().with_compression(compression)) + fn consume(track: moq_net::track::Subscriber, compression: bool) -> Consumer { + Consumer::new( + track, + Config { + compression: if compression { + Compression::Deflate + } else { + Compression::None + }, + }, + ) } /// Drain every record currently available without blocking. @@ -76,13 +89,13 @@ mod test { #[test] fn plaintext_roundtrip_in_order() { - let (mut producer, track) = producer(ProducerConfig::default()); + let (mut producer, track) = producer(Config::default()); for n in 0..5 { producer.append(&json!({ "n": n })).unwrap(); } producer.finish().unwrap(); - let records = drain(consumer(track, false)); + let records = drain(consume(track, false)); assert_eq!(records, (0..5).map(|n| json!({ "n": n })).collect::>()); } @@ -94,7 +107,7 @@ mod test { } producer.finish().unwrap(); - let records = drain(consumer(track, true)); + let records = drain(consume(track, true)); assert_eq!(records.len(), 20); assert_eq!(records[7], json!({ "group": 7, "pts": 14_000 })); } @@ -109,13 +122,13 @@ mod test { // Never rolled: a single group holds the whole log. assert_eq!(track.latest(), Some(0)); - assert_eq!(drain(consumer(track, true)).len(), 50); + assert_eq!(drain(consume(track, true)).len(), 50); } #[test] fn live_consumer_sees_each_record() { let (mut producer, track) = producer(compressed()); - let mut consumer = consumer(track, true); + let mut consumer = consume(track, true); let waiter = kio::Waiter::noop(); for n in 0..3 { @@ -166,7 +179,7 @@ mod test { .create_track("test", None) .unwrap(); let mut subscriber = track.subscribe(None); - let mut producer = Producer::>::new(track, ProducerConfig::default()); + let mut producer = Producer::>::new(track, Config::default()); let mut bad = std::collections::BTreeMap::new(); bad.insert((1, 2), 3); @@ -202,7 +215,7 @@ mod 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()); + let mut producer = Producer::::new(track, Config::default()); assert!(matches!(producer.append(&json!({ "n": 1 })), Err(crate::Error::Net(_)))); @@ -219,7 +232,7 @@ mod test { #[test] fn a_failed_write_ends_the_track() { let track = rejecting_track(); - let mut producer = Producer::::new(track, ProducerConfig::default().with_compression(true)); + let mut producer = Producer::::new(track, compressed()); assert!(matches!(producer.append(&json!({ "n": 1 })), Err(crate::Error::Net(_)))); @@ -248,7 +261,7 @@ mod test { producer.finish().unwrap(); assert!(producer.append(&json!({ "n": 1 })).is_err()); - assert_eq!(drain(consumer(producer.consume(), true)), vec![json!({ "n": 0 })]); + assert_eq!(drain(consume(producer.consume(), true)), vec![json!({ "n": 0 })]); } /// A stream is one group. A publisher that opens a second lost whatever would have completed the @@ -277,7 +290,7 @@ mod test { .write_frame(moq_net::Timestamp::now(), br#"{"n":1}"#.as_slice()) .unwrap(); - let mut consumer = consumer(subscriber, false); + let mut consumer = consume(subscriber, false); let waiter = kio::Waiter::noop(); assert!(matches!( @@ -310,7 +323,7 @@ mod test { } producer.finish().unwrap(); - let records = drain(consumer(track, true)); + let records = drain(consume(track, true)); assert_eq!(records, vec![value.clone(), value.clone(), value.clone(), value]); } } diff --git a/rs/moq-json/src/stream/producer.rs b/rs/moq-json/src/stream/producer.rs index f5a54e8cbc5..92d7872959e 100644 --- a/rs/moq-json/src/stream/producer.rs +++ b/rs/moq-json/src/stream/producer.rs @@ -5,9 +5,11 @@ use std::sync::{Arc, Mutex}; use serde::Serialize; -use super::{Encoder, ProducerConfig}; +use super::Encoder; use crate::Result; +pub use super::Config; + /// Publishes an ordered log of JSON records over a track, one record per frame in a single group. /// /// An [`Encoder`] that owns its track. When something else already owns the track, use the @@ -41,7 +43,7 @@ impl Producer { impl Producer { /// Create a producer that publishes to the given track. - pub fn new(track: moq_net::track::Producer, config: ProducerConfig) -> Self { + pub fn new(track: moq_net::track::Producer, config: Config) -> Self { Self { inner: Arc::new(Mutex::new(Inner { track: Track { diff --git a/rs/moq-json/src/window/encoder.rs b/rs/moq-json/src/window/encoder.rs index 59e1354436c..58abe657c12 100644 --- a/rs/moq-json/src/window/encoder.rs +++ b/rs/moq-json/src/window/encoder.rs @@ -34,7 +34,7 @@ pub struct ProducerConfig { /// `0` disables ops entirely, so every edit is its own single-frame group. /// /// This is the window's counterpart to - /// [`snapshot::ProducerConfig::delta_ratio`](crate::snapshot::ProducerConfig::delta_ratio), and + /// [`snapshot::Config::delta_ratio`](crate::snapshot::Config::delta_ratio), and /// the same trade: a bigger ratio spends less on headers and makes a late joiner read more ops. /// /// Defaults to `8`. diff --git a/rs/moq-mux/src/binary.rs b/rs/moq-mux/src/binary.rs index 7a470adc5b1..d0a18e93313 100644 --- a/rs/moq-mux/src/binary.rs +++ b/rs/moq-mux/src/binary.rs @@ -108,10 +108,11 @@ impl Snapshot { mut rendition: Rendition, config: &Config, ) -> crate::Result { - let inner = moq_binary::snapshot::Producer::new( - track, - moq_binary::snapshot::ProducerConfig::default().with_compression(config.compression), - ); + let mut binary = moq_binary::snapshot::Config::default(); + if config.compression { + binary.compression = moq_binary::Compression::Deflate; + } + let inner = moq_binary::snapshot::Producer::new(track, binary); rendition.set(config.entry(Mode::Snapshot))?; Ok(Self { inner, rendition }) } @@ -161,10 +162,11 @@ impl Stream { mut rendition: Rendition, config: &Config, ) -> crate::Result { - let inner = moq_binary::stream::Producer::new( - track, - moq_binary::stream::ProducerConfig::default().with_compression(config.compression), - ); + let mut binary = moq_binary::stream::Config::default(); + if config.compression { + binary.compression = moq_binary::Compression::Deflate; + } + let inner = moq_binary::stream::Producer::new(track, binary); rendition.set(config.entry(Mode::Stream))?; Ok(Self { inner, @@ -243,14 +245,20 @@ impl Consumer { 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), - )), + Mode::Snapshot => { + let mut binary = moq_binary::snapshot::Config::default(); + if compression { + binary.compression = moq_binary::Compression::Deflate; + } + Inner::Snapshot(moq_binary::snapshot::Consumer::new(track, binary)) + } + Mode::Stream => { + let mut binary = moq_binary::stream::Config::default(); + if compression { + binary.compression = moq_binary::Compression::Deflate; + } + Inner::Stream(moq_binary::stream::Consumer::new(track, binary)) + } other => return Err(crate::Error::UnsupportedMode(other.to_string())), }; diff --git a/rs/moq-mux/src/catalog/hang/consumer.rs b/rs/moq-mux/src/catalog/hang/consumer.rs index 1df876cc1b9..065f89b5632 100644 --- a/rs/moq-mux/src/catalog/hang/consumer.rs +++ b/rs/moq-mux/src/catalog/hang/consumer.rs @@ -28,7 +28,7 @@ impl Consumer { pub fn new(track: moq_net::track::Subscriber) -> Self { Self { base: track.broadcast().path.clone(), - inner: moq_json::snapshot::Consumer::new(track, moq_json::snapshot::ConsumerConfig::default()), + inner: moq_json::snapshot::Consumer::new(track, moq_json::snapshot::consumer::Config::default()), } } @@ -36,8 +36,8 @@ impl Consumer { /// /// The track must be the compressed one (see [`hang::Catalog::COMPRESSED_NAME`]). pub fn compressed(track: moq_net::track::Subscriber) -> Self { - let mut config = moq_json::snapshot::ConsumerConfig::default(); - config.compression = true; + let mut config = moq_json::snapshot::consumer::Config::default(); + config.compression = moq_json::Compression::Deflate; Self { base: track.broadcast().path.clone(), inner: moq_json::snapshot::Consumer::new(track, config), diff --git a/rs/moq-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index e1013bac744..6b4e74f96b3 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -294,13 +294,13 @@ impl Producer { let msf_track = broadcast.create_track(moq_msf::DEFAULT_NAME, msf_info)?; // Disable deltas for now to stay byte-compatible with consumers that only read snapshots. - let mut json_config = moq_json::snapshot::ProducerConfig::default(); + let mut json_config = moq_json::snapshot::Config::default(); json_config.delta_ratio = 0; let hang = moq_json::snapshot::Producer::new(hang_track.clone(), json_config.clone()); // The `.z` track carries the same catalog, DEFLATE-compressed. Deltas stay off for parity // with the plaintext track; only the per-group compression differs. - json_config.compression = true; + json_config.compression = moq_json::Compression::Deflate; let hangz = moq_json::snapshot::Producer::new(hangz_track, json_config); let timeline = crate::timeline::Producer::new(broadcast, crate::timeline::Config::default()); diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs index f8cbaea8c16..9e5211e360f 100644 --- a/rs/moq-mux/src/json.rs +++ b/rs/moq-mux/src/json.rs @@ -112,10 +112,11 @@ impl Snapshot { mut rendition: Rendition, config: &Config, ) -> crate::Result { - let inner = moq_json::snapshot::Producer::new( - track, - moq_json::snapshot::ProducerConfig::default().with_compression(config.compression), - ); + let mut json = moq_json::snapshot::Config::default(); + if config.compression { + json.compression = moq_json::Compression::Deflate; + } + let inner = moq_json::snapshot::Producer::new(track, json); rendition.set(config.entry(Mode::Snapshot))?; Ok(Self { inner, rendition }) } @@ -165,10 +166,11 @@ impl Stream { mut rendition: Rendition, config: &Config, ) -> crate::Result { - let inner = moq_json::stream::Producer::new( - track, - moq_json::stream::ProducerConfig::default().with_compression(config.compression), - ); + let mut json = moq_json::stream::Config::default(); + if config.compression { + json.compression = moq_json::Compression::Deflate; + } + let inner = moq_json::stream::Producer::new(track, json); rendition.set(config.entry(Mode::Stream))?; Ok(Self { inner, @@ -247,14 +249,20 @@ impl Consumer { 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), - )), + Mode::Snapshot => { + let mut json = moq_json::snapshot::consumer::Config::default(); + if compression { + json.compression = moq_json::Compression::Deflate; + } + Inner::Snapshot(moq_json::snapshot::Consumer::new(track, json)) + } + Mode::Stream => { + let mut json = moq_json::stream::Config::default(); + if compression { + json.compression = moq_json::Compression::Deflate; + } + Inner::Stream(moq_json::stream::Consumer::new(track, json)) + } other => return Err(crate::Error::UnsupportedMode(other.to_string())), }; diff --git a/rs/moq-stats/src/aggregate.rs b/rs/moq-stats/src/aggregate.rs index 13a9068c24b..3295489a7d7 100644 --- a/rs/moq-stats/src/aggregate.rs +++ b/rs/moq-stats/src/aggregate.rs @@ -260,7 +260,7 @@ struct Merged { depth: usize, /// Track name subscribed on each node broadcast. name: String, - config: moq_json::snapshot::ConsumerConfig, + config: moq_json::snapshot::consumer::Config, /// One entry per live node broadcast, keyed by absolute announced path. nodes: HashMap>, } @@ -273,7 +273,13 @@ impl Merged { prefix: config.prefix.clone(), depth: config.depth, name, - config: moq_json::snapshot::ConsumerConfig::default().with_compression(config.compression), + config: { + let mut json = moq_json::snapshot::consumer::Config::default(); + if config.compression { + json.compression = moq_json::Compression::Deflate; + } + json + }, nodes: HashMap::new(), } } @@ -385,7 +391,7 @@ impl Merged { fn advance( node: &mut Node, origin: &origin::Consumer, - config: &moq_json::snapshot::ConsumerConfig, + config: &moq_json::snapshot::consumer::Config, name: &str, waiter: &Waiter, ) -> bool { @@ -602,7 +608,7 @@ mod tests { source.announce(origin::Route::default()).expect("announce"); let name = traffic_track(&Tier::default(), Role::Publisher, false); let track = source.create_track(name, None).expect("create track"); - let config = moq_json::snapshot::ProducerConfig::default().with_delta_ratio(0); + let config = moq_json::snapshot::Config::default().with_delta_ratio(0); Self { traffic: moq_json::snapshot::Producer::new(track.clone(), config), track, diff --git a/rs/moq-stats/src/consume.rs b/rs/moq-stats/src/consume.rs index 1bb39fac6ce..7f44d5bd01d 100644 --- a/rs/moq-stats/src/consume.rs +++ b/rs/moq-stats/src/consume.rs @@ -68,7 +68,10 @@ impl Consumer { async fn subscribe(&self, name: &str) -> Result> { let track = self.broadcast.track(name)?.subscribe(None).await?; - let config = moq_json::snapshot::ConsumerConfig::default().with_compression(self.config.compression); + let mut config = moq_json::snapshot::consumer::Config::default(); + if self.config.compression { + config.compression = moq_json::Compression::Deflate; + } Ok(moq_json::snapshot::Consumer::new(track, config)) } } diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index 49e0e20443f..8a9a20edcee 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -399,8 +399,9 @@ impl TrackPair { } fn from_tracks(plain_track: track::Producer, compressed_track: track::Producer) -> Self { - let plain_config = moq_json::snapshot::ProducerConfig::default().with_delta_ratio(0); - let compressed_config = moq_json::snapshot::ProducerConfig::default().with_compression(true); + let plain_config = moq_json::snapshot::Config::default().with_delta_ratio(0); + let mut compressed_config = moq_json::snapshot::Config::default(); + compressed_config.compression = moq_json::Compression::Deflate; Self { plain: moq_json::snapshot::Producer::new(plain_track, plain_config), From 7f7229fbb457c2f10529595e1719d6c81fb27a76 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 03:46:55 -0700 Subject: [PATCH 2/4] docs(json): limit Config rename guidance to snapshot and stream Window still uses ProducerConfig / ConsumerConfig and boolean compression. Co-Authored-By: grok-4.6 --- doc/lib/js/json.md | 7 ++++--- doc/lib/rs/moq-json.md | 8 +++++--- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/doc/lib/js/json.md b/doc/lib/js/json.md index 64c540e08f9..235d9b2514a 100644 --- a/doc/lib/js/json.md +++ b/doc/lib/js/json.md @@ -13,9 +13,10 @@ JSON over [`@moq/net`](/lib/js/net) tracks, in three modes: - **Stream**: lossless append-log in a single group. - **Window**: a bounded run of records a reader can join at any point. -`Config` is the codec options. `Producer.Config` / `Consumer.Config` add the -track. Compression is a shared `"none" | "deflate"` enum, not a boolean: both -sides set the same field. +On Snapshot and Stream, `Config` is the codec options. `Producer.Config` / +`Consumer.Config` add the track. Compression is a shared `"none" | "deflate"` +enum, not a boolean: both sides set the same field. Window still uses +`ProducerConfig` / `ConsumerConfig` and a boolean `compression` flag. ```ts import { Snapshot } from "@moq/json"; diff --git a/doc/lib/rs/moq-json.md b/doc/lib/rs/moq-json.md index 0977265f8f7..9723a79968c 100644 --- a/doc/lib/rs/moq-json.md +++ b/doc/lib/rs/moq-json.md @@ -14,9 +14,11 @@ JSON over [`moq-net`](/lib/rs/moq-net) tracks, in three modes: - **stream**: lossless append-log in a single group. - **window**: a bounded run of records a reader can join at any point. -`Config` is the codec options. The track-owning pair is `producer::Config` / -`consumer::Config`. Compression is a shared `Compression` enum (`None` or -`Deflate`), not a bool: both sides set the same field. +On snapshot and stream, `Config` is the codec options. The track-owning pair is +`producer::Config` / `consumer::Config`. Compression is a shared `Compression` +enum (`None` or `Deflate`), not a bool: both sides set the same field. Window +still uses `ProducerConfig` / `ConsumerConfig` and a boolean `compression` +flag. ```rust let mut config = moq_json::snapshot::Config::default(); From 18fef8f3c04c7adfb8ec9a12dc7af5ea8c32e036 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 04:48:53 -0700 Subject: [PATCH 3/4] fix(json): crate-private is_deflate and a subscriber in the example Co-Authored-By: grok-4.6 --- doc/lib/js/json.md | 2 +- js/json/README.md | 4 ++-- rs/moq-binary/src/lib.rs | 3 +-- rs/moq-json/src/lib.rs | 3 +-- 4 files changed, 5 insertions(+), 7 deletions(-) diff --git a/doc/lib/js/json.md b/doc/lib/js/json.md index 235d9b2514a..d46843738b6 100644 --- a/doc/lib/js/json.md +++ b/doc/lib/js/json.md @@ -24,7 +24,7 @@ import { Snapshot } from "@moq/json"; const producer = new Snapshot.Producer({ track, compression: "deflate" }); producer.update({ hello: "world" }); -const consumer = new Snapshot.Consumer({ track, compression: "deflate" }); +const consumer = new Snapshot.Consumer({ track: track.subscribe(), compression: "deflate" }); for await (const value of consumer) { console.log(value); } diff --git a/js/json/README.md b/js/json/README.md index 82b225f821e..10eb2b80cf9 100644 --- a/js/json/README.md +++ b/js/json/README.md @@ -32,7 +32,7 @@ const producer = new Snapshot.Producer({ track }); producer.update({ hello: "world" }); // Consume: yields the latest reconstructed value, collapsing any backlog. -const consumer = new Snapshot.Consumer({ track }); +const consumer = new Snapshot.Consumer({ track: track.subscribe() }); for await (const value of consumer) { console.log(value); } @@ -51,7 +51,7 @@ const producer = new Stream.Producer({ track }); producer.append({ event: "started" }); producer.append({ event: "stopped" }); -const consumer = new Stream.Consumer({ track }); +const consumer = new Stream.Consumer({ track: track.subscribe() }); for await (const record of consumer) { console.log(record); } diff --git a/rs/moq-binary/src/lib.rs b/rs/moq-binary/src/lib.rs index 27c94d503f2..a38495c204b 100644 --- a/rs/moq-binary/src/lib.rs +++ b/rs/moq-binary/src/lib.rs @@ -39,8 +39,7 @@ pub enum Compression { } impl Compression { - /// Whether frames are DEFLATE-compressed. - pub const fn is_deflate(self) -> bool { + pub(crate) const fn is_deflate(self) -> bool { matches!(self, Self::Deflate) } } diff --git a/rs/moq-json/src/lib.rs b/rs/moq-json/src/lib.rs index a17fac6fa65..5bf688d22c7 100644 --- a/rs/moq-json/src/lib.rs +++ b/rs/moq-json/src/lib.rs @@ -36,8 +36,7 @@ pub enum Compression { } impl Compression { - /// Whether frames are DEFLATE-compressed. - pub const fn is_deflate(self) -> bool { + pub(crate) const fn is_deflate(self) -> bool { matches!(self, Self::Deflate) } } From a1828a5fe49e783a183b119716503395c9e35ad8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 05:16:58 -0700 Subject: [PATCH 4/4] fix(msf): keep colliding_member visible to release type-checking debug_assert type-checks its arguments without debug_assertions, so the helper cannot be cfg-gated. Co-Authored-By: grok-4.6 --- rs/moq-msf/src/lib.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/rs/moq-msf/src/lib.rs b/rs/moq-msf/src/lib.rs index b408e566214..ad2b61cc5f2 100644 --- a/rs/moq-msf/src/lib.rs +++ b/rs/moq-msf/src/lib.rs @@ -223,9 +223,8 @@ const CURRENT_VERSION: &str = "draft-01"; /// The extension's first member that collides with one MSF defines, if any. /// -/// Serializes the extension to inspect its member names, so it is only called under -/// `debug_assertions`. -#[cfg(debug_assertions)] +/// Serializes the extension to inspect its member names. Called from `debug_assert`, which +/// type-checks its arguments in release too, so this cannot be `cfg(debug_assertions)`. fn colliding_member(ext: &E) -> Option { match serde_json::to_value(ext) { Ok(serde_json::Value::Object(members)) => members.into_iter().map(|(name, _)| name).find(|n| reserved_root(n)),