diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index 2b1f516eb10..2b49aeef8cc 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON snapshot `deltaRatio` is `deltas` + +`SnapshotConfig.deltaRatio` is replaced by `bool deltas` (default `true`). +Pass `deltas: false` where you passed `deltaRatio: 0`, and drop the argument otherwise. +Publish the track with a `refresh` ratio so a joiner gets the value restated in a fresh group. + ### Priorities are signed (#6142) `TrackInfo.priority`, `Subscription.priority`, and `FetchGroupOptions.priority` take `-128..=127`, higher first, and 0 is the unset midpoint. diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index b94b2a2f438..f530ade4eea 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -930,9 +930,9 @@ class FfiConverterMoqFlateConfig { } class MoqJsonSnapshotConfig { - final int deltaRatio; + final bool deltas; final bool compression; - MoqJsonSnapshotConfig({this.deltaRatio = 8, this.compression = false}); + MoqJsonSnapshotConfig({this.deltas = true, this.compression = false}); } class FfiConverterMoqJsonSnapshotConfig { @@ -942,25 +942,25 @@ class FfiConverterMoqJsonSnapshotConfig { static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final deltaRatio_lifted = FfiConverterUInt32.read( + final deltas_lifted = FfiConverterBool.read( Uint8List.view(buf.buffer, new_offset), ); - final deltaRatio = deltaRatio_lifted.value; - new_offset += deltaRatio_lifted.bytesRead; + final deltas = deltas_lifted.value; + new_offset += deltas_lifted.bytesRead; final compression_lifted = FfiConverterBool.read( Uint8List.view(buf.buffer, new_offset), ); final compression = compression_lifted.value; new_offset += compression_lifted.bytesRead; return LiftRetVal( - MoqJsonSnapshotConfig(deltaRatio: deltaRatio, compression: compression), + MoqJsonSnapshotConfig(deltas: deltas, compression: compression), new_offset - buf.offsetInBytes, ); } static RustBuffer lower(MoqJsonSnapshotConfig value) { final total_length = - FfiConverterUInt32.allocationSize(value.deltaRatio) + + FfiConverterBool.allocationSize(value.deltas) + FfiConverterBool.allocationSize(value.compression) + 0; final buf = Uint8List(total_length); @@ -970,8 +970,8 @@ class FfiConverterMoqJsonSnapshotConfig { static int write(MoqJsonSnapshotConfig value, Uint8List buf) { int new_offset = buf.offsetInBytes; - new_offset += FfiConverterUInt32.write( - value.deltaRatio, + new_offset += FfiConverterBool.write( + value.deltas, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterBool.write( @@ -982,7 +982,7 @@ class FfiConverterMoqJsonSnapshotConfig { } static int allocationSize(MoqJsonSnapshotConfig value) { - return FfiConverterUInt32.allocationSize(value.deltaRatio) + + return FfiConverterBool.allocationSize(value.deltas) + FfiConverterBool.allocationSize(value.compression) + 0; } diff --git a/doc/lib/js/json.md b/doc/lib/js/json.md index 9aeb944122e..62c8d1f0631 100644 --- a/doc/lib/js/json.md +++ b/doc/lib/js/json.md @@ -12,9 +12,9 @@ are the catalog modes on the [hang](/concept/hang#data-tracks) page. Window is a third framing for a raw track: both ends opt into it, and a generic catalog reader will not pick it up. -- **Snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. A delta before any snapshot is an error. `next()` yields every state in order; `latest()` skips to the newest. +- **Snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. A delta before any snapshot is an error. `next()` yields every state in order; `latest()` skips to the newest. Deltas ride one group until a joiner wants a fresh one: give the track a `refresh` ratio (8 is typical) and the producer restates the value in a new group. Without a ratio a group rolls only at its caps. - **Stream**: lossless append-log in a single group. A reader that falls behind fails the read rather than resuming mid-log. -- **Window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice. +- **Window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice. Its ops roll on the track's `refresh` ratio the same way. Both sides choose the same compression, `"none"` or `"deflate"`. Producers take a `Timed` value, `{ value, at }`, where `at` is the capture time written as diff --git a/doc/lib/rs/moq-json.md b/doc/lib/rs/moq-json.md index 0b944f17eb8..7bcadde2df2 100644 --- a/doc/lib/rs/moq-json.md +++ b/doc/lib/rs/moq-json.md @@ -13,9 +13,9 @@ stream are the catalog modes on the [hang](/concept/hang#data-tracks) page. Window is a third framing for a raw track: both ends opt into it, and a generic catalog reader will not pick it up. -- **snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. An unchanged update publishes nothing. Several owners can edit their own keys in place instead of clobbering one document. +- **snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. An unchanged update publishes nothing. Several owners can edit their own keys in place instead of clobbering one document. Deltas ride one group until a joiner wants a fresh one: set the track's `refresh` ratio (8 is typical) and drive `Producer::refresh`, which restates the value in a new group. Without a ratio a group rolls only at its caps. - **stream**: lossless append-log in a single group. A reader that falls behind fails the read rather than resuming mid-log. -- **window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice. +- **window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice. Its ops roll on the track's `refresh` ratio the same way. Both sides choose the same compression. A bare value stays untimed; publish `moq_net::Timed::from(&value).at(captured)` to retain a capture timestamp. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index eae8355de43..68287cb9129 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON snapshot `DeltaRatio` is `Deltas` + +`json.SnapshotOptions.DeltaRatio *uint32` and `json.DefaultDeltaRatio` are replaced by `Deltas *bool` (nil enables deltas). +Set `Deltas` to a pointer to `false` where you set `DeltaRatio` to a pointer to `0`, and leave it nil otherwise. +Publish the track with a `Refresh` ratio so a joiner gets the value restated in a fresh group. + ### Priorities are signed (#6142) `TrackInfo.Priority`, `Subscription.Priority`, and `FetchGroupOptions.Priority` are `int8`, and `GroupRequest.Priority()` returns one. diff --git a/go/wrapper/json/json.go b/go/wrapper/json/json.go index 9a1293db8fd..257478b1081 100644 --- a/go/wrapper/json/json.go +++ b/go/wrapper/json/json.go @@ -20,26 +20,22 @@ import ( "moq.dev/moq/internal/bridge" ) -// DefaultDeltaRatio is used when [SnapshotOptions.DeltaRatio] is nil. Go has no field -// defaults, so unlike the other bindings this restates the `#[uniffi(default = 8)]` on -// moq-ffi's MoqJsonSnapshotConfig (itself pinned to moq-json's default by a Rust test). -const DefaultDeltaRatio uint32 = 8 - // SnapshotOptions configures a lossy latest-value JSON producer. type SnapshotOptions struct { - // DeltaRatio controls how aggressively deltas replace full snapshots. Nil uses - // [DefaultDeltaRatio]; a pointer to zero disables deltas entirely. - DeltaRatio *uint32 + // Deltas encodes updates as merge-patch deltas against the group's snapshot. Nil + // enables them, matching the other bindings; a pointer to false publishes every + // update as a full snapshot in its own group. With deltas on, give the track a + // refresh ratio so a joiner past it gets the value restated in a fresh group. + Deltas *bool // Compression enables group-scoped DEFLATE and must match on the consumer. Compression bool } -// deltaRatio resolves the configured ratio, falling back to the shared default. -func (o SnapshotOptions) deltaRatio() uint32 { - if o.DeltaRatio == nil { - return DefaultDeltaRatio - } - return *o.DeltaRatio +// deltas resolves the configured switch. Go has no field defaults, so this restates the +// `#[uniffi(default = true)]` on moq-ffi's MoqJsonSnapshotConfig (itself pinned to +// moq-json's default by a Rust test). +func (o SnapshotOptions) deltas() bool { + return o.Deltas == nil || *o.Deltas } // StreamOptions configures a lossless append-log JSON producer. @@ -69,7 +65,7 @@ func NewSnapshotProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProdu inner, err := ffi.NewMoqJsonSnapshotProducer( bridge.BroadcastProducer(broadcast), bridge.TrackProducer(track), - ffi.MoqJsonSnapshotConfig{DeltaRatio: options.deltaRatio(), Compression: options.Compression}, + ffi.MoqJsonSnapshotConfig{Deltas: options.deltas(), Compression: options.Compression}, ) if err != nil { return nil, err @@ -182,7 +178,7 @@ type SnapshotConsumer struct { // NewSnapshotConsumer reads track as a lossy latest-value JSON track. It takes over // track, whose handle is closed afterward, and fails if track has already read a group. func NewSnapshotConsumer(track *moq.TrackConsumer, options ConsumerOptions) (*SnapshotConsumer, error) { - // DeltaRatio is producer-only; the consumer ignores it. + // Deltas is producer-only; the consumer ignores it. inner, err := ffi.NewMoqJsonSnapshotConsumer( bridge.TrackConsumer(track), ffi.MoqJsonSnapshotConfig{Compression: options.Compression}, diff --git a/js/hang/src/catalog/consumer.test.ts b/js/hang/src/catalog/consumer.test.ts index 820f89d9451..8de5cca9a96 100644 --- a/js/hang/src/catalog/consumer.test.ts +++ b/js/hang/src/catalog/consumer.test.ts @@ -60,7 +60,7 @@ test("the shared containment check covers every section carrying a broadcast ref test("watch refuses an oversized catalog update", async () => { const broadcast = new Moq.Broadcast.Producer(); const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI }); - const producer = new Json.Snapshot.Producer({ track, deltaRatio: 0 }); + const producer = new Json.Snapshot.Producer({ track, deltas: false }); const consumer = watch(broadcast.consume())[Symbol.asyncIterator](); producer.update({ value: catalog(MAX_RENDITIONS + 1), at: Moq.Time.Timestamp.now() }); await expect(consumer.next()).rejects.toBeInstanceOf(TooManyRenditions); @@ -71,7 +71,7 @@ test("watch refuses an oversized catalog update", async () => { test("watch refuses a catalog needing a newer reader", async () => { const broadcast = new Moq.Broadcast.Producer(); const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI }); - const producer = new Json.Snapshot.Producer({ track, deltaRatio: 0 }); + const producer = new Json.Snapshot.Producer({ track, deltas: false }); const consumer = watch(broadcast.consume())[Symbol.asyncIterator](); producer.update({ value: { version: VERSION + 1 }, at: Moq.Time.Timestamp.now() }); await expect(consumer.next()).rejects.toBeInstanceOf(UnsupportedVersion); @@ -92,7 +92,7 @@ async function watchRequested(root: Root) { const origin = new Moq.Origin.Producer(); const broadcast = origin.createBroadcast(Moq.Path.from("room/alice")); const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI }); - const producer = new Json.Snapshot.Producer({ track, deltaRatio: 0 }); + const producer = new Json.Snapshot.Producer({ track, deltas: false }); broadcast.announce(); const request = origin.request(Moq.Path.from("room/alice")); const active = request.active.peek(); @@ -121,7 +121,7 @@ test("watch accepts a sibling reference under the same root and yields it unreso test("watch on a standalone broadcast refuses any parent reference", async () => { const broadcast = new Moq.Broadcast.Producer(); const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI }); - const producer = new Json.Snapshot.Producer({ track, deltaRatio: 0 }); + const producer = new Json.Snapshot.Producer({ track, deltas: false }); const consumer = watch(broadcast.consume())[Symbol.asyncIterator](); producer.update({ value: referencing("../bob"), at: Moq.Time.Timestamp.now() }); await expect(consumer.next()).rejects.toBeInstanceOf(EscapingBroadcast); @@ -132,7 +132,7 @@ test("watch on a standalone broadcast refuses any parent reference", async () => test("watch subscribes and yields typed catalog updates", async () => { const broadcast = new Moq.Broadcast.Producer(); const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI }); - const producer = new Json.Snapshot.Producer({ track, deltaRatio: 0 }); + const producer = new Json.Snapshot.Producer({ track, deltas: false }); const consumer = watch(broadcast.consume())[Symbol.asyncIterator](); producer.update({ value: catalog(1), at: Moq.Time.Timestamp.now() }); expect(await consumer.next()).toMatchObject({ value: catalog(1) }); diff --git a/js/json/MIGRATE.md b/js/json/MIGRATE.md index 3bf664a5d5e..0de64bf2179 100644 --- a/js/json/MIGRATE.md +++ b/js/json/MIGRATE.md @@ -4,6 +4,16 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Groups roll on joiner demand + +`Snapshot` `deltaRatio` and `Window` `opRatio` are replaced by `deltas` and `ops` booleans (both default `true`). +Pass `deltas: false` where you passed `deltaRatio: 0`, and `ops: false` where you passed `opRatio: 0`. +A group no longer rolls on a byte budget: create the track with a `refresh` ratio (`8` matches the old default), and the producer restates the value or window in a new group when a joiner asks. +Without a ratio a group rolls only at its frame and byte caps. +An `Encoder` user restates with `encoder.snapshot()` once `demand().wanted` passes the largest group it wrote. + +`encoder.value` (and so `producer.mutate()`) now holds the last committed value: a rejected publish no longer carries into the next edit, so retry the edit yourself if you still want it. + ### Duplicate keys are refused Every decoder throws `DuplicateKey` for a frame in which a JSON object repeats a key, where `JSON.parse` used to keep the last copy. diff --git a/js/json/README.md b/js/json/README.md index 173950b2dfc..0774fad9acd 100644 --- a/js/json/README.md +++ b/js/json/README.md @@ -42,7 +42,7 @@ for await (const { value, at } of consumer) { const current = await consumer.latest(); ``` -Pass `{ deltaRatio: x }` with a positive `x` to `Snapshot.Producer` to emit merge-patch deltas. A new snapshot group rolls once the deltas *already written* to the group exceed `x` times the fresh snapshot size; the delta that crosses the budget still lands first, so a group overshoots by at most one delta. `deltaRatio` defaults to `8` when unset. Set it to `0` to disable deltas: every change becomes a fresh single-frame snapshot group. Arrays are replaced wholesale within a delta; a value set to `null` falls back to a snapshot, since merge patch reads `null` as a key deletion. +Changes ride as merge-patch deltas by default; pass `{ deltas: false }` to make every change a fresh single-frame snapshot group. A group of deltas runs until a joiner wants a fresh one: give the track a `refresh` ratio (`track.accept({ refresh: 8 })`), and once the deltas outweigh that many snapshots a join asks for a new group, which the producer answers by restating the value at the newest timestamp written. Without a ratio a group rolls only at its frame or byte cap. Arrays are replaced wholesale within a delta; a value set to `null` falls back to a snapshot, since merge patch reads `null` as a key deletion. ### Stream: every record diff --git a/js/json/bench/codec.ts b/js/json/bench/codec.ts index 750d94a2ef3..fc993857930 100644 --- a/js/json/bench/codec.ts +++ b/js/json/bench/codec.ts @@ -9,7 +9,7 @@ for (const keys of [1, 10, 100, 1000]) { for (const compression of ["none", "deflate"] as const) { const samples: number[] = []; for (let sample = 0; sample < 3; sample++) { - const config = { deltaRatio: 100, compression }; + const config = { compression }; const encoder = new Encoder>(config); const decoder = new Decoder>(config); let value = Object.fromEntries(Array.from({ length: keys }, (_, n) => [`k${n}`, 0])); diff --git a/js/json/src/snapshot/codec.test.ts b/js/json/src/snapshot/codec.test.ts index cd9be372c64..805307e48b3 100644 --- a/js/json/src/snapshot/codec.test.ts +++ b/js/json/src/snapshot/codec.test.ts @@ -57,7 +57,7 @@ test("an unchanged value encodes nothing", () => { }); test("changes ride as deltas", () => { - const frames = encode({ deltaRatio: 100 }, [ + const frames = encode({ deltas: true }, [ { a: 1, b: 1 }, { a: 1, b: 2 }, { a: 1, b: 3 }, @@ -66,7 +66,7 @@ test("changes ride as deltas", () => { }); test("deltas off forces a keyframe per change", () => { - const frames = encode({ deltaRatio: 0 }, [{ a: 1 }, { a: 2 }]); + const frames = encode({ deltas: false }, [{ a: 1 }, { a: 2 }]); expect(frames.map((f) => f[0])).toEqual([true, true]); }); @@ -74,7 +74,7 @@ test("deltas off forces a keyframe per change", () => { // setting a field to JSON null reads as a key deletion. The encoder has to override the caller here, // which is why `keyframe` is a return value rather than a parameter. test("a null field forces a keyframe", () => { - const frames = encode({ deltaRatio: 100 }, [ + const frames = encode({ deltas: true }, [ { a: 1, b: 1 }, { a: 1, b: null }, ]); @@ -85,13 +85,13 @@ test("a null field forces a keyframe", () => { // would drop the key instead of reconstructing the null. test("a null inside a new object forces a keyframe", () => { const values = [{ items: {} }, { items: { a: { parent: null, n: 1 } } }]; - expect(roundtrip({ deltaRatio: 100 }, values)).toEqual(values); + expect(roundtrip({ deltas: true }, values)).toEqual(values); }); // A caller that closes the group behind the encoder's back has to say so, or the next value would be // a delta against a window and a baseline the new group never carried. test("reset forces the next update to be a keyframe", () => { - const encoder = new Encoder({ deltaRatio: 100 }); + const encoder = new Encoder({ deltas: true }); expect(commit(encoder, { a: 1 })?.keyframe).toBe(true); expect(commit(encoder, { a: 2 })?.keyframe).toBe(false); @@ -110,7 +110,7 @@ test("reset republishes an unchanged value", () => { }); test("the encoder tracks the published baseline", () => { - const encoder = new Encoder({ deltaRatio: 100 }); + const encoder = new Encoder({ deltas: true }); expect(encoder.value).toBeUndefined(); commit(encoder, { a: 1, b: 1 }); @@ -141,9 +141,55 @@ test("compressed roundtrip", () => { // 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: "deflate" }, values); - expect(got.at(-1)).toEqual({ n: 40 }); + // Past the frame cap, so the group rolls mid-stream. + const values: Doc[] = Array.from({ length: 300 }, (_, n) => ({ n })); + const got = roundtrip({ compression: "deflate" }, values); + expect(got.at(-1)).toEqual({ n: 299 }); +}); + +test("deltas off: every change is a keyframe", () => { + const frames = encode({ deltas: false }, [{ a: 1 }, { a: 2 }, { a: 3 }]); + expect(frames.map(([keyframe]) => keyframe)).toEqual([true, true, true]); +}); + +test("deltas never roll on their own", () => { + // Deltas far outweighing the snapshot still ride in its group: only a joiner or a cap rolls it. + const values: Doc[] = Array.from({ length: 100 }, (_, n) => ({ n, pad: "x".repeat(n) })); + const frames = encode({}, values); + expect(frames.filter(([keyframe]) => keyframe).length).toBe(1); +}); + +test("snapshot restates the last value", () => { + const encoder = new Encoder({ compression: "deflate" }); + expect(encoder.snapshot()).toBeUndefined(); + + commit(encoder, { a: 1, b: 1 }); + commit(encoder, { a: 1, b: 2 }); + const frame = encoder.snapshot(); + if (!frame) throw new Error("expected a snapshot"); + expect(frame.keyframe).toBe(true); + frame.commit(); + + // The restatement opens a fresh group (and DEFLATE window) a new decoder reads on its own, and + // the next change rides as a delta against it. + const decoder = new Decoder({ compression: "deflate" }); + decoder.snapshot(frame.payload); + expect(decoder.decode()).toEqual({ a: 1, b: 2 }); + const delta = encoder.update({ a: 1, b: 3 }); + if (!delta) throw new Error("expected a delta"); + expect(delta.keyframe).toBe(false); + decoder.delta(delta.payload); + delta.commit(); + expect(decoder.decode()).toEqual({ a: 1, b: 3 }); +}); + +test("an uncommitted snapshot resynchronizes", () => { + const encoder = new Encoder({}); + commit(encoder, { a: 1 }); + expect(encoder.snapshot()?.keyframe).toBe(true); + + // The restatement never reached the wire, so the next change opens a group of its own. + expect(encoder.update({ a: 2 })?.keyframe).toBe(true); }); test("no value before the first snapshot", () => { @@ -159,7 +205,7 @@ test("a delta before a snapshot throws", () => { // A backlog is applied in full but materialized once: the intermediate reconstructions are stale. test("frames apply without materializing", () => { - const encoder = new Encoder({ deltaRatio: 100 }); + const encoder = new Encoder({ deltas: true }); const decoder = new Decoder({}); for (let n = 0; n <= 20; n += 1) { @@ -178,10 +224,7 @@ 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: "deflate" }, [ - { note: phrase }, - { note: phrase, echo: phrase }, - ]); + const frames = encode({ deltas: true, 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; @@ -194,7 +237,7 @@ test("compressed deltas reuse the group window", () => { // resynchronize on its own: a caller cannot be relied on to remember. (Rust does this at drop; JS // has no destructor, so it happens on the next update.) test("an uncommitted frame resynchronizes the encoder", () => { - const encoder = new Encoder({ deltaRatio: 100 }); + const encoder = new Encoder({ deltas: true }); commit(encoder, { a: 1 }); expect(commit(encoder, { a: 2 })?.keyframe).toBe(false); @@ -220,7 +263,7 @@ test("an uncommitted first frame is re-encoded", () => { // The baseline is what the next delta is diffed against, so handing out the live object lets a // caller mutate it and make a real change look unchanged, silently starving consumers. test("the value getter does not expose the live baseline", () => { - const encoder = new Encoder({ deltaRatio: 100 }); + const encoder = new Encoder({ deltas: true }); commit(encoder, { a: 1 }); const leaked = encoder.value as { a: number }; @@ -240,7 +283,7 @@ test("a value JSON cannot represent is rejected", () => { // the newer frame, or a later loss of that one goes unnoticed. (Rust cannot express this: its // `Pending` borrows the encoder, so a second `update` while one is outstanding does not compile.) test("a stale commit does not clear a newer pending frame", () => { - const encoder = new Encoder({ deltaRatio: 100 }); + const encoder = new Encoder({ deltas: true }); const first = encoder.update({ a: 1 }); // The second update starts before the first frame settles, so the encoder resyncs around it. @@ -256,17 +299,29 @@ test("a stale commit does not clear a newer pending frame", () => { // The baseline is also what `Producer.mutate` seeds an edit from, so a resync must not erase it: // the next edit would otherwise publish a document with every other field missing. test("a resync keeps the value for mutate", () => { - const encoder = new Encoder({ deltaRatio: 100 }); + const encoder = new Encoder({ deltas: true }); commit(encoder, { video: "v1", scte35: 1 }); encoder.reset(); expect(encoder.value).toEqual({ video: "v1", scte35: 1 }); }); +// A frame that never reached the wire must not become the value a refresh restates or an edit +// starts from. (Mirrors the Rust `value_tracks_the_baseline`.) +test("an uncommitted frame leaves the value at the last committed", () => { + const encoder = new Encoder({ deltas: true }); + commit(encoder, { a: 1, b: 1 }); + commit(encoder, { a: 1, b: 2 }); + + encoder.update({ a: 1, b: 3 }); + expect(encoder.value).toEqual({ a: 1, b: 2 }); + expect(encoder.snapshot()?.payload).toEqual(new TextEncoder().encode(JSON.stringify({ a: 1, b: 2 }))); +}); + // The reconstruction is the base every later delta merges into, so handing out the live object lets // a caller change fields that no frame ever carried. test("the decoder does not expose its live reconstruction", () => { - const encoder = new Encoder({ deltaRatio: 100 }); + const encoder = new Encoder({ deltas: true }); const decoder = new Decoder({}); const snapshot = commit(encoder, { a: 1, b: 1 }); @@ -289,7 +344,7 @@ test("update after finish reports the closed track", async () => { const { Producer } = await import("./producer.ts"); const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100 }); + const producer = new Producer({ track, deltas: true }); producer.update({ value: { a: 1 } }); producer.update({ value: { a: 2 } }); // a delta, so a group is open producer.finish(); @@ -301,7 +356,7 @@ test("update after finish reports the closed track", async () => { // the delta budget. Matches the Rust `a_non_object_root_forces_a_keyframe`. test("a non-object root forces a keyframe", () => { // Typed as `unknown` because the root deliberately stops being an object partway through. - const encoder = new Encoder({ deltaRatio: 100 }); + const encoder = new Encoder({ deltas: true }); const object = encoder.update({ a: 1 }); object?.commit(); @@ -314,13 +369,11 @@ test("a non-object root forces a keyframe", () => { // The per-group frame cap rolls a new snapshot even when the byte budget is nowhere near spent, so a // late joiner can always read frame 0. Matches the Rust `frame_cap_forces_a_keyframe`. test("the frame cap forces a keyframe", () => { - // Mirrors MAX_DELTA_FRAMES in the encoder; a ratio this large takes the byte budget out of play, - // so the cap is the only thing that can roll the group. + // Mirrors MAX_DELTA_FRAMES in the encoder. const FRAME_CAP = 256; - const UNBOUNDED_RATIO = 1_000_000; const values: Doc[] = Array.from({ length: FRAME_CAP + 1 }, (_, n) => ({ n })); - const frames = encode({ deltaRatio: UNBOUNDED_RATIO }, values); + const frames = encode({ deltas: true }, values); // The snapshot plus FRAME_CAP - 1 deltas fill the group, then the cap rolls it. expect(frames.length).toBe(FRAME_CAP + 1); diff --git a/js/json/src/snapshot/compression.test.ts b/js/json/src/snapshot/compression.test.ts index c87cd02c0bd..3592819ed00 100644 --- a/js/json/src/snapshot/compression.test.ts +++ b/js/json/src/snapshot/compression.test.ts @@ -40,7 +40,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: "deflate" }); + const producer = new Producer({ track, deltas: false, compression: "deflate" }); producer.update({ value: { a: 1 } }); producer.update({ value: { a: 2 } }); producer.finish(); @@ -52,7 +52,7 @@ 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: "deflate" }); + const producer = new Producer({ track, deltas: true, compression: "deflate" }); const consumer = new Consumer({ track: track.subscribe(), compression: "deflate" }); for (let n = 1; n <= 5; 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: "deflate" }); + const producer = new Producer({ track, deltas: true, compression: "deflate" }); producer.update({ value: { a: 1, b: 1 } }); producer.update({ value: { a: 1, b: 2 } }); producer.update({ value: { 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: "deflate" }); + const producer = new Producer({ track, deltas: true, compression: "deflate" }); producer.update({ value: { a: 1, b: 1 } }); producer.update({ value: { a: 1, b: 2 } }); producer.update({ value: { 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: "deflate" }); + const producer = new Producer({ track, deltas: false, compression: "deflate" }); producer.update({ value: { 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: "deflate" }); + const producer = new Producer({ track, deltas: true, compression: "deflate" }); const phrase = "Media over QUIC delivers real-time latency at massive scale"; producer.update({ value: { note: phrase } }); producer.update({ value: { note: phrase, echo: phrase } }); @@ -121,24 +121,25 @@ test("compression shrinks a repetitive frame", async () => { const value = { renditions: Array(3).fill("video".repeat(50)) }; const plain = new Track.Producer("plain"); - new Producer({ track: plain, deltaRatio: 0 }).update({ value: value }); + new Producer({ track: plain, deltas: false }).update({ value: value }); const compressed = new Track.Producer("compressed"); - new Producer({ track: compressed, deltaRatio: 0, compression: "deflate" }).update({ value: value }); + new Producer({ track: compressed, deltas: false, compression: "deflate" }).update({ value: value }); const plainLen = (await firstFrame(plain.subscribe().ordered())).length; const compressedLen = (await firstFrame(compressed.subscribe().ordered())).length; expect(compressedLen).toBeLessThan(plainLen); }); -test("compressed deltas roll on the compressed budget", async () => { - // With compression the budget is measured on compressed frame sizes: #snapshotLen and #deltaBytes - // are the written slice lengths, not the raw JSON. A tight ratio over many distinct updates must - // roll more than one group, and a late joiner must still rebuild the final value across the - // compressed group boundary. Guards against the budget regressing to raw lengths. Two identical - // producers (deterministic output) keep the group-count and reconstruction reads independent. +test("compressed deltas reconstruct across group boundaries", async () => { + // Each group opens a fresh DEFLATE window, so a late joiner must rebuild the final value across + // the compressed boundaries. 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: "deflate" }); - for (let n = 0; n <= 40; n++) producer.update({ value: { n } }); + const producer = new Producer({ track, compression: "deflate" }); + for (let n = 0; n <= 40; n++) { + producer.update({ value: { n } }); + if (n % 7 === 6) producer.cut(); + } producer.finish(); }; diff --git a/js/json/src/snapshot/encoder.ts b/js/json/src/snapshot/encoder.ts index cf0fe652978..f62688666c4 100644 --- a/js/json/src/snapshot/encoder.ts +++ b/js/json/src/snapshot/encoder.ts @@ -9,26 +9,16 @@ import { deepEqual, diff } from "../diff.ts"; // well below the per-group frame cap so a late joiner can always read the snapshot at frame 0. const MAX_DELTA_FRAMES = 256; -// Delta ratio used when {@link Config.deltaRatio} is left unset. Not re-exported from the package -// entrypoint: the Producer needs it to know whether to hold a group open, nothing else does. -export const DEFAULT_DELTA_RATIO = 8; - /** Options shared by an {@link Encoder} and the {@link Producer} that wraps one. */ export interface Config { - // Controls how aggressively the encoder emits deltas (merge patches) instead of full snapshots. - // - // `0` disables deltas: every change is encoded as a new snapshot. + // Encode changes as deltas (merge patches) against the group's snapshot. `false` encodes every + // change as a new snapshot in its own group. // - // A positive number enables deltas: a new snapshot is emitted once the deltas already written - // to the current group (excluding the snapshot frame) exceed `deltaRatio` times the snapshot size. - // The pending delta is excluded from that check, so the one that first crosses the budget still - // lands before the group rolls. So `1` allows roughly one snapshot's worth of deltas before rolling. + // A group of deltas runs until a joiner wants a fresh one, judged by the track's `refresh` ratio + // (see {@link Encoder.snapshot}), or until it reaches the frame or byte cap. // - // When {@link compression} is on, both sides of the comparison are measured on the compressed frame - // sizes (the real wire cost). - // - // Defaults to `8` when unset. - deltaRatio?: number; + // Defaults to `true`. + deltas?: boolean; // Optional zod schema used to validate each value before publishing. schema?: z.ZodMiniType; @@ -64,8 +54,8 @@ export interface Encoded { * merge patch that must be appended to the group the last snapshot opened. * * The encoder decides this, never the caller: a value that sets a field to JSON null, or whose - * root isn't an object, cannot be expressed as a merge patch at all, and the delta budget and - * frame cap force a snapshot independently of what the caller wanted. + * root isn't an object, cannot be expressed as a merge patch at all, and the frame and byte caps + * force a snapshot independently of what the caller wanted. */ keyframe: boolean; } @@ -73,17 +63,19 @@ export interface Encoded { /** * An encoded frame the caller has not yet acknowledged writing, returned by {@link Encoder.update}. * - * Write the frame, then {@link commit}. A frame that is never committed never reached the wire, so - * the encoder resynchronizes on the next {@link Encoder.update}: it starts a fresh snapshot rather - * than emitting deltas against a baseline no consumer received. + * Write the frame, then {@link commit}. The frame's value is staged until commit, so one that is + * never committed leaves {@link Encoder.value} at the last value that reached the wire, and the + * encoder resynchronizes on the next {@link Encoder.update}: it starts a fresh snapshot rather than + * emitting deltas against a group no consumer received. * - * This is a recovery, not a rollback. Producing a delta payload advances the group's DEFLATE window - * and that can't be undone, so a snapshot is the only sound way back. Forgetting to commit a frame - * that *was* written is therefore merely wasteful (one redundant snapshot), never incorrect. + * The group state is a recovery, not a rollback. Producing a delta payload advances the group's + * DEFLATE window and that can't be undone, so a snapshot is the only sound way back. Forgetting to + * commit a frame that *was* written therefore costs one redundant snapshot and leaves the value a + * step behind, but never corrupts the stream. */ export interface Pending extends Encoded { /** - * Acknowledge that the frame reached the wire, keeping the encoder's state. + * Acknowledge that the frame reached the wire, applying its value to the baseline. * * Only call this once the write has actually succeeded. Committing a frame that failed to write * is the one thing that corrupts the stream. @@ -116,16 +108,13 @@ export class Encoder { #compress: boolean; #maxGroupBytes: number; - // The last encoded value, normalized through JSON so it matches what landed on the wire. The - // baseline every delta is diffed against, and `undefined` until the first snapshot. + // The last committed value, normalized through JSON so it matches what landed on the wire. The + // baseline every delta is diffed against, and `undefined` until the first snapshot commits. #last?: unknown; - // Bytes of deltas already emitted into the current group, excluding the snapshot frame. Compressed - // frame sizes when compressing, raw otherwise, matching {@link #snapshotLen} so the budget check is - // like-for-like (and identical to the Rust encoder). - #deltaBytes = 0; - // Size of the current group's snapshot frame, the reference the delta budget is measured against. - #snapshotLen = 0; + // Bytes emitted into the current group, snapshot included: compressed frame sizes when + // compressing, raw otherwise, matching what the group holds on the wire. + #groupBytes = 0; // Frames emitted into the current group, snapshot included. #groupFrames = 0; @@ -153,9 +142,10 @@ export class Encoder { } /** - * A copy of the last encoded value, or `undefined` before the first snapshot. + * A copy of the last committed value, or `undefined` before the first snapshot commits. * - * Copied rather than shared: the baseline is what the next delta is diffed against, so a caller + * A frame left uncommitted never reached the wire, so its value never lands here. Copied rather + * than shared: the baseline is what the next delta is diffed against, so a caller * mutating it in place would make a later change look unchanged and never reach consumers. */ get value(): T | undefined { @@ -174,8 +164,7 @@ export class Encoder { */ reset(): void { this.#flate = undefined; - this.#deltaBytes = 0; - this.#snapshotLen = 0; + this.#groupBytes = 0; this.#groupFrames = 0; this.#resync = true; this.#pending = false; @@ -184,14 +173,14 @@ export class Encoder { /** * Encode a new value, as a snapshot or a delta. * - * Returns `undefined` when the value is unchanged from the last one encoded, so nothing needs to - * be written. Otherwise the frame comes back as a {@link Pending} the caller writes and then + * Returns `undefined` when the value is unchanged from the last one committed, so nothing needs + * to be written. Otherwise the frame comes back as a {@link Pending} the caller writes and then * commits; leaving one uncommitted resynchronizes the encoder here, on the next call. */ update(value: T): Pending | undefined { - // The previous frame was never acknowledged, so it never reached the wire. Drop the baseline - // and the DEFLATE window so this value goes out as a fresh snapshot rather than as a patch - // against a state no consumer holds. + // The previous frame was never acknowledged, so it never reached the wire. Drop the DEFLATE + // window so this value goes out as a fresh snapshot rather than as a patch against a state no + // consumer holds. if (this.#pending) this.reset(); const valid = this.#config.schema ? this.#config.schema.parse(value) : value; @@ -213,9 +202,9 @@ export class Encoder { const delta = this.#delta(json); - // Compress only after the diff, and advance the baseline only once the payload exists: framing - // can throw, and a baseline ahead of the wire would make the next delta unreadable. Matches the - // Rust encoder, which completes every fallible step before mutating state. + // Compress only after the diff, and advance the group only once the payload exists: framing can + // throw. The baseline advances on commit, so it never runs ahead of the wire. Matches the Rust + // encoder, which completes every fallible step before mutating state. if (delta) { const payload = this.#frame(delta); @@ -228,21 +217,34 @@ export class Encoder { // can come out slightly larger than its input, so the plaintext is not an upper bound. // Compressing first advances the window, but `#snapshot` opens a fresh one, so an // over-budget delta costs only the wasted compression. - if (this.#snapshotLen + this.#deltaBytes + payload.length <= this.#maxGroupBytes) { - this.#last = json; - this.#deltaBytes += payload.length; + if (this.#groupBytes + payload.length <= this.#maxGroupBytes) { + this.#groupBytes += payload.length; this.#groupFrames += 1; - return this.#pend({ payload, keyframe: false }); + return this.#pend({ payload, keyframe: false }, json); } } const payload = this.#snapshot(new TextEncoder().encode(text)); - this.#last = json; - return this.#pend({ payload, keyframe: true }); + return this.#pend({ payload, keyframe: true }, json); } - // Hand a frame to the caller, marking it unacknowledged until they commit. - #pend(encoded: Encoded): Pending { + /** + * Restate the last committed value as a full snapshot, which must open a new group. + * + * For a caller that opens groups itself: call it when a joiner wants a fresh group, such as when + * the track's `demand().wanted` passes the largest group written, so the joiner reads the value + * without the deltas before it. Returns `undefined` before the first value, when there is nothing + * to restate. The frame is a {@link Pending} like any other. + */ + snapshot(): Pending | undefined { + if (this.#last === undefined) return undefined; + const payload = this.#snapshot(new TextEncoder().encode(JSON.stringify(this.#last))); + return this.#pend({ payload, keyframe: true }, this.#last); + } + + // Hand a frame to the caller, marking it unacknowledged until they commit, when `value` becomes + // the baseline. + #pend(encoded: Encoded, value: unknown): Pending { this.#pending = true; const generation = ++this.#generation; @@ -252,34 +254,23 @@ export class Encoder { // A caller that starts the next update before this frame settles has already made the // encoder resynchronize around it. Acknowledging it now would clear the flag belonging to // the newer frame, so a later loss of that one would go unnoticed. - if (this.#generation === generation) this.#pending = false; + if (this.#generation !== generation) return; + this.#pending = false; + this.#last = value; }, }; } - // Resolved delta ratio: the configured value, or the default when unset. `0` disables deltas. - get #deltaRatio(): number { - return this.#config.deltaRatio ?? DEFAULT_DELTA_RATIO; - } - // Build a delta frame, or `undefined` to signal that a fresh snapshot should be emitted. - // - // The budget gate runs first, against the deltas already written, so rolling a new group costs no - // merge-patch work. Since the gate excludes the frame about to be written, the delta that tips the - // group past `ratio * snapshot` still lands: a group overshoots the budget by at most one delta. #delta(json: unknown): Uint8Array | undefined { // A lost frame, or a group the caller closed, leaves the consumer's state unknown, so the next // frame has to be a full snapshot. if (this.#resync) return undefined; - const ratio = this.#deltaRatio; - if (ratio === 0) return undefined; + if (this.#config.deltas === false) return undefined; if (this.#last === undefined) return undefined; if (this.#groupFrames === 0 || this.#groupFrames >= MAX_DELTA_FRAMES) return undefined; - // Gate on the deltas accumulated so far (snapshot frame excluded), before computing the patch. - if (this.#deltaBytes > ratio * this.#snapshotLen) return undefined; - const result = diff(this.#last, json); if (result.forcedSnapshot) return undefined; @@ -308,8 +299,7 @@ export class Encoder { const payload = flate ? flate.frame(frame) : frame; this.#flate = flate; - this.#snapshotLen = payload.length; - this.#deltaBytes = 0; + this.#groupBytes = payload.length; this.#groupFrames = 1; this.#resync = false; diff --git a/js/json/src/snapshot/index.ts b/js/json/src/snapshot/index.ts index a6b4d103fea..3bb074e92f8 100644 --- a/js/json/src/snapshot/index.ts +++ b/js/json/src/snapshot/index.ts @@ -13,7 +13,10 @@ * following frames are RFC 7396 JSON Merge Patch deltas applied in order. Interoperable with the * Rust `moq_json::snapshot`. * - * The encoder rolls a group on its own budget, but a caller can roll one for its own reasons with + * A group of deltas runs until a joiner wants a fresh one: once the deltas outweigh the track's + * `refresh` ratio times the snapshot, a join asks for a group past the largest, and the + * {@link Producer} restates the value there. The encoder also rolls at its frame and byte caps. + * A caller can roll one for its own reasons with * {@link Producer.cut}: it closes the open group and leaves the next update to open the replacement * with a full snapshot, so the deltas already written stop being provisional without publishing an * empty group. diff --git a/js/json/src/snapshot/producer.ts b/js/json/src/snapshot/producer.ts index 72e91649c62..638c40e59ad 100644 --- a/js/json/src/snapshot/producer.ts +++ b/js/json/src/snapshot/producer.ts @@ -1,7 +1,7 @@ import type { Time, Timed } from "@moq/net"; import * as Moq from "@moq/net"; -import { type Config as CodecConfig, DEFAULT_DELTA_RATIO, type Encoded, Encoder } from "./encoder.ts"; +import { type Config as CodecConfig, type Encoded, Encoder } from "./encoder.ts"; /** * Publishes a JSON value over a track, choosing snapshots and deltas automatically. @@ -9,6 +9,11 @@ import { type Config as CodecConfig, DEFAULT_DELTA_RATIO, type Encoded, Encoder * An {@link Encoder} that owns its track: it writes each encoded frame and rolls a group whenever * the encoder emits a snapshot. When something else already owns the track, use the {@link Encoder} * directly. + * + * A group of deltas runs until a joiner wants a fresh one: once the deltas outweigh the track's + * `refresh` ratio times the snapshot, a join asks for a group past the largest, and the producer + * restates the value there at the newest timestamp written. Set the ratio when creating the + * track, or joins never ask. */ export class Producer { #track: Moq.Track.Producer; @@ -21,11 +26,38 @@ export class Producer { // is closed the moment it's written and never held open. #deltas: boolean; + // The sequence of the newest group written, which a joiner's wanted group has to pass. + #largest?: number; + // The newest timestamp written, which a refresh restates the value at. An update may carry an + // older timestamp than its group's first frame, and a new group may not start before that one. + #at?: Time.Timestamp; + // Stops watching the track's demand. + #unwatch?: () => void; + constructor(config: Producer.Config) { this.#track = config.track; this.#encoder = new Encoder(config); this.#initial = config.initial; - this.#deltas = (config.deltaRatio ?? DEFAULT_DELTA_RATIO) !== 0; + this.#deltas = config.deltas !== false; + + // With deltas off every group holds one frame, so no join ever asks for a fresh one. + if (this.#deltas) this.#unwatch = this.#track.demand().wanted.subscribe((wanted) => this.#refresh(wanted)); + } + + // Restate the value in a new group once a joiner wants one past the largest written. + #refresh(wanted: number | undefined): void { + if (wanted === undefined || this.#largest === undefined || wanted <= this.#largest) return; + const frame = this.#encoder.snapshot(); + if (!frame) return; + + // Nobody awaits a refresh, so a failed write has no caller to report to. Abort the track rather + // than leave its newest group without the value, where a latest-value subscriber would wait. + try { + this.#write(frame, this.#at); + frame.commit(); + } catch (err) { + this.#close(err instanceof Error ? err : new Error(String(err))); + } } /** @@ -62,9 +94,11 @@ export class Producer { if (!frame) return; // A throw here leaves the frame uncommitted, so the next update resynchronizes with a fresh - // snapshot. A delta against a snapshot no consumer ever saw would be unreadable. + // snapshot. A delta against a snapshot no consumer ever saw would be unreadable. The value + // stays the last one written, so a refresh restates that rather than the rejection. this.#write(frame, at); frame.commit(); + if (at && !at.isBefore(this.#at ?? at)) this.#at = at; } #write(encoded: Encoded, at: Time.Timestamp | undefined): void { @@ -81,6 +115,7 @@ export class Producer { this.#group = undefined; const group = this.#track.appendGroup(); + this.#largest = group.sequence; try { group.writeFrame({ payload: encoded.payload, timestamp: at }); } catch (err) { @@ -125,11 +160,10 @@ export class Producer { * starts from the latest value, so sections compose instead of clobbering one another. Use * {@link update} to replace the whole value instead. * - * After a rejected write the current value is what the producer last *tried* to publish, which - * consumers never received. That is deliberate: dropping a rejected owner's field would clobber it - * for whoever edits next, which is the failure this API exists to prevent. The owner whose write - * failed sees the error, and the next successful publish is a full snapshot carrying the composed - * value, so consumers converge on it either way. + * A rejected edit never reached the wire, so the current value stays the last one that did. The + * owner whose write failed sees the error and can retry; carrying the rejected edit forward would + * instead fail every later owner's publish the same way, or publish a value its owner was told + * failed. */ mutate(fn: (value: T) => void, at?: Time.Timestamp): void { // Start from the last-published value, falling back to the configured initial value. We @@ -146,14 +180,20 @@ export class Producer { /** Finish the track, closing any open group. */ finish(): void { - this.#group?.close(); + this.#close(); + } + + #close(abort?: Error): void { + this.#unwatch?.(); + this.#unwatch = undefined; + this.#group?.close(abort); this.#group = undefined; // The open group goes with the track, so the encoder must not keep emitting deltas into it. // Any further update fails on the closed track, but it has to fail as a track error rather // than as a delta with nowhere to put it. this.#encoder.reset(); - this.#track.close(); + this.#track.close(abort); } } diff --git a/js/json/src/snapshot/properties.test.ts b/js/json/src/snapshot/properties.test.ts index e777b0179e0..08658d05866 100644 --- a/js/json/src/snapshot/properties.test.ts +++ b/js/json/src/snapshot/properties.test.ts @@ -4,7 +4,7 @@ import { Decoder } from "./decoder.ts"; import { Encoder } from "./encoder.ts"; type Json = null | boolean | number | string | Json[] | { [key: string]: Json }; -type Step = { value: Json; reset: boolean }; +type Step = { value: Json; reset: boolean; restate: boolean }; // Mirror the Rust generator: bounded JSON trees plus edits to a persistent // object, so sequences exercise deltas as well as unrelated snapshot roots. @@ -27,17 +27,19 @@ const value: fc.Arbitrary = fc.letrec<{ value: Json }>((tie) => ({ ), })).value; const reset = fc.integer({ min: 0, max: 15 }).map((n) => n === 0); -const roots = fc.array(fc.record({ value, reset }), { minLength: 1, maxLength: 32 }); +// Restate the value before the step with `Encoder.snapshot`, as a refresh does. +const restate = fc.integer({ min: 0, max: 15 }).map((n) => n === 0); +const roots = fc.array(fc.record({ value, reset, restate }), { minLength: 1, maxLength: 32 }); const edits = fc - .array(fc.record({ key, value, remove: fc.boolean(), reset }), { minLength: 1, maxLength: 32 }) + .array(fc.record({ key, value, remove: fc.boolean(), reset, restate }), { minLength: 1, maxLength: 32 }) .map((edits): Step[] => { let current: Record = {}; - return edits.map(({ key, value, remove, reset }) => { + return edits.map(({ key, value, remove, reset, restate }) => { const next = { ...current }; if (remove) delete next[key]; else Object.defineProperty(next, key, { value, enumerable: true, configurable: true, writable: true }); current = next; - return { value: next, reset }; + return { value: next, reset, restate }; }); }); @@ -55,27 +57,33 @@ test("snapshot codec property reconstructs each JSON value", () => { const seed = setting("MOQ_JSON_SEED", 0x6d6f71, 0); const numRuns = setting("MOQ_JSON_CASES", 256, 1); fc.assert( - fc.property( - fc.constantFrom(0, 1, 2, 8, 100), - fc.boolean(), - fc.oneof(roots, edits), - (deltaRatio, deflate, steps) => { - const config = { deltaRatio, compression: deflate ? ("deflate" as const) : ("none" as const) }; - const encoder = new Encoder(config); - const decoder = new Decoder(config); - for (const { value, reset } of steps) { - if (reset) encoder.reset(); - const frame = encoder.update(value); + fc.property(fc.boolean(), fc.boolean(), fc.oneof(roots, edits), (deltas, deflate, steps) => { + const config = { deltas, compression: deflate ? ("deflate" as const) : ("none" as const) }; + const encoder = new Encoder(config); + const decoder = new Decoder(config); + for (const { value, reset, restate } of steps) { + if (reset) encoder.reset(); + if (restate) { + const before = decoder.decode(); + const frame = encoder.snapshot(); + expect(frame === undefined).toBe(before === undefined); if (frame) { - if (frame.keyframe) decoder.snapshot(frame.payload); - else decoder.delta(frame.payload); + expect(frame.keyframe).toBe(true); + decoder.snapshot(frame.payload); frame.commit(); + expect(decoder.decode()).toEqual(before); } - // JSON serialization defines the domain, including its normalization. - expect(decoder.decode()).toEqual(JSON.parse(JSON.stringify(value))); } - }, - ), + const frame = encoder.update(value); + if (frame) { + if (frame.keyframe) decoder.snapshot(frame.payload); + else decoder.delta(frame.payload); + frame.commit(); + } + // JSON serialization defines the domain, including its normalization. + expect(decoder.decode()).toEqual(JSON.parse(JSON.stringify(value))); + } + }), { seed, numRuns }, ); }); diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 34431979ab8..b6357f525f6 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -43,7 +43,7 @@ async function structure(track: Track.Ordered): Promise { test("a cut makes the next update a snapshot group", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100 }); + const producer = new Producer({ track, deltas: true }); producer.update({ value: { a: 1, b: 1 } }); producer.update({ value: { a: 1, b: 2 } }); producer.cut(); @@ -58,7 +58,7 @@ test("a cut makes the next update a snapshot group", async () => { test("a cut republishes an unchanged value", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100 }); + const producer = new Producer({ track, deltas: true }); producer.update({ value: { a: 1 } }); producer.cut(); @@ -72,7 +72,7 @@ test("a cut republishes an unchanged value", async () => { test("a cut opens no replacement group", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100 }); + const producer = new Producer({ track, deltas: true }); producer.update({ value: { a: 1 } }); producer.cut(); producer.finish(); @@ -83,7 +83,7 @@ test("a cut opens no replacement group", async () => { test("a cut is idempotent", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100 }); + const producer = new Producer({ track, deltas: true }); // Nothing published yet, so there is no group to cut. producer.cut(); @@ -101,7 +101,7 @@ test("a cut is idempotent", async () => { test("a cut is inert without deltas", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 0 }); + const producer = new Producer({ track, deltas: false }); producer.update({ value: { a: 1 } }); // With deltas off every frame already closes its own group, so there is never one to cut. @@ -114,7 +114,7 @@ test("a cut is inert without deltas", async () => { test("deltas off: a snapshot group per change", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 0 }); + const producer = new Producer({ track, deltas: false }); producer.update({ value: { a: 1 } }); producer.update({ value: { a: 2 } }); producer.finish(); @@ -126,33 +126,21 @@ test("deltas off: a snapshot group per change", async () => { expect(await drainLatest(track.subscribe({ maxDelay: REPLAY_LATENCY }))).toEqual([{ a: 2 }]); }); -test("deltaRatio 0 disables deltas, like off", async () => { - const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 0 }); - producer.update({ value: { a: 1 } }); - producer.update({ value: { a: 2 } }); - producer.finish(); - - // `0` is treated as off, not a degenerate "enabled" value that keeps the group open: each change - // is its own single-frame snapshot group. - expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([1, 1]); -}); - // `latest()` holding a group must jump when a newer snapshot group rolls: the // buffered deltas in the held group only reconstruct superseded state, and every // group restarts from a full snapshot (mirrors the Rust consumer, which drains to // the newest group on every poll). test("latest abandons a held group when a newer snapshot group rolls", async () => { const track = new Track.Producer("test"); - // A tiny ratio forces the update after any delta to roll a fresh snapshot group. - const producer = new Producer({ track, deltaRatio: 0.001 }); + const producer = new Producer({ track }); const consumer = new Consumer({ track: track.subscribe({ maxDelay: REPLAY_LATENCY }) }); producer.update({ value: { a: 1 } }); expect((await consumer.latest())?.value).toEqual({ a: 1 }); - // A delta lands in the held group, then the ratio rolls a new snapshot group. + // A delta lands in the held group, then a cut rolls a new snapshot group. producer.update({ value: { a: 2 } }); + producer.cut(); producer.update({ value: { a: 3 } }); producer.finish(); @@ -163,13 +151,14 @@ test("latest abandons a held group when a newer snapshot group rolls", async () // `next()` finishes the held group before the newer one, so a playhead sees every state. test("next reads a held group out before a newer snapshot group", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 0.001 }); + const producer = new Producer({ track }); const consumer = new Consumer({ track: track.subscribe({ maxDelay: REPLAY_LATENCY }) }); producer.update({ value: { a: 1 } }); expect((await consumer.next())?.value).toEqual({ a: 1 }); producer.update({ value: { a: 2 } }); + producer.cut(); producer.update({ value: { a: 3 } }); producer.finish(); @@ -182,7 +171,7 @@ test("next reads a held group out before a newer snapshot group", async () => { // as on any ordered track, so a reader that falls behind jumps ahead instead of replaying it. test("next skips the groups the max delay abandons", async () => { const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI }); - const producer = new Producer({ track, deltaRatio: 0 }); + const producer = new Producer({ track, deltas: false }); for (let n = 1; n <= 3; n++) producer.update({ value: { n }, at: Time.Timestamp.fromMillis(n * 1_000) }); producer.finish(); @@ -215,7 +204,7 @@ test("unchanged value writes nothing", async () => { test("deltas share one group", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100 }); + const producer = new Producer({ track, deltas: true }); producer.update({ value: { a: 1, b: 1 } }); producer.update({ value: { a: 1, b: 2 } }); producer.update({ value: { a: 1, b: 3 } }); @@ -227,7 +216,7 @@ test("deltas share one group", async () => { test("deltas reconstruct to the final value", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100 }); + const producer = new Producer({ track, deltas: true }); producer.update({ value: { a: 1, b: 1 } }); producer.update({ value: { a: 1, b: 2 } }); producer.update({ value: { a: 5, b: 2 } }); @@ -267,6 +256,30 @@ test("mutate starts from the configured initial value", async () => { expect((await consumer.next())?.value).toEqual({ a: 1 }); }); +// A rejected edit never reached the wire, so the next owner starts from the last value that did. +// Carrying the rejected edit forward would fail every later publish the same way. (Mirrors the Rust +// `a_rejected_edit_leaves_modify_at_the_last_written_value`.) +test("a rejected mutate leaves the value at the last one written", async () => { + const track = new Track.Producer("test"); + const producer = new Producer({ track, initial: {} }); + producer.mutate((v) => { + v.video = "v1"; + }); + + // Serializes past the group cache limit, so the frame cannot be published. + expect(() => + producer.mutate((v) => { + v.big = "x".repeat(Group.MAX_GROUP_CACHE_BYTES + 1); + }), + ).toThrow(NetError.FrameTooLarge); + + producer.mutate((v) => { + v.scte35 = 42; + }); + producer.finish(); + expect(await drainLatest(track.subscribe())).toEqual([{ video: "v1", scte35: 42 }]); +}); + test("mutate without a prior value or initial throws", () => { const producer = new Producer({ track: new Track.Producer("test") }); expect(() => producer.mutate(() => {})).toThrow(); @@ -276,7 +289,7 @@ test("mutate without a prior value or initial throws", () => { // Exercised with deltas on to cover the merge-patch null-deletion path. test("mutate removes a section", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100, initial: {} }); + const producer = new Producer({ track, deltas: true, initial: {} }); const consumer = new Consumer({ track: track.subscribe() }); producer.mutate((v) => { @@ -291,38 +304,161 @@ test("mutate removes a section", async () => { expect((await consumer.next())?.value).toEqual({ a: 1 }); }); -test("tight ratio rolls snapshots", async () => { - const track = new Track.Producer("test"); - // A ratio of 1 budgets deltas up to one snapshot (equal 7-byte frames => 7 bytes). The gate checks - // the deltas already written, so the delta that tips the group over budget still lands (a one-frame - // overshoot): group 0 takes two deltas (14 bytes) before the fourth update rolls group 1. - const producer = new Producer({ track, deltaRatio: 1 }); - producer.update({ value: { a: 1 } }); // snapshot, group 0 - producer.update({ value: { a: 2 } }); // delta, group 0 (deltas = 7) - producer.update({ value: { a: 3 } }); // delta, group 0 (deltas = 14, now over budget) - producer.update({ value: { a: 4 } }); // budget already exceeded, rolls group 1 +// Let the producer see a demand change, which the signal delivers in a microtask. +async function settle(): Promise { + await new Promise((resolve) => queueMicrotask(resolve)); +} + +// Publish `{"n":0}` through `{"n":3}`: a 7-byte snapshot and 21 bytes of deltas. +function fill(producer: Producer): void { + for (let n = 0; n <= 3; n++) producer.update({ value: { n } }); +} + +test("deltas never roll without a joiner", async () => { + const track = new Track.Producer("test").accept({ refresh: 1 }); + const producer = new Producer({ track }); + for (let n = 0; n <= 10; n++) producer.update({ value: { n } }); + producer.finish(); + + // The deltas outweigh the snapshot ten times over, but nobody joined to ask for a fresh group. + expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([11]); +}); + +test("a joiner over the ratio gets a fresh snapshot", async () => { + for (const [refresh, layout] of [ + [8, [4]], + [1, [4, 1]], + ] as const) { + const track = new Track.Producer("test").accept({ refresh }); + const producer = new Producer({ track }); + fill(producer); + + // The joiner still reads the open group; the restatement serves whoever joins next. + const joiner = track.subscribe(); + await settle(); + producer.finish(); + joiner.close(); + + expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([...layout]); + expect(await drainLatest(track.subscribe())).toEqual([{ n: 3 }]); + } +}); + +test("a refresh reuses the newest timestamp", async () => { + const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, refresh: 1 }); + const producer = new Producer({ track }); + for (let n = 0; n <= 3; n++) producer.update({ value: { n }, at: Time.Timestamp.fromMillis(n * 10) }); + + const joiner = track.subscribe(); + await settle(); + producer.finish(); + joiner.close(); + + const ordered = track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered(); + const timestamps: (number | undefined)[] = []; + for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { + const frame = await group.readFrame(); + timestamps.push(frame?.timestamp?.asMillis()); + while ((await group.readFrame()) !== undefined) {} + } + // The restated group opens at the newest timestamp written, not a new one. + expect(timestamps).toEqual([0, 30]); +}); + +test("a refresh after an older update starts at the newest timestamp", async () => { + const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, refresh: 1 }); + const producer = new Producer({ track }); + // Deltas may carry timestamps older than their group's first frame. + for (const [n, ms] of [30, 10, 20, 15].entries()) + producer.update({ value: { n }, at: Time.Timestamp.fromMillis(ms) }); + + const joiner = track.subscribe(); + await settle(); producer.finish(); + joiner.close(); + + const ordered = track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered(); + const restated: [number | undefined, unknown][] = []; + for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { + const frame = await group.readFrame(); + restated.push([frame?.timestamp?.asMillis(), frame && JSON.parse(new TextDecoder().decode(frame.payload))]); + while ((await group.readFrame()) !== undefined) {} + } + // Restating at the last update's 15 would rewind past group 0's start and be refused. + expect(restated).toEqual([ + [30, { n: 0 }], + [30, { n: 3 }], + ]); +}); + +// A refresh restates the last value written, never one whose update was rejected, and the next +// update rides as a delta against it. (Mirrors the Rust +// `a_refresh_after_a_rejected_update_restates_the_last_written_value`.) +test("a refresh after a rejected update restates the last written value", async () => { + const track = new Track.Producer("test").accept({ refresh: 1 }); + const producer = new Producer({ track }); + fill(producer); + + // Serializes past the group cache limit, so the frame cannot be published. + const oversized = { big: "x".repeat(Group.MAX_GROUP_CACHE_BYTES + 1) }; + expect(() => producer.update({ value: oversized })).toThrow(NetError.FrameTooLarge); - expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([3, 1]); + const joiner = track.subscribe(); + await settle(); + producer.update({ value: { n: 4 } }); + producer.finish(); + joiner.close(); + + expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([4, 2]); + expect(await drain(track.subscribe({ maxDelay: REPLAY_LATENCY }))).toEqual([ + { n: 0 }, + { n: 1 }, + { n: 2 }, + { n: 3 }, + { n: 3 }, + { n: 4 }, + ]); }); -test("deltas stay within ratio times snapshot", async () => { +test("no ratio never refreshes", async () => { const track = new Track.Producer("test"); - // The budget covers only the deltas, not the snapshot frame, measured against the group's snapshot - // size. Single-digit values keep every frame at a constant 7 bytes (`{"n":N}`), so a ratio of 8 - // budgets 56 bytes of deltas. The gate checks the deltas already written, so the group keeps filling - // until they first exceed 56 (nine deltas = 63 bytes) and the next update rolls (a one-frame - // overshoot past the 56-byte budget). - const producer = new Producer({ track, deltaRatio: 8 }); - for (let n = 0; n <= 10; n++) producer.update({ value: { n } }); + const producer = new Producer({ track }); + fill(producer); + + const joiner = track.subscribe(); + await settle(); + producer.finish(); + joiner.close(); + + expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([4]); +}); + +test("a compressed refresh opens a fresh window", async () => { + const track = new Track.Producer("test").accept({ refresh: 0 }); + const producer = new Producer({ track, compression: "deflate" }); + producer.update({ value: { a: 1, b: 1 } }); + producer.update({ value: { a: 1, b: 2 } }); + + const joiner = track.subscribe(); + await settle(); + // The change after the restatement rides as a delta in the new group's window. + producer.update({ value: { a: 1, b: 3 } }); producer.finish(); + joiner.close(); - expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([10, 1]); + expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([2, 2]); + const consumer = new Consumer({ track: track.subscribe(), compression: "deflate" }); + const values: Value[] = []; + for await (const { value } of consumer) values.push(value); + expect(values).toEqual([ + { a: 1, b: 2 }, + { a: 1, b: 3 }, + ]); }); test("array change is a wholesale delta", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100 }); + const producer = new Producer({ track, deltas: true }); producer.update({ value: { list: [1, 2] } }); producer.update({ value: { list: [1, 2, 3] } }); producer.finish(); @@ -333,7 +469,7 @@ test("array change is a wholesale delta", async () => { test("a late joiner reads a buffered backlog state by state, or collapses it to the latest", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100 }); + const producer = new Producer({ track, deltas: true }); const subscriber = track.subscribe(); const collapsed = track.subscribe(); for (let n = 0; n <= 20; n++) { @@ -349,7 +485,7 @@ test("a late joiner reads a buffered backlog state by state, or collapses it to test("frame cap rolls snapshot", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 1_000_000 }); + const producer = new Producer({ track, deltas: true }); // First update is the snapshot; deltas fill the group until the frame cap forces a roll. for (let i = 0; i <= 256; i++) { producer.update({ value: { n: i } }); @@ -364,7 +500,7 @@ test("a rejected update leaves the previous value readable", async () => { // rejecting the frame inside writeFrame would supersede the last good value with an empty group. // A snapshot consumer jumps to the newest, so that value would vanish on a failed update. const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 0 }); + const producer = new Producer({ track, deltas: false }); producer.update({ value: { keep: true } }); // Serializes past the group cache limit, so the frame cannot be published. @@ -451,7 +587,7 @@ test("snapshot consumer propagates a non-gap frame failure", async () => { test("an update without a timestamp goes out untimed", async () => { const track = new Track.Producer("test").accept({}); - const producer = new Producer({ track, deltaRatio: 100 }); + const producer = new Producer({ track, deltas: true }); producer.update({ value: { a: 1, b: "x".repeat(64) } }); producer.mutate((value) => { value.a = 2; @@ -465,7 +601,7 @@ test("an update without a timestamp goes out untimed", async () => { test("a capture timestamp is written on snapshots and deltas alike", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 100 }); + const producer = new Producer({ track, deltas: true }); producer.update({ value: { a: 1, b: "x".repeat(64) }, at: Time.Timestamp.fromMillis(1_000) }); producer.update({ value: { a: 2, b: "x".repeat(64) }, at: Time.Timestamp.fromMillis(2_000) }); producer.finish(); @@ -477,7 +613,7 @@ test("a capture timestamp is written on snapshots and deltas alike", async () => test("an untimed state reads back untimed", async () => { const track = new Track.Producer("test").accept({}); - const producer = new Producer({ track, deltaRatio: 100 }); + const producer = new Producer({ track, deltas: true }); producer.update({ value: { a: 1, b: "x".repeat(64) } }); producer.update({ value: { a: 2, b: "x".repeat(64) } }); producer.finish(); @@ -491,7 +627,7 @@ test("an untimed state reads back untimed", async () => { // hold it back until a playhead reaches it. `latest()` reports the head's own frame. test("each state reads back with its frame's timestamp", async () => { const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI }); - const producer = new Producer({ track, deltaRatio: 100, compression: "deflate" }); + const producer = new Producer({ track, deltas: true, compression: "deflate" }); for (let n = 1; n <= 3; n++) { producer.update({ value: { n, b: "x".repeat(64) }, at: Time.Timestamp.fromMillis(n * 1_000) }); } diff --git a/js/json/src/types.test.ts b/js/json/src/types.test.ts index 93bd1a016db..e33b5d99384 100644 --- a/js/json/src/types.test.ts +++ b/js/json/src/types.test.ts @@ -29,9 +29,9 @@ test("track-owning wrappers take one options object", () => { }); test("consumer options omit producer-only knobs", () => { - const delta: Has<"deltaRatio", SnapshotConsumerInit> = false; + const delta: Has<"deltas", SnapshotConsumerInit> = false; const initial: Has<"initial", SnapshotConsumerInit> = false; - const op: Has<"opRatio", WindowConsumerInit> = false; + const op: Has<"ops", WindowConsumerInit> = false; const checkpoint: Has<"checkpointRecords", WindowConsumerInit> = false; expect([delta, initial, op, checkpoint]).toEqual([false, false, false, false]); @@ -40,8 +40,8 @@ test("consumer options omit producer-only knobs", () => { const schema: Has<"schema", SnapshotConsumerInit> = true; expect([track, compression, schema]).toEqual([true, true, true]); - const producerDelta: Has<"deltaRatio", SnapshotProducerInit> = true; - const producerOp: Has<"opRatio", WindowProducerInit> = true; + const producerDelta: Has<"deltas", SnapshotProducerInit> = true; + const producerOp: Has<"ops", WindowProducerInit> = true; const streamCompression: Has<"compression", StreamProducerInit> = true; expect([producerDelta, producerOp, streamCompression]).toEqual([true, true, true]); }); @@ -49,16 +49,16 @@ test("consumer options omit producer-only knobs", () => { test("object literals reject producer knobs and positional tracks", () => { const track = new Track.Producer("test").subscribe(); const reject = () => { - // @ts-expect-error deltaRatio is producer-only - new Snapshot.Consumer({ track, deltaRatio: 8 }); + // @ts-expect-error deltas is producer-only + new Snapshot.Consumer({ track, deltas: true }); // @ts-expect-error initial is producer-only new Snapshot.Consumer({ track, initial: {} }); // @ts-expect-error a positional track is not an options object new Snapshot.Consumer(track); // @ts-expect-error a producer track is not a subscriber new Snapshot.Consumer({ track: new Track.Producer("test") }); - // @ts-expect-error opRatio is producer-only - new Window.Consumer({ track, opRatio: 8 }); + // @ts-expect-error ops is producer-only + new Window.Consumer({ track, ops: true }); // @ts-expect-error checkpointRecords is producer-only new Window.Consumer({ track, checkpointRecords: 4 }); // @ts-expect-error a positional track is not an options object diff --git a/js/json/src/window/encoder.ts b/js/json/src/window/encoder.ts index fed75c145bb..471535e75ce 100644 --- a/js/json/src/window/encoder.ts +++ b/js/json/src/window/encoder.ts @@ -4,23 +4,20 @@ import { Group } from "@moq/net"; /** Frames (header included) in one group before a new group is forced, matching the Snapshot cap. Kept well below the net per-group cap so a roll always precedes GroupTooLarge. */ const MAX_GROUP_FRAMES = 1024; -/** Op ratio used when {@link Config.opRatio} is left unset. */ -const DEFAULT_OP_RATIO = 8; - -type Edit = { push: string } | { pop: number }; +// A restatement changes nothing on commit; it only opens a group. +type Edit = { push: string } | { pop: number } | { restate: true }; /** Options for an {@link Encoder}. */ export interface Config { /** - * How much the ops in a group may cost before a fresh group is emitted. - * - * A new group opens once the pushes and pops *already written* exceed `opRatio` times the size of - * the group's header frame. The pending op is excluded, so the one that tips the group over budget - * still lands. `0` disables ops entirely, so every edit is its own single-frame group. + * Encode edits as ops appended to the group's header. `false` restates the window in a new + * single-frame group for every edit. * - * The window's counterpart to Snapshot's `deltaRatio`. Defaults to `8`. + * A group of ops runs until a joiner wants a fresh one, judged by the track's `refresh` ratio + * (see {@link Encoder.snapshot}), or until it reaches the frame or byte cap. The window's + * counterpart to Snapshot's `deltas`. Defaults to `true`. */ - opRatio?: number; + ops?: boolean; /** * Compress each group as one sync-flushed `deflate-raw` stream, so every op reuses the header and @@ -47,7 +44,7 @@ export interface Encoded { /** * Whether this frame is a group header, which must open a new group. * - * The encoder decides this, never the caller: the op budget and the frame cap force a new group + * The encoder decides this, never the caller: the frame and byte caps force a new group * independently of which edit was requested. */ keyframe: boolean; @@ -74,7 +71,7 @@ export interface Pending extends Encoded { * @public */ export class Encoder { - #opRatio: number; + #ops: boolean; #compress: boolean; #checkpointRecords?: number; @@ -86,10 +83,8 @@ export class Encoder { #start = 0; #flate?: Flate; - // Bytes of pushes and pops in this group, excluding its header frame. - #opBytes = 0; - // Reference size the op budget is measured against: this group's header frame. - #headerLen = 0; + // Bytes in this group, header included. + #groupBytes = 0; #groupFrames = 0; // Whether the next frame must be a header after a lost frame. #resync = true; @@ -100,10 +95,7 @@ export class Encoder { #generation = 0; constructor(config: Config = {}) { - this.#opRatio = config.opRatio ?? DEFAULT_OP_RATIO; - if (!Number.isSafeInteger(this.#opRatio) || this.#opRatio < 0 || this.#opRatio > 0xffffffff) { - throw new Error("opRatio must be an unsigned 32-bit integer"); - } + this.#ops = config.ops ?? true; this.#compress = config.compression ?? false; this.#checkpointRecords = config.checkpointRecords; if ( @@ -141,8 +133,7 @@ export class Encoder { /** Discard group-local state after an encoded frame did not reach the wire. */ #resyncGroup(): void { this.#flate = undefined; - this.#opBytes = 0; - this.#headerLen = 0; + this.#groupBytes = 0; this.#groupFrames = 0; this.#resync = true; this.#pending = false; @@ -197,14 +188,20 @@ export class Encoder { return this.#emitPopHeader(offset, edit); } - /** Whether the pending edit may ride as an op in the open group. */ + /** + * Restate the retained window in a header, which must open a new group. + * + * For a caller that opens groups itself: call it when a joiner wants a fresh group, such as when + * the track's `demand().wanted` passes the largest group written, so the joiner reads the window + * without the ops before it. The frame is a {@link Pending} like any other. + */ + snapshot(): Pending { + return this.#emitHeader(this.#offset, this.#start, this.#window, { restate: true }); + } + + /** Whether the pending edit may ride as an op in the open group, which is under its frame cap. */ #opAllowed(): boolean { - return ( - this.#opRatio !== 0 && - this.#groupFrames > 0 && - this.#groupFrames < MAX_GROUP_FRAMES && - this.#opBytes <= this.#opRatio * this.#headerLen - ); + return this.#ops && this.#groupFrames > 0 && this.#groupFrames < MAX_GROUP_FRAMES; } /** Compress an already-serialized op into the open group, if its header remains cached. */ @@ -215,9 +212,9 @@ export class Encoder { } const payload = this.#flate ? this.#flate.frame(bytes) : bytes; - this.#opBytes += payload.length; + this.#groupBytes += payload.length; this.#groupFrames += 1; - if (this.#headerLen + this.#opBytes > Group.MAX_GROUP_CACHE_BYTES) { + if (this.#groupBytes > Group.MAX_GROUP_CACHE_BYTES) { this.#resyncGroup(); return undefined; } @@ -255,8 +252,7 @@ export class Encoder { } this.#flate = flate; - this.#headerLen = payload.length; - this.#opBytes = 0; + this.#groupBytes = payload.length; this.#groupFrames = 1; this.#resync = false; @@ -288,7 +284,7 @@ export class Encoder { this.#window.splice(0, dropped); this.#start += dropped; } - } else { + } else if ("pop" in edit) { const offset = this.#offset + edit.pop; const stored = Math.min(Math.max(offset - this.#start, 0), this.#window.length); this.#window.splice(0, stored); diff --git a/js/json/src/window/index.ts b/js/json/src/window/index.ts index 364919621ff..ed8260a6c5d 100644 --- a/js/json/src/window/index.ts +++ b/js/json/src/window/index.ts @@ -18,10 +18,11 @@ * Trimming is therefore an op, not a group boundary, so dropping a record costs one small frame * inside the shared compression window instead of a roll that would throw that window away. * - * The publisher rolls a group when the ops in it outgrow {@link ProducerConfig.opRatio} times the - * header that opened it. That is purely a compression decision: there is no caller-driven cut and no - * age bound, and a {@link Consumer} never surfaces it. `ProducerConfig.checkpointRecords` bounds the - * suffix repeated on each roll for a long-lived window. + * The publisher rolls a group when a joiner wants a fresh one: once the ops in the open group + * outweigh the track's `refresh` ratio times the header that opened it, a join asks for a group past + * the largest, and the {@link Producer} restates the window there. It also rolls at the frame and + * byte caps, or when the caller cuts. A {@link Consumer} never surfaces a roll. + * `ProducerConfig.checkpointRecords` bounds the suffix repeated on each roll for a long-lived window. * * A reader gets a `push` event when a record arrives, `pop` when a contiguous span leaves, and * `skip` when a span was dropped before this reader saw it. A reader that keeps up sees pushes and diff --git a/js/json/src/window/producer.ts b/js/json/src/window/producer.ts index 1761de44f25..fdecbd3e6bd 100644 --- a/js/json/src/window/producer.ts +++ b/js/json/src/window/producer.ts @@ -13,6 +13,11 @@ export type ProducerConfig = Config & { track: Moq.Track.Producer }; * the encoder emits a header. When something else already owns the track, use the {@link Encoder} * directly. * + * A group of ops runs until a joiner wants a fresh one: once the ops outweigh the track's `refresh` + * ratio times the header, a join asks for a group past the largest, and the producer restates the + * window there at the newest timestamp written. Set the ratio when creating the track, or joins + * never ask. + * * @public */ export class Producer { @@ -23,10 +28,36 @@ export class Producer { // The group an op would be appended to, open after a header. #group?: Moq.Group.Producer; + // The sequence of the newest group written, which a joiner's wanted group has to pass. + #largest?: number; + // The newest timestamp written, which a refresh restates the window at. An edit may carry an + // older timestamp than its group's first frame, and a new group may not start before that one. + #at?: Time.Timestamp; + // Stops watching the track's demand. + #unwatch?: () => void; + /** Wrap a track to publish a window into it. */ constructor(config: ProducerConfig) { this.#track = config.track; this.#encoder = new Encoder(config); + + // With ops off every group holds one frame, so no join ever asks for a fresh one. + if (config.ops !== false) { + this.#unwatch = this.#track.demand().wanted.subscribe((wanted) => this.#refresh(wanted)); + } + } + + // Restate the window in a new group once a joiner wants one past the largest written. + #refresh(wanted: number | undefined): void { + if (this.#finished || wanted === undefined || this.#largest === undefined || wanted <= this.#largest) return; + + // Nobody awaits a refresh, so a failed write has no caller to report to. Abort the track rather + // than leave its newest group without the window, where a joiner would wait. + try { + this.#write(this.#encoder.snapshot(), this.#at); + } catch (err) { + this.#close(err instanceof Error ? err : new Error(String(err))); + } } /** The retained checkpoint suffix, oldest first. This is complete unless bounded in the config. */ @@ -48,6 +79,7 @@ export class Producer { push({ value, at }: Timed): void { this.#assertOpen(); this.#write(this.#encoder.push(value), at); + this.#advance(at); } /** @@ -62,7 +94,14 @@ export class Producer { pop(count: number, at?: Time.Timestamp): void { this.#assertOpen(); const frame = this.#encoder.pop(count); - if (frame) this.#write(frame, at); + if (!frame) return; + this.#write(frame, at); + this.#advance(at); + } + + // Remember `at` if it is the newest timestamp written. + #advance(at: Time.Timestamp | undefined): void { + if (at && !at.isBefore(this.#at ?? at)) this.#at = at; } #assertOpen(): void { @@ -79,6 +118,7 @@ export class Producer { this.#group = undefined; const group = this.#track.appendGroup(); + this.#largest = group.sequence; try { group.writeFrame({ payload: encoded.payload, timestamp: at }); } catch (err) { @@ -118,12 +158,18 @@ export class Producer { /** Finish the track, closing any open group. */ finish(): void { + this.#close(); + } + + #close(abort?: Error): void { if (this.#finished) return; this.#finished = true; + this.#unwatch?.(); + this.#unwatch = undefined; - this.#group?.close(); + this.#group?.close(abort); this.#group = undefined; - this.#track.close(); + this.#track.close(abort); } } diff --git a/js/json/src/window/properties.test.ts b/js/json/src/window/properties.test.ts index 74559633a8f..d48070feaca 100644 --- a/js/json/src/window/properties.test.ts +++ b/js/json/src/window/properties.test.ts @@ -4,7 +4,8 @@ import { Decoder, type Event } from "./decoder.ts"; import { type Config, Encoder, type Pending } from "./encoder.ts"; type Json = null | boolean | number | string | Json[] | { [key: string]: Json }; -type Step = { edit: { push: Json } | { pop: number }; reset: boolean; drop: boolean }; +// `restate` stands for `Encoder.snapshot`, as a refresh does. +type Step = { edit: { push: Json } | { pop: number } | { restate: true }; reset: boolean; drop: boolean }; type Frame = { payload: Uint8Array; offset: number; records: Json[] }; // Mirror the Rust generator, including nulls and keys that are special to JS objects. @@ -29,8 +30,9 @@ const value: fc.Arbitrary = fc.letrec<{ value: Json }>((tie) => ({ const steps = fc.array( fc.record({ edit: fc.oneof( - value.map((push) => ({ push })), - fc.integer({ min: 0, max: 8 }).map((pop) => ({ pop })), + { arbitrary: value.map((push) => ({ push })), weight: 4 }, + { arbitrary: fc.integer({ min: 0, max: 8 }).map((pop) => ({ pop })), weight: 4 }, + { arbitrary: fc.constant({ restate: true as const }), weight: 1 }, ), reset: fc.integer({ min: 0, max: 15 }).map((n) => n === 0), drop: fc.boolean(), @@ -60,6 +62,9 @@ function check(config: Config, steps: Step[], join: number): void { if ("push" in step.edit) { frame = encoder.push(step.edit.push); records = [...records, step.edit.push]; + } else if ("restate" in step.edit) { + frame = encoder.snapshot(); + expect(frame.keyframe).toBe(true); } else { frame = encoder.pop(step.edit.pop); const count = Math.min(step.edit.pop, records.length); @@ -158,7 +163,7 @@ test("window codec property matches every reader's logical window", () => { fc.assert( fc.property( fc.record({ - opRatio: fc.constantFrom(0, 1, 2, 8, 100), + ops: fc.boolean(), compression: fc.boolean(), checkpointRecords: fc.option(fc.integer({ min: 1, max: 8 }), { nil: undefined }), }), diff --git a/js/json/src/window/vectors.test.ts b/js/json/src/window/vectors.test.ts index 2e7f30b226f..5f66d61cb4e 100644 --- a/js/json/src/window/vectors.test.ts +++ b/js/json/src/window/vectors.test.ts @@ -40,14 +40,14 @@ test("the encoder emits the shared frame bytes", () => { }); test("the encoder emits the shared group header bytes", () => { - // opRatio 0 forces every edit to restate the window in a new group. - const encoder = new Encoder<{ n: number }>({ opRatio: 0 }); + // Without ops every edit restates the window in a new group. + const encoder = new Encoder<{ n: number }>({ ops: false }); commit(encoder.push({ n: 0 })); expect(commit(encoder.push({ n: 1 }))).toBe(frame("group header from zero")); }); test("the encoder emits the shared bounded checkpoint bytes", () => { - const encoder = new Encoder<{ n: number }>({ opRatio: 0, checkpointRecords: 1 }); + const encoder = new Encoder<{ n: number }>({ ops: false, checkpointRecords: 1 }); commit(encoder.push({ n: 0 })); expect(commit(encoder.push({ n: 1 }))).toBe(frame("group header with a bounded checkpoint")); }); diff --git a/js/json/src/window/window.test.ts b/js/json/src/window/window.test.ts index 9afc87b48dd..df40978a6da 100644 --- a/js/json/src/window/window.test.ts +++ b/js/json/src/window/window.test.ts @@ -1,4 +1,5 @@ import { expect, test } from "bun:test"; +import { Milli } from "@moq/clock"; import { Group, Error as NetError, StreamCode, Time, type Timed, Track } from "@moq/net"; import { Consumer } from "./consumer.ts"; import { Decoder, Encoder, type Event, Producer, type Span } from "./index.ts"; @@ -18,7 +19,7 @@ class Live { events: Event[] = []; #next?: Promise> | undefined>; - constructor(config: { opRatio?: number; compression?: boolean; checkpointRecords?: number } = {}) { + constructor(config: { ops?: boolean; compression?: boolean; checkpointRecords?: number } = {}) { const track = new Track.Producer("test"); this.producer = new Producer({ track, ...config }); this.consumer = new Consumer({ track: track.subscribe(), compression: config.compression }); @@ -120,7 +121,7 @@ test("writes after finish are rejected before encoding", () => { test("a popped record is never restated", async () => { // Ops disabled, so every single edit is its own group restating the whole window. - const live = new Live({ opRatio: 0 }); + const live = new Live({ ops: false }); await live.push(0); await live.push(1); await live.pop(1); @@ -137,7 +138,7 @@ test("a popped record is never restated", async () => { }); test("bounded checkpoints keep a following consumer contiguous", async () => { - const live = new Live({ opRatio: 0, checkpointRecords: 2 }); + const live = new Live({ ops: false, checkpointRecords: 2 }); for (let n = 0; n < 6; n++) await live.push(n); expect(live.producer.offset).toBe(0); @@ -148,7 +149,7 @@ test("bounded checkpoints keep a following consumer contiguous", async () => { }); test("a late consumer skips to the bounded checkpoint", () => { - const encoder = new Encoder({ opRatio: 0, checkpointRecords: 2 }); + const encoder = new Encoder({ ops: false, checkpointRecords: 2 }); let latest: Uint8Array | undefined; for (let n = 0; n < 5; n++) { const frame = encoder.push({ n }); @@ -186,8 +187,8 @@ test("pops cross the omitted checkpoint prefix", () => { test("rolling is invisible to the consumer", async () => { // The same edits, framed two ways: one group for everything, versus a roll per edit. - const edits = async (opRatio: number) => { - const live = new Live({ opRatio }); + const edits = async (ops: boolean) => { + const live = new Live({ ops }); for (let n = 0; n < 6; n++) { await live.push(n); if (n >= 3) await live.pop(1); @@ -195,20 +196,129 @@ test("rolling is invisible to the consumer", async () => { return live.finish(); }; - expect(await edits(1000)).toEqual(await edits(0)); + expect(await edits(true)).toEqual(await edits(false)); }); test("compressed round-trip across rolls", async () => { - const live = new Live({ compression: true, opRatio: 1 }); + const live = new Live({ compression: true }); for (let n = 0; n < 40; n++) { await live.push(n); if (n >= 10) await live.pop(1); + if (n % 7 === 6) live.producer.cut(); } - // A tight ratio rolls many times; every record still arrives exactly once, in order. + // Every roll opens a fresh window; every record still arrives exactly once, in order. expect(pushed(await live.finish())).toEqual(Array.from({ length: 40 }, (_, n) => n)); }); +// The frame count and first-frame timestamp of each group in a finished track. +async function groups(track: Track.Producer): Promise<[number, number | undefined][]> { + const ordered = track.subscribe({ maxDelay: Milli(30_000) }).ordered(); + const out: [number, number | undefined][] = []; + for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { + const first = await group.readFrame(); + let frames = first ? 1 : 0; + while ((await group.readFrame()) !== undefined) frames++; + out.push([frames, first?.timestamp?.asMillis()]); + } + return out; +} + +// Let the producer see a demand change, which the signal delivers in a microtask. +async function settle(): Promise { + await new Promise((resolve) => queueMicrotask(resolve)); +} + +test("a joiner over the ratio gets a fresh header", async () => { + // A 35-byte header and 16-byte pushes: two pushes stay under a ratio of 1, three cross it. + for (const [pushes, layout] of [ + [2, [3]], + [3, [4, 1]], + ] as const) { + const track = new Track.Producer("test").accept({ refresh: 1 }); + const producer = new Producer({ track }); + producer.push({ value: { n: 1000 } }); + for (let n = 0; n < pushes; n++) producer.push({ value: { n } }); + + const joiner = track.subscribe(); + await settle(); + producer.finish(); + joiner.close(); + + expect((await groups(track)).map(([frames]) => frames)).toEqual([...layout]); + } +}); + +test("a window refresh reuses the newest timestamp", async () => { + const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, refresh: 0 }); + const producer = new Producer({ track }); + producer.push({ value: { n: 0 }, at: Time.Timestamp.fromMillis(10) }); + producer.push({ value: { n: 1 }, at: Time.Timestamp.fromMillis(20) }); + producer.pop(1, Time.Timestamp.fromMillis(30)); + + const joiner = track.subscribe(); + await settle(); + producer.finish(); + joiner.close(); + + // The restated header opens at the newest timestamp written, and carries the window as it stands. + expect(await groups(track)).toEqual([ + [3, 10], + [1, 30], + ]); + const consumer = new Consumer({ track: track.subscribe() }); + const event = await consumer.next(); + expect(event?.value).toEqual({ push: { index: 1, value: { n: 1 } } }); + expect(event?.at?.as(Time.Timescale.MILLI)).toBe(30); +}); + +test("a window refresh after an older edit starts at the newest timestamp", async () => { + const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, refresh: 0 }); + const producer = new Producer({ track }); + producer.push({ value: { n: 0 }, at: Time.Timestamp.fromMillis(30) }); + // Ops may carry timestamps older than their group's first frame. + producer.push({ value: { n: 1 }, at: Time.Timestamp.fromMillis(10) }); + + const joiner = track.subscribe(); + await settle(); + producer.finish(); + joiner.close(); + + // Restating at the last edit's 10 would rewind past group 0's start and be refused. + expect(await groups(track)).toEqual([ + [2, 30], + [1, 30], + ]); +}); + +test("a window refresh needs a ratio", async () => { + const track = new Track.Producer("test"); + const producer = new Producer({ track }); + for (let n = 0; n < 4; n++) producer.push({ value: { n } }); + + const joiner = track.subscribe(); + await settle(); + producer.finish(); + joiner.close(); + + expect((await groups(track)).map(([frames]) => frames)).toEqual([4]); +}); + +test("snapshot restates the window in a header", () => { + const encoder = new Encoder({ checkpointRecords: 2 }); + for (let n = 0; n < 3; n++) encoder.push({ n }).commit(); + encoder.pop(1)?.commit(); + + const frame = encoder.snapshot(); + expect(frame.keyframe).toBe(true); + frame.commit(); + expect(new TextDecoder().decode(frame.payload)).toBe('{"offset":1,"records":[{"n":1},{"n":2}]}'); + + // A restatement changes nothing, and the next edit rides as an op against it. + expect(encoder.window).toEqual([{ n: 1 }, { n: 2 }]); + expect(encoder.push({ n: 3 }).keyframe).toBe(false); +}); + test("the window slides", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); @@ -246,7 +356,7 @@ test("an empty pop writes nothing", async () => { test("a lagging consumer is told what it missed", async () => { // Ops disabled, so every edit rolls: a reader that stops polling really does lose groups. const track = new Track.Producer("test"); - const producer = new Producer({ track, opRatio: 0 }); + const producer = new Producer({ track, ops: false }); const live = new Live(); live.producer = producer; const subscriber = track.subscribe(); @@ -286,7 +396,7 @@ test("consumer resumes at a checkpoint after losing a group", async () => { ]) { const track = new Track.Producer("test"); const consumer = new Consumer({ track: track.subscribe() }); - const encoder = new Encoder({ opRatio: 0 }); + const encoder = new Encoder({ ops: false }); let frame = encoder.push({ n: 0 }); let group = track.appendGroup(); @@ -309,7 +419,7 @@ test("consumer resumes at a checkpoint after losing a group", async () => { test("a fresh consumer adopts the current offset", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, opRatio: 0 }); + const producer = new Producer({ track, ops: false }); for (let n = 0; n < 5; n++) producer.push({ value: { n } }); producer.pop(3); @@ -384,7 +494,7 @@ test("pop counts are nonnegative safe integers", () => { }); test("an op that would evict the header rolls first", () => { - const encoder = new Encoder({ opRatio: 0xffffffff }); + const encoder = new Encoder({ ops: true }); const first = "a".repeat(16 * 1024 * 1024); const next = "b".repeat(15 * 1024 * 1024); diff --git a/js/net/src/time.test.ts b/js/net/src/time.test.ts index 58e08dbc7ee..a49ff802689 100644 --- a/js/net/src/time.test.ts +++ b/js/net/src/time.test.ts @@ -54,3 +54,15 @@ test("Timestamp.as rejects conversions past the safe integer range", () => { // Source value and destination scale are each legal; the converted wire value is not. expect(() => Timestamp.fromMillis(2000).as(Timescale(Number.MAX_SAFE_INTEGER))).toThrow(RangeError); }); + +test("Timestamp.isBefore orders across scales exactly", () => { + expect(Timestamp.fromMillis(1).isBefore(Timestamp.fromMicros(1_001))).toBe(true); + expect(Timestamp.fromMillis(1).isBefore(Timestamp.fromMicros(1_000))).toBe(false); + expect(Timestamp.fromMicros(1_000).isBefore(Timestamp.fromMillis(1))).toBe(false); + // Products past 2^53 still compare exactly. + const micros = new Timestamp(Number.MAX_SAFE_INTEGER, Timescale.MICRO); + const millis = new Timestamp(Number.MAX_SAFE_INTEGER - 1, Timescale.MILLI); + expect(micros.isBefore(millis)).toBe(true); + expect(millis.isBefore(micros)).toBe(false); + expect(new Timestamp(0.5, Timescale.SECOND).isBefore(Timestamp.fromMillis(501))).toBe(true); +}); diff --git a/js/net/src/time.ts b/js/net/src/time.ts index 165b99b04fe..febc6eac4c8 100644 --- a/js/net/src/time.ts +++ b/js/net/src/time.ts @@ -100,4 +100,25 @@ export class Timestamp { asMicros(): number { return this.as(Timescale.MICRO); } + + /** Whether this presents before `other`, whatever their scales. */ + isBefore(other: Timestamp): boolean { + if (this.scale === other.scale) return this.value < other.value; + // Cross-scale products can pass 2^53, so they are compared exactly in BigInt, as Rust does in u128. + const [ma, ea] = binary(this.value); + const [mb, eb] = binary(other.value); + const e = Math.min(ea, eb); + return (ma * BigInt(other.scale)) << BigInt(ea - e) < (mb * BigInt(this.scale)) << BigInt(eb - e); + } +} + +// A finite, non-negative `value` exactly as `mantissa * 2^exponent`. Doubling is exact, so +// a fraction becomes an integer within its binary digits. +function binary(value: number): [bigint, number] { + let exponent = 0; + while (!Number.isInteger(value)) { + value *= 2; + exponent--; + } + return [BigInt(value), exponent]; } diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 8c65a991c0f..6ea3545ddf2 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -581,27 +581,6 @@ type CachedGroup = { // A group's checked start, kept by sequence. type Start = { sequence: number; start: Timestamp }; -// Whether `a` presents before `b`, whatever their scales. Cross-scale products can pass -// 2^53, so they are compared exactly in BigInt, as Rust does in u128. -function earlier(a: Timestamp, b: Timestamp): boolean { - if (a.scale === b.scale) return a.value < b.value; - const [ma, ea] = binary(a.value); - const [mb, eb] = binary(b.value); - const e = Math.min(ea, eb); - return (ma * BigInt(b.scale)) << BigInt(ea - e) < (mb * BigInt(a.scale)) << BigInt(eb - e); -} - -// A finite, non-negative `value` exactly as `mantissa * 2^exponent`. Doubling is exact, so -// a fraction becomes an integer within its binary digits. -function binary(value: number): [bigint, number] { - let exponent = 0; - while (!Number.isInteger(value)) { - value *= 2; - exponent--; - } - return [BigInt(value), exponent]; -} - let bindProducerSequence: (producer: Producer, sequence: TrackSequence) => void; // A fresh read handle on a group the producer still caches; assigned in its static block. let cachedMirror: (producer: Producer, sequence: number) => GroupConsumer | undefined; @@ -1146,11 +1125,11 @@ export class Producer { const evicted = this.#evicted; const late = evicted !== undefined && sequence <= evicted.sequence; if (evicted && late) { - if (ceiling === undefined || earlier(evicted.start, ceiling)) ceiling = evicted.start; + if (ceiling === undefined || evicted.start.isBefore(ceiling)) ceiling = evicted.start; } else if (evicted) { - if (floor === undefined || earlier(floor, evicted.start)) floor = evicted.start; + if (floor === undefined || floor.isBefore(evicted.start)) floor = evicted.start; } - if ((floor && earlier(start, floor)) || (ceiling && earlier(ceiling, start))) throw new TimestampMismatch(); + if ((floor && start.isBefore(floor)) || ceiling?.isBefore(start)) throw new TimestampMismatch(); return late; } diff --git a/js/publish/src/catalog.ts b/js/publish/src/catalog.ts index 8adecfa6d5b..636b4f93c02 100644 --- a/js/publish/src/catalog.ts +++ b/js/publish/src/catalog.ts @@ -83,7 +83,7 @@ export class CatalogProducer { const output = new Json.Snapshot.Producer({ track, compression: opts?.compression ? "deflate" : "none", - deltaRatio: 0, + deltas: false, }); output.update({ value: this.#value, at: Time.Timestamp.now() }); diff --git a/js/room/src/chat.ts b/js/room/src/chat.ts index 944c137ec47..69193d60a39 100644 --- a/js/room/src/chat.ts +++ b/js/room/src/chat.ts @@ -37,7 +37,7 @@ export class Publisher { /** Publish a chat window over an existing track. */ constructor(track: Track.Producer) { // Every edit restates the retained window, so a late reader never replays expired records. - this.#producer = new Json.Window.Producer({ track, opRatio: 0 }); + this.#producer = new Json.Window.Producer({ track, ops: false }); this.#signals.run((effect) => { const next = effect.get(this.#expires)[0]; if (next === undefined) return; diff --git a/js/watch/src/broadcast.test.ts b/js/watch/src/broadcast.test.ts index 6ddd404a982..7d847986fd6 100644 --- a/js/watch/src/broadcast.test.ts +++ b/js/watch/src/broadcast.test.ts @@ -102,7 +102,7 @@ describe("unsupported catalog", () => { const track = published.createTrack(format === "hang" ? Catalog.TRACK : Catalog.TRACK_COMPRESSED); const producer = new Json.Snapshot.Producer({ track, - deltaRatio: 0, + deltas: false, compression: format === "hangz" ? "deflate" : "none", }); const enabled = new Signal(true); @@ -144,7 +144,7 @@ it("keeps playing a finished catalog until the broadcast ends", async () => { const published = publish(owner, name); const producer = new Json.Snapshot.Producer({ track: published.createTrack(Catalog.TRACK), - deltaRatio: 0, + deltas: false, }); const source = new Broadcast({ origin: owner, name, catalogFormat: "hang", enabled: true }); try { @@ -175,7 +175,7 @@ it("reports a catalog that ends empty as offline", async () => { const published = publish(owner, name); const producer = new Json.Snapshot.Producer({ track: published.createTrack(Catalog.TRACK), - deltaRatio: 0, + deltas: false, }); const source = new Broadcast({ origin: owner, name, catalogFormat: "hang", enabled: true }); try { diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 500678d4768..214011b3f42 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON snapshot `deltaRatio` is `deltas` + +`SnapshotConfig.deltaRatio: UInt` is replaced by `deltas: Boolean` (default `true`). +Pass `deltas = false` where you passed `deltaRatio = 0u`, and drop the argument otherwise. +Publish the track with a `refresh` ratio so a joiner gets the value restated in a fresh group. + ### Priorities are signed (#6142) `TrackInfo.priority`, `Subscription.priority`, and `FetchGroupOptions.priority` are `Byte`, higher first, and 0 is the unset midpoint; write `priority = 3` instead of `3u`. diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index c045c86dcc1..cb250c62126 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -178,7 +178,7 @@ class SmokeTest { framerate = 60.0, optimizeForLatency = true, ) - val snapshot: SnapshotConfig = SnapshotConfig(deltaRatio = 8u, compression = false) + val snapshot: SnapshotConfig = SnapshotConfig(deltas = true, compression = false) val stream: StreamConfig = StreamConfig(compression = false) val properties: VideoProperties = VideoProperties(rotation = 315.0) val backoff: Backoff = Backoff( @@ -198,7 +198,7 @@ class SmokeTest { assertEquals(listOf("localhost"), server.tls.generate) val status: ConnectionStatus = ConnectionStatus.CONNECTED assertEquals(4_000_000uL, hint.bitrate) - assertEquals(8u, snapshot.deltaRatio) + assertEquals(true, snapshot.deltas) assertEquals(false, stream.compression) assertNull(properties.display) assertNull(properties.flip) @@ -429,7 +429,7 @@ class SmokeTest { @Test fun `typed json snapshot round-trips a serializable value`() = runTest { BroadcastProducer().use { broadcast -> - val config = SnapshotConfig(deltaRatio = 8u, compression = false) + val config = SnapshotConfig(deltas = true, compression = false) val track = broadcast.publishTrack("status", TrackInfo(timescale = 1_000_000uL)) val producer = SnapshotProducer(broadcast, track, config) val consumer = SnapshotConsumer(broadcast.consume().subscribeTrack("status", null), config) @@ -445,7 +445,7 @@ class SmokeTest { @Test fun `json producer demand follows subscribers`() = runTest { BroadcastProducer().use { broadcast -> - val config = SnapshotConfig(deltaRatio = 0u, compression = false) + val config = SnapshotConfig(deltas = false, compression = false) val producer = SnapshotProducer(broadcast, broadcast.publishTrack("status", null), config) val demand: TrackDemand = producer.demand() assertEquals("status", demand.name()) @@ -461,7 +461,7 @@ class SmokeTest { @Test fun `cancelling a flow collection cancels its native handle`() = runTest { BroadcastProducer().use { broadcast -> - val config = SnapshotConfig(deltaRatio = 0u, compression = false) + val config = SnapshotConfig(deltas = false, compression = false) val producer = SnapshotProducer(broadcast, broadcast.publishTrack("status", null), config) val demand: TrackDemand = producer.demand() producer.update(Status(state = "live")) @@ -482,7 +482,7 @@ class SmokeTest { @Test fun `raw json string passes through unencoded`() = runTest { BroadcastProducer().use { broadcast -> - val config = SnapshotConfig(deltaRatio = 0u, compression = false) + val config = SnapshotConfig(deltas = false, compression = false) val producer = SnapshotProducer(broadcast, broadcast.publishTrack("status", null), config) producer.update("""{"state":"raw"}""") diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index 3d50bab2cab..81a829b3690 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON snapshot `delta_ratio` is `deltas` + +`SnapshotProducer(delta_ratio=...)` is replaced by `deltas: bool = True`. +Pass `deltas=False` where you passed `delta_ratio=0`, and drop the argument otherwise. +Publish the track with a `refresh` ratio so a joiner gets the value restated in a fresh group. + ### Priorities are signed (#6142) `TrackInfo.priority`, `Subscription.priority`, and `FetchGroupOptions.priority` take `-128..=127`, higher first, and 0 is the unset midpoint. diff --git a/py/moq-rs/moq/json.py b/py/moq-rs/moq/json.py index 5179910e0de..f5831ab473e 100644 --- a/py/moq-rs/moq/json.py +++ b/py/moq-rs/moq/json.py @@ -54,10 +54,11 @@ class SnapshotProducer: """Publish a JSON value that consumers see as a single latest state (lossy). Each :meth:`update` supersedes the last; a late joiner only sees the newest value, encoded as - snapshots and merge-patch deltas automatically. ``delta_ratio`` controls how aggressively - deltas replace full snapshots (0 disables them); ``None`` uses the binding's default. Set - ``compression`` to DEFLATE-compress each group; the consumer must pass the same flag. A name - the catalog already carries is refused. + snapshots and merge-patch deltas automatically. Set ``deltas=False`` to publish every update + as a full snapshot in its own group. With deltas on, give the track a ``refresh`` ratio so a + joiner that would download more than that many snapshots' worth of deltas gets the value + restated in a fresh group. Set ``compression`` to DEFLATE-compress each group; the consumer + must pass the same flag. A name the catalog already carries is refused. """ def __init__( @@ -65,15 +66,10 @@ def __init__( broadcast: BroadcastProducer, track: publish.TrackProducer, *, - delta_ratio: int | None = None, + deltas: bool = True, compression: bool = False, ) -> None: - # Let the record supply delta_ratio's default rather than restating it here. - config = ( - MoqJsonSnapshotConfig(compression=compression) - if delta_ratio is None - else MoqJsonSnapshotConfig(delta_ratio=delta_ratio, compression=compression) - ) + config = MoqJsonSnapshotConfig(deltas=deltas, compression=compression) self._inner = MoqJsonSnapshotProducer(broadcast._inner, track._inner, config) def demand(self) -> TrackDemand: @@ -126,7 +122,7 @@ class SnapshotConsumer(_Stream[Timed]): """ def __init__(self, track: subscribe.TrackConsumer, *, compression: bool = False) -> None: - # delta_ratio is producer-only, so leave it at its default here. + # deltas is producer-only, so leave it at its default here. config = MoqJsonSnapshotConfig(compression=compression) self._inner = MoqJsonSnapshotConsumer(track._inner, config) diff --git a/quest/m1/compress/migrate.md b/quest/m1/compress/migrate.md index f43070e290d..76915941907 100644 --- a/quest/m1/compress/migrate.md +++ b/quest/m1/compress/migrate.md @@ -58,13 +58,7 @@ reader, so this quest lands after both and only sets the flag. Public API: removals listed above. Wire: the hang catalog loses `compression` and the `.z` tracks, in its draft too; moq-net none. -Decided 2026-10-22 (maintainer): this waits on -[Refresh JSON](/quest/m1/refresh/json.md), since both rewrite moq-json's -`snapshot::Config` and moq-stats' `TrackPair` -([#6054](https://github.com/moq-dev/moq/pull/6054) implements it). - ## Required - [Catalog HLS field](/quest/m1/archive/catalog-hls.md) - renames the timeline to `.hls`, which this compresses - [Archive consumer](/quest/m1/archive/consumer.md) - replaces the CLI archive reader that reads `.z` timelines -- [Refresh JSON](/quest/m1/refresh/json.md) - rewrites `snapshot::Config` and moq-stats' `TrackPair` first diff --git a/quest/m1/refresh/README.md b/quest/m1/refresh/README.md index a255071319f..3227037a0a9 100644 --- a/quest/m1/refresh/README.md +++ b/quest/m1/refresh/README.md @@ -1,4 +1,4 @@ -# Refresh: new groups on demand +# [M] Refresh: new groups on demand ## Goal @@ -61,10 +61,6 @@ Work owned by this README, after the children land: what the ratio means, what a publisher does on `wanted`, and how relays forward it. No new guide. -## Required - -- [moq-json](/quest/m1/refresh/json.md) - snapshot and window groups roll on a qualifying join, reading the ratio from the track; `delta_ratio` and `op_ratio` become `deltas` and `ops` switches in every binding - ## Related - [moq-transport passthrough](/quest/m1/ietf-extension/README.md) - its dynamic-groups child is the IETF half this epic promotes diff --git a/quest/m1/refresh/json.md b/quest/m1/refresh/json.md deleted file mode 100644 index a4f93b7b5d7..00000000000 --- a/quest/m1/refresh/json.md +++ /dev/null @@ -1,89 +0,0 @@ -# [M] moq-json groups roll on demand - -## Goal - -moq-json and `@moq/json` snapshot and window producers roll a new group only -when a joiner wants one, or at the existing hard caps, instead of whenever -deltas reach `delta_ratio` times the snapshot (or ops reach `op_ratio` -times the window). The ratio comes from the track's `track::Info::refresh`. -`delta_ratio` and `op_ratio` are removed in Rust, JS, moq-ffi, and every -binding, and a `deltas` / `ops` switch keeps today's no-delta mode. - -## Plan - -Decided 2026-10-16 (see the [epic](/quest/m1/refresh/README.md)), and -revised in the #5734 review. - -- **The ratio lives only on `track::Info::refresh`.** The producers receive - an already-created track, and `track::Info` is fixed at `create_track`, - so a json config field could never reach TRACK_INFO. The producers read - `track.info().refresh` instead. Constructors do not change, and there is - one source of truth. The default is therefore `None`: groups roll only at - the caps unless the caller sets it. Docs, examples, and in-repo callers - set `Some(8)`, today's `delta_ratio` default. -- **No-delta mode.** `delta_ratio = 0` and `op_ratio = 0` mean "never send - deltas or ops" today, which the catalog producers and moq-stats' plain - track rely on. That becomes `snapshot::Config::deltas: bool` and - `window::ProducerConfig::ops: bool` (JS `deltas` / `ops`), default true. - False makes every update its own snapshot group, and refresh is moot. - Rust `with_delta_ratio` and `with_op_ratio` and JS `deltaRatio` and - `opRatio` go away. -- **Producers.** When `Demand::wanted` passes the largest group, the - producer re-emits the current value as a snapshot (or the current window) - in a new group immediately, rather than waiting for the next update. -- **Driver.** The producers are synchronous and moq-json has no runtime, - so the Rust caller drives refresh: `Producer::refresh(&self).await` (plus - `poll_refresh` for sync owners) waits until `wanted` passes the largest - group, then re-emits. Callers loop or select on it beside their updates. - JS producers drive it internally. Decided in the #5734 review, over a - driver handle returned by the constructor and over checking only on - update, which never refreshes an idle value. -- **Driver (moq-ffi).** Each bound json producer drives refresh - internally, as JS does: its constructor starts a task with - `crate::ffi::spawn` that waits on the track's demand, re-emits the value - under the producer's lock, and stops on finish or drop. Bindings gain no - refresh API. Decided in the #5734 review over exposing an async - `refresh()` in moq-ffi and every wrapper (about 150 lines), which every - binding caller would have to loop on, and a missed loop fails silently. -- **Timestamp.** Producers and encoders retain the timestamp of the last - committed update, and a refresh restates the value at it. That is the - state's own time and never rewinds, because it equals the previous - group's last frame. Untimed tracks restate untimed. -- **Track-free encoders.** `snapshot::Encoder` (and the window encoder, JS - too) gain a `snapshot()` operation that re-encodes the retained value as a - snapshot now, for owners that open groups themselves. moq-stats moves to - `snapshot::Producer` where its shared-sequence needs allow, and otherwise - watches `Demand::wanted` and calls `Encoder::snapshot()`. The maintainer - asked for both. -- **Caps.** The unconditional budget roll goes away. `MAX_DELTA_FRAMES` and - the group byte cap still force a snapshot. They are the bound behind a hop - that cannot forward requests, so a joiner there downloads at most up to - the caps. -- This works locally without wire support: a local subscriber's join - drives `wanted` through the track model alone. -- **In-repo users follow:** the hang and moq-mux catalog producers - (`deltas: false`), `js/publish` catalog, moq-stats, the moq-room and - `js/room` chat windows, the moq-hls and moq-archive tests, benches, and - examples. The tracks they create set `track::Info::refresh` where they - keep deltas. -- **Bindings.** Replace `delta_ratio` with `deltas` in moq-ffi - (`rs/moq-ffi/src/json.rs`), moq-c, the py, swift, go, kt, and dart wrappers, and - `doc/lib/*`. The ratio reaches them through `MoqTrackInfo::refresh`, and - the moq-ffi driver above refreshes - their producers with no wrapper change. Update the moq-json and `@moq/json` - READMEs and add an entry to each affected package's `MIGRATE.md`. -- moq-flate is unchanged. Its snapshot mode already opens a group per - update, and its stream mode keeps one group by design. - -Tests: under simulated time, a joiner below the ratio gets the current -group, and a joiner above it gets a fresh snapshot group. With no joiner the -group grows to the caps. `refresh: None` never rolls early, `deltas: false` -writes one snapshot group per update, and `Encoder::snapshot()` restates the -retained value. A refresh on a timed track reuses the last committed -timestamp. Run in Rust and JS. A moq-ffi test shows an idle bound -snapshot producer re-emitting its value when a joiner crosses the ratio. - -Public API: breaking (`delta_ratio` and `op_ratio` replaced by `deltas` and -`ops` in Rust, JS, and every binding that exposes them; `Encoder::snapshot()` -and Rust `Producer::refresh` / `poll_refresh` added; bindings gain no refresh -method because moq-ffi drives it internally). Wire: none. diff --git a/rs/moq-archive/src/reader/tests.rs b/rs/moq-archive/src/reader/tests.rs index 19a6cedb6b8..d21f28732fe 100644 --- a/rs/moq-archive/src/reader/tests.rs +++ b/rs/moq-archive/src/reader/tests.rs @@ -28,20 +28,20 @@ struct Encoder { /// Writes archive objects the way a recording writer lays them out. struct Archive { store: Store, - op_ratio: u32, + ops: bool, encoders: HashMap, } impl Archive { async fn new() -> Self { - Self::with_op_ratio(0).await + Self::with_ops(false).await } - /// `op_ratio` 0 makes every window edit its own checkpoint group. - async fn with_op_ratio(op_ratio: u32) -> Self { + /// Without ops every window edit is its own checkpoint group. + async fn with_ops(ops: bool) -> Self { Self { store: Store::new(Mock::memory(), "rec"), - op_ratio, + ops, encoders: HashMap::new(), } } @@ -58,7 +58,7 @@ impl Archive { .unwrap(); let config = window::ProducerConfig::default() .with_compression(true) - .with_op_ratio(self.op_ratio); + .with_ops(self.ops); self.encoders.insert( track.to_string(), Encoder { @@ -661,7 +661,7 @@ async fn a_track_without_usable_info_is_not_found() { #[tokio::test] async fn multi_frame_timeline_groups_decode() { - let mut archive = Archive::with_op_ratio(64).await; + let mut archive = Archive::with_ops(true).await; let first = archive.record("video", Position::group(0), Position::group(1), 1).await; let second = archive.record("video", Position::group(1), Position::group(2), 1).await; let mut groups = archive.edit("video", &first, 0).await; diff --git a/rs/moq-boy/src/status.rs b/rs/moq-boy/src/status.rs index 6d726b38d1e..c97b5e041d4 100644 --- a/rs/moq-boy/src/status.rs +++ b/rs/moq-boy/src/status.rs @@ -42,7 +42,10 @@ impl StatusPublisher { pub fn new(broadcast: &mut moq_net::broadcast::Producer) -> anyhow::Result { let producer = broadcast.create_track( "status", - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI), + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + // A joiner asks for a fresh snapshot once the deltas outweigh eight of them. + .with_refresh(8), )?; Ok(Self { @@ -51,7 +54,13 @@ impl StatusPublisher { } /// Publish status, a no-op if unchanged since the last call. + /// + /// Also restates the status in a fresh group when a joiner wants one. Status is published every + /// frame, so checking here answers a joiner within a frame without a task of its own. pub fn publish(&mut self, status: &Status) { + if let std::task::Poll::Ready(Err(err)) = self.producer.poll_refresh(&moq_net::kio::Waiter::noop()) { + tracing::warn!(%err, "failed to refresh status"); + } if let Err(err) = self .producer .update(moq_net::Timed::from(status).at(moq_net::Timestamp::now())) diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index 165238a7348..f064ca2f464 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON snapshot `delta_ratio` is `deltas` + +`moq_json_snapshot_config.delta_ratio` is replaced by `bool deltas`. +Set `deltas = false` where you set `delta_ratio = 0`, and `deltas = true` for any positive ratio. +With deltas on, the track carries a refresh ratio of 8 and the producer restates the value in a new group when a joiner asks. + ### Priorities are signed (#6142) `moq_track_info.priority` and `moq_subscription.priority` are `int8_t`, and `moq_group_request_priority` writes an `int8_t`, which changes the ABI. diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 647f3e1f37b..aa7170afaa1 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -423,14 +423,14 @@ pub struct moq_audio_config { /// Options for a JSON snapshot track (lossy latest-value mode). /// /// The same config is passed to a producer and its consumers, but the consumer reads only -/// `compression`; `delta_ratio` is producer-only. +/// `compression`; `deltas` is producer-only. #[repr(C)] #[allow(non_camel_case_types)] pub struct moq_json_snapshot_config { - /// How aggressively the producer emits deltas instead of full snapshots. `0` disables deltas - /// (one snapshot per group); a positive value allows roughly that many snapshots' worth of - /// deltas before rolling. Ignored by the consumer. - pub delta_ratio: u32, + /// Encode updates as deltas against the group's snapshot. When off, each update opens a new + /// group with a full snapshot. When on, a joiner that would download more than eight + /// snapshots' worth of deltas gets the value restated in a fresh group. Ignored by the consumer. + pub deltas: bool, /// DEFLATE-compress each group. Must match on the producer and consumer. pub compression: bool, @@ -3293,7 +3293,7 @@ pub unsafe extern "C" fn moq_publish_json_snapshot( let config = unsafe { config.as_ref() }.ok_or(Error::InvalidPointer)?; let producer = moq_mux::json::Config::default() .with_compression(config.compression) - .with_delta_ratio(config.delta_ratio); + .with_deltas(config.deltas); State::lock().publish.json_snapshot(broadcast, name, producer) }) } diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 9e1f14a074f..b91a258f62a 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -136,6 +136,14 @@ struct Data { clock: moq_mux::Clock, } +/// A JSON snapshot producer, kept beside the signal that stops its refresh task. +struct JsonSnapshot { + data: Data>, + + /// Closed when the entry is removed, which wakes the refresh task to stop. + _alive: kio::Producer<()>, +} + struct Container { inner: import::Container, driver: crate::ffi::Background, @@ -164,7 +172,7 @@ pub struct Publish { /// JSON snapshot producers (lossy latest-value tracks), each advertised in its broadcast's /// catalog for as long as it lives. - json_snapshot: NonZeroSlab>>, + json_snapshot: NonZeroSlab, /// JSON stream producers (lossless append-log tracks), advertised the same way. json_stream: NonZeroSlab>>, @@ -922,17 +930,19 @@ impl Publish { /// Create a track on a broadcast and hand it, with the broadcast's catalog, to `publish`, which /// wraps it in a data producer that advertises the track in that catalog. + /// + /// `refresh` sets the track's [`refresh`](moq_net::track::Info::refresh) ratio. fn data_track( &mut self, broadcast: Id, name: &str, + refresh: Option, publish: impl FnOnce(&moq_mux::catalog::Producer, moq_net::track::Producer) -> moq_mux::Result, ) -> Result, Error> { let broadcast = self.broadcast_mut(broadcast)?; - let track = broadcast.producer.create_track( - name, - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI), - )?; + let mut info = moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI); + info.refresh = refresh; + let track = broadcast.producer.create_track(name, info)?; let producer = publish(&broadcast.catalog, track)?; Ok(Data { producer, @@ -945,24 +955,62 @@ impl Publish { /// Values published via [`Self::json_snapshot_update`] reach subscribers as a single latest /// state; a late joiner only sees the newest value. The catalog entry (`json.tracks.`, /// `mode: snapshot`) is written now and retired when the track finishes or fails. + /// + /// With deltas on, the track carries a refresh ratio of 8: a joiner that would download more + /// than eight snapshots' worth of deltas gets the value restated in a fresh group, by a task + /// that runs until the track is finished. pub fn json_snapshot(&mut self, broadcast: Id, name: &str, config: moq_mux::json::Config) -> Result { - let producer = self.data_track(broadcast, name, |catalog, track| catalog.json_snapshot(track, config))?; - self.json_snapshot.insert(producer) + let refresh = config.deltas.then_some(8); + let data = self.data_track(broadcast, name, refresh, |catalog, track| { + catalog.json_snapshot(track, config) + })?; + let alive = kio::Producer::new(()); + let closed = alive.consume(); + let id = self.json_snapshot.insert(JsonSnapshot { data, _alive: alive })?; + crate::ffi::Background::new(async move { + Self::json_snapshot_refresh(id, closed).await; + Ok(()) + }); + Ok(id) + } + + /// Answer joiners of the JSON snapshot `id` until it is removed, or a refresh fails. + /// + /// A failed restatement only stops the refreshes: the error that caused it (a closed track, a + /// rejected write) reaches the caller through its next update. + async fn json_snapshot_refresh(id: Id, closed: kio::Consumer<()>) { + loop { + let stop = kio::wait(|waiter| { + // Check under the state lock that removes the entry, so a removal never slips between + // the check and the lookup. + let state = State::lock(); + if closed.poll_closed(waiter).is_ready() { + return std::task::Poll::Ready(true); + } + match state.publish.json_snapshot.get(id) { + Some(json) => json.data.producer.poll_refresh(waiter).map(|res| res.is_err()), + None => std::task::Poll::Ready(true), + } + }) + .await; + if stop { + return; + } + } } /// Publish a new value to a JSON snapshot track. A no-op if unchanged. pub fn json_snapshot_update(&mut self, json: Id, value: serde_json::Value) -> Result<(), Error> { - let producer = self.json_snapshot.get_mut(json).ok_or(Error::TrackNotFound)?; - producer - .producer - .update(moq_net::Timed::from(&value).at(producer.clock.now()))?; + let json = &mut self.json_snapshot.get_mut(json).ok_or(Error::TrackNotFound)?.data; + json.producer + .update(moq_net::Timed::from(&value).at(json.clock.now()))?; Ok(()) } /// Finish a JSON snapshot track and retire its catalog entry. No more values can be published. pub fn json_snapshot_finish(&mut self, json: Id) -> Result<(), Error> { - let producer = self.json_snapshot.remove(json).ok_or(Error::TrackNotFound)?; - producer.producer.finish()?; + let json = self.json_snapshot.remove(json).ok_or(Error::TrackNotFound)?; + json.data.producer.finish()?; Ok(()) } @@ -971,7 +1019,9 @@ impl Publish { /// Every record appended via [`Self::json_stream_append`] is preserved and delivered in order. /// The catalog entry (`json.tracks.`, `mode: stream`) lives as long as the track. pub fn json_stream(&mut self, broadcast: Id, name: &str, config: moq_mux::json::Config) -> Result { - let producer = self.data_track(broadcast, name, |catalog, track| catalog.json_stream(track, config))?; + let producer = self.data_track(broadcast, name, None, |catalog, track| { + catalog.json_stream(track, config) + })?; self.json_stream.insert(producer) } @@ -994,7 +1044,9 @@ impl Publish { /// Create a binary snapshot track (lossy latest-value) on a broadcast, advertised in its catalog /// as `binary.tracks.`, `mode: snapshot`. pub fn binary_snapshot(&mut self, broadcast: Id, name: &str, config: moq_mux::binary::Config) -> Result { - let producer = self.data_track(broadcast, name, |catalog, track| catalog.binary_snapshot(track, config))?; + let producer = self.data_track(broadcast, name, None, |catalog, track| { + catalog.binary_snapshot(track, config) + })?; self.binary_snapshot.insert(producer) } @@ -1017,7 +1069,9 @@ impl Publish { /// Create a binary stream track (lossless append-log) on a broadcast, advertised in its catalog /// as `binary.tracks.`, `mode: stream`. pub fn binary_stream(&mut self, broadcast: Id, name: &str, config: moq_mux::binary::Config) -> Result { - let producer = self.data_track(broadcast, name, |catalog, track| catalog.binary_stream(track, config))?; + let producer = self.data_track(broadcast, name, None, |catalog, track| { + catalog.binary_stream(track, config) + })?; self.binary_stream.insert(producer) } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 2e679bc5e65..d98cc3fe827 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -2065,7 +2065,7 @@ fn json_snapshot_publish_consume() { let track_name = b"meta"; let config = moq_json_snapshot_config { - delta_ratio: 8, + deltas: true, compression: true, }; let producer = id(unsafe { @@ -5818,7 +5818,7 @@ fn json_tracks_are_advertised_in_the_catalog() { status.as_ptr() as *const c_char, status.len(), &moq_json_snapshot_config { - delta_ratio: 4, + deltas: true, compression: true, }, ) @@ -5963,7 +5963,7 @@ fn data_track_names_cannot_collide() { name.as_ptr() as *const c_char, name.len(), &moq_json_snapshot_config { - delta_ratio: 0, + deltas: false, compression: false, }, ) diff --git a/rs/moq-cli/src/report.rs b/rs/moq-cli/src/report.rs index b6553eddb6f..fdbcf7be822 100644 --- a/rs/moq-cli/src/report.rs +++ b/rs/moq-cli/src/report.rs @@ -52,13 +52,15 @@ impl Pair { fn create(broadcast: &mut moq_net::broadcast::Producer, name: &str) -> anyhow::Result { let info = moq_net::track::Info::default().with_priority(PRIORITY); let plain = broadcast.create_track(name, info.clone())?; - let compressed = broadcast.create_track(format!("{name}{COMPRESSED}").as_str(), info)?; + // The compressed flavor keeps deltas, so a joiner asks for a fresh group once they outweigh + // eight snapshots. + let compressed = broadcast.create_track(format!("{name}{COMPRESSED}").as_str(), info.with_refresh(8))?; let mut deflate = moq_json::snapshot::Config::default(); deflate.compression = moq_json::Compression::Deflate; Ok(Self { plain: Some(moq_json::snapshot::Producer::new( plain, - moq_json::snapshot::Config::default().with_delta_ratio(0), + moq_json::snapshot::Config::default().with_deltas(false), )), compressed: Some(moq_json::snapshot::Producer::new(compressed, deflate)), }) @@ -77,12 +79,19 @@ impl Pair { /// Publish `value` on both tracks. A track that refuses a write would refuse every later one, /// so it is closed with the cause, which its subscribers then read, and reported once. + /// + /// Also restates the value in a fresh group when a joiner wants one. Reports are written every + /// interval, so checking here answers a joiner within one without a task of its own. fn write(&mut self, value: &T) { for slot in [&mut self.plain, &mut self.compressed] { let Some(track) = slot else { continue; }; - if let Err(err) = track.update(value) { + let refreshed = match track.poll_refresh(&moq_net::kio::Waiter::noop()) { + std::task::Poll::Ready(Err(err)) => Err(err), + _ => Ok(()), + }; + if let Err(err) = refreshed.and_then(|()| track.update(value)) { tracing::warn!(%err, "a report track failed; closing it"); if let Some(track) = slot.take() { let _ = track.abort(moq_net::Error::Transport(err.to_string())); @@ -614,6 +623,24 @@ mod tests { assert!(matches!(read.next().await, Err(moq_json::Error::TooLarge(MAX_REPORT)))); } + /// A joiner once the compressed track's deltas outweigh its refresh ratio gets the report + /// restated in a fresh group on the next write. + #[tokio::test] + async fn a_late_joiner_gets_a_fresh_report_group() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let mut pair = Pair::::create(&mut broadcast, STATS_TRACK).unwrap(); + let compressed = pair.compressed.clone().unwrap(); + let _early = compressed.consume(); + for n in 0..100 { + pair.write(&serde_json::json!({ "n": n })); + } + + let mut late = compressed.consume(); + assert_eq!(compressed.demand().wanted(), Some(1), "the join asks for a fresh group"); + pair.write(&serde_json::json!({ "n": 100 })); + assert_eq!(late.largest().await.map(|position| position.group), Some(1)); + } + /// A feedback track can outlive its route, so a reader left to drain stops after `DRAIN`. #[tokio::test(start_paused = true)] async fn an_ended_feedback_reader_stops_after_draining() { diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index be16b1d0ccd..11ad49bbd94 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,6 +5,12 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased +### JSON snapshot `delta_ratio` is `deltas` + +`MoqJsonSnapshotConfig::delta_ratio` is replaced by `deltas: bool` (default `true`). +Set `deltas: false` where you set `delta_ratio: 0`. +Snapshot groups roll on joiner demand, which the producer answers on its own: publish the track with `MoqTrackInfo::refresh` (`Some(8)` matches the old default), or its groups roll only at their caps. + ### Priorities are signed (#6142) `MoqTrackInfo.priority`, `MoqSubscription.priority`, `MoqFetchGroupOptions.priority`, and `MoqGroupRequest.priority()` are `i8`, higher first, and 0 is the unset midpoint. diff --git a/rs/moq-ffi/src/json.rs b/rs/moq-ffi/src/json.rs index 82353be924f..fe95f5e9173 100644 --- a/rs/moq-ffi/src/json.rs +++ b/rs/moq-ffi/src/json.rs @@ -20,14 +20,14 @@ use moq_mux::catalog::hang::Extra; /// Options for a JSON snapshot track (lossy latest-value mode). /// /// The same config is passed to both the producer and the consumer, but the consumer reads only -/// [`compression`](Self::compression); [`delta_ratio`](Self::delta_ratio) is producer-only. +/// [`compression`](Self::compression); [`deltas`](Self::deltas) is producer-only. #[derive(Clone, uniffi::Record)] pub struct MoqJsonSnapshotConfig { - /// How aggressively the producer emits deltas instead of full snapshots. `0` disables deltas - /// (one snapshot per group); a positive value allows roughly that many snapshots' worth of - /// deltas before rolling a new group. Ignored by the consumer. - #[uniffi(default = 8)] - pub delta_ratio: u32, + /// Encode updates as deltas against the group's snapshot. When off, each update opens a new + /// group with a full snapshot. How long a group runs is set by the track's `refresh` ratio + /// instead. Ignored by the consumer. + #[uniffi(default = true)] + pub deltas: bool, /// DEFLATE-compress each group. Must match on the producer and consumer. #[uniffi(default = false)] @@ -45,7 +45,7 @@ fn compression(on: bool) -> moq_json::Compression { impl From for moq_json::snapshot::Config { fn from(config: MoqJsonSnapshotConfig) -> Self { let mut out = moq_json::snapshot::Config::default(); - out.delta_ratio = config.delta_ratio; + out.deltas = config.deltas; out.compression = compression(config.compression); out } @@ -85,7 +85,7 @@ mod tests { #[test] fn record_defaults_match_moq_json() { let snapshot = moq_json::snapshot::Config::default(); - assert_eq!(snapshot.delta_ratio, 8, "update #[uniffi(default)] on delta_ratio"); + assert!(snapshot.deltas, "update #[uniffi(default)] on deltas"); assert_eq!( snapshot.compression, moq_json::Compression::None, @@ -102,9 +102,50 @@ mod tests { // ---- Snapshot ---- /// Publishes a JSON value that consumers see as a single latest state. +/// +/// A joiner that would download more deltas than the track's `refresh` ratio allows gets the +/// value restated in a fresh group, by a task this producer runs until it is finished or dropped. #[derive(uniffi::Object)] pub struct MoqJsonSnapshotProducer { - inner: std::sync::Mutex>>, + inner: Arc>>>, + + /// Closed on finish or drop, which stops the refresh task. + alive: kio::Producer<()>, +} + +impl MoqJsonSnapshotProducer { + /// Answer joiners until the producer is finished or dropped, or a refresh fails. + /// + /// A failed restatement only stops the refreshes: the error that caused it (a closed track, a + /// rejected write) reaches the caller through its next update. + async fn refresh( + inner: Arc>>>, + alive: kio::Consumer<()>, + ) { + loop { + let stop = kio::wait(|waiter| { + if alive.poll_closed(waiter).is_ready() { + return std::task::Poll::Ready(true); + } + match inner.lock().unwrap().as_ref() { + Some(producer) => producer.poll_refresh(waiter).map(|res| res.is_err()), + None => std::task::Poll::Ready(true), + } + }) + .await; + if stop { + return; + } + } + } +} + +impl Drop for MoqJsonSnapshotProducer { + fn drop(&mut self) { + // The refresh task shares `inner`, so drop the producer here rather than whenever the task + // next wakes: dropping it retires the catalog entry. + self.inner.lock().unwrap().take(); + } } #[uniffi::export] @@ -127,12 +168,13 @@ impl MoqJsonSnapshotProducer { let _guard = crate::ffi::enter(); let config = moq_mux::json::Config::default() .with_compression(config.compression) - .with_delta_ratio(config.delta_ratio); + .with_deltas(config.deltas); let producer = track .adopt(|track| broadcast.with_state(|state| Ok(state.catalog.json_snapshot::(track, config)?)))?; - Ok(Arc::new(Self { - inner: std::sync::Mutex::new(Some(producer)), - })) + let inner = Arc::new(std::sync::Mutex::new(Some(producer))); + let alive = kio::Producer::new(()); + crate::ffi::spawn(Self::refresh(inner.clone(), alive.consume())); + Ok(Arc::new(Self { inner, alive })) } /// Publish a new value, encoded as a snapshot or delta automatically. `value` is a JSON @@ -161,6 +203,7 @@ impl MoqJsonSnapshotProducer { pub fn finish(&self) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let producer = self.inner.lock().unwrap().take().ok_or(MoqError::Closed)?; + let _ = self.alive.close(); producer.finish()?; Ok(()) } diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 1a1ff215d64..262e046ded3 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -960,7 +960,7 @@ async fn data_writes_preserve_optional_timestamps() { &broadcast, &track, MoqJsonSnapshotConfig { - delta_ratio: 0, + deltas: false, compression: false, }, ) @@ -1082,7 +1082,7 @@ async fn catalog_now_fixes_the_clock_for_later_media() { async fn json_snapshot_roundtrip() { let broadcast = MoqBroadcastProducer::new().unwrap(); let config = MoqJsonSnapshotConfig { - delta_ratio: 8, + deltas: true, compression: true, }; let info = MoqTrackInfo { @@ -1150,12 +1150,66 @@ async fn json_snapshot_roundtrip() { assert_eq!(end, None); } +/// An idle snapshot producer restates its value in a fresh group once a joiner would otherwise +/// download more deltas than the track's refresh ratio allows. +#[tokio::test] +async fn json_snapshot_refreshes_for_a_joiner() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let track = broadcast + .publish_track( + "meta".into(), + Some(MoqTrackInfo { + priority: 127, + max_age_us: None, + refresh: Some(1), + timescale: None, + compress: false, + }), + ) + .unwrap(); + let config = MoqJsonSnapshotConfig { + deltas: true, + compression: false, + }; + let producer = MoqJsonSnapshotProducer::new(&broadcast, &track, config.clone()).unwrap(); + for n in 0..4 { + producer.update(format!(r#"{{"n":{n}}}"#), None).unwrap(); + } + + // The join crosses the ratio, so the producer restates the value without another update. The + // joiner may read the open group first or skip straight to the restatement. + let joiner = subscribe(&broadcast, "meta").await; + let refreshed = tokio::time::timeout(TIMEOUT, async { + loop { + let group = joiner.recv_group().await.unwrap().expect("expected a group"); + if group.sequence() > 0 { + return group; + } + } + }) + .await + .expect("timed out waiting for the refresh"); + assert_eq!(refreshed.sequence(), 1); + let consumer = MoqJsonSnapshotConsumer::new(&*subscribe(&broadcast, "meta").await, config).unwrap(); + let value = tokio::time::timeout(TIMEOUT, consumer.next()) + .await + .expect("timed out waiting for the restated value") + .unwrap() + .expect("expected a value"); + assert_eq!( + serde_json::from_str::(&value.value).unwrap(), + serde_json::json!({ "n": 3 }) + ); + + producer.finish().unwrap(); +} + /// JSON producers report subscriber demand through a handle, like the media and raw track producers. #[tokio::test] async fn json_demand() { let broadcast = MoqBroadcastProducer::new().unwrap(); let snapshot_config = MoqJsonSnapshotConfig { - delta_ratio: 8, + deltas: true, compression: true, }; let stream_config = MoqJsonStreamConfig { compression: true }; @@ -6805,7 +6859,7 @@ async fn json_tracks_are_advertised_in_the_catalog() { &broadcast, &broadcast.publish_track("status".into(), None).unwrap(), MoqJsonSnapshotConfig { - delta_ratio: 4, + deltas: true, compression: true, }, ) @@ -6890,7 +6944,7 @@ async fn data_track_names_cannot_collide() { &broadcast, &broadcast.publish_track("state".into(), None).unwrap(), MoqJsonSnapshotConfig { - delta_ratio: 0, + deltas: false, compression: false, }, ) diff --git a/rs/moq-hls/src/export/archive_tests.rs b/rs/moq-hls/src/export/archive_tests.rs index b11c885c580..8025a454d6c 100644 --- a/rs/moq-hls/src/export/archive_tests.rs +++ b/rs/moq-hls/src/export/archive_tests.rs @@ -137,9 +137,7 @@ impl Recording { .put_info(&timeline(track), &Info::new(0, Some(1000)).unwrap()) .await .unwrap(); - let config = window::ProducerConfig::default() - .with_compression(true) - .with_op_ratio(0); + let config = window::ProducerConfig::default().with_compression(true).with_ops(false); let encoder = Encoder { encoder: window::Encoder::new(config), group: 0, @@ -307,7 +305,7 @@ impl Replay { .create_track(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()) .unwrap(); let mut json = moq_json::snapshot::Config::default(); - json.delta_ratio = 0; + json.deltas = false; let mut catalog = moq_json::snapshot::Producer::new(track, json); catalog .update(moq_net::Timed::from(&self::catalog(archive)).at(moq_net::Timestamp::now())) @@ -408,7 +406,7 @@ async fn segments_with(count: u64, checkpoint: Option) -> Recording { window::ProducerConfig::default() .with_compression(true) .with_checkpoint_records(limit) - .with_op_ratio(0), + .with_ops(false), ); } } diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index 67dae16cc96..342bf97bced 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -2509,7 +2509,7 @@ mod tests { snapshot.video.renditions.insert("video0".to_string(), video_config()); snapshot.archive = Some(timelines.section()); let mut json = moq_json::snapshot::Config::default(); - json.delta_ratio = 0; + json.deltas = false; let mut catalog = moq_json::snapshot::Producer::new( broadcast .create_track(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()) @@ -4903,8 +4903,9 @@ mod tests { let (_track, mut video0) = early.publish("video0"); // A day of 10s GOPs per round. const DAY: u64 = 86_400 / 10; - // A checkpoint, plus the edits one timeline group holds before the publisher rolls it. - let bound = segments::MAX_SEGMENTS * (1 + moq_json::window::ProducerConfig::default().op_ratio as usize); + // A checkpoint, plus the edits one timeline group holds before a join over its ratio rolls it. + let ratio = moq_mux::timeline::Producer::info().refresh.unwrap() as usize; + let bound = segments::MAX_SEGMENTS * (1 + ratio); for day in 1..=3 { for sequence in (day - 1) * DAY..day * DAY { video0 diff --git a/rs/moq-json/MIGRATE.md b/rs/moq-json/MIGRATE.md index d888087cec3..b991973441f 100644 --- a/rs/moq-json/MIGRATE.md +++ b/rs/moq-json/MIGRATE.md @@ -4,6 +4,16 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Groups roll on joiner demand + +`snapshot::Config::delta_ratio` and `window::ProducerConfig::op_ratio`, with `with_delta_ratio` and `with_op_ratio`, are replaced by `deltas: bool` and `ops: bool` (both default `true`). +Set `deltas: false` where you set `delta_ratio = 0`, and `ops: false` where you set `op_ratio = 0`. +A group no longer rolls on a byte budget: create the track with `Info::refresh` (`Some(8)` matches the old default) and drive `Producer::refresh` (or `poll_refresh`) beside your edits, so a joiner past the ratio gets the value or window restated in a new group. +Without a ratio a group rolls only at its frame and byte caps. +An `Encoder` user restates with `Encoder::snapshot()` once `Demand::wanted` passes the largest group it wrote. + +`Encoder::value` (and so `Producer::modify`/`mutate`) now holds the last committed value: a rejected publish no longer carries into the next edit, so retry the edit yourself if you still want it. + ### Consumers return `Timed` (#5677) Snapshot, stream, and window `next` / `poll_next` return `moq_net::Timed`: read `.value` for the value and `.at` for the frame's exact timestamp, `None` when untimed. diff --git a/rs/moq-json/benches/allocations.rs b/rs/moq-json/benches/allocations.rs index a5271cfa525..5b2daeb0a36 100644 --- a/rs/moq-json/benches/allocations.rs +++ b/rs/moq-json/benches/allocations.rs @@ -73,7 +73,7 @@ fn measure(fields: usize, changed_percent: usize, compressed: bool) -> (usize, u } else { moq_json::Compression::None }; - let mut config = snapshot::Config::default().with_delta_ratio(u32::MAX); + let mut config = snapshot::Config::default().with_deltas(true); config.compression = compression; let mut encoder = Encoder::::new(config); let mut decoder_config = snapshot::consumer::Config::default(); diff --git a/rs/moq-json/benches/table.rs b/rs/moq-json/benches/table.rs index 81052a97176..53f31e79184 100644 --- a/rs/moq-json/benches/table.rs +++ b/rs/moq-json/benches/table.rs @@ -3,8 +3,8 @@ //! (100 rows at 100%, 10k at 1%) separate a cost that grows with the table from one that grows with //! the changed rows. //! -//! Each iteration is one tick against a long-lived encoder, so the periodic snapshots the delta -//! budget forces are amortized in, as they are in production. +//! Each iteration is one tick against a long-lived encoder, so the snapshots the frame cap +//! forces are amortized in, as they are in production without a joiner asking for refreshes. //! //! Run with `cargo bench -p moq-json --bench table`. @@ -69,7 +69,7 @@ impl Table { fn configs() -> [(&'static str, Config); 2] { let mut compressed = Config::default(); compressed.compression = moq_json::Compression::Deflate; - [("json.z", compressed), ("json", Config::default().with_delta_ratio(0))] + [("json.z", compressed), ("json", Config::default().with_deltas(false))] } fn table(c: &mut Criterion) { diff --git a/rs/moq-json/examples/telemetry.rs b/rs/moq-json/examples/telemetry.rs index dbf377d7a33..a40159b2e94 100644 --- a/rs/moq-json/examples/telemetry.rs +++ b/rs/moq-json/examples/telemetry.rs @@ -186,9 +186,9 @@ fn verify_late_joiner(producer_config: snapshot::Config, ticks: u64) -> usize { yielded } -fn cfg(delta_ratio: u32, compression: bool) -> snapshot::Config { +fn cfg(deltas: bool, compression: bool) -> snapshot::Config { let mut config = snapshot::Config::default(); - config.delta_ratio = delta_ratio; + config.deltas = deltas; config.compression = if compression { Compression::Deflate } else { @@ -207,10 +207,10 @@ fn main() { let snapshot_len = serde_json::to_vec(&telemetry(0)).unwrap().len(); let combos = [ - ("snapshot-per-group, plaintext", cfg(0, false)), - ("snapshot-per-group, deflate ", cfg(0, true)), - ("snapshot+delta, plaintext", cfg(8, false)), - ("snapshot+delta, deflate ", cfg(8, true)), + ("snapshot-per-group, plaintext", cfg(false, false)), + ("snapshot-per-group, deflate ", cfg(false, true)), + ("snapshot+delta, plaintext", cfg(true, false)), + ("snapshot+delta, deflate ", cfg(true, true)), ]; println!("Telemetry stream: {TICKS} ticks, ~{snapshot_len} bytes per snapshot\n"); diff --git a/rs/moq-json/src/lib.rs b/rs/moq-json/src/lib.rs index 67d8a3ede7b..db8d156e5fe 100644 --- a/rs/moq-json/src/lib.rs +++ b/rs/moq-json/src/lib.rs @@ -21,6 +21,7 @@ mod diff; mod merge; +mod refresh; pub mod snapshot; pub mod stream; mod strict; diff --git a/rs/moq-json/src/refresh.rs b/rs/moq-json/src/refresh.rs new file mode 100644 index 00000000000..b945ed91212 --- /dev/null +++ b/rs/moq-json/src/refresh.rs @@ -0,0 +1,38 @@ +//! Waiting for a joiner to want a fresh group. + +use std::task::Poll; + +use crate::Result; + +/// Watches a track's [`Demand`](moq_net::track::Demand) for a group past the largest one written. +/// +/// A join judged by the track's [`refresh`](moq_net::track::Info::refresh) ratio asks for the next +/// free sequence, so a producer restating its value in a new group answers it. +pub(crate) struct Refresh { + demand: moq_net::track::Demand, +} + +impl Refresh { + pub fn new(track: &moq_net::track::Producer) -> Self { + Self { demand: track.demand() } + } + + /// Ready once consumers want a group past `largest`, the newest group written, arming `waiter` + /// for the next demand change otherwise. Never ready before a group is written (`None`), since + /// there is nothing to restate yet. Errors once the track closes. + pub fn poll(&mut self, largest: Option, waiter: &kio::Waiter) -> Poll> { + // Drain the changes so `waiter` is armed for the next one; the decision reads the level. + loop { + match self.demand.poll_wanted_changed(waiter) { + Poll::Ready(Ok(_)) => continue, + Poll::Ready(Err(err)) => return Poll::Ready(Err(err.into())), + Poll::Pending => break, + } + } + + match (self.demand.wanted(), largest) { + (Some(wanted), Some(largest)) if wanted > largest => Poll::Ready(Ok(())), + _ => Poll::Pending, + } + } +} diff --git a/rs/moq-json/src/snapshot/consumer.rs b/rs/moq-json/src/snapshot/consumer.rs index 688d4d3ea96..a21692f2d16 100644 --- a/rs/moq-json/src/snapshot/consumer.rs +++ b/rs/moq-json/src/snapshot/consumer.rs @@ -180,8 +180,10 @@ mod timestamps { let mut subscription = subscriber.subscription(); subscription.max_delay = std::time::Duration::MAX; subscriber.update(subscription).unwrap(); - let mut config = crate::snapshot::Config::default().with_delta_ratio(100); - config.compression = compression; + let config = crate::snapshot::Config { + compression, + ..Default::default() + }; let mut producer = crate::snapshot::Producer::new(track, config.clone()); let mut consumer = Consumer::::new( subscriber, @@ -242,7 +244,7 @@ mod timestamps { let subscriber = track.subscribe(None); let config = crate::snapshot::Config { compression: crate::Compression::Deflate, - ..crate::snapshot::Config::default().with_delta_ratio(100) + ..crate::snapshot::Config::default() }; let mut producer = crate::snapshot::Producer::new(track, config.clone()); let mut consumer = Consumer::::new( diff --git a/rs/moq-json/src/snapshot/decoder.rs b/rs/moq-json/src/snapshot/decoder.rs index 3159b851c4e..835e9441c7b 100644 --- a/rs/moq-json/src/snapshot/decoder.rs +++ b/rs/moq-json/src/snapshot/decoder.rs @@ -186,6 +186,7 @@ impl Decoder { #[cfg(test)] mod test { use super::super::consumer::Config as ConsumerConfig; + use super::super::encoder::MAX_DELTA_FRAMES; use super::super::{Config, Encoder}; use super::*; use crate::Compression; @@ -344,14 +345,43 @@ mod test { 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 - /// that kept the old window here would fail to inflate the new group's snapshot. + /// The window is per group, so a keyframe mid-stream has to restart it on both sides. An encoder + /// that kept the old window would emit frames a joiner starting at the new group can't inflate. #[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 = deflate().with_delta_ratio(2); - assert_eq!(roundtrip(config, &values).last().unwrap(), &json!({ "n": 40 })); + let mut encoder = Encoder::::new(deflate().with_deltas(true)); + // One decoder reads every group in turn, and a joiner starts cold at each group, as a late + // subscriber does. The joiner catches an encoder that carries its window across the boundary. + let mut decoder = Decoder::::new(consume(Compression::Deflate)); + let mut joiner = Decoder::::new(consume(Compression::Deflate)); + + // The frame cap rolls the group partway through, and a restatement rolls it again. + let restate = MAX_DELTA_FRAMES + 10; + let mut keyframes = 0; + for n in 0..=2 * MAX_DELTA_FRAMES { + let value = json!({ "n": n }); + let frame = if n == restate { + encoder.update(&value).unwrap().unwrap().commit(); + encoder.snapshot().unwrap().unwrap() + } else { + encoder.update(&value).unwrap().unwrap() + }; + if frame.keyframe { + keyframes += 1; + joiner = Decoder::::new(consume(Compression::Deflate)); + decoder.snapshot(&frame.payload).unwrap(); + joiner.snapshot(&frame.payload).unwrap(); + } else { + decoder.delta(&frame.payload).unwrap(); + joiner.delta(&frame.payload).unwrap(); + } + frame.commit(); + assert_eq!(decoder.decode().unwrap(), Some(value.clone()), "after update {n}"); + assert_eq!(joiner.decode().unwrap(), Some(value), "a joiner after update {n}"); + } + + // The first group, the cap roll, and the restatement. + assert_eq!(keyframes, 3, "the stream has to cross group boundaries"); } #[test] @@ -371,7 +401,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(Config::default().with_delta_ratio(100)); + let mut encoder = Encoder::::new(Config::default().with_deltas(true)); 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 c2acbb4b577..493e3dc49c2 100644 --- a/rs/moq-json/src/snapshot/encoder.rs +++ b/rs/moq-json/src/snapshot/encoder.rs @@ -19,7 +19,7 @@ pub(super) const MAX_DELTA_FRAMES: usize = 256; /// What an [`Encoder`] keeps of the value it last emitted. /// /// A delta is a diff against the previous value, so one has to be parsed to diff against -/// whenever deltas are possible. With `delta_ratio = 0` none ever are, and the only question +/// whenever deltas are possible. With [`Config::deltas`] off none ever are, and the only question /// an update asks of the baseline is whether the value changed at all, which the encoded /// bytes answer directly. The parse is deferred in that case, and a value that is only ever /// published never pays for one. @@ -50,25 +50,21 @@ impl Baseline { /// 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 [`with_delta_ratio`](Self::with_delta_ratio). +/// options stay additive), or chain [`with_deltas`](Self::with_deltas). +/// +/// How long a group runs is not a codec option: a group grows until a joiner wants a fresh one, +/// judged by the track's [`refresh`](moq_net::track::Info::refresh) ratio, or until it reaches +/// the frame or byte cap. #[derive(Debug, Clone)] #[non_exhaustive] 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. - /// - /// A positive ratio enables deltas. A new snapshot is emitted once the deltas *already written* - /// to the current group (excluding the snapshot frame) exceed `ratio` times the snapshot size. - /// The pending delta is excluded from that check, so the one that first crosses the budget - /// still lands before the group rolls. So `1` allows roughly one snapshot's worth of deltas before - /// rolling, and a larger ratio tolerates more. + /// Whether changes ride as merge-patch deltas in the open group. /// - /// When [`compression`](Self::compression) is [`Compression::Deflate`], both sides of the - /// comparison are measured on the *compressed* frame sizes (the real wire cost). + /// `false` makes every change its own single-frame snapshot group, identical on the wire to a + /// plain "one JSON blob per group" track, so refresh never applies. /// - /// Defaults to `8`. - pub delta_ratio: u32, + /// Defaults to `true`. + pub deltas: bool, /// Compress each group as one sync-flushed DEFLATE stream, so deltas reuse the snapshot as /// context and shrink sharply. @@ -80,9 +76,9 @@ pub struct Config { } 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; + /// Set [`deltas`](Self::deltas) (a builder, since the struct is `#[non_exhaustive]`). + pub fn with_deltas(mut self, deltas: bool) -> Self { + self.deltas = deltas; self } } @@ -90,7 +86,7 @@ impl Config { impl Default for Config { fn default() -> Self { Self { - delta_ratio: 8, + deltas: true, compression: Compression::None, } } @@ -108,9 +104,10 @@ pub struct Encoded { /// merge patch that must be appended to the group the last snapshot opened. Mapping straight onto /// [`moq_mux::container::Frame::keyframe`] is the point of the name. /// - /// The encoder decides this, never the caller: a value that sets a field to JSON null, or whose - /// root isn't an object, cannot be expressed as a merge patch at all, and the delta budget and - /// frame cap force a snapshot independently of what the caller wanted. + /// The encoder decides this for an [`update`](Encoder::update): a value that sets a field to JSON + /// null, or whose root isn't an object, cannot be expressed as a merge patch at all, and the + /// group's frame and byte caps force a snapshot independently of what the caller wanted. A caller + /// asks for one with [`snapshot`](Encoder::snapshot). /// /// [`moq_mux::container::Frame::keyframe`]: https://docs.rs/moq-mux/latest/moq_mux/container/struct.Frame.html pub keyframe: bool, @@ -122,26 +119,38 @@ pub struct Encoded { /// [`keyframe`](Encoded::keyframe) through the [`Deref`](std::ops::Deref) to [`Encoded`], write the /// frame, then [`commit`](Self::commit). /// -/// Dropping it uncommitted [`Encoder::reset`]s, so a frame that never reached the wire leaves the -/// encoder resynchronizing with a fresh snapshot rather than emitting deltas against a baseline no -/// consumer received. Note that this is a recovery, not a rollback: producing a delta payload -/// advances the group's DEFLATE window, and that can't be undone, so a snapshot is the only sound -/// way back. Forgetting to commit a frame that *was* written is therefore merely wasteful (one -/// redundant snapshot), never incorrect. +/// The frame's value is staged until commit, so dropping it uncommitted leaves +/// [`Encoder::value`] at the last value that reached the wire, and [`Encoder::reset`]s so the next +/// frame is a fresh snapshot rather than a delta against a group no consumer received. The group +/// state is a recovery, not a rollback: producing a delta payload advances the group's DEFLATE +/// window, and that can't be undone, so a snapshot is the only sound way back. Forgetting to commit +/// a frame that *was* written therefore costs one redundant snapshot and leaves the value a step +/// behind, but never corrupts the stream. #[must_use = "the frame must be written and committed, or dropped to resynchronize the encoder"] pub struct Pending<'a, T> { encoder: &'a mut Encoder, encoded: Encoded, - committed: bool, + edit: Option, +} + +/// The baseline change staged behind a [`Pending`] frame. +enum Edit { + /// A snapshot replaces the baseline. + Snapshot(Baseline), + /// A delta folds this merge patch into the baseline. + Delta(Bytes), + /// A snapshot restating the baseline as it is, which changes nothing. + Restate, } impl Pending<'_, T> { - /// Acknowledge that the frame reached the wire, keeping the encoder's state. + /// Acknowledge that the frame reached the wire, applying its value to the baseline. /// /// Only call this once the write has actually succeeded. Committing a frame that failed to write /// is the one thing that corrupts the stream. pub fn commit(mut self) { - self.committed = true; + let edit = self.edit.take().expect("pending edit"); + self.encoder.commit(edit); } } @@ -155,7 +164,7 @@ impl std::ops::Deref for Pending<'_, T> { impl Drop for Pending<'_, T> { fn drop(&mut self) { - if !self.committed { + if self.edit.is_some() { self.encoder.reset(); } } @@ -189,12 +198,14 @@ impl Drop for Pending<'_, T> { /// fresh snapshot. Committing a frame you failed to write is the one way to corrupt the stream. /// /// 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. +/// [`reset`](Self::reset) directly so the next value opens the new group with a snapshot. To open +/// one right away, such as when a joiner wants a fresh group (see +/// [`Demand::wanted`](moq_net::track::Demand::wanted)), call [`snapshot`](Self::snapshot). pub struct Encoder { 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. + /// The last committed value, the baseline every delta is diffed against. `None` until the first + /// snapshot commits, which is what makes that first [`update`](Self::update) a keyframe. last: Option, /// Reused key buffers for comparing unchanged fields without per-update allocations, and the @@ -204,13 +215,8 @@ pub struct Encoder { /// The current group's DEFLATE encoder (one window per group), `Some` while compressing. flate: Option, - /// Bytes of deltas emitted into the current group, excluding the snapshot frame. Compressed - /// slice sizes when compressing, raw patch sizes otherwise. - delta_bytes: u64, - - /// Reference size the delta budget is measured against: the current group's snapshot frame. - /// Its compressed slice size when compressing, raw otherwise. - snapshot_len: u64, + /// Payload bytes emitted into the current group, snapshot included. + group_bytes: u64, /// Frames emitted into the current group, snapshot included. group_frames: usize, @@ -236,8 +242,7 @@ impl Encoder { last: None, scratch: RefCell::new(crate::diff::Scratch::memoized()), flate: None, - delta_bytes: 0, - snapshot_len: 0, + group_bytes: 0, group_frames: 0, max_group_bytes: moq_net::group::MAX_CACHE_BYTES, resync: false, @@ -245,10 +250,11 @@ impl Encoder { } } - /// The last encoded value, or `None` before the first snapshot. + /// The last committed value, or `None` before the first snapshot commits. /// /// This is the baseline the next delta is diffed against, which is what a caller editing the - /// value in place needs to start from. + /// value in place needs to start from. A frame dropped uncommitted never reached the wire, so its + /// value never lands here. /// /// With deltas disabled the baseline is held as the encoded bytes, so the first call parses /// them; the result is cached, and callers that never read the value never pay for it. @@ -266,37 +272,139 @@ impl Encoder { /// caller editing in place starts from. pub fn reset(&mut self) { self.flate = None; - self.delta_bytes = 0; - self.snapshot_len = 0; + self.group_bytes = 0; self.group_frames = 0; self.resync = true; } + + /// Restate the last committed value as a full snapshot, which must open a new group. + /// + /// For a caller that opens groups itself: call it when a joiner wants a fresh group, such as when + /// [`Demand::wanted`](moq_net::track::Demand::wanted) passes the largest group written, so the + /// joiner reads the value without the deltas before it. Returns `None` before the first value, + /// when there is nothing to restate. The frame is a [`Pending`] like any other. + pub fn snapshot(&mut self) -> Result>> { + let bytes = match &self.last { + None => return Ok(None), + // A delta-free baseline is the emitted bytes already. + Some(Baseline::Encoded { bytes, .. }) => bytes.clone(), + Some(Baseline::Parsed(value)) => Bytes::from(serde_json::to_vec(value)?), + }; + let encoded = self.snapshot_encoded(bytes)?; + Ok(Some(Pending { + encoder: self, + encoded, + edit: Some(Edit::Restate), + })) + } + + /// Apply a frame's staged value to the baseline once the frame reached the wire. + fn commit(&mut self, edit: Edit) { + match edit { + Edit::Snapshot(last) => { + self.last = Some(last); + // Seeded from the snapshot rather than a diff, so no root entry is memoized against it yet. + self.scratch.get_mut().clear_memo(); + } + Edit::Delta(patch) => { + // Reaching a delta means `delta_allowed`, which means deltas are on, which is what keeps + // the baseline parsed. + let Some(Baseline::Parsed(last)) = self.last.as_mut() else { + unreachable!("a parsed snapshot precedes any delta") + }; + crate::merge::apply_generated_bytes(last, &patch) + .expect("the diff serializer emits a valid merge patch"); + self.scratch.get_mut().commit_memo(); + } + Edit::Restate => {} + } + } + + /// Encode an already-serialized value as a full snapshot, staging it as the new baseline. + fn snapshot_staged(&mut self, snapshot: Bytes) -> Result<(Encoded, Edit)> { + // With deltas possible, read the baseline back out of those same bytes rather than + // serializing `value` a second time, so the baseline IS the emitted snapshot by + // construction. A `Serialize` impl reading a clock or interior mutable state would otherwise + // seed the baseline with a value no consumer ever received, and every later delta would + // rebase them onto it. `T` is also only visited once, which is what a caller with an + // expensive or effectful `Serialize` pays for. + // + // That trades a second walk of `T` for a parse of the bytes, so it is not automatically + // cheaper than `to_value` (see the `baseline` benchmark); consistency is the reason. With + // deltas off there is no diff to rebase and no reason to pay it at all. + // + // Every fallible step runs before any state changes, so a failure leaves the encoder exactly + // as it was rather than half-advanced with no frame to show for it. + let last = if self.config.deltas { + Baseline::Parsed(serde_json::from_slice(&snapshot)?) + } else { + // No delta will ever diff against this, so hold the bytes instead. Uncompressed, they are + // the same allocation the payload carries, so the baseline costs a refcount. + Baseline::Encoded { + bytes: snapshot.clone(), + parsed: OnceLock::new(), + } + }; + + let encoded = self.snapshot_encoded(snapshot)?; + Ok((encoded, Edit::Snapshot(last))) + } + + /// Encode an already-serialized value as a full snapshot, opening a new group. + fn snapshot_encoded(&mut self, snapshot: Bytes) -> Result { + // 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.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()); + } + + // Open a fresh per-group encoder (cold window) and compress the snapshot as frame 0. + let (payload, flate) = match self.config.compression { + Compression::Deflate => { + let mut flate = moq_flate::Encoder::new(); + let payload = flate.frame(&snapshot); + (payload, Some(flate)) + } + Compression::None => (snapshot, None), + }; + + self.group_bytes = payload.len() as u64; + self.group_frames = 1; + self.flate = flate; + self.resync = false; + + Ok(Encoded { + payload, + keyframe: true, + }) + } } impl Encoder { /// Encode a new value, as a snapshot or a delta. /// - /// Returns `None` when the value is unchanged from the last one encoded, so nothing needs to be + /// Returns `None` when the value is unchanged from the last one committed, so nothing needs to be /// written. Otherwise the frame comes back as a [`Pending`] the caller writes and then /// [`commit`](Pending::commit)s; dropping it uncommitted resynchronizes the encoder. pub fn update(&mut self, value: &T) -> Result>> { - Ok(self.encode(value)?.map(|encoded| Pending { + Ok(self.encode(value)?.map(|(encoded, edit)| Pending { encoder: self, encoded, - committed: false, + edit: Some(edit), })) } - /// Encode a new value into a bare frame, advancing the encoder's state. + /// Encode a new value into a bare frame and the baseline change it stages, advancing the group. /// /// The state change is what [`Pending`] guards, so this stays private: every caller goes through /// [`update`](Self::update) and has to say whether the frame reached the wire. - fn encode(&mut self, value: &T) -> Result> { + fn encode(&mut self, value: &T) -> Result> { // A lost frame, or a group the caller cut, leaves the consumer's state unknown. Re-seed with a // full snapshot even when the value is unchanged, since the frame that carried it may never // have landed. if self.resync { - return self.snapshot(value).map(Some); + return self.encode_snapshot(value).map(Some); } // With deltas disabled there is nothing to diff, so the only question is whether the value @@ -309,12 +417,12 @@ impl Encoder { if next.as_slice() == bytes.as_ref() { return Ok(None); } - return self.snapshot_encoded(next).map(Some); + return self.snapshot_staged(Bytes::from(next)).map(Some); } // The first update has no baseline to diff against, so it seeds the stream with a snapshot. let Some(Baseline::Parsed(last)) = self.last.as_ref() else { - return self.snapshot(value).map(Some); + return self.encode_snapshot(value).map(Some); }; // Diff straight off `T`, without building a full `Value` for the new value first. @@ -327,10 +435,10 @@ impl Encoder { return Ok(None); } - // A forced snapshot (a genuine null, or a non-object root) or an exhausted delta budget starts a + // A forced snapshot (a genuine null, or a non-object root) or a full group starts a // new group; otherwise the change rides as a delta in the open one. if forced_snapshot || !self.delta_allowed() { - return self.snapshot(value).map(Some); + return self.encode_snapshot(value).map(Some); } // Compress into the per-group window only now, for a frame we are committed to emitting. @@ -354,112 +462,36 @@ impl Encoder { // // Measured on the encoded payload rather than the plaintext: a sync-flushed DEFLATE frame can // come out slightly larger than its input, so the plaintext is not an upper bound. Compressing - // first advances the window, but [`Self::snapshot`] opens a fresh one, so an over-budget delta + // first advances the window, but a snapshot opens a fresh one, so an over-budget delta // costs only the wasted compression. - if self.snapshot_len + self.delta_bytes + payload.len() as u64 > self.max_group_bytes { - return self.snapshot(value).map(Some); + if self.group_bytes + payload.len() as u64 > self.max_group_bytes { + return self.encode_snapshot(value).map(Some); } - self.delta_bytes += payload.len() as u64; + self.group_bytes += payload.len() as u64; self.group_frames += 1; - // Fold the delta into the baseline so the next diff is against the value we just encoded. - // Reaching a delta means `delta_allowed`, which means a non-zero ratio, which is what keeps - // the baseline parsed. - let Some(Baseline::Parsed(last)) = self.last.as_mut() else { - unreachable!("a parsed snapshot precedes any delta") - }; - crate::merge::apply_generated_bytes(last, &bytes)?; - self.scratch.get_mut().commit_memo(); - - Ok(Some(Encoded { + // The patch folds into the baseline on commit, so a frame that never reaches the wire leaves + // the baseline at the last value consumers received. + let encoded = Encoded { payload, keyframe: false, - })) + }; + Ok(Some((encoded, Edit::Delta(bytes)))) } - /// Whether the current change may ride as a delta in the open group. - /// - /// The budget gate measures the deltas *already emitted* (excluding the frame about to land) - /// against the group's snapshot frame. Both are compressed sizes when compressing and raw - /// otherwise, so the comparison is like-for-like. Because the pending frame is excluded, the delta - /// that tips the group past `ratio * snapshot` still lands: a group overshoots by at most one delta - /// before rolling. + /// Whether the current change may ride as a delta in the open group: deltas are on and the group + /// is under its frame cap. The byte cap is checked once the delta is encoded. fn delta_allowed(&self) -> bool { - let ratio = u64::from(self.config.delta_ratio); - ratio != 0 - && self.group_frames > 0 - && self.group_frames < MAX_DELTA_FRAMES - && self.delta_bytes <= ratio * self.snapshot_len + self.config.deltas && self.group_frames > 0 && self.group_frames < MAX_DELTA_FRAMES } - /// Encode a full snapshot of `value`, opening a new group and reseeding the baseline. - fn snapshot(&mut self, value: &T) -> Result { + /// Encode a full snapshot of `value`, opening a new group and staging it as the baseline. + fn encode_snapshot(&mut self, value: &T) -> Result<(Encoded, Edit)> { // Serialize directly from `value` so the snapshot frame preserves the type's own field order, // keeping the wire bytes identical to serializing `T` straight to a frame. let snapshot = serde_json::to_vec(value)?; - self.snapshot_encoded(snapshot) - } - - /// [`snapshot`](Self::snapshot) for a value that is already serialized, so an update that - /// encoded `T` to compare it against a byte baseline does not encode it a second time. - fn snapshot_encoded(&mut self, snapshot: Vec) -> Result { - // 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.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()); - } - - // With deltas possible, read the baseline back out of those same bytes rather than - // serializing `value` a second time, so the baseline IS the emitted snapshot by - // construction. A `Serialize` impl reading a clock or interior mutable state would otherwise - // seed the baseline with a value no consumer ever received, and every later delta would - // rebase them onto it. `T` is also only visited once, which is what a caller with an - // expensive or effectful `Serialize` pays for. - // - // That trades a second walk of `T` for a parse of the bytes, so it is not automatically - // cheaper than `to_value` (see the `baseline` benchmark); consistency is the reason. With - // deltas off there is no diff to rebase and no reason to pay it at all. - // - // Every fallible step runs before any state changes, so a failure leaves the encoder exactly - // as it was rather than half-advanced with no frame to show for it. - let snapshot = Bytes::from(snapshot); - let last = if self.config.delta_ratio == 0 { - // No delta will ever diff against this, so hold the bytes instead. Uncompressed, they are - // the same allocation the payload carries, so the baseline costs a refcount. - Baseline::Encoded { - bytes: snapshot.clone(), - parsed: OnceLock::new(), - } - } else { - Baseline::Parsed(serde_json::from_slice(&snapshot)?) - }; - - // 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 { - Compression::Deflate => { - let mut flate = moq_flate::Encoder::new(); - let payload = flate.frame(&snapshot); - (payload, Some(flate)) - } - Compression::None => (snapshot, None), - }; - - self.snapshot_len = payload.len() as u64; - self.delta_bytes = 0; - self.group_frames = 1; - self.flate = flate; - self.last = Some(last); - self.resync = false; - // Seeded from the snapshot rather than a diff, so no root entry is memoized against it yet. - self.scratch.get_mut().clear_memo(); - - Ok(Encoded { - payload, - keyframe: true, - }) + self.snapshot_staged(Bytes::from(snapshot)) } } @@ -510,6 +542,8 @@ mod test { struct PropertyStep { value: Value, reset: bool, + /// Restate the previous value with [`Encoder::snapshot`] before this step. + restate: bool, } fn property_sequence() -> proptest::strategy::BoxedStrategy> { @@ -520,6 +554,7 @@ mod test { .map(|(value, reset)| PropertyStep { value, reset: reset == 0, + restate: reset == 1, }) .collect() }); @@ -537,6 +572,7 @@ mod test { PropertyStep { value: Value::Object(current.clone()), reset: reset == 0, + restate: reset == 1, } }) .collect() @@ -567,22 +603,15 @@ mod test { failure_persistence: None, ..Default::default() }); - let sequence = ( - proptest::sample::select(vec![0, 1, 2, 8, 100]), - any::(), - property_sequence(), - ); + let sequence = (any::(), any::(), property_sequence()); runner - .run(&sequence, |(delta_ratio, deflate, steps)| { + .run(&sequence, |(deltas, deflate, steps)| { let compression = if deflate { Compression::Deflate } else { Compression::None }; - let mut encoder = Encoder::::new(Config { - delta_ratio, - compression, - }); + let mut encoder = Encoder::::new(Config { deltas, compression }); let mut decoder = super::super::Decoder::::new(super::super::consumer::Config { compression, ..Default::default() @@ -591,6 +620,18 @@ mod test { if step.reset { encoder.reset(); } + if step.restate { + let previous = decoder.decode().unwrap(); + match encoder.snapshot().unwrap() { + Some(frame) => { + prop_assert!(frame.keyframe); + decoder.snapshot(&frame.payload).unwrap(); + frame.commit(); + } + None => prop_assert!(index == 0, "a value was encoded before step {}", index), + } + prop_assert_eq!(decoder.decode().unwrap(), previous, "restate before step {}", index); + } if let Some(frame) = encoder.update(&step.value).unwrap() { if frame.keyframe { decoder.snapshot(&frame.payload).unwrap(); @@ -629,7 +670,7 @@ mod test { .unwrap() .unwrap() .commit(); - let err = encoder.encode(&Duplicate { duplicate: true }).unwrap_err(); + let err = encoder.update(&Duplicate { duplicate: true }).err().expect("refused"); assert!(err.to_string().contains("duplicate JSON object key")); } @@ -674,7 +715,7 @@ mod test { #[test] fn changes_ride_as_deltas() { let frames = encode( - Config::default().with_delta_ratio(100), + Config::default().with_deltas(true), &[ json!({ "a": 1, "b": 1 }), json!({ "a": 1, "b": 2 }), @@ -684,10 +725,63 @@ mod test { assert_eq!(frames.iter().map(|f| f.0).collect::>(), vec![true, false, false]); } + /// Without a joiner asking, a group runs on to the caps however much the deltas outweigh the + /// snapshot. + #[test] + fn deltas_never_roll_on_their_own() { + let big = "x".repeat(1024); + let values: Vec = (0..32).map(|n| json!({ "n": n, "pad": format!("{n}{big}") })).collect(); + let frames = encode(Config::default(), &values); + assert_eq!(frames.iter().filter(|f| f.0).count(), 1); + } + + /// `snapshot` restates the retained value as a keyframe, and the next change is a delta in the + /// group it opens. + #[test] + fn snapshot_restates_the_retained_value() { + for compression in [Compression::None, Compression::Deflate] { + for deltas in [true, false] { + let config = Config { deltas, compression }; + let mut encoder = Encoder::::new(config); + assert!(encoder.snapshot().unwrap().is_none(), "nothing to restate yet"); + + commit(&mut encoder, &json!({ "a": 1 })).unwrap(); + commit(&mut encoder, &json!({ "a": 2 })).unwrap(); + + let frame = encoder.snapshot().unwrap().unwrap(); + assert!(frame.keyframe); + let mut decoder = super::super::Decoder::::new(super::super::consumer::Config { + compression, + ..Default::default() + }); + decoder.snapshot(&frame.payload).unwrap(); + frame.commit(); + assert_eq!(decoder.decode().unwrap(), Some(json!({ "a": 2 }))); + + let next = commit(&mut encoder, &json!({ "a": 3 })).unwrap(); + assert_eq!(next.keyframe, !deltas, "deltas={deltas}"); + match next.keyframe { + true => decoder.snapshot(&next.payload).unwrap(), + false => decoder.delta(&next.payload).unwrap(), + } + assert_eq!(decoder.decode().unwrap(), Some(json!({ "a": 3 }))); + } + } + } + + /// A restatement that never reached the wire resynchronizes like any other lost frame. + #[test] + fn an_uncommitted_snapshot_resynchronizes() { + let mut encoder = Encoder::::new(Config::default()); + commit(&mut encoder, &json!({ "a": 1 })).unwrap(); + drop(encoder.snapshot().unwrap().unwrap()); + assert!(commit(&mut encoder, &json!({ "a": 2 })).unwrap().keyframe); + } + #[test] fn deltas_off_forces_a_keyframe_per_change() { let frames = encode( - Config::default().with_delta_ratio(0), + Config::default().with_deltas(false), &[json!({ "a": 1 }), json!({ "a": 2 })], ); assert_eq!(frames.iter().map(|f| f.0).collect::>(), vec![true, true]); @@ -699,7 +793,7 @@ mod test { #[test] fn deltas_off_still_skips_an_unchanged_value() { let frames = encode( - Config::default().with_delta_ratio(0), + Config::default().with_deltas(false), &[json!({ "a": 1 }), json!({ "a": 1 }), json!({ "a": 1 })], ); assert_eq!(frames.len(), 1); @@ -710,7 +804,7 @@ mod test { #[test] fn deltas_off_detects_a_change_under_the_same_keys() { let frames = encode( - Config::default().with_delta_ratio(0), + Config::default().with_deltas(false), &[json!({ "a": 1, "b": 2 }), json!({ "a": 1, "b": 3 })], ); assert_eq!(frames.len(), 2); @@ -721,7 +815,7 @@ mod test { /// `modify` start from `T::default()` and publish a document with every other field missing. #[test] fn deltas_off_still_exposes_the_value() { - let mut encoder = Encoder::::new(Config::default().with_delta_ratio(0)); + let mut encoder = Encoder::::new(Config::default().with_deltas(false)); assert_eq!(encoder.value(), None); commit(&mut encoder, &json!({ "a": 1, "b": 2 })).unwrap(); @@ -735,7 +829,7 @@ mod test { /// has to hold the plaintext rather than the compressed frame. #[test] fn deltas_off_while_compressing_keeps_the_plaintext_baseline() { - let mut config = Config::default().with_delta_ratio(0); + let mut config = Config::default().with_deltas(false); config.compression = Compression::Deflate; let mut encoder = Encoder::::new(config); @@ -750,7 +844,7 @@ mod test { #[test] fn a_null_field_forces_a_keyframe() { let frames = encode( - Config::default().with_delta_ratio(100), + Config::default().with_deltas(true), &[json!({ "a": 1, "b": 1 }), json!({ "a": 1, "b": null })], ); assert_eq!(frames.iter().map(|f| f.0).collect::>(), vec![true, true]); @@ -760,7 +854,7 @@ mod test { #[test] fn a_non_object_root_forces_a_keyframe() { let frames = encode( - Config::default().with_delta_ratio(100), + Config::default().with_deltas(true), &[json!({ "a": 1 }), json!([1, 2, 3])], ); assert_eq!(frames.iter().map(|f| f.0).collect::>(), vec![true, true]); @@ -769,7 +863,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(Config::default().with_delta_ratio(1_000_000), &values); + let frames = encode(Config::default().with_deltas(true), &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); @@ -781,7 +875,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(Config::default().with_delta_ratio(100)); + let mut encoder = Encoder::::new(Config::default().with_deltas(true)); assert!(commit(&mut encoder, &json!({ "a": 1 })).unwrap().keyframe); assert!(!commit(&mut encoder, &json!({ "a": 2 })).unwrap().keyframe); @@ -794,7 +888,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(Config::default().with_delta_ratio(100)); + let mut encoder = Encoder::::new(Config::default().with_deltas(true)); 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. @@ -850,7 +944,7 @@ mod test { let patched = json!({ "v": "x".repeat(1000), "q": "a" }); let plaintext = serde_json::to_vec(&json!({ "q": "a" })).unwrap().len(); let config = Config { - delta_ratio: 100, + deltas: true, compression: Compression::Deflate, }; @@ -886,7 +980,7 @@ mod test { let phrase = "Media over QUIC delivers real-time latency at massive scale"; let frames = encode( Config { - delta_ratio: 100, + deltas: true, compression: Compression::Deflate, }, &[json!({ "note": phrase }), json!({ "note": phrase, "echo": phrase })], @@ -946,7 +1040,7 @@ mod test { #[test] fn a_delta_serializes_each_entry_once() { let value = std::collections::BTreeMap::from([("row", Ticking(std::cell::Cell::new(0)))]); - let mut encoder = Encoder::new(Config::default().with_delta_ratio(100)); + let mut encoder = Encoder::new(Config::default().with_deltas(true)); encoder.update(&value).unwrap().expect("a snapshot").commit(); let frame = encoder.update(&value).unwrap().expect("a delta"); @@ -1003,20 +1097,20 @@ mod test { } } - let config = Config::default().with_delta_ratio(100); + let config = Config::default().with_deltas(true); let (plain, repeat) = (Doc { repeat: false }, Doc { repeat: true }); // A new entry: the first diff after a snapshot has nothing memoized yet. let mut encoder = Encoder::::new(config.clone()); encoder.update(&plain).unwrap().expect("a snapshot").commit(); - let err = encoder.encode(&repeat).unwrap_err(); + let err = encoder.update(&repeat).err().expect("refused"); assert!(err.to_string().contains("duplicate JSON object key"), "{err}"); // A memoized entry whose scalar becomes an object. let mut encoder = Encoder::::new(config); encoder.update(&plain).unwrap().expect("a snapshot").commit(); assert!(encoder.update(&plain).unwrap().is_none(), "unchanged, now memoized"); - let err = encoder.encode(&repeat).unwrap_err(); + let err = encoder.update(&repeat).err().expect("refused"); assert!(err.to_string().contains("duplicate JSON object key"), "{err}"); } @@ -1091,7 +1185,7 @@ mod test { (2, Compression::Deflate), (3, Compression::None), ] { - let mut config = Config::default().with_delta_ratio(2); + let mut config = Config::default().with_deltas(true); config.compression = compression; let mut memoized = Encoder::::new(config.clone()); let mut plain = Encoder::::new(config); @@ -1152,7 +1246,7 @@ mod test { #[test] fn value_tracks_the_baseline() { - let mut encoder = Encoder::::new(Config::default().with_delta_ratio(100)); + let mut encoder = Encoder::::new(Config::default().with_deltas(true)); assert_eq!(encoder.value(), None); commit(&mut encoder, &json!({ "a": 1, "b": 1 })); @@ -1160,5 +1254,9 @@ mod test { // The delta was folded into the baseline, so it reflects what was actually published. assert_eq!(encoder.value(), Some(&json!({ "a": 1, "b": 2 }))); + + // A frame that never reached the wire leaves the value at the last one that did. + drop(encoder.update(&json!({ "a": 1, "b": 3 })).unwrap()); + assert_eq!(encoder.value(), Some(&json!({ "a": 1, "b": 2 }))); } } diff --git a/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index e3a987e7fc5..00e3b2fa8d0 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -11,13 +11,21 @@ //! order. Every group starts independently, so a reader can resynchronize after skipping //! superseded groups without needing earlier deltas. //! -//! 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. +//! [`Config::deltas`] turns deltas off, 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 -//! [`Producer::cut`]: it closes the open group and leaves the next update to open the replacement -//! with a full snapshot, so the deltas already written stop being provisional without publishing an -//! empty group. +//! # Refresh +//! +//! A group of deltas grows until a joiner wants a fresh one. A track created with a +//! [`refresh`](moq_net::track::Info::refresh) ratio asks for one when a subscriber joins while the +//! open group's deltas outweigh that ratio times its snapshot, so the joiner never downloads much +//! more than the value itself. [`Producer::refresh`] answers by restating the value as a snapshot in +//! a new group; [`Encoder::snapshot`] does the same for a caller that owns the track. Without a ratio, +//! or behind a relay that cannot forward the ask, a group runs to the encoder's frame and byte caps. +//! +//! A caller can also roll a group for its own reasons with [`Producer::cut`]: it closes the open +//! group and leaves the next update to open the replacement with a full snapshot, so the deltas +//! already written stop being provisional without publishing an empty group. //! //! # Choosing a layer //! @@ -59,7 +67,7 @@ mod test { #[test] fn editing_keeps_the_callers_timestamp_on_commit_and_drop() { - let (mut producer, _) = producer_on(cfg(100), timed()); + let (mut producer, _) = producer_on(cfg(true), timed()); let mut groups = producer.consume(); let first = moq_net::Timestamp::from_millis(100).unwrap(); let second = moq_net::Timestamp::from_millis(200).unwrap(); @@ -81,7 +89,7 @@ mod test { #[test] fn a_missing_edit_timestamp_is_refused_on_a_timed_track() { - let (mut producer, _) = producer_on(cfg(0), timed()); + let (mut producer, _) = producer_on(cfg(false), timed()); let mut edit = producer.modify(None).unwrap(); edit["n"] = json!(1); assert!(matches!( @@ -104,8 +112,8 @@ mod test { /// Refused before a replacement group is published, so the last value stays readable. #[test] fn a_timed_track_refuses_a_bare_publish() { - for delta_ratio in [0, 100] { - let (mut producer, track) = producer_on(cfg(delta_ratio), timed()); + for deltas in [false, true] { + let (mut producer, track) = producer_on(cfg(deltas), timed()); let at = moq_net::Timestamp::from_millis(100).unwrap(); producer .update(moq_net::Timed::from(&json!({ "n": 1 })).at(at)) @@ -115,7 +123,7 @@ mod test { Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) )); producer.finish().unwrap(); - assert_eq!(drain(track), vec![json!({ "n": 1 })], "delta_ratio={delta_ratio}"); + assert_eq!(drain(track), vec![json!({ "n": 1 })], "deltas={deltas}"); } } @@ -143,15 +151,15 @@ mod test { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) } - /// An uncompressed config with the given delta ratio. - fn cfg(delta_ratio: u32) -> Config { - Config::default().with_delta_ratio(delta_ratio) + /// An uncompressed config, with or without deltas. + fn cfg(deltas: bool) -> Config { + Config::default().with_deltas(deltas) } - /// A DEFLATE-compressed config with the given delta ratio. - fn cfg_deflate(delta_ratio: u32) -> Config { + /// A DEFLATE-compressed config, with or without deltas. + fn cfg_deflate(deltas: bool) -> Config { Config { - delta_ratio, + deltas, compression: Compression::Deflate, } } @@ -211,7 +219,7 @@ mod test { #[test] fn next_preserves_intermediate_states() { - let (mut producer, mut track) = producer(cfg(100)); + let (mut producer, mut track) = producer(cfg(true)); let mut subscription = track.subscription(); subscription.max_delay = std::time::Duration::MAX; track.update(subscription).unwrap(); @@ -294,7 +302,7 @@ mod test { #[test] fn a_cut_makes_the_next_update_a_snapshot_group() { - let (mut producer, mut track) = producer(cfg(100)); + let (mut producer, mut track) = producer(cfg(true)); producer.update(&json!({ "a": 1, "b": 1 })).unwrap(); producer.update(&json!({ "a": 1, "b": 2 })).unwrap(); producer.cut().unwrap(); @@ -313,7 +321,7 @@ mod test { #[test] fn a_cut_republishes_an_unchanged_value() { - let (mut producer, mut track) = producer(cfg(100)); + let (mut producer, mut track) = producer(cfg(true)); producer.update(&json!({ "a": 1 })).unwrap(); producer.cut().unwrap(); @@ -331,7 +339,7 @@ mod test { #[test] fn a_cut_opens_no_replacement_group() { - let (mut producer, mut track) = producer(cfg(100)); + let (mut producer, mut track) = producer(cfg(true)); producer.update(&json!({ "a": 1 })).unwrap(); producer.cut().unwrap(); producer.finish().unwrap(); @@ -347,7 +355,7 @@ mod test { #[test] fn a_cut_is_idempotent() { - let (mut producer, mut track) = producer(cfg(100)); + let (mut producer, mut track) = producer(cfg(true)); // Nothing published yet, so there is no group to cut. producer.cut().unwrap(); @@ -373,7 +381,7 @@ mod test { #[test] fn a_cut_is_inert_without_deltas() { - let (mut producer, mut track) = producer(cfg(0)); + let (mut producer, mut track) = producer(cfg(false)); producer.update(&json!({ "a": 1 })).unwrap(); // With deltas off every frame already closes its own group, so there is never one to cut. @@ -390,7 +398,7 @@ mod test { #[test] fn deltas_off_snapshot_per_group() { - let (mut producer, mut track) = producer(cfg(0)); + let (mut producer, mut track) = producer(cfg(false)); producer.update(&json!({ "a": 1 })).unwrap(); producer.update(&json!({ "a": 2 })).unwrap(); producer.finish().unwrap(); @@ -425,7 +433,7 @@ mod test { /// update. #[test] fn a_rejected_update_leaves_the_previous_value_readable() { - let (mut producer, track) = producer(cfg(0)); + let (mut producer, track) = producer(cfg(false)); producer.update(&json!({ "keep": true })).unwrap(); // Serializes past the group cache limit, so the frame cannot be published. @@ -459,7 +467,7 @@ mod test { /// size is the encoded frame. #[test] fn a_stamped_update_writes_its_capture_time() { - let (mut producer, _track) = producer_on(cfg(100), timed()); + let (mut producer, _track) = producer_on(cfg(true), timed()); let mut groups = producer.consume(); let first = moq_net::Timestamp::from_millis(1_000).unwrap(); let second = moq_net::Timestamp::from_millis(2_000).unwrap(); @@ -481,30 +489,182 @@ mod test { } } + /// With nobody joining, deltas pile up in one group however far they outweigh the snapshot. #[test] - fn deltas_stay_within_ratio_times_snapshot() { - // The budget covers only the deltas, not the snapshot frame, measured against the group's - // snapshot size. Single-digit values keep every frame at a constant 7 bytes (`{"n":N}`), so - // `ratio = 8` budgets 56 bytes of deltas. The gate checks the deltas already written, so the - // group keeps filling until the accumulated deltas first exceed 56 (nine deltas = 63 bytes) and - // the next update rolls (a one-frame overshoot past the 56-byte budget). - let (mut producer, mut track) = producer(cfg(8)); + fn deltas_never_roll_without_a_joiner() { + let (mut producer, mut track) = producer_on(cfg(true), moq_net::track::Info::default().with_refresh(1)); for n in 0..=10 { producer.update(&json!({ "n": n })).unwrap(); } + assert!(producer.poll_refresh(&kio::Waiter::noop()).is_pending()); producer.finish().unwrap(); - // Group 0 carries the snapshot plus 9 deltas (10 frames); the 10th delta opens group 1. assert_eq!( track.largest().now_or_never().flatten().map(|position| position.group), - Some(1) + Some(0) ); assert_eq!(drain(track).last().unwrap(), &json!({ "n": 10 })); } + /// The frames of `group` received so far: each timestamp and decoded payload. + fn frames(group: &mut moq_net::group::Consumer) -> Vec<(Option, Value)> { + let waiter = kio::Waiter::noop(); + let mut out = Vec::new(); + while let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) { + out.push((frame.timestamp, serde_json::from_slice(&frame.payload).unwrap())); + } + out + } + + /// Every group `subscriber` has received so far. + fn groups(subscriber: &mut moq_net::track::Subscriber) -> Vec { + let waiter = kio::Waiter::noop(); + let mut out = Vec::new(); + while let Poll::Ready(Ok(Some(group))) = subscriber.poll_recv_group(&waiter) { + out.push(group); + } + out + } + + /// A joiner under the ratio reads the open group, and one over it gets the value restated in a + /// fresh group, where the next change rides as a delta. + #[test] + fn a_joiner_over_the_ratio_gets_a_fresh_snapshot() { + let waiter = kio::Waiter::noop(); + let (mut producer, _track) = producer_on(cfg(true), moq_net::track::Info::default().with_refresh(1)); + + // A 13 byte snapshot and a 7 byte delta: under the ratio. + producer.update(&json!({ "n": 0, "p": 0 })).unwrap(); + producer.update(&json!({ "n": 1, "p": 0 })).unwrap(); + let _early = producer.consume(); + assert!(producer.poll_refresh(&waiter).is_pending(), "a join under the ratio"); + + // A second delta takes the group past it, and the next join asks for a fresh one. + producer.update(&json!({ "n": 2, "p": 0 })).unwrap(); + assert!(producer.poll_refresh(&waiter).is_pending(), "no join, no refresh"); + let mut late = producer.consume(); + assert!(matches!(producer.poll_refresh(&waiter), Poll::Ready(Ok(())))); + assert!(producer.poll_refresh(&waiter).is_pending(), "answered once"); + + let mut fresh = groups(&mut late).pop().expect("the fresh group"); + assert_eq!(fresh.sequence, 1); + assert_eq!(frames(&mut fresh), vec![(None, json!({ "n": 2, "p": 0 }))]); + + producer.update(&json!({ "n": 3, "p": 0 })).unwrap(); + assert_eq!(frames(&mut fresh), vec![(None, json!({ "n": 3 }))]); + } + + /// A refresh restates the value at the newest timestamp written rather than inventing one. + #[test] + fn a_refresh_reuses_the_newest_timestamp() { + let ms = |n| moq_net::Timestamp::from_millis(n).unwrap(); + let (mut producer, _track) = producer_on(cfg(true), timed().with_refresh(1)); + producer + .update(moq_net::Timed::from(&json!({ "n": 0 })).at(ms(100))) + .unwrap(); + for n in 1..=3 { + producer + .update(moq_net::Timed::from(&json!({ "n": n })).at(ms(100 + n))) + .unwrap(); + } + + let mut late = producer.consume(); + assert!(matches!( + producer.poll_refresh(&kio::Waiter::noop()), + Poll::Ready(Ok(())) + )); + let mut fresh = groups(&mut late).pop().expect("the fresh group"); + assert_eq!(fresh.sequence, 1); + assert_eq!(frames(&mut fresh), vec![(Some(ms(103)), json!({ "n": 3 }))]); + } + + /// A delta may carry a timestamp older than its group's first frame, but a new group may not + /// start before that frame, so the restatement takes the newest timestamp written. + #[test] + fn a_refresh_after_an_older_update_starts_at_the_newest_timestamp() { + let ms = |n| moq_net::Timestamp::from_millis(n).unwrap(); + let (mut producer, _track) = producer_on(cfg(true), timed().with_refresh(1)); + for (n, at) in [130, 110, 120, 115].into_iter().enumerate() { + producer + .update(moq_net::Timed::from(&json!({ "n": n })).at(ms(at))) + .unwrap(); + } + + let mut late = producer.consume(); + assert!(matches!( + producer.poll_refresh(&kio::Waiter::noop()), + Poll::Ready(Ok(())) + )); + let mut fresh = groups(&mut late).pop().expect("the fresh group"); + assert_eq!(fresh.sequence, 1); + assert_eq!(frames(&mut fresh), vec![(Some(ms(130)), json!({ "n": 3 }))]); + } + + /// A refresh restates the last value written, never one whose update was rejected, and the next + /// update rides as a delta against it. + #[test] + fn a_refresh_after_a_rejected_update_restates_the_last_written_value() { + let ms = |n| moq_net::Timestamp::from_millis(n).unwrap(); + let (mut producer, track) = producer_on(cfg(true), timed().with_refresh(1)); + for n in 0..=3 { + producer + .update(moq_net::Timed::from(&json!({ "n": n })).at(ms(100 + n))) + .unwrap(); + } + + // Untimed on a timed track, so the frame is rejected before it reaches a group. + assert!(matches!( + producer.update(&json!({ "n": 99 })), + Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) + )); + + let mut late = producer.consume(); + assert!(matches!( + producer.poll_refresh(&kio::Waiter::noop()), + Poll::Ready(Ok(())) + )); + let mut fresh = groups(&mut late).pop().expect("the fresh group"); + assert_eq!(fresh.sequence, 1); + assert_eq!(frames(&mut fresh), vec![(Some(ms(103)), json!({ "n": 3 }))]); + + producer + .update(moq_net::Timed::from(&json!({ "n": 4 })).at(ms(104))) + .unwrap(); + producer.finish().unwrap(); + assert_eq!(drain(track).last(), Some(&json!({ "n": 4 }))); + } + + /// Without a ratio on the track, no join asks for a group, however large the deltas grow. + #[test] + fn no_ratio_never_refreshes() { + let (mut producer, _track) = producer(cfg(true)); + for n in 0..=10 { + producer.update(&json!({ "n": n })).unwrap(); + } + let _late = producer.consume(); + assert!(producer.poll_refresh(&kio::Waiter::noop()).is_pending()); + } + + /// `refresh` resolves on a join over the ratio and errors once the track closes. + #[test] + fn refresh_resolves_on_a_join_and_errors_on_close() { + let (mut producer, _track) = producer_on(cfg(true), moq_net::track::Info::default().with_refresh(1)); + producer.update(&json!({ "n": 0 })).unwrap(); + producer.update(&json!({ "n": 1 })).unwrap(); + producer.update(&json!({ "n": 2 })).unwrap(); + + let mut refresh = Box::pin(producer.refresh()); + assert!(refresh.as_mut().now_or_never().is_none()); + let _late = producer.consume(); + assert!(matches!(refresh.now_or_never(), Some(Ok(())))); + + producer.finish().unwrap(); + assert!(matches!(producer.refresh().now_or_never(), Some(Err(_)))); + } + #[test] fn array_change_is_delta() { - let (mut producer, mut track) = producer(cfg(100)); + let (mut producer, mut track) = producer(cfg(true)); producer.update(&json!({ "list": [1, 2] })).unwrap(); producer.update(&json!({ "list": [1, 2, 3] })).unwrap(); producer.finish().unwrap(); @@ -519,7 +679,7 @@ mod test { #[test] fn frame_cap_rolls_snapshot() { - let (mut producer, mut track) = producer(cfg(1_000_000)); + let (mut producer, mut track) = producer(cfg(true)); // First update is the snapshot (frame 0); then MAX_DELTA_FRAMES - 1 deltas fill the group. for i in 0..=MAX_DELTA_FRAMES { producer.update(&json!({ "n": i })).unwrap(); @@ -573,7 +733,7 @@ mod test { .produce() .create_track("test", moq_net::track::Info::default()) .unwrap(); - let mut producer = Producer::::new(track.clone(), cfg(0)); + let mut producer = Producer::::new(track.clone(), cfg(false)); producer.update(&json!({ "a": 1 })).unwrap(); track.finish_at(moq_net::track::Position::group(2)).unwrap(); @@ -644,7 +804,7 @@ mod test { .create_track("test", moq_net::track::Info::default()) .unwrap(); let mut consumer = track.subscribe(None); - let mut producer = Producer::::new(track, cfg(0)); + let mut producer = Producer::::new(track, cfg(false)); producer.mutate(None, |doc| doc.video = Some("v1".to_string())).unwrap(); @@ -683,7 +843,7 @@ mod test { #[test] fn mutate_returns_the_publish_error() { // Unlike a dropped guard, the closure form hands the failure back to the caller. - let (mut producer, _track) = producer(cfg(0)); + let (mut producer, _track) = producer(cfg(false)); producer.update(&json!({ "keep": true })).unwrap(); assert!(matches!( @@ -696,7 +856,7 @@ mod test { #[test] fn a_dropped_edit_publishes_a_snapshot_then_a_delta() { - let (mut producer, mut track) = producer(cfg(100)); + let (mut producer, mut track) = producer(cfg(true)); *producer.modify(None).unwrap() = json!({ "a": 1, "b": 1 }); *producer.modify(None).unwrap() = json!({ "a": 1, "b": 2 }); @@ -712,7 +872,7 @@ mod test { #[test] fn modify_refuses_a_finished_track() { - let (mut producer, track) = producer(cfg(0)); + let (mut producer, track) = producer(cfg(false)); producer.update(&json!({ "a": 1 })).unwrap(); producer.finish().unwrap(); @@ -725,7 +885,7 @@ mod test { #[test] fn a_dropped_failed_edit_aborts_the_track() { - let (mut producer, track) = producer(cfg(0)); + let (mut producer, track) = producer(cfg(false)); producer.update(&json!({ "keep": true })).unwrap(); let mut subscriber = track.ordered(); @@ -749,7 +909,7 @@ mod test { #[test] fn a_failed_commit_leaves_the_track_open() { - let (mut producer, track) = producer(cfg(0)); + let (mut producer, track) = producer(cfg(false)); producer.update(&json!({ "keep": true })).unwrap(); let mut guard = producer.modify(None).unwrap(); @@ -767,7 +927,7 @@ mod test { #[test] fn a_panicking_edit_does_not_publish() { - let (mut producer, mut track) = producer(cfg(0)); + let (mut producer, mut track) = producer(cfg(false)); producer.update(&json!({ "a": 1 })).unwrap(); let panicked = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { @@ -788,36 +948,25 @@ mod test { assert_eq!(drain(track).last().unwrap(), &json!({ "a": 3 })); } - /// A rejected frame must not erase the last-published value: `modify` seeds its editing guard from - /// it, so losing it makes the next edit publish a document with every other field dropped. + /// A rejected edit never reached the wire, so the next `modify` starts from the last value that + /// did: neither erased (every other field dropped) nor carrying the rejected edit, which would + /// fail again, or publish something its owner was told failed, under whoever edits next. #[test] - fn a_failed_publish_keeps_the_value_for_modify() { - #[derive(serde::Serialize, serde::Deserialize, Default, PartialEq, Debug)] - struct Doc { - #[serde(skip_serializing_if = "Option::is_none")] - video: Option, - #[serde(skip_serializing_if = "Option::is_none")] - scte35: Option, - } - - // Every frame is rejected, so each publish fails and the encoder resynchronizes. - let mut producer = Producer::::new(rejecting_track(), Config::default()); - - let mut guard = producer.modify(Some(late())).unwrap(); - guard.video = Some("v1".to_string()); - assert!(guard.commit().is_err()); + fn a_rejected_edit_leaves_modify_at_the_last_written_value() { + let ms = |n| moq_net::Timestamp::from_millis(n).unwrap(); + let (mut producer, _track) = producer_on(cfg(true), timed()); + producer + .mutate(Some(ms(100)), |value| *value = json!({ "video": "v1" })) + .unwrap(); - let mut guard = producer.modify(Some(late())).unwrap(); - guard.scte35 = Some(42); - assert!(guard.commit().is_err()); + // Untimed on a timed track, so the frame is rejected before it reaches a group. + assert!(matches!( + producer.mutate(None, |value| value["scte35"] = json!(42)), + Err(crate::Error::Net(moq_net::Error::TimestampMismatch)) + )); - // The editing baseline still carries the composed value. - let guard = producer.modify(Some(late())).unwrap(); - assert_eq!( - guard.video, - Some("v1".to_string()), - "a rejected frame erased the baseline" - ); + let guard = producer.modify(Some(ms(101))).unwrap(); + assert_eq!(*guard, json!({ "video": "v1" })); } /// Finishing takes the open group with it, so the encoder must stop emitting deltas into a group @@ -825,7 +974,7 @@ mod test { /// writing a delta with nowhere to put it. #[test] fn update_after_finish_errors_instead_of_panicking() { - let (mut producer, _track) = producer(cfg(100)); + let (mut producer, _track) = producer(cfg(true)); producer.update(&json!({ "a": 1 })).unwrap(); producer.update(&json!({ "a": 2 })).unwrap(); // a delta, so a group is open producer.finish().unwrap(); @@ -860,7 +1009,7 @@ mod test { fn a_rejected_snapshot_does_not_strand_an_empty_group() { let track = rejecting_track(); let mut subscriber = track.subscribe(None).ordered(); - let mut producer = Producer::::new(track, cfg(0)); + let mut producer = Producer::::new(track, cfg(false)); assert!(matches!( producer.update(moq_net::Timed::from(&json!({ "a": 1 })).at(late())), @@ -889,7 +1038,7 @@ mod test { .create_track("test", moq_net::track::Info::default()) .unwrap(); let mut consumer = track.subscribe(None); - let mut producer = Producer::::new(track, cfg(0)); + let mut producer = Producer::::new(track, cfg(false)); let mut guard = producer.modify(None).unwrap(); guard.a = 1; @@ -909,9 +1058,8 @@ mod test { #[test] fn newer_group_supersedes_in_progress_reconstruction() { - // A tight ratio fills group 0 with a couple of deltas, then forces a later update into a new - // snapshot group (the gate overshoots the budget by one delta before rolling). - let (mut producer, track) = producer(cfg(1)); + // A couple of deltas fill group 0, then a cut leaves the last update to open group 1. + let (mut producer, track) = producer(cfg(true)); let mut observer = producer.consume(); let mut consumer = Consumer::::new(track, consumer::Config::default()); let waiter = kio::Waiter::noop(); @@ -922,9 +1070,10 @@ mod test { other => panic!("expected first value, got {other:?}"), } - producer.update(&json!({ "a": 2 })).unwrap(); // delta in group 0 (deltas = 7) - producer.update(&json!({ "a": 3 })).unwrap(); // delta in group 0 (deltas = 14, now over budget) - producer.update(&json!({ "a": 4 })).unwrap(); // budget already exceeded, rolls group 1 + producer.update(&json!({ "a": 2 })).unwrap(); // delta in group 0 + producer.update(&json!({ "a": 3 })).unwrap(); // delta in group 0 + producer.cut().unwrap(); + producer.update(&json!({ "a": 4 })).unwrap(); // snapshot, group 1 producer.finish().unwrap(); assert_eq!( observer @@ -979,7 +1128,7 @@ mod test { fn late_joiner_collapses_backlog_to_latest() { // A whole group's worth of snapshot + deltas is buffered before the consumer reads. It should // apply them all but yield only the latest value once, not replay every superseded state. - let (mut producer, mut track) = producer(cfg(100)); + let (mut producer, mut track) = producer(cfg(true)); for n in 0..=20 { producer.update(&json!({ "n": n })).unwrap(); } @@ -1001,7 +1150,7 @@ mod test { #[test] fn compressed_late_joiner_collapses_backlog_to_latest() { // Same collapse, exercising the lazy decoder replaying the group's slices to warm its window. - let (mut producer, mut track) = producer(cfg_deflate(100)); + let (mut producer, mut track) = producer(cfg_deflate(true)); for n in 0..=20 { producer.update(&json!({ "n": n })).unwrap(); } @@ -1021,7 +1170,7 @@ mod test { #[test] fn compressed_snapshot_per_group_roundtrips() { - let (mut producer, mut track) = producer(cfg_deflate(0)); + let (mut producer, mut track) = producer(cfg_deflate(false)); producer.update(&json!({ "a": 1 })).unwrap(); producer.update(&json!({ "a": 2 })).unwrap(); producer.finish().unwrap(); @@ -1035,29 +1184,27 @@ mod test { assert_eq!(values, vec![json!({ "a": 2 })]); } + /// A refresh on a compressed track opens a fresh DEFLATE window, so a late joiner rebuilds the + /// value from the restated group alone, and later deltas compress against it. #[test] - fn compressed_deltas_roll_on_compressed_budget() { - // With compression the budget is measured on compressed frame sizes: `snapshot_len` and - // `delta_bytes` are the compressed slice lengths, not the raw JSON. A tight ratio over many - // distinct updates must therefore roll at least one group, and a late joiner must still rebuild - // the final value across the compressed group boundary (per-group decoder reset). Guards against - // the budget regressing to raw lengths. - let (mut producer, mut track) = producer(cfg_deflate(2)); + fn a_compressed_refresh_opens_a_fresh_window() { + let (mut producer, mut track) = producer_on(cfg_deflate(true), moq_net::track::Info::default().with_refresh(1)); for n in 0..=40 { producer.update(&json!({ "n": n })).unwrap(); } + let late = producer.consume(); + assert!(matches!( + producer.poll_refresh(&kio::Waiter::noop()), + Poll::Ready(Ok(())) + )); + producer.update(&json!({ "n": 41 })).unwrap(); producer.finish().unwrap(); - assert!( - track - .largest() - .now_or_never() - .flatten() - .map(|position| position.group) - .unwrap() > 0, - "a tight ratio should roll at least one compressed group" + assert_eq!( + track.largest().now_or_never().flatten().map(|position| position.group), + Some(1) ); - assert_eq!(drain_with(deflate_consumer(track)).last().unwrap(), &json!({ "n": 40 })); + assert_eq!(drain_with(deflate_consumer(late)).last().unwrap(), &json!({ "n": 41 })); } #[test] @@ -1065,8 +1212,8 @@ mod test { // A repetitive payload should serialize to fewer wire bytes compressed than plaintext. let value = json!({ "renditions": ["video".repeat(50), "video".repeat(50), "video".repeat(50)] }); - let plaintext_bytes = wire_frame_len(cfg(0), &value); - let compressed_bytes = wire_frame_len(cfg_deflate(0), &value); + let plaintext_bytes = wire_frame_len(cfg(false), &value); + let compressed_bytes = wire_frame_len(cfg_deflate(false), &value); assert!( compressed_bytes < plaintext_bytes, "compressed frame {compressed_bytes} should be smaller than plaintext {plaintext_bytes}" @@ -1077,7 +1224,7 @@ mod test { fn compressed_deltas_reuse_window() { // The shared per-group window is the whole point: a delta that restates content already in // the snapshot compresses to far fewer bytes than the raw patch. - let (mut producer, track) = producer(cfg_deflate(100)); + let (mut producer, track) = producer(cfg_deflate(true)); let phrase = "Media over QUIC delivers real-time latency at massive scale"; producer.update(&json!({ "note": phrase })).unwrap(); producer.update(&json!({ "note": phrase, "echo": phrase })).unwrap(); @@ -1118,7 +1265,7 @@ mod test { inner: Inner, } - let (mut producer, track) = producer(cfg(0)); + let (mut producer, track) = producer(cfg(false)); producer.update(&json!({ "inner": { "count": 300 } })).unwrap(); let mut consumer = Consumer::::new(track, consumer::Config::default()); @@ -1133,7 +1280,7 @@ mod test { #[test] fn rejected_root_omits_the_path() { - let (mut producer, track) = producer(cfg(0)); + let (mut producer, track) = producer(cfg(false)); producer.update(&json!("not a map")).unwrap(); let mut consumer = Consumer::>::new(track, consumer::Config::default()); diff --git a/rs/moq-json/src/snapshot/producer.rs b/rs/moq-json/src/snapshot/producer.rs index a64e03ab71e..e8a49f56272 100644 --- a/rs/moq-json/src/snapshot/producer.rs +++ b/rs/moq-json/src/snapshot/producer.rs @@ -8,6 +8,7 @@ use serde::Serialize; use serde::de::DeserializeOwned; use super::{Encoded, Encoder}; +use crate::refresh::Refresh; use moq_net::Timed; use crate::{Error, Result}; @@ -29,6 +30,10 @@ fn take(inner: &Mutex>) -> MutexGuard<'_, Inner> { /// encoder emits a snapshot. When something else already owns the track, use the [`Encoder`] /// directly. /// +/// A group runs until a joiner wants a fresh one, which [`refresh`](Self::refresh) answers, or until +/// it reaches the encoder's caps. Set the track's [`refresh`](moq_net::track::Info::refresh) ratio +/// when creating it, or joins never ask. +/// /// Cheaply clonable: clones share one underlying track and publishing state, like other MoQ /// producers. pub struct Producer { @@ -64,18 +69,40 @@ impl Producer { pub fn new(track: moq_net::track::Producer, config: Config) -> Self { Self { inner: Arc::new(Mutex::new(Inner { + refresh: Refresh::new(&track), track: Track { inner: track, group: None, - deltas: config.delta_ratio != 0, + largest: None, + deltas: config.deltas, }, encoder: Encoder::new(config), + at: None, aborted: None, })), _marker: PhantomData, } } + /// Wait for a joiner to want a fresh group, then restate the current value as a snapshot in one. + /// + /// A join wants one once the open group's deltas outweigh the track's + /// [`refresh`](moq_net::track::Info::refresh) ratio times its snapshot (see + /// [`Demand::wanted`](moq_net::track::Demand::wanted)), so that joiner reads the value without + /// downloading them. The snapshot carries the newest timestamp written, so the new group never starts before the last. + /// Nothing happens before the first update, or on a track without a ratio. + /// + /// The producer has no runtime of its own, so the owner drives this: loop on it, or select on it + /// beside the updates. Errors once the track is closed. + pub async fn refresh(&self) -> Result<()> { + kio::wait(|waiter| self.poll_refresh(waiter)).await + } + + /// Poll for [`refresh`](Self::refresh), for an owner driving the producer synchronously. + pub fn poll_refresh(&self, waiter: &kio::Waiter) -> std::task::Poll> { + take(&self.inner).poll_refresh(waiter) + } + /// Publish a new value, emitting a snapshot or a delta automatically. /// /// Returns the encoded size of the frame written, or `None` if the value is unchanged from the @@ -120,12 +147,10 @@ impl Producer { /// so far, composed, or `T::default()` if nothing has been. Editing it through [`DerefMut`] marks /// the guard dirty; when a dirty guard drops it publishes the result, a no-op if unchanged. /// - /// After a rejected frame the current value is what the producer last *tried* to publish, which - /// consumers never received. That is deliberate. The guard exists so independent owners can each - /// edit their own field without clobbering, and dropping a rejected owner's field would clobber it - /// for whoever edits next, which is the failure this API exists to prevent. The owner whose write - /// failed sees the error and can act on it; the next successful publish is a full snapshot - /// carrying the composed value, so consumers converge on it either way. + /// A rejected edit never reached the wire, so the current value stays the last one that did. The + /// owner whose write failed sees the error and can retry; carrying the rejected edit forward would + /// instead fail every later owner's publish the same way, or publish a value its owner was told + /// failed. /// /// Reach for this over [`mutate`](Self::mutate) when several edits belong to one publish. The /// guard holds the producer's lock for its lifetime, so independent owners are serialized: each @@ -164,7 +189,7 @@ impl Producer { /// Finish the open group, so the deltas already written stop being provisional. /// - /// No replacement group opens until the next [`update`](Self::update), which emits a full + /// No replacement group opens until the next [`update`](Self::update) or [`refresh`](Self::refresh), which emits a full /// snapshot as its first frame even when the value is unchanged. A consumer joining at that group /// therefore reads the whole value without the deltas that preceded it. /// @@ -270,6 +295,13 @@ struct Inner { track: Track, encoder: Encoder, + /// Watches for a joiner wanting a group past the largest written. + refresh: Refresh, + + /// The newest timestamp written, which a refresh restates the value at. An update may carry an + /// older timestamp than its group's first frame, and a new group may not start before that one. + at: Option, + /// Why this producer aborted the track, so [`Producer::modify`] can report the cause rather than /// the closed track it left behind. aborted: Option, @@ -340,14 +372,31 @@ impl Inner { // A failed write drops `frame` uncommitted, which resets the encoder so the next update // resynchronizes with a fresh snapshot. Most failures kill the track outright, but a rejected // frame (too large) doesn't, and a delta against a snapshot no consumer ever saw is unreadable. + // The value stays the last one written, so a refresh restates that rather than the rejection. let timestamp = payload.at; track.write(timestamp, &frame)?; let size = frame.payload.len(); frame.commit(); + self.at = self.at.max(timestamp); Ok(Some(size)) } + fn poll_refresh(&mut self, waiter: &kio::Waiter) -> std::task::Poll> { + // A finished track still has subscribers draining it, so its demand alone never says stop. + self.open()?; + std::task::ready!(self.refresh.poll(self.track.largest, waiter))?; + + let Inner { track, encoder, at, .. } = self; + // A group was written, so a value was encoded and there is one to restate. + let Some(frame) = encoder.snapshot()? else { + return std::task::Poll::Pending; + }; + track.write(*at, &frame)?; + frame.commit(); + std::task::Poll::Ready(Ok(())) + } + fn finish(&mut self) -> Result<()> { // The open group goes with the track, so the encoder must not keep emitting deltas into it. // Any further update fails on the closed track, but it has to fail as an error rather than by @@ -364,6 +413,9 @@ struct Track { /// The group a delta would be appended to, open only while deltas are enabled. group: Option, + /// The sequence of the newest group written, which a refresh has to pass. + largest: Option, + /// Whether the encoder can emit deltas at all. With them off every frame is a snapshot, so a /// group is closed the moment it's written and never held open. deltas: bool, @@ -406,6 +458,7 @@ impl Track { } let mut group = self.inner.append_group()?; + self.largest = Some(group.sequence); if let Err(err) = group.write_frame(timestamp, payload) { // `append_group` already published this group, and a rejected frame (too large) doesn't // close the track. Dropping the handle does NOT close the group, so leaving it would strand diff --git a/rs/moq-json/src/window/encoder.rs b/rs/moq-json/src/window/encoder.rs index f06d52b9887..8f348944305 100644 --- a/rs/moq-json/src/window/encoder.rs +++ b/rs/moq-json/src/window/encoder.rs @@ -26,19 +26,16 @@ pub(super) const MAX_INDEX: u64 = (1 << 53) - 1; #[derive(Debug, Clone)] #[non_exhaustive] pub struct ProducerConfig { - /// How much the ops in a group may cost before a fresh group is emitted. + /// Whether edits ride as push and pop ops in the open group. /// - /// A new group opens once the pushes and pops *already written* exceed `op_ratio` times the - /// size of the group's header frame. The pending op is excluded from that check, so the one that - /// tips the group over budget still lands: a group overshoots by at most one op before rolling. - /// `0` disables ops entirely, so every edit is its own single-frame group. + /// `false` makes every edit its own single-frame group restating the window. The window's + /// counterpart to [`snapshot::Config::deltas`](crate::snapshot::Config::deltas). How long a + /// group of ops runs is not an option: it grows until a joiner wants a fresh one, judged by the + /// track's [`refresh`](moq_net::track::Info::refresh) ratio, or until it reaches the frame or + /// byte cap. /// - /// This is the window's counterpart to - /// [`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`. - pub op_ratio: u32, + /// Defaults to `true`. + pub ops: bool, /// Compress each group as one sync-flushed DEFLATE stream, so every op reuses the header and the /// ops before it as context. @@ -58,7 +55,7 @@ pub struct ProducerConfig { impl Default for ProducerConfig { fn default() -> Self { Self { - op_ratio: 8, + ops: true, compression: false, checkpoint_records: None, } @@ -66,9 +63,9 @@ impl Default for ProducerConfig { } impl ProducerConfig { - /// Set [`op_ratio`](Self::op_ratio) (a builder, since the struct is `#[non_exhaustive]`). - pub fn with_op_ratio(mut self, op_ratio: u32) -> Self { - self.op_ratio = op_ratio; + /// Set [`ops`](Self::ops) (a builder, since the struct is `#[non_exhaustive]`). + pub fn with_ops(mut self, ops: bool) -> Self { + self.ops = ops; self } @@ -104,8 +101,9 @@ pub struct Encoded { /// Whether this frame is a group header, which must open a new group. /// - /// The encoder decides this, never the caller: the op budget and the frame cap force a new group - /// independently of which edit was requested. + /// The encoder decides this for an edit: the group's frame and byte caps force a new group + /// independently of which edit was requested. A caller asks for one with + /// [`snapshot`](Encoder::snapshot). pub keyframe: bool, } @@ -124,6 +122,8 @@ pub struct Pending<'a, T> { enum Edit { Push(Value), Pop(u64), + /// A header restating the window as it is, which changes nothing. + Restate, } impl std::ops::Deref for Pending<'_, T> { @@ -160,7 +160,9 @@ impl Drop for Pending<'_, T> { /// /// Frames must reach the wire in the order they were encoded, and a frame with /// [`keyframe`](Encoded::keyframe) set must open a new group: both the positional indices and the -/// group-scoped DEFLATE window depend on it. +/// group-scoped DEFLATE window depend on it. When a joiner wants a fresh group (see +/// [`Demand::wanted`](moq_net::track::Demand::wanted)), [`snapshot`](Self::snapshot) restates the +/// window in one. pub struct Encoder { config: ProducerConfig, @@ -176,11 +178,8 @@ pub struct Encoder { /// The current group's DEFLATE encoder (one window per group), `Some` while compressing. flate: Option, - /// Bytes of pushes and pops emitted into the current group, excluding its header frame. - op_bytes: u64, - - /// Reference size the op budget is measured against: the current group's header frame. - header_len: u64, + /// Payload bytes emitted into the current group, header included. + group_bytes: u64, /// Frames emitted into the current group, header included. group_frames: usize, @@ -205,8 +204,7 @@ impl Encoder { offset: 0, start: 0, flate: None, - op_bytes: 0, - header_len: 0, + group_bytes: 0, group_frames: 0, resync: true, _marker: PhantomData, @@ -231,12 +229,28 @@ impl Encoder { /// how the encoder recovers after an encoded frame did not reach the wire. pub fn reset(&mut self) { self.flate = None; - self.op_bytes = 0; - self.header_len = 0; + self.group_bytes = 0; self.group_frames = 0; self.resync = true; } + /// Restate the retained window in a header, which must open a new group. + /// + /// For a caller that opens groups itself: call it when a joiner wants a fresh group, such as when + /// [`Demand::wanted`](moq_net::track::Demand::wanted) passes the largest group written, so the + /// joiner reads the window without the ops before it. The frame is a [`Pending`] like any other. + pub fn snapshot(&mut self) -> Result> { + let bytes = Self::header( + &self.config, + self.offset, + self.start, + self.window.len(), + self.window.iter(), + )?; + let encoded = self.emit_header(bytes)?; + Ok(self.pending(encoded, Edit::Restate)) + } + /// Apply an edit after its encoded frame reached the wire. fn commit(&mut self, edit: Edit) { match edit { @@ -256,16 +270,14 @@ impl Encoder { self.start += stored; self.offset = offset; } + Edit::Restate => {} } } - /// Whether the pending edit may ride as an op in the open group. + /// Whether the pending edit may ride as an op in the open group: ops are on and the group is + /// under its frame cap. The byte cap is checked once the op is encoded. fn op_allowed(&self) -> bool { - let ratio = u64::from(self.config.op_ratio); - ratio != 0 - && self.group_frames > 0 - && self.group_frames < MAX_GROUP_FRAMES - && self.op_bytes <= ratio * self.header_len + self.config.ops && self.group_frames > 0 && self.group_frames < MAX_GROUP_FRAMES } /// Reject plaintext that the paired DEFLATE decoder could not produce. @@ -278,7 +290,7 @@ impl Encoder { Ok(()) } - /// Compress an already-serialized op into the open group, charging it to the budget. + /// Compress an already-serialized op into the open group, counting it toward the caps. fn frame(&mut self, bytes: Vec) -> Result { Self::validate_plaintext(bytes.len(), "frame")?; let payload = match self.flate.as_mut() { @@ -286,7 +298,7 @@ impl Encoder { None => Bytes::from(bytes), }; - self.op_bytes += payload.len() as u64; + self.group_bytes += payload.len() as u64; self.group_frames += 1; Ok(Encoded { @@ -298,8 +310,7 @@ impl Encoder { /// Emit an op when the header will remain cached, otherwise restate the window in a new group. fn emit_op(&mut self, bytes: Vec) -> Result> { let encoded = self.frame(bytes)?; - let group_bytes = self.header_len.saturating_add(self.op_bytes); - if group_bytes > moq_net::group::MAX_CACHE_BYTES { + if self.group_bytes > moq_net::group::MAX_CACHE_BYTES { self.reset(); Ok(None) } else { @@ -334,8 +345,7 @@ impl Encoder { fn emit_header(&mut self, bytes: Vec) -> Result { Self::validate_plaintext(bytes.len(), "header")?; - // Open a fresh per-group encoder (cold window) and compress the header as frame 0, recording - // its wire size as the op budget's anchor. + // Open a fresh per-group encoder (cold window) and compress the header as frame 0. let (payload, flate) = match self.config.compression { true => { let mut flate = moq_flate::Encoder::new(); @@ -348,8 +358,7 @@ impl Encoder { return Err(Error::Json("window header exceeds the group cache limit".into())); } - self.header_len = payload.len() as u64; - self.op_bytes = 0; + self.group_bytes = payload.len() as u64; self.group_frames = 1; self.flate = flate; self.resync = false; @@ -443,7 +452,7 @@ impl Encoder { /// Append one record to the back of the window. /// /// Emits a push into the open group, or a header restating the window (the new record included) - /// when the op budget is spent or a frame was lost. + /// when the group is full or a frame was lost. pub fn push(&mut self, value: &T) -> Result> { // Serialize before touching the window, so a value that can't be encoded leaves the encoder // exactly as it was. Reading the record back out of its own bytes keeps the stored copy @@ -493,7 +502,7 @@ mod test { #[test] fn an_op_that_would_evict_the_header_rolls_first() { - let mut encoder = Encoder::::new(ProducerConfig::default().with_op_ratio(u32::MAX)); + let mut encoder = Encoder::::new(ProducerConfig::default().with_ops(true)); let first = "a".repeat(16 * 1024 * 1024); let next = "b".repeat(15 * 1024 * 1024); diff --git a/rs/moq-json/src/window/mod.rs b/rs/moq-json/src/window/mod.rs index bc28c879e27..54eda8b8757 100644 --- a/rs/moq-json/src/window/mod.rs +++ b/rs/moq-json/src/window/mod.rs @@ -24,11 +24,13 @@ //! //! # Group boundaries are invisible //! -//! The publisher rolls a group when the ops in it outgrow -//! [`ProducerConfig::op_ratio`](ProducerConfig::op_ratio) times the header that opened it, exactly as -//! [`snapshot`](crate::snapshot) rolls on its delta budget. That is purely a compression decision -//! with no age bound, and a [`Consumer`] never surfaces it. A caller that stores complete groups -//! can also end one with [`Producer::cut`]; the next edit opens a new group with a header. A header +//! The publisher rolls a group when a joiner wants a fresh one, exactly as +//! [`snapshot`](crate::snapshot) does: on a track created with a +//! [`refresh`](moq_net::track::Info::refresh) ratio, a subscriber joining once the open group's ops +//! outweigh that ratio times its header asks for one, and [`Producer::refresh`] restates the window +//! in it. Otherwise a group runs to the frame and byte caps. A [`Consumer`] never surfaces a roll. +//! A caller that stores complete groups can also end one with [`Producer::cut`]; the next edit +//! opens a new group with a header. A header //! restating records a reader already has yields nothing, so however often the publisher rolls, the //! reader sees one continuous stream of [`Event`]s. [`ProducerConfig::checkpoint_records`] bounds //! the suffix repeated on each roll for a long-lived window. @@ -383,7 +385,7 @@ mod test { #[test] fn a_popped_record_is_never_restated() { // Ops disabled, so every single edit is its own group restating the whole window. - let mut live = Live::new(ProducerConfig::default().with_op_ratio(0)); + let mut live = Live::new(ProducerConfig::default().with_ops(false)); live.push(0); live.push(1); live.pop(1); @@ -413,7 +415,7 @@ mod test { #[test] fn bounded_checkpoints_keep_a_following_consumer_contiguous() { - let config = ProducerConfig::default().with_op_ratio(0).with_checkpoint_records(2); + let config = ProducerConfig::default().with_ops(false).with_checkpoint_records(2); let mut live = Live::new(config); for n in 0..6 { live.push(n); @@ -428,7 +430,7 @@ mod test { #[test] fn a_late_consumer_skips_to_the_bounded_checkpoint() { - let config = ProducerConfig::default().with_op_ratio(0).with_checkpoint_records(2); + let config = ProducerConfig::default().with_ops(false).with_checkpoint_records(2); let mut encoder = Encoder::::new(config); let mut latest = None; for n in 0..5 { @@ -457,7 +459,7 @@ mod test { #[test] fn a_resumed_encoder_continues_the_window() { - let config = ProducerConfig::default().with_op_ratio(0).with_checkpoint_records(2); + let config = ProducerConfig::default().with_ops(false).with_checkpoint_records(2); let mut original = Encoder::::new(config.clone()); let mut decoder = Decoder::::new(ConsumerConfig::default()); for n in 0..4 { @@ -527,7 +529,7 @@ mod test { .produce() .create_track("test", moq_net::track::Info::default()) .unwrap(); - let mut producer = Producer::::new(track, ProducerConfig::default().with_op_ratio(0)); + let mut producer = Producer::::new(track, ProducerConfig::default().with_ops(false)); for n in 0..5 { producer.push(&rec(n)).unwrap(); @@ -568,7 +570,7 @@ mod test { // Ops are disabled, so every edit opens a new group. Feed the first two groups to the // decoder, skip the middle groups as a lagging track subscriber would, then resume at the // latest header. - let mut encoder = Encoder::::new(ProducerConfig::default().with_op_ratio(0)); + let mut encoder = Encoder::::new(ProducerConfig::default().with_ops(false)); let mut decoder = Decoder::::new(ConsumerConfig::default()); for n in 0..2 { let frame = encoder.push(&rec(n)).unwrap(); @@ -646,7 +648,7 @@ mod test { .create_track("test", timed()) .unwrap(); let mut consumer = consumer(track.subscribe(None), false); - let mut encoder = Encoder::::new(ProducerConfig::default().with_op_ratio(0)); + let mut encoder = Encoder::::new(ProducerConfig::default().with_ops(false)); let first = encoder.push(&rec(0)).unwrap(); let payload = first.payload.clone(); @@ -680,17 +682,133 @@ mod test { } } + /// A joiner under the ratio reads the open group, and one over it gets the window restated in a + /// fresh group, where it reads the same records with none of the ops before it. + #[test] + fn a_joiner_over_the_ratio_gets_a_fresh_header() { + let waiter = kio::Waiter::noop(); + let (mut producer, _track) = producer_on( + ProducerConfig::default(), + moq_net::track::Info::default().with_refresh(1), + ); + + // A 32 byte header and a 16 byte push: under the ratio. + producer.push(&rec(0)).unwrap(); + producer.push(&rec(1)).unwrap(); + let _early = producer.consume(); + assert!(producer.poll_refresh(&waiter).is_pending(), "a join under the ratio"); + + producer.push(&rec(2)).unwrap(); + producer.pop(1).unwrap(); + assert!(producer.poll_refresh(&waiter).is_pending(), "no join, no refresh"); + let mut late = producer.consume(); + assert!(matches!(producer.poll_refresh(&waiter), Poll::Ready(Ok(())))); + assert!(producer.poll_refresh(&waiter).is_pending(), "answered once"); + + let mut fresh = std::iter::from_fn(|| match late.poll_recv_group(&waiter) { + Poll::Ready(Ok(Some(group))) => Some(group), + _ => None, + }) + .last() + .expect("the fresh group"); + assert_eq!(fresh.sequence, 1); + let Poll::Ready(Ok(Some(header))) = fresh.poll_read_frame(&waiter) else { + panic!("expected the restating header"); + }; + assert_eq!( + serde_json::from_slice::(&header.payload).unwrap(), + json!({ "offset": 1, "records": [rec(1), rec(2)] }) + ); + + // The next edit rides as an op in the fresh group. + producer.push(&rec(3)).unwrap(); + let Poll::Ready(Ok(Some(op))) = fresh.poll_read_frame(&waiter) else { + panic!("expected an op in the fresh group"); + }; + assert_eq!( + serde_json::from_slice::(&op.payload).unwrap(), + json!({ "push": rec(3) }) + ); + } + + /// A refresh restates the window at the newest timestamp written. + #[test] + fn a_refresh_reuses_the_newest_timestamp() { + let waiter = kio::Waiter::noop(); + let ms = |n| moq_net::Timestamp::from_millis(n).unwrap(); + let (mut producer, _track) = producer_on(ProducerConfig::default(), timed().with_refresh(1)); + for n in 0..4 { + producer.push(moq_net::Timed::from(&rec(n)).at(ms(100 + n))).unwrap(); + } + producer.pop(moq_net::Timed::from(1).at(ms(200))).unwrap(); + + let mut late = producer.consume(); + assert!(matches!(producer.poll_refresh(&waiter), Poll::Ready(Ok(())))); + let mut fresh = std::iter::from_fn(|| match late.poll_recv_group(&waiter) { + Poll::Ready(Ok(Some(group))) => Some(group), + _ => None, + }) + .last() + .expect("the fresh group"); + let Poll::Ready(Ok(Some(header))) = fresh.poll_read_frame(&waiter) else { + panic!("expected the restating header"); + }; + assert_eq!(header.timestamp, Some(ms(200))); + } + + /// An op may carry a timestamp older than its group's first frame, but a new group may not start + /// before that frame, so the restating header takes the newest timestamp written. + #[test] + fn a_refresh_after_an_older_edit_starts_at_the_newest_timestamp() { + let waiter = kio::Waiter::noop(); + let ms = |n| moq_net::Timestamp::from_millis(n).unwrap(); + let (mut producer, _track) = producer_on(ProducerConfig::default(), timed().with_refresh(1)); + for (n, at) in [130, 110, 120, 115].into_iter().enumerate() { + producer.push(moq_net::Timed::from(&rec(n as u64)).at(ms(at))).unwrap(); + } + + let mut late = producer.consume(); + assert!(matches!(producer.poll_refresh(&waiter), Poll::Ready(Ok(())))); + let mut fresh = std::iter::from_fn(|| match late.poll_recv_group(&waiter) { + Poll::Ready(Ok(Some(group))) => Some(group), + _ => None, + }) + .last() + .expect("the fresh group"); + let Poll::Ready(Ok(Some(header))) = fresh.poll_read_frame(&waiter) else { + panic!("expected the restating header"); + }; + assert_eq!(header.timestamp, Some(ms(130))); + } + + /// Without a ratio no join asks for a group, and a finished producer stops refreshing. + #[test] + fn refresh_needs_a_ratio_and_an_open_track() { + let (mut producer, _track) = producer(ProducerConfig::default()); + for n in 0..8 { + producer.push(&rec(n)).unwrap(); + } + let _late = producer.consume(); + assert!(producer.poll_refresh(&kio::Waiter::noop()).is_pending()); + + producer.finish().unwrap(); + assert!(matches!(producer.refresh().now_or_never(), Some(Err(_)))); + } + #[test] fn compressed_round_trip_across_rolls() { - let mut live = Live::new(ProducerConfig::default().with_compression(true).with_op_ratio(1)); + let mut live = Live::new(ProducerConfig::default().with_compression(true)); for n in 0..40 { live.push(n); if n >= 10 { live.pop(1); } + if n % 7 == 6 { + live.producer.cut().unwrap(); + } } - // A tight ratio rolls many times; every record still arrives exactly once, in order. + // Cuts roll many compressed groups; every record still arrives exactly once, in order. assert_eq!(Live::pushed(&live.finish()), (0..40).collect::>()); } @@ -920,8 +1038,8 @@ mod test { #[test] fn rolling_is_invisible_to_the_consumer() { // The same edits, framed two ways: one group for everything, versus a roll per edit. - let edits = |ratio: u32| { - let mut live = Live::new(ProducerConfig::default().with_op_ratio(ratio)); + let edits = |ops: bool| { + let mut live = Live::new(ProducerConfig::default().with_ops(ops)); for n in 0..6 { live.push(n); if n >= 3 { @@ -931,6 +1049,6 @@ mod test { live.finish() }; - assert_eq!(edits(1_000), edits(0)); + assert_eq!(edits(true), edits(false)); } } diff --git a/rs/moq-json/src/window/producer.rs b/rs/moq-json/src/window/producer.rs index fca8ebd605b..00c51ef2e67 100644 --- a/rs/moq-json/src/window/producer.rs +++ b/rs/moq-json/src/window/producer.rs @@ -9,12 +9,17 @@ use serde_json::Value; use super::{Checkpoint, Encoded, Encoder, ProducerConfig}; use crate::Result; +use crate::refresh::Refresh; /// Publishes a sliding window of JSON records over a track. /// /// An [`Encoder`] that owns its track: it writes each encoded frame and rolls a group whenever the /// encoder emits a header. When something else already owns the track, use the [`Encoder`] directly. /// +/// A group runs until a joiner wants a fresh one, which [`refresh`](Self::refresh) answers, or until +/// it reaches the encoder's caps. Set the track's [`refresh`](moq_net::track::Info::refresh) ratio +/// when creating it, or joins never ask. +/// /// Cheaply clonable: clones share one underlying track and window, like other MoQ producers. pub struct Producer { inner: Arc>>, @@ -39,11 +44,14 @@ impl Producer { fn with_encoder(track: moq_net::track::Producer, encoder: Encoder) -> Self { Self { inner: Arc::new(Mutex::new(Inner { + refresh: Refresh::new(&track), track: Track { inner: track, group: None, + largest: None, }, encoder, + at: None, finished: false, })), _marker: PhantomData, @@ -83,6 +91,25 @@ impl Producer { self.inner.lock().unwrap().cut() } + /// Wait for a joiner to want a fresh group, then restate the window in a header opening one. + /// + /// A join wants one once the open group's ops outweigh the track's + /// [`refresh`](moq_net::track::Info::refresh) ratio times its header (see + /// [`Demand::wanted`](moq_net::track::Demand::wanted)), so that joiner reads the window without + /// downloading them. The header carries the newest timestamp written. Nothing happens before + /// the first edit, or on a track without a ratio. + /// + /// The producer has no runtime of its own, so the owner drives this: loop on it, or select on it + /// beside the edits. Errors once the track is finished or closed. + pub async fn refresh(&self) -> Result<()> { + kio::wait(|waiter| self.poll_refresh(waiter)).await + } + + /// Poll for [`refresh`](Self::refresh), for an owner driving the producer synchronously. + pub fn poll_refresh(&self, waiter: &kio::Waiter) -> std::task::Poll> { + self.inner.lock().unwrap().poll_refresh(waiter) + } + /// Finish the track, closing any open group. /// /// Borrows rather than consumes, matching snapshot and stream, so the handle stays @@ -119,6 +146,14 @@ impl Producer { struct Inner { track: Track, encoder: Encoder, + + /// Watches for a joiner wanting a group past the largest written. + refresh: Refresh, + + /// The newest timestamp written, which a refresh restates the window at. An edit may carry an + /// older timestamp than its group's first frame, and a new group may not start before that one. + at: Option, + finished: bool, } @@ -135,10 +170,23 @@ impl Inner { // new group because the attempted frame advanced the group-local compression state. track.write(count.at, &frame)?; frame.commit(); + self.at = self.at.max(count.at); Ok(()) } + fn poll_refresh(&mut self, waiter: &kio::Waiter) -> std::task::Poll> { + // A finished track still has subscribers draining it, so its demand alone never says stop. + self.ensure_open()?; + std::task::ready!(self.refresh.poll(self.track.largest, waiter))?; + + let Inner { track, encoder, at, .. } = self; + let frame = encoder.snapshot()?; + track.write(*at, &frame)?; + frame.commit(); + std::task::Poll::Ready(Ok(())) + } + fn cut(&mut self) -> Result<()> { let Some(mut group) = self.track.group.take() else { return Ok(()); @@ -174,6 +222,7 @@ impl Inner { let frame = encoder.push(value.value)?; track.write(value.at, &frame)?; frame.commit(); + self.at = self.at.max(value.at); Ok(()) } @@ -185,6 +234,9 @@ struct Track { /// The group an op would be appended to, open after a header. group: Option, + + /// The sequence of the newest group written, which a refresh has to pass. + largest: Option, } impl Track { @@ -210,6 +262,7 @@ impl Track { } let mut group = self.inner.append_group()?; + self.largest = Some(group.sequence); if let Err(err) = group.write_frame(timestamp, payload) { // `append_group` already published this group, and a rejected frame (too large) doesn't // close the track. Dropping the handle does NOT close the group, so leaving it would strand diff --git a/rs/moq-json/src/window/properties.rs b/rs/moq-json/src/window/properties.rs index d1b7a7d7ca7..742656ca944 100644 --- a/rs/moq-json/src/window/properties.rs +++ b/rs/moq-json/src/window/properties.rs @@ -46,6 +46,8 @@ fn value() -> BoxedStrategy { enum Edit { Push(Value), Pop(u64), + /// Restate the window with [`Encoder::snapshot`], as a refresh does. + Restate, } #[derive(Clone, Debug)] @@ -105,6 +107,11 @@ fn check(config: ProducerConfig, steps: Vec, join: usize) -> TestCaseResul records.drain(..count); frame } + Edit::Restate => { + let frame = encoder.snapshot().unwrap(); + prop_assert!(frame.keyframe); + Some(frame) + } }; if let Some(frame) = frame { if frame.keyframe { @@ -236,7 +243,11 @@ fn window_codec_property_matches_every_readers_logical_window() { }); let steps = proptest::collection::vec( ( - prop_oneof![value().prop_map(Edit::Push), (0u64..=8).prop_map(Edit::Pop)], + prop_oneof![ + 4 => value().prop_map(Edit::Push), + 4 => (0u64..=8).prop_map(Edit::Pop), + 1 => Just(Edit::Restate), + ], 0u8..16, any::(), ) @@ -248,16 +259,13 @@ fn window_codec_property_matches_every_readers_logical_window() { 1..65, ); let sequence = ( - ( - proptest::sample::select(vec![0, 1, 2, 8, 100]), - any::(), - proptest::option::of(1usize..=8), - ) - .prop_map(|(op_ratio, compression, checkpoint_records)| ProducerConfig { - op_ratio, + (any::(), any::(), proptest::option::of(1usize..=8)).prop_map( + |(ops, compression, checkpoint_records)| ProducerConfig { + ops, compression, checkpoint_records, - }), + }, + ), steps, 0usize..64, ); diff --git a/rs/moq-mux/MIGRATE.md b/rs/moq-mux/MIGRATE.md index 6b367a8d6f6..a3ff4833685 100644 --- a/rs/moq-mux/MIGRATE.md +++ b/rs/moq-mux/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON `delta_ratio` is `deltas` + +`json::Config::delta_ratio` and `with_delta_ratio` are replaced by `deltas: bool` and `with_deltas` (default `true`). +Call `with_deltas(false)` where you called `with_delta_ratio(0)`. +Snapshot groups roll on joiner demand: create the track with `Info::refresh` and drive `json::Snapshot::refresh` (or `poll_refresh`) beside your updates. + ### Priorities are signed (#6142) `track_info` on the catalog producer and tracks takes an `i8` priority, higher first, with 0 unset; pass `hang::catalog::PRIORITY` as before. diff --git a/rs/moq-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index e0e236c1023..dd22ffde43e 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -434,7 +434,7 @@ impl Producer { // Disable deltas for now to stay byte-compatible with consumers that only read snapshots. let mut json_config = moq_json::snapshot::Config::default(); - json_config.delta_ratio = 0; + json_config.deltas = false; 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 @@ -974,10 +974,12 @@ impl Producer { /// `config` is a [`json::Config`](crate::json::Config) for the `json` section, or an /// application's own entry embedding a [`JsonConfig`](hang::catalog::JsonConfig) (see /// [`IntoRendition`](super::IntoRendition)). The producer sets its `mode`, encodes the track - /// with its `compression`, and fills an absent `bitrate` from what it writes. A - /// [`delta_ratio`](crate::json::Config::delta_ratio) on `json::Config` selects the snapshot - /// encoder; it is not written into the catalog entry. The config is `'static` so that ratio - /// can be read off the builder. + /// with its `compression`, and fills an absent `bitrate` from what it writes. The + /// [`deltas`](crate::json::Config::deltas) switch on `json::Config` configures the snapshot + /// encoder; it is not written into the catalog entry. The config is `'static` so that switch + /// can be read off the builder. With deltas, create `track` with a + /// [`refresh`](moq_net::track::Info::refresh) ratio and drive + /// [`Snapshot::refresh`](crate::json::Snapshot::refresh), so joiners get a fresh group. /// /// Errors if the entry's section already carries that name, for example an entry seeded /// through [`Config::with_catalog`] or one pointing at a sibling broadcast, or if the entry diff --git a/rs/moq-mux/src/json.rs b/rs/moq-mux/src/json.rs index be61879db91..68c7c654663 100644 --- a/rs/moq-mux/src/json.rs +++ b/rs/moq-mux/src/json.rs @@ -92,7 +92,7 @@ use crate::catalog::{IntoRendition, Listing, RenditionConfig}; /// Start from [`default`](Default::default) and chain the setters. The mode is not in here: it is /// fixed by which producer you create. To list the track in an application's own catalog section /// instead of `json`, pass that section's entry (see [`IntoRendition`]). -#[derive(Debug, Clone, Default)] +#[derive(Debug, Clone)] #[non_exhaustive] pub struct Config { /// DEFLATE-compress the track's frames, advertised as @@ -104,12 +104,23 @@ pub struct Config { /// An optional identifier for the shape of each value, typically a JSON Schema URL. pub schema: Option, - /// Override the snapshot encoder's [`delta_ratio`](moq_json::snapshot::Config::delta_ratio), - /// or `None` for its default. Only a [`Snapshot`] reads it: a stream has no deltas. + /// Whether the snapshot encoder emits merge-patch deltas (see + /// [`moq_json::snapshot::Config::deltas`]). Only a [`Snapshot`] reads it: a stream has no + /// deltas. Defaults to `true`. /// /// Not part of the catalog entry: deltas are a property of the frames, which every consumer /// decodes the same way, so a reader needs nothing from the entry to follow them. - pub delta_ratio: Option, + pub deltas: bool, +} + +impl Default for Config { + fn default() -> Self { + Self { + compression: false, + schema: None, + deltas: true, + } + } } impl Config { @@ -125,9 +136,9 @@ impl Config { self } - /// 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 = Some(delta_ratio); + /// Set [`deltas`](Self::deltas) (a builder, since the struct is `#[non_exhaustive]`). + pub fn with_deltas(mut self, deltas: bool) -> Self { + self.deltas = deltas; self } } @@ -157,14 +168,14 @@ fn prepare(config: &mut impl AsMut, mode: Mode) -> crate::Result(config: &C) -> Option { +fn deltas_of(config: &C) -> bool { (config as &dyn std::any::Any) .downcast_ref::() - .and_then(|config| config.delta_ratio) + .is_none_or(|config| config.deltas) } /// Publishes a latest-value JSON track, advertised in the catalog for as long as this handle lives. @@ -187,17 +198,14 @@ impl Snapshot { where C: IntoRendition + std::any::Any, { - // Read before `into_rendition` consumes the builder. Only [`Config`] carries a ratio; - // a custom section entry has none, and the default encoder ratio applies. - let delta_ratio = delta_ratio_of(&config); + // Read before `into_rendition` consumes the builder. Only [`Config`] carries the switch; + // a custom section entry has none, and the encoder default applies. + let deltas = deltas_of(&config); let mut config = config.into_rendition(); - let mut json = moq_json::snapshot::Config::default(); + let mut json = moq_json::snapshot::Config::default().with_deltas(deltas); if prepare(&mut config, Mode::Snapshot)? { json.compression = moq_json::Compression::Deflate; } - if let Some(delta_ratio) = delta_ratio { - json.delta_ratio = delta_ratio; - } let inner = moq_json::snapshot::Producer::new(track, json); let listing = Listing::new(rendition, config)?; Ok(Self { @@ -222,6 +230,19 @@ impl Snapshot { self.inner.demand() } + /// Wait for a joiner to want a fresh group, then restate the value in one; see + /// [`moq_json::snapshot::Producer::refresh`]. + /// + /// A restatement is not a new value, so it measures neither `jitter` nor `delay`. + pub async fn refresh(&self) -> crate::Result<()> { + Ok(self.inner.refresh().await?) + } + + /// Poll for [`refresh`](Self::refresh), for an owner driving the producer synchronously. + pub fn poll_refresh(&self, waiter: &kio::Waiter) -> std::task::Poll> { + self.inner.poll_refresh(waiter).map_err(Into::into) + } + /// Publish a new value, superseding the previous one. /// /// A value timed on the broadcast clock is written at that timestamp and measures the entry's @@ -602,16 +623,16 @@ mod test { } } - /// `delta_ratio` is an encoder setting on [`Config`], not a catalog field. A ratio of 0 - /// publishes each value as its own group; a positive ratio keeps the next value in that group. + /// `deltas` is an encoder setting on [`Config`], not a catalog field. Without deltas + /// each value is its own group; with them the next value joins that group. #[test] - fn a_config_delta_ratio_reaches_the_encoder() { + fn a_config_deltas_switch_reaches_the_encoder() { let (mut broadcast, catalog) = catalog(); let mut full = catalog - .json_snapshot::(track(&mut broadcast, "full"), Config::default().with_delta_ratio(0)) + .json_snapshot::(track(&mut broadcast, "full"), Config::default().with_deltas(false)) .unwrap(); let mut delta = catalog - .json_snapshot::(track(&mut broadcast, "delta"), Config::default().with_delta_ratio(100)) + .json_snapshot::(track(&mut broadcast, "delta"), Config::default()) .unwrap(); let mut full_track = full.consume(); @@ -624,8 +645,8 @@ mod test { delta.finish().unwrap(); // The default subscription budget keeps only the latest group, aging untimed groups by - // wall clock. Ratio 0 rolled a new group for the second value, so that group holds one - // frame. A positive ratio appends the second value to the same group. + // wall clock. Without deltas the second value rolled a new group, so that group holds one + // frame. With deltas the second value joins the same group. assert_eq!(ready_groups(&mut full_track), vec![1]); assert_eq!(ready_groups(&mut delta_track), vec![2]); } diff --git a/rs/moq-mux/src/timeline.rs b/rs/moq-mux/src/timeline.rs index 4015446a65c..4b4721195eb 100644 --- a/rs/moq-mux/src/timeline.rs +++ b/rs/moq-mux/src/timeline.rs @@ -442,6 +442,8 @@ impl Producer { moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MILLI) .with_priority(hang::catalog::PRIORITY.catalog) + // A joiner asks for a fresh group once the ops outweigh eight headers. + .with_refresh(8) } /// Publish onto `track`, starting at record zero. @@ -488,6 +490,7 @@ impl Producer { actual: record.sequence, }); } + self.refresh()?; self.sink .push(moq_net::Timed::from(record).at(moq_net::Timestamp::now())) .map_err(json) @@ -495,6 +498,7 @@ impl Producer { /// Remove up to `count` oldest records from the window. pub fn pop(&mut self, count: u64) -> crate::Result<()> { + self.refresh()?; self.sink .pop(moq_net::Timed::from(count).at(moq_net::Timestamp::now())) .map_err(json) @@ -512,6 +516,17 @@ impl Producer { pub fn finish(&mut self) -> crate::Result<()> { self.sink.finish().map_err(json) } + + /// Restate the window in a fresh group if a joiner wants one. + /// + /// Checked on each edit rather than driven by a task, since nothing here owns a runtime. A + /// timeline gains a record every segment, so a joiner waits at most about one segment. + fn refresh(&mut self) -> crate::Result<()> { + match self.sink.poll_refresh(&kio::Waiter::noop()) { + std::task::Poll::Ready(Err(err)) => Err(json(err)), + _ => Ok(()), + } + } } /// Surface a transport failure as one, rather than wrapped in the JSON layer. diff --git a/rs/moq-room/src/chat.rs b/rs/moq-room/src/chat.rs index d98d56e17eb..b9d2db7e208 100644 --- a/rs/moq-room/src/chat.rs +++ b/rs/moq-room/src/chat.rs @@ -77,7 +77,7 @@ impl Publisher { Self { producer: moq_json::window::Producer::new( track, - moq_json::window::ProducerConfig::default().with_op_ratio(0), + moq_json::window::ProducerConfig::default().with_ops(false), ), expires: VecDeque::new(), deadline: Deadline::new(), @@ -285,7 +285,7 @@ mod tests { let mut demand = track.demand(); let mut chat = moq_json::window::Producer::::new( track, - moq_json::window::ProducerConfig::default().with_op_ratio(0), + moq_json::window::ProducerConfig::default().with_ops(false), ); let at = |millis| moq_net::Timestamp::from_millis(millis).unwrap(); chat.push(moq_net::Timed::from(&"first".to_owned()).at(at(0))).unwrap(); diff --git a/rs/moq-stats/benches/aggregate.rs b/rs/moq-stats/benches/aggregate.rs index 4a21aa0e944..b96a78bf363 100644 --- a/rs/moq-stats/benches/aggregate.rs +++ b/rs/moq-stats/benches/aggregate.rs @@ -50,7 +50,7 @@ impl Node { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI), ) .unwrap(); - let config = moq_json::snapshot::Config::default().with_delta_ratio(0); + let config = moq_json::snapshot::Config::default().with_deltas(false); let frame = (0..KEYS) .map(|key| { let mut traffic = Traffic::default(); diff --git a/rs/moq-stats/benches/decode.rs b/rs/moq-stats/benches/decode.rs index a9760fecab9..611311a20e9 100644 --- a/rs/moq-stats/benches/decode.rs +++ b/rs/moq-stats/benches/decode.rs @@ -74,7 +74,7 @@ fn traffic(index: usize, tick: u64, changed_percent: usize) -> Traffic { /// The compressed frames one tier's producer would publish over the run, snapshot first. fn frames(broadcasts: usize, tier: usize, changed_percent: usize) -> Vec<(Vec, bool)> { - let mut config = snapshot::Config::default().with_delta_ratio(u32::MAX); + let mut config = snapshot::Config::default().with_deltas(true); config.compression = moq_json::Compression::Deflate; let mut encoder = Encoder::::new(config); (0..TICKS + 2) diff --git a/rs/moq-stats/src/aggregate.rs b/rs/moq-stats/src/aggregate.rs index efe5baa5bc3..1e234c37147 100644 --- a/rs/moq-stats/src/aggregate.rs +++ b/rs/moq-stats/src/aggregate.rs @@ -1114,7 +1114,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, timed()).expect("create track"); - let config = moq_json::snapshot::Config::default().with_delta_ratio(0); + let config = moq_json::snapshot::Config::default().with_deltas(false); Self { traffic: moq_json::snapshot::Producer::new(track.clone(), config), track, @@ -1890,7 +1890,7 @@ mod tests { .expect("create broadcast"); source.announce(origin::Route::default()).expect("announce"); let track = source.create_track(totals_track(false), timed()).expect("create track"); - let config = moq_json::snapshot::Config::default().with_delta_ratio(0); + let config = moq_json::snapshot::Config::default().with_deltas(false); Self { _source: source, totals: moq_json::snapshot::Producer::new(track, config), diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index 34769299624..b4c3342622c 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -451,11 +451,16 @@ impl Serialize for Frame { /// resumes past any group a subscriber has cached, without retaining a /// tombstone per requested name. A new group broadcast is a new epoch, so its /// allocator starts over. +/// +/// The shared allocator is why this wraps the encoder rather than a +/// `moq_json::snapshot::Producer`, which numbers its own groups. struct Snapshot { track: track::Producer, encoder: moq_json::snapshot::Encoder>, group: Option, sequence: Arc, + /// The sequence of the newest group written, which a refresh has to pass. + largest: Option, deltas: bool, } @@ -463,10 +468,11 @@ impl Snapshot { fn new(track: track::Producer, config: moq_json::snapshot::Config, sequence: Arc) -> Self { Self { track, - deltas: config.delta_ratio != 0, + deltas: config.deltas, encoder: moq_json::snapshot::Encoder::new(config), group: None, sequence, + largest: None, } } @@ -484,6 +490,14 @@ impl Snapshot { if self.track.is_closed() { return Ok(None); } + // A joiner wants a group past the newest, so open this tick's with a snapshot, even of an + // unchanged value. Answered once per tick rather than at once: a joiner waits at most one + // interval, the same as for any change. + if let (Some(wanted), Some(largest)) = (self.track.demand().wanted(), self.largest) + && wanted > largest + { + self.encoder.reset(); + } let Some(frame) = self.encoder.update(value)? else { return Ok(None); }; @@ -500,9 +514,9 @@ impl Snapshot { if let Some(mut group) = self.group.take() { group.finish()?; } - self.group = Some(self.track.create_group(moq_net::group::Info { - sequence: self.sequence.fetch_add(1, Ordering::Relaxed), - })?); + let sequence = self.sequence.fetch_add(1, Ordering::Relaxed); + self.group = Some(self.track.create_group(moq_net::group::Info { sequence })?); + self.largest = Some(sequence); } let group = self.group.as_mut().expect("a delta follows a snapshot"); if let Err(err) = group.write_frame(moq_net::Timestamp::now(), frame.payload.clone()) { @@ -550,15 +564,22 @@ fn info() -> track::Info { track::Info::default().with_timescale(moq_net::Timescale::MILLI) } +/// The compressed flavor keeps deltas, so a joiner asks for a fresh group once they outweigh +/// eight snapshots. +fn compressed_info() -> track::Info { + info().with_refresh(8) +} + impl TrackPair { fn create(broadcast: &broadcast::Producer, name: &str, sequence: Arc) -> Result { let plain_track = broadcast.create_track(name, info())?; - let compressed_track = broadcast.create_track(format!("{name}{COMPRESSED_SUFFIX}").as_str(), info())?; + let compressed_track = + broadcast.create_track(format!("{name}{COMPRESSED_SUFFIX}").as_str(), compressed_info())?; Ok(Self::from_tracks(plain_track, compressed_track, sequence)) } fn from_tracks(plain_track: track::Producer, compressed_track: track::Producer, sequence: Arc) -> Self { - let plain_config = moq_json::snapshot::Config::default().with_delta_ratio(0); + let plain_config = moq_json::snapshot::Config::default().with_deltas(false); let mut compressed_config = moq_json::snapshot::Config::default(); compressed_config.compression = moq_json::Compression::Deflate; @@ -653,8 +674,8 @@ impl PendingPair { None => broadcast.create_track(name, info())?, }; let compressed_track = match compressed { - Some(request) => request.accept(info()), - None => broadcast.create_track(format!("{name}{COMPRESSED_SUFFIX}").as_str(), info())?, + Some(request) => request.accept(compressed_info()), + None => broadcast.create_track(format!("{name}{COMPRESSED_SUFFIX}").as_str(), compressed_info())?, }; Ok(TrackPair::from_tracks(plain_track, compressed_track, sequence)) } @@ -1584,6 +1605,39 @@ mod tests { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) } + /// A joiner once the deltas outweigh the compressed track's ratio gets a fresh snapshot group on + /// the next tick, even of an unchanged value, and deltas resume in it. + #[test] + fn a_joiner_over_the_ratio_gets_a_snapshot_next_tick() { + let broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast.create_track("t.json.z", compressed_info()).unwrap(); + let mut snapshot = Snapshot::::new( + track.clone(), + moq_json::snapshot::Config::default(), + Arc::new(AtomicU64::new(0)), + ); + let frame = |n| Frame { + entries: vec![(PathOwned::from("a"), n)], + }; + let wanted = |track: &track::Producer| track.demand().wanted(); + + // A 7 byte snapshot and nine 7 byte deltas: past eight snapshots. + for n in 0..10 { + snapshot.update(&frame(n)).unwrap(); + } + assert_eq!(snapshot.largest, Some(0)); + let _late = track.subscribe(None); + assert_eq!(wanted(&track), Some(1), "the join asks for a fresh group"); + + assert!( + snapshot.update(&frame(9)).unwrap().is_some(), + "restated though unchanged" + ); + assert_eq!(snapshot.largest, Some(1)); + assert!(snapshot.update(&frame(10)).unwrap().is_some()); + assert_eq!(snapshot.largest, Some(1), "the next change is a delta"); + } + #[tokio::test(start_paused = true)] async fn reclaimed_requested_tracks_resume_after_the_last_group() { use futures::FutureExt; diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index b57dcd64d06..8c55896b050 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### JSON snapshot `deltaRatio` is `deltas` + +`Json.SnapshotProducer(deltaRatio:)` and `MoqJsonSnapshotConfig.deltaRatio` are replaced by `deltas: Bool` (default `true`). +Pass `deltas: false` where you passed `deltaRatio: 0`, and drop the argument otherwise. +Publish the track with a `refresh` ratio so a joiner gets the value restated in a fresh group. + ### Priorities are signed (#6142) `TrackInfo.priority`, `Subscription.priority`, `FetchGroupOptions.priority`, and `GroupRequest.priority` are `Int8`, higher first, and 0 is the unset midpoint. diff --git a/swift/Sources/Moq/Json.swift b/swift/Sources/Moq/Json.swift index e6c3c6a9d7a..ca944101067 100644 --- a/swift/Sources/Moq/Json.swift +++ b/swift/Sources/Moq/Json.swift @@ -43,19 +43,20 @@ extension Json { /// finishes. Takes over `track`, whose handle is closed afterward; throws if the catalog /// already carries the track's name. /// - /// `deltaRatio` controls how aggressively merge-patch deltas replace full snapshots (`0` - /// disables deltas). Set `compression` to DEFLATE each group; the consumer must pass the - /// same flag. + /// `deltas` encodes updates as merge-patch deltas; with it off every update is a full + /// snapshot in its own group. With deltas on, give the track a `refresh` ratio so a joiner + /// past it gets the value restated in a fresh group. Set `compression` to DEFLATE each + /// group; the consumer must pass the same flag. public init( broadcast: BroadcastProducer, track: TrackProducer, - deltaRatio: UInt32 = MoqJsonSnapshotConfig().deltaRatio, + deltas: Bool = MoqJsonSnapshotConfig().deltas, compression: Bool = false ) throws { ffi = try MoqJsonSnapshotProducer( broadcast: broadcast.ffi, track: track.ffi, - config: MoqJsonSnapshotConfig(deltaRatio: deltaRatio, compression: compression) + config: MoqJsonSnapshotConfig(deltas: deltas, compression: compression) ) } @@ -89,7 +90,7 @@ extension Json { /// afterward; throws if it has already read a group. `compression` must match the flag /// the producer used. public init(track: TrackConsumer, compression: Bool = false) throws { - // deltaRatio is producer-only, so leave it at its default here. + // deltas is producer-only, so leave it at its default here. ffi = try MoqJsonSnapshotConsumer(track: track.ffi, config: MoqJsonSnapshotConfig(compression: compression)) }