From 988ac2da7f5d6c13c5ce8479481fccf1f74def23 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 21:39:13 -0700 Subject: [PATCH 01/17] quest: claim m1/refresh/json Co-Authored-By: Claude Opus 5.5 From b37ccd98d8c5df91acfe9f72077b9ccf0fbdf55b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 21:55:51 -0700 Subject: [PATCH 02/17] feat(json)!: roll snapshot and window groups on joiner demand Co-Authored-By: Claude Opus 5.5 --- rs/moq-json/benches/allocations.rs | 2 +- rs/moq-json/benches/table.rs | 6 +- rs/moq-json/examples/telemetry.rs | 12 +- rs/moq-json/src/lib.rs | 1 + rs/moq-json/src/refresh.rs | 38 +++ rs/moq-json/src/snapshot/decoder.rs | 4 +- rs/moq-json/src/snapshot/encoder.rs | 348 ++++++++++++++++----------- rs/moq-json/src/snapshot/mod.rs | 278 +++++++++++++-------- rs/moq-json/src/snapshot/producer.rs | 57 ++++- rs/moq-json/src/window/encoder.rs | 95 ++++---- rs/moq-json/src/window/mod.rs | 127 ++++++++-- rs/moq-json/src/window/producer.rs | 52 ++++ rs/moq-json/src/window/properties.rs | 19 +- 13 files changed, 725 insertions(+), 314 deletions(-) create mode 100644 rs/moq-json/src/refresh.rs 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 7fdceb8db1c..31ff7fc8606 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 42c095d9766..f64e5f83da1 100644 --- a/rs/moq-json/src/lib.rs +++ b/rs/moq-json/src/lib.rs @@ -19,6 +19,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/decoder.rs b/rs/moq-json/src/snapshot/decoder.rs index 3159b851c4e..596881501ad 100644 --- a/rs/moq-json/src/snapshot/decoder.rs +++ b/rs/moq-json/src/snapshot/decoder.rs @@ -350,7 +350,7 @@ mod test { fn compressed_roundtrip_across_a_group_boundary() { // A tight ratio guarantees at least one roll partway through. let values: Vec = (0..=40).map(|n| json!({ "n": n })).collect(); - let config = deflate().with_delta_ratio(2); + let config = deflate().with_deltas(true); assert_eq!(roundtrip(config, &values).last().unwrap(), &json!({ "n": 40 })); } @@ -371,7 +371,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..fb6906b2700 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, @@ -189,7 +186,9 @@ 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, @@ -204,13 +203,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 +230,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, @@ -266,11 +259,89 @@ 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 encoded 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, + committed: false, + })) + } + + /// Encode an already-serialized value as a full snapshot, opening a new group and reseeding the + /// baseline. + 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()); + } + + // 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(), + } + }; + + // 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.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, + }) + } } impl Encoder { @@ -296,7 +367,7 @@ impl Encoder { // 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 +380,12 @@ impl Encoder { if next.as_slice() == bytes.as_ref() { return Ok(None); } - return self.snapshot_encoded(next).map(Some); + return self.snapshot_encoded(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 +398,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,17 +425,17 @@ 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 + // 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") @@ -378,88 +449,18 @@ impl Encoder { })) } - /// 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 { + fn encode_snapshot(&mut self, value: &T) -> Result { // 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_encoded(Bytes::from(snapshot)) } } @@ -510,6 +511,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 +523,7 @@ mod test { .map(|(value, reset)| PropertyStep { value, reset: reset == 0, + restate: reset == 1, }) .collect() }); @@ -537,6 +541,7 @@ mod test { PropertyStep { value: Value::Object(current.clone()), reset: reset == 0, + restate: reset == 1, } }) .collect() @@ -568,19 +573,19 @@ mod test { ..Default::default() }); let sequence = ( - proptest::sample::select(vec![0, 1, 2, 8, 100]), + 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, + deltas, compression, }); let mut decoder = super::super::Decoder::::new(super::super::consumer::Config { @@ -591,6 +596,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(); @@ -674,7 +691,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 +701,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 +769,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 +780,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 +791,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 +805,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 +820,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 +830,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 +839,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 +851,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 +864,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 +920,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 +956,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 +1016,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,7 +1073,7 @@ 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. @@ -1091,7 +1161,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 +1222,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 })); diff --git a/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index 8f51bc3e2de..edd38844d5b 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -13,13 +13,21 @@ //! order. A consumer jumps to the newest group, reads the snapshot, and applies the deltas, so //! a late joiner never needs older groups. //! -//! Deltas are controlled by [`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 //! @@ -61,7 +69,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(); @@ -83,7 +91,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!( @@ -106,8 +114,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)) @@ -117,7 +125,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}"); } } @@ -145,15 +153,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, } } @@ -272,7 +280,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(); @@ -291,7 +299,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(); @@ -309,7 +317,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(); @@ -325,7 +333,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(); @@ -351,7 +359,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. @@ -368,7 +376,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(); @@ -403,7 +411,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. @@ -437,7 +445,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(); @@ -461,7 +469,7 @@ mod test { #[test] fn deltas_share_one_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.update(&json!({ "a": 1, "b": 3 })).unwrap(); @@ -476,49 +484,127 @@ mod test { assert_eq!(values.last().unwrap(), &json!({ "a": 1, "b": 3 })); } + /// With nobody joining, deltas pile up in one group however far they outweigh the snapshot. #[test] - fn tight_ratio_rolls_snapshots() { - // 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. (Still distinct from 0, which disables deltas entirely.) - let (mut producer, mut track) = producer(cfg(1)); - producer.update(&json!({ "a": 1 })).unwrap(); // snapshot, group 0 - producer.update(&json!({ "a": 2 })).unwrap(); // delta, group 0 (deltas = 7) - producer.update(&json!({ "a": 3 })).unwrap(); // delta, group 0 (deltas = 14, now over budget) - producer.update(&json!({ "a": 4 })).unwrap(); // budget already exceeded, rolls group 1 + 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(); 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 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 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 last committed update's timestamp, the value's own time, + /// rather than inventing one. + #[test] + fn a_refresh_reuses_the_last_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 }))]); + } + + /// 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(); } - producer.finish().unwrap(); + let _late = producer.consume(); + assert!(producer.poll_refresh(&kio::Waiter::noop()).is_pending()); + } - // 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) - ); - assert_eq!(drain(track).last().unwrap(), &json!({ "n": 10 })); + /// `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(); @@ -533,7 +619,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(); @@ -550,7 +636,7 @@ mod test { #[test] fn late_joiner_reconstructs_from_deltas() { - let (mut producer, track) = producer(cfg(100)); + let (mut producer, track) = producer(cfg(true)); producer.update(&json!({ "a": 1, "b": 1 })).unwrap(); producer.update(&json!({ "a": 1, "b": 2 })).unwrap(); producer.update(&json!({ "a": 5, "b": 2 })).unwrap(); @@ -599,7 +685,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(); @@ -670,7 +756,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(); @@ -709,7 +795,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!( @@ -722,7 +808,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 }); @@ -738,7 +824,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(); @@ -751,7 +837,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(); @@ -775,7 +861,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(); @@ -793,7 +879,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(|| { @@ -851,7 +937,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(); @@ -886,7 +972,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())), @@ -915,7 +1001,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; @@ -935,9 +1021,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(); @@ -948,9 +1033,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 @@ -1005,7 +1091,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(); } @@ -1027,7 +1113,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(); } @@ -1047,7 +1133,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(); @@ -1063,7 +1149,7 @@ mod test { #[test] fn compressed_deltas_share_one_group() { - let (mut producer, mut track) = producer(cfg_deflate(100)); + let (mut producer, mut track) = producer(cfg_deflate(true)); producer.update(&json!({ "a": 1, "b": 1 })).unwrap(); producer.update(&json!({ "a": 1, "b": 2 })).unwrap(); producer.update(&json!({ "a": 1, "b": 3 })).unwrap(); @@ -1080,7 +1166,7 @@ mod test { #[test] fn compressed_late_joiner_reconstructs_from_deltas() { - let (mut producer, track) = producer(cfg_deflate(100)); + let (mut producer, track) = producer(cfg_deflate(true)); producer.update(&json!({ "a": 1, "b": 1 })).unwrap(); producer.update(&json!({ "a": 1, "b": 2 })).unwrap(); producer.update(&json!({ "a": 5, "b": 2 })).unwrap(); @@ -1091,29 +1177,27 @@ mod test { assert_eq!(values.last().unwrap(), &json!({ "a": 5, "b": 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] @@ -1121,8 +1205,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}" @@ -1133,7 +1217,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(); @@ -1174,7 +1258,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()); @@ -1189,7 +1273,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 26295ace55f..2b40b362a9e 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 timestamp of the last update, the value's own time. + /// 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 @@ -164,7 +191,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 +297,12 @@ struct Inner { track: Track, encoder: Encoder, + /// Watches for a joiner wanting a group past the largest written. + refresh: Refresh, + + /// The timestamp of the last committed update, which a refresh restates the value at. + 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, @@ -344,10 +377,26 @@ impl Inner { track.write(timestamp, &frame)?; let size = frame.payload.len(); frame.commit(); + self.at = 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 82c5fdc0eea..46674d65f6c 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. @@ -304,7 +306,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); @@ -334,7 +336,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); @@ -349,7 +351,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 { @@ -378,7 +380,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 { @@ -448,7 +450,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(); @@ -489,7 +491,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(); @@ -562,7 +564,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(); @@ -596,17 +598,108 @@ 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 last committed edit's timestamp. + #[test] + fn a_refresh_reuses_the_last_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))); + } + + /// 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::>()); } @@ -836,8 +929,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 { @@ -847,6 +940,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 babb9356a24..452666627a1 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 timestamp of the last edit. 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,13 @@ impl Producer { struct Inner { track: Track, encoder: Encoder, + + /// Watches for a joiner wanting a group past the largest written. + refresh: Refresh, + + /// The timestamp of the last committed edit, which a refresh restates the window at. + at: Option, + finished: bool, } @@ -135,10 +169,23 @@ impl Inner { // new group because the attempted frame advanced the group-local compression state. track.write(count.at, &frame)?; frame.commit(); + self.at = 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(group) = self.track.group.take() else { return Ok(()); @@ -174,6 +221,7 @@ impl Inner { let frame = encoder.push(value.value)?; track.write(value.at, &frame)?; frame.commit(); + self.at = value.at; Ok(()) } @@ -185,6 +233,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 +261,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..e103e24388d 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::(), ) @@ -249,12 +260,12 @@ fn window_codec_property_matches_every_readers_logical_window() { ); let sequence = ( ( - proptest::sample::select(vec![0, 1, 2, 8, 100]), + any::(), any::(), proptest::option::of(1usize..=8), ) - .prop_map(|(op_ratio, compression, checkpoint_records)| ProducerConfig { - op_ratio, + .prop_map(|(ops, compression, checkpoint_records)| ProducerConfig { + ops, compression, checkpoint_records, }), From 1ec5cf2a109bd92926d126e83e76544c560c6b6e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 22:09:26 -0700 Subject: [PATCH 03/17] feat(json)!: move in-repo callers to deltas/ops switches and refresh Co-Authored-By: Claude Opus 5.5 --- rs/moq-archive/src/reader/tests.rs | 14 ++--- rs/moq-boy/src/status.rs | 11 +++- rs/moq-hls/src/export/archive_tests.rs | 6 +-- rs/moq-hls/src/export/mod.rs | 7 +-- rs/moq-mux/src/catalog/producer.rs | 12 +++-- rs/moq-mux/src/json.rs | 71 +++++++++++++++++--------- rs/moq-mux/src/timeline.rs | 15 ++++++ rs/moq-room/src/chat.rs | 2 +- rs/moq-stats/benches/aggregate.rs | 2 +- rs/moq-stats/benches/decode.rs | 2 +- rs/moq-stats/src/aggregate.rs | 4 +- rs/moq-stats/src/produce.rs | 67 +++++++++++++++++++++--- 12 files changed, 156 insertions(+), 57 deletions(-) diff --git a/rs/moq-archive/src/reader/tests.rs b/rs/moq-archive/src/reader/tests.rs index 3cf641605e3..2f525ba3da5 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-hls/src/export/archive_tests.rs b/rs/moq-hls/src/export/archive_tests.rs index df5f9227aa4..005330953f1 100644 --- a/rs/moq-hls/src/export/archive_tests.rs +++ b/rs/moq-hls/src/export/archive_tests.rs @@ -139,7 +139,7 @@ impl Recording { .unwrap(); let config = window::ProducerConfig::default() .with_compression(true) - .with_op_ratio(0); + .with_ops(false); let encoder = Encoder { encoder: window::Encoder::new(config), group: 0, @@ -307,7 +307,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())) @@ -392,7 +392,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 63f019c019b..1590889e065 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -2429,7 +2429,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()) @@ -4565,8 +4565,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-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index 86dea6fbeda..10f31da18a8 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -431,7 +431,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 @@ -954,10 +954,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 0a1fdb054c6..02bdb0c6e8e 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 @@ -581,16 +602,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(); @@ -603,8 +624,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 4fed58ca324..b927baf67b7 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 e80316df8e7..59de1441c9d 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(), 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 a3bb8a6885a..412fe5b0a0c 100644 --- a/rs/moq-stats/src/aggregate.rs +++ b/rs/moq-stats/src/aggregate.rs @@ -1113,7 +1113,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, @@ -1889,7 +1889,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 d98dd4fce38..9f115d4aa49 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(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,36 @@ 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; From 86111bdf8f60ae4a5f57abe2eb0f8c5831fcf6bb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 22:15:39 -0700 Subject: [PATCH 04/17] feat(ffi)!: replace delta_ratio with deltas and drive json snapshot refresh Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/api.rs | 12 +++---- rs/moq-c/src/publish.rs | 80 ++++++++++++++++++++++++++++++++--------- rs/moq-c/src/test.rs | 6 ++-- rs/moq-ffi/src/json.rs | 69 ++++++++++++++++++++++++++++------- rs/moq-ffi/src/test.rs | 65 ++++++++++++++++++++++++++++++--- 5 files changed, 189 insertions(+), 43 deletions(-) diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index dcf61f57367..6a14b20769c 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -412,14 +412,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, @@ -3136,7 +3136,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 4b66375bbc0..cdae7de0161 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -65,6 +65,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, @@ -92,7 +100,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>>, @@ -812,17 +820,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, @@ -835,24 +845,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(()) } @@ -861,7 +909,7 @@ 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) } @@ -884,7 +932,7 @@ 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) } @@ -907,7 +955,7 @@ 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 3364763c905..ec26254acbc 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -1818,7 +1818,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 { @@ -5424,7 +5424,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, }, ) @@ -5569,7 +5569,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-ffi/src/json.rs b/rs/moq-ffi/src/json.rs index 429c7963361..b6fd7b34416 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 58ea35e056d..3eaff038cf8 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -977,7 +977,7 @@ async fn data_writes_preserve_optional_timestamps() { &broadcast, &track, MoqJsonSnapshotConfig { - delta_ratio: 0, + deltas: false, compression: false, }, ) @@ -1098,7 +1098,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 track = broadcast.publish_track("meta".into(), None).unwrap(); @@ -1139,12 +1139,67 @@ async fn json_snapshot_roundtrip() { )); } +/// 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, + }), + ) + .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 joiner still reads the open group, which carries the snapshot and every delta. + let joiner = subscribe(&broadcast, "meta").await; + let first = tokio::time::timeout(TIMEOUT, joiner.recv_group()) + .await + .expect("timed out waiting for the open group") + .unwrap() + .expect("expected a group"); + assert_eq!(first.sequence(), 0); + + // Its join crossed the ratio, so the producer restates the value without another update. + let refreshed = tokio::time::timeout(TIMEOUT, joiner.recv_group()) + .await + .expect("timed out waiting for the refresh") + .unwrap() + .expect("expected a refreshed group"); + 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).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 }; @@ -6432,7 +6487,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, }, ) @@ -6517,7 +6572,7 @@ async fn data_track_names_cannot_collide() { &broadcast, &broadcast.publish_track("state".into(), None).unwrap(), MoqJsonSnapshotConfig { - delta_ratio: 0, + deltas: false, compression: false, }, ) From aafc85e85231599d017448607afc1fe0df70411c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 22:22:38 -0700 Subject: [PATCH 05/17] feat(json)!: replace deltaRatio/opRatio with deltas/ops and refresh on joiner demand in JS Co-Authored-By: Claude Opus 5.5 --- js/hang/src/catalog/consumer.test.ts | 10 +- js/json/README.md | 2 +- js/json/bench/codec.ts | 2 +- js/json/src/snapshot/codec.test.ts | 88 +++++++++--- js/json/src/snapshot/compression.test.ts | 33 ++--- js/json/src/snapshot/encoder.ts | 74 +++++------ js/json/src/snapshot/index.ts | 5 +- js/json/src/snapshot/producer.ts | 37 +++++- js/json/src/snapshot/properties.test.ts | 31 +++-- js/json/src/snapshot/snapshot.test.ts | 162 +++++++++++++++-------- js/json/src/types.test.ts | 16 +-- js/json/src/window/encoder.ts | 66 +++++---- js/json/src/window/index.ts | 9 +- js/json/src/window/producer.ts | 36 ++++- js/json/src/window/properties.test.ts | 13 +- js/json/src/window/vectors.test.ts | 6 +- js/json/src/window/window.test.ts | 115 ++++++++++++++-- js/publish/src/catalog.ts | 2 +- js/room/src/chat.ts | 2 +- js/watch/src/broadcast.test.ts | 2 +- 20 files changed, 485 insertions(+), 226 deletions(-) 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/README.md b/js/json/README.md index 173950b2dfc..86c0d06fe21 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 last update's timestamp. 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 1abc04c5a9a..8a2c388ea63 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..b6662ea2338 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,7 +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" }, [ + const frames = encode({ deltas: true, compression: "deflate" }, [ { note: phrase }, { note: phrase, echo: phrase }, ]); @@ -194,7 +240,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 +266,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 +286,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,7 +302,7 @@ 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(); @@ -266,7 +312,7 @@ test("a resync keeps the value for mutate", () => { // 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 +335,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 +347,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 +360,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 f42ec058142..893579a097c 100644 --- a/js/json/src/snapshot/encoder.ts +++ b/js/json/src/snapshot/encoder.ts @@ -9,30 +9,20 @@ 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; - // Bytes a group may hold before it rolls when {@link Config.maxGroupBytes} is left unset: moq-net's // per-group cache limit. Not re-exported from the package entrypoint; a test pins it to that limit. export const DEFAULT_MAX_GROUP_BYTES = Group.MAX_GROUP_CACHE_BYTES; /** 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; @@ -68,8 +58,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; } @@ -124,12 +114,9 @@ export class Encoder { // baseline every delta is diffed against, and `undefined` until the first snapshot. #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; @@ -178,8 +165,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; @@ -232,9 +218,9 @@ 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) { + if (this.#groupBytes + payload.length <= this.#maxGroupBytes) { this.#last = json; - this.#deltaBytes += payload.length; + this.#groupBytes += payload.length; this.#groupFrames += 1; return this.#pend({ payload, keyframe: false }); } @@ -245,6 +231,20 @@ export class Encoder { return this.#pend({ payload, keyframe: true }); } + /** + * Restate the last encoded 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 }); + } + // Hand a frame to the caller, marking it unacknowledged until they commit. #pend(encoded: Encoded): Pending { this.#pending = true; @@ -261,29 +261,16 @@ export class Encoder { }; } - // 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; @@ -312,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..2ecd5e93903 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 timestamp of the last update. Set the ratio when creating the + * track, or joins never ask. */ export class Producer { #track: Moq.Track.Producer; @@ -21,11 +26,35 @@ 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 timestamp of the last committed update, which a refresh restates the value at. + #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. It leaves the frame + // uncommitted, so the next update resynchronizes and reports the error itself. + try { + this.#write(frame, this.#at); + frame.commit(); + } catch {} } /** @@ -65,6 +94,7 @@ export class Producer { // snapshot. A delta against a snapshot no consumer ever saw would be unreadable. this.#write(frame, at); frame.commit(); + this.#at = at; } #write(encoded: Encoded, at: Time.Timestamp | undefined): void { @@ -81,6 +111,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) { @@ -146,6 +177,8 @@ export class Producer { /** Finish the track, closing any open group. */ finish(): void { + this.#unwatch?.(); + this.#unwatch = undefined; this.#group?.close(); this.#group = undefined; diff --git a/js/json/src/snapshot/properties.test.ts b/js/json/src/snapshot/properties.test.ts index e777b0179e0..7984948ff79 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 }; }); }); @@ -56,15 +58,26 @@ test("snapshot codec property reconstructs each JSON value", () => { const numRuns = setting("MOQ_JSON_CASES", 256, 1); fc.assert( fc.property( - fc.constantFrom(0, 1, 2, 8, 100), + fc.boolean(), fc.boolean(), fc.oneof(roots, edits), - (deltaRatio, deflate, steps) => { - const config = { deltaRatio, compression: deflate ? ("deflate" as const) : ("none" as const) }; + (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 } of steps) { + 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) { + expect(frame.keyframe).toBe(true); + decoder.snapshot(frame.payload); + frame.commit(); + expect(decoder.decode()).toEqual(before); + } + } const frame = encoder.update(value); if (frame) { if (frame.keyframe) decoder.snapshot(frame.payload); diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 2b513b922d8..457a57eb898 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 } }); @@ -276,7 +265,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 +280,103 @@ 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) => setTimeout(resolve, 0)); +} + +// 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(); - expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([3, 1]); + // 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("deltas stay within ratio times snapshot", async () => { +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 last 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 last update's timestamp, not a new one. + expect(timestamps).toEqual([0, 30]); +}); + +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([10, 1]); + 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([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 +387,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 +403,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 +418,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. @@ -456,7 +510,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; @@ -470,7 +524,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(); @@ -482,7 +536,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(); @@ -496,7 +550,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..a4d13390797 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 timestamp of the last edit. Set the ratio when creating the track, or joins + * never ask. + * * @public */ export class Producer { @@ -23,10 +28,33 @@ 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 timestamp of the last committed edit, which a refresh restates the window at. + #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. It leaves the frame + // uncommitted, so the next edit opens a new group and reports the error itself. + try { + this.#write(this.#encoder.snapshot(), this.#at); + } catch {} } /** The retained checkpoint suffix, oldest first. This is complete unless bounded in the config. */ @@ -48,6 +76,7 @@ export class Producer { push({ value, at }: Timed): void { this.#assertOpen(); this.#write(this.#encoder.push(value), at); + this.#at = at; } /** @@ -62,7 +91,9 @@ 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.#at = at; } #assertOpen(): void { @@ -79,6 +110,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) { @@ -120,6 +152,8 @@ export class Producer { finish(): void { if (this.#finished) return; this.#finished = true; + this.#unwatch?.(); + this.#unwatch = undefined; this.#group?.close(); this.#group = undefined; 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 bd0c3da9a0f..40729517ec5 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, 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,108 @@ 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) => setTimeout(resolve, 0)); +} + +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 last 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 last edit's timestamp, and carries the window as it stands. + expect(await groups(track)).toEqual([ + [3, 10], + [1, 30], + ]); + const consumer = new Consumer({ track: track.subscribe() }); + expect(await consumer.next()).toEqual({ push: { index: 1, value: { n: 1 } } }); +}); + +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 +335,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 +375,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 +398,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 +473,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/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 d322d4905b8..019cd21998f 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 bef9431ea36..1d7cb54c969 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); From f2c7219f8d37c8956fdb03041b2a8a9a0d635b6b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 22:31:08 -0700 Subject: [PATCH 06/17] feat(bindings)!: replace delta_ratio with deltas across bindings, docs, and migrations Co-Authored-By: Claude Opus 5.5 --- dart/moq/MIGRATE.md | 6 ++ dart/moq_ffi/lib/src/moq.dart | 20 ++-- doc/lib/js/json.md | 4 +- doc/lib/rs/moq-json.md | 4 +- go/wrapper/MIGRATE.md | 6 ++ go/wrapper/json/json.go | 28 +++--- js/json/MIGRATE.md | 8 ++ kt/moq/MIGRATE.md | 6 ++ .../kotlin/dev/moq/SmokeTest.kt | 10 +- py/moq-rs/MIGRATE.md | 6 ++ py/moq-rs/moq/json.py | 20 ++-- quest/m1/refresh/README.md | 1 - quest/m1/refresh/json.md | 94 ------------------- rs/moq-c/MIGRATE.md | 6 ++ rs/moq-ffi/MIGRATE.md | 6 ++ rs/moq-json/MIGRATE.md | 8 ++ rs/moq-mux/MIGRATE.md | 6 ++ swift/MIGRATE.md | 6 ++ swift/Sources/Moq/Json.swift | 13 +-- 19 files changed, 110 insertions(+), 148 deletions(-) delete mode 100644 quest/m1/refresh/json.md diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index ed1ab20569c..7dfc4f39cc0 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. + ### Track demand reports the wanted group (#5930) `TrackDemand.isUsed()`, `used()`, and `unused()` are gone. diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 2947697cf54..33beccc8fc3 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -861,9 +861,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 { @@ -873,25 +873,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); @@ -901,8 +901,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( @@ -913,7 +913,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 2338572eae0..3b59257e6b6 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 fb4aaa95358..a986368082f 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. + ### Track demand reports the wanted group (#5930) `TrackDemand.IsUsed`, `Used`, and `Unused` are gone. diff --git a/go/wrapper/json/json.go b/go/wrapper/json/json.go index 71833c6b86e..24ed0acd22c 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 @@ -160,7 +156,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/json/MIGRATE.md b/js/json/MIGRATE.md index fb5fcf6ef66..d458e0b9623 100644 --- a/js/json/MIGRATE.md +++ b/js/json/MIGRATE.md @@ -4,6 +4,14 @@ 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. + ### 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/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index ca9296bd2cd..d0d6f9b33e0 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. + ### Track demand reports the wanted group (#5930) `TrackDemand.isUsed()`, `used()`, and `unused()` are gone. diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 4477fd607b8..ddd86bbea9c 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -175,7 +175,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( @@ -195,7 +195,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) @@ -409,7 +409,7 @@ class SmokeTest { @Test fun `typed json snapshot round-trips a serializable value`() = 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(Status(state = "live")) @@ -421,7 +421,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()) @@ -442,7 +442,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 733e35e2118..3373ca0512e 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. + ### Track demand reports the wanted group (#5930) `TrackDemand.is_used()`, `used()`, and `unused()` are gone. diff --git a/py/moq-rs/moq/json.py b/py/moq-rs/moq/json.py index a82414a1863..c10a0cfb648 100644 --- a/py/moq-rs/moq/json.py +++ b/py/moq-rs/moq/json.py @@ -32,10 +32,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__( @@ -43,15 +44,10 @@ def __init__( broadcast: BroadcastProducer, track: 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: @@ -101,7 +97,7 @@ class SnapshotConsumer: """ def __init__(self, track: 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/refresh/README.md b/quest/m1/refresh/README.md index 708e994f19d..4ee9b545f0e 100644 --- a/quest/m1/refresh/README.md +++ b/quest/m1/refresh/README.md @@ -63,7 +63,6 @@ Work owned by this README, after the children land: ## Required - [Lite wire](/quest/m1/refresh/lite.md) - lite-07 TRACK_INFO advertises the ratio and SUBSCRIBE_UPDATE carries the wanted group, so a join at any relay reaches the origin -- [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 - [Video](/quest/m1/refresh/video.md) - video publishers advertise refresh and force a keyframe on demand, keeping the encoder's max GOP ## Related diff --git a/quest/m1/refresh/json.md b/quest/m1/refresh/json.md deleted file mode 100644 index afd9086fc12..00000000000 --- a/quest/m1/refresh/json.md +++ /dev/null @@ -1,94 +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. - -## Related - -- [JSON window timestamps](/quest/m1/json-window-timestamps.md) - touches the same window code -- [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - touches the same snapshot consumers and bindings diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index 3f6ece96e60..0b215424e09 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. + ### Demand reports the wanted group (#5930) `moq_track_info` gains `refresh` and `refresh_present`, which changes its ABI; a zeroed field leaves refresh off. diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 2d09c4a2fe3..ebca901b882 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. + ### Track demand reports the wanted group (#5930) `MoqTrackDemand::is_used`, `used`, and `unused` are gone. diff --git a/rs/moq-json/MIGRATE.md b/rs/moq-json/MIGRATE.md index 132a07630d0..1e2e22bf17c 100644 --- a/rs/moq-json/MIGRATE.md +++ b/rs/moq-json/MIGRATE.md @@ -4,6 +4,14 @@ 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. + ### Duplicate keys are refused Every decoder refuses a frame in which a JSON object repeats a key with `Error::DuplicateKey`, where stream and window decoders used to keep the last copy and snapshots returned `Error::Json`. diff --git a/rs/moq-mux/MIGRATE.md b/rs/moq-mux/MIGRATE.md index 928d95f1ff4..7a988d9471a 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. + ### TS sections use PCR placement A `verbatim` section frame's timestamp is the program clock at its first section byte, derived from the PCR, rather than the latest video PTS. diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index f4ee0968d8c..8e9bc3953e6 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. + ### Track demand reports the wanted group (#5930) `TrackDemand.isUsed`, `used()`, and `unused()` are gone. diff --git a/swift/Sources/Moq/Json.swift b/swift/Sources/Moq/Json.swift index e1f36f3acf0..708a374de76 100644 --- a/swift/Sources/Moq/Json.swift +++ b/swift/Sources/Moq/Json.swift @@ -22,19 +22,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) ) } @@ -67,7 +68,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)) } From 2dca98a822eb964d2f005afe165a1f124d793528 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 22:36:06 -0700 Subject: [PATCH 07/17] style: format refresh changes and fix the merged chat caller Co-Authored-By: Claude Opus 5.5 --- js/json/src/snapshot/codec.test.ts | 5 +-- js/json/src/snapshot/properties.test.ts | 51 +++++++++++-------------- js/json/src/snapshot/snapshot.test.ts | 5 ++- rs/moq-c/src/publish.rs | 12 ++++-- rs/moq-hls/src/export/archive_tests.rs | 4 +- rs/moq-json/src/snapshot/encoder.rs | 11 +----- rs/moq-json/src/window/properties.rs | 11 ++---- rs/moq-room/src/chat.rs | 2 +- rs/moq-stats/src/produce.rs | 5 ++- 9 files changed, 49 insertions(+), 57 deletions(-) diff --git a/js/json/src/snapshot/codec.test.ts b/js/json/src/snapshot/codec.test.ts index b6662ea2338..25563559e96 100644 --- a/js/json/src/snapshot/codec.test.ts +++ b/js/json/src/snapshot/codec.test.ts @@ -224,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({ deltas: true, 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; diff --git a/js/json/src/snapshot/properties.test.ts b/js/json/src/snapshot/properties.test.ts index 7984948ff79..08658d05866 100644 --- a/js/json/src/snapshot/properties.test.ts +++ b/js/json/src/snapshot/properties.test.ts @@ -57,38 +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.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) { - expect(frame.keyframe).toBe(true); - decoder.snapshot(frame.payload); - frame.commit(); - expect(decoder.decode()).toEqual(before); - } - } - 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 457a57eb898..e5db09f367a 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -371,7 +371,10 @@ test("a compressed refresh opens a fresh window", async () => { 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 }]); + expect(values).toEqual([ + { a: 1, b: 2 }, + { a: 1, b: 3 }, + ]); }); test("array change is a wholesale delta", async () => { diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index cdae7de0161..4449b6b1bc5 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -909,7 +909,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, None, |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) } @@ -932,7 +934,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, None, |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) } @@ -955,7 +959,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, None, |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-hls/src/export/archive_tests.rs b/rs/moq-hls/src/export/archive_tests.rs index 005330953f1..c79475b3406 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_ops(false); + let config = window::ProducerConfig::default().with_compression(true).with_ops(false); let encoder = Encoder { encoder: window::Encoder::new(config), group: 0, diff --git a/rs/moq-json/src/snapshot/encoder.rs b/rs/moq-json/src/snapshot/encoder.rs index fb6906b2700..f5198d50ffc 100644 --- a/rs/moq-json/src/snapshot/encoder.rs +++ b/rs/moq-json/src/snapshot/encoder.rs @@ -572,11 +572,7 @@ mod test { failure_persistence: None, ..Default::default() }); - let sequence = ( - any::(), - any::(), - property_sequence(), - ); + let sequence = (any::(), any::(), property_sequence()); runner .run(&sequence, |(deltas, deflate, steps)| { let compression = if deflate { @@ -584,10 +580,7 @@ mod test { } else { Compression::None }; - let mut encoder = Encoder::::new(Config { - deltas, - compression, - }); + let mut encoder = Encoder::::new(Config { deltas, compression }); let mut decoder = super::super::Decoder::::new(super::super::consumer::Config { compression, ..Default::default() diff --git a/rs/moq-json/src/window/properties.rs b/rs/moq-json/src/window/properties.rs index e103e24388d..742656ca944 100644 --- a/rs/moq-json/src/window/properties.rs +++ b/rs/moq-json/src/window/properties.rs @@ -259,16 +259,13 @@ fn window_codec_property_matches_every_readers_logical_window() { 1..65, ); let sequence = ( - ( - any::(), - any::(), - proptest::option::of(1usize..=8), - ) - .prop_map(|(ops, compression, checkpoint_records)| ProducerConfig { + (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-room/src/chat.rs b/rs/moq-room/src/chat.rs index acf63f55b7b..b5de5b28d54 100644 --- a/rs/moq-room/src/chat.rs +++ b/rs/moq-room/src/chat.rs @@ -277,7 +277,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/src/produce.rs b/rs/moq-stats/src/produce.rs index 9f115d4aa49..e193fd96395 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -1629,7 +1629,10 @@ mod tests { 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!( + 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"); From db915ceeb5b4ef301b84f00ad3388bbe3b5b45bf Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 22:42:23 -0700 Subject: [PATCH 08/17] test(ffi): accept a joiner that skips straight to the refreshed group Co-Authored-By: Claude Opus 5.5 --- rs/moq-ffi/src/test.rs | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 3eaff038cf8..9d336197652 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1164,21 +1164,19 @@ async fn json_snapshot_refreshes_for_a_joiner() { producer.update(format!(r#"{{"n":{n}}}"#), None).unwrap(); } - // The joiner still reads the open group, which carries the snapshot and every delta. + // 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 first = tokio::time::timeout(TIMEOUT, joiner.recv_group()) - .await - .expect("timed out waiting for the open group") - .unwrap() - .expect("expected a group"); - assert_eq!(first.sequence(), 0); - - // Its join crossed the ratio, so the producer restates the value without another update. - let refreshed = tokio::time::timeout(TIMEOUT, joiner.recv_group()) - .await - .expect("timed out waiting for the refresh") - .unwrap() - .expect("expected a refreshed group"); + 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()) From 1c8adf3d8d1c1dda6a846f5aa18ee033b3175113 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 01:12:12 -0700 Subject: [PATCH 09/17] test(json): cross real group boundaries in the compressed roundtrip Without the ratio rollover, 41 updates never left the first group. Run past MAX_DELTA_FRAMES plus a restatement, assert three keyframes, and decode each group with a cold joiner so an encoder that keeps its DEFLATE window across a boundary fails. Co-Authored-By: Claude Opus 5.5 --- rs/moq-json/src/snapshot/decoder.rs | 42 ++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 6 deletions(-) diff --git a/rs/moq-json/src/snapshot/decoder.rs b/rs/moq-json/src/snapshot/decoder.rs index 596881501ad..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_deltas(true); - 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] From 4dc084c05bf07605461e6c8c7a110d63a7345a15 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 10:26:52 -0700 Subject: [PATCH 10/17] fix(json): restate at the newest timestamp written An update or edit may carry a timestamp older than its group's first frame, but a new group may not start before that frame. A refresh restated at the last update's timestamp, so it could rewind and be refused with TimestampMismatch, and JS swallowed the error after publishing an empty newest group. Refreshes now restate at the newest timestamp written, in Rust and JS, and a failed JS refresh aborts the track instead of stranding latest-value subscribers. @moq/net's Timestamp gains isBefore, the exact cross-scale ordering the track already used for group starts. Co-Authored-By: Claude Opus 5.5 --- js/json/src/snapshot/producer.ts | 23 +++++++++++++------- js/json/src/snapshot/snapshot.test.ts | 30 +++++++++++++++++++++++++-- js/json/src/window/producer.ts | 30 +++++++++++++++++++-------- js/json/src/window/window.test.ts | 23 ++++++++++++++++++-- js/net/src/time.test.ts | 12 +++++++++++ js/net/src/time.ts | 21 +++++++++++++++++++ js/net/src/track.ts | 27 +++--------------------- rs/moq-json/src/snapshot/mod.rs | 27 +++++++++++++++++++++--- rs/moq-json/src/snapshot/producer.rs | 7 ++++--- rs/moq-json/src/window/mod.rs | 29 ++++++++++++++++++++++++-- rs/moq-json/src/window/producer.rs | 9 ++++---- 11 files changed, 181 insertions(+), 57 deletions(-) diff --git a/js/json/src/snapshot/producer.ts b/js/json/src/snapshot/producer.ts index 2ecd5e93903..a0108f3a18d 100644 --- a/js/json/src/snapshot/producer.ts +++ b/js/json/src/snapshot/producer.ts @@ -12,7 +12,7 @@ import { type Config as CodecConfig, type Encoded, Encoder } from "./encoder.ts" * * 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 timestamp of the last update. Set the ratio when creating the + * restates the value there at the newest timestamp written. Set the ratio when creating the * track, or joins never ask. */ export class Producer { @@ -28,7 +28,8 @@ export class Producer { // The sequence of the newest group written, which a joiner's wanted group has to pass. #largest?: number; - // The timestamp of the last committed update, which a refresh restates the value at. + // 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; @@ -49,12 +50,14 @@ export class Producer { const frame = this.#encoder.snapshot(); if (!frame) return; - // Nobody awaits a refresh, so a failed write has no caller to report to. It leaves the frame - // uncommitted, so the next update resynchronizes and reports the error itself. + // 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 {} + } catch (err) { + this.#close(err instanceof Error ? err : new Error(String(err))); + } } /** @@ -94,7 +97,7 @@ export class Producer { // snapshot. A delta against a snapshot no consumer ever saw would be unreadable. this.#write(frame, at); frame.commit(); - this.#at = at; + if (at && !at.isBefore(this.#at ?? at)) this.#at = at; } #write(encoded: Encoded, at: Time.Timestamp | undefined): void { @@ -177,16 +180,20 @@ export class Producer { /** Finish the track, closing any open group. */ finish(): void { + this.#close(); + } + + #close(abort?: Error): void { this.#unwatch?.(); this.#unwatch = undefined; - this.#group?.close(); + 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/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index e5db09f367a..9f9c0eb642a 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -320,7 +320,7 @@ test("a joiner over the ratio gets a fresh snapshot", async () => { } }); -test("a refresh reuses the last timestamp", async () => { +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) }); @@ -337,10 +337,36 @@ test("a refresh reuses the last timestamp", async () => { timestamps.push(frame?.timestamp?.asMillis()); while ((await group.readFrame()) !== undefined) {} } - // The restated group opens at the last update's timestamp, not a new one. + // 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 }], + ]); +}); + test("no ratio never refreshes", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); diff --git a/js/json/src/window/producer.ts b/js/json/src/window/producer.ts index a4d13390797..fdecbd3e6bd 100644 --- a/js/json/src/window/producer.ts +++ b/js/json/src/window/producer.ts @@ -15,7 +15,7 @@ export type ProducerConfig = Config & { track: Moq.Track.Producer }; * * 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 timestamp of the last edit. Set the ratio when creating the track, or joins + * window there at the newest timestamp written. Set the ratio when creating the track, or joins * never ask. * * @public @@ -30,7 +30,8 @@ export class Producer { // The sequence of the newest group written, which a joiner's wanted group has to pass. #largest?: number; - // The timestamp of the last committed edit, which a refresh restates the window at. + // 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; @@ -50,11 +51,13 @@ export class Producer { #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. It leaves the frame - // uncommitted, so the next edit opens a new group and reports the error itself. + // 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 {} + } 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. */ @@ -76,7 +79,7 @@ export class Producer { push({ value, at }: Timed): void { this.#assertOpen(); this.#write(this.#encoder.push(value), at); - this.#at = at; + this.#advance(at); } /** @@ -93,7 +96,12 @@ export class Producer { const frame = this.#encoder.pop(count); if (!frame) return; this.#write(frame, at); - this.#at = 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 { @@ -150,14 +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/window.test.ts b/js/json/src/window/window.test.ts index 40729517ec5..8b72b928fdd 100644 --- a/js/json/src/window/window.test.ts +++ b/js/json/src/window/window.test.ts @@ -249,7 +249,7 @@ test("a joiner over the ratio gets a fresh header", async () => { } }); -test("a window refresh reuses the last timestamp", async () => { +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) }); @@ -261,7 +261,7 @@ test("a window refresh reuses the last timestamp", async () => { producer.finish(); joiner.close(); - // The restated header opens at the last edit's timestamp, and carries the window as it stands. + // 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], @@ -270,6 +270,25 @@ test("a window refresh reuses the last timestamp", async () => { expect(await consumer.next()).toEqual({ push: { index: 1, value: { n: 1 } } }); }); +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 }); 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 47b3eef98bc..6f74dfd0da0 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -531,27 +531,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; @@ -1036,11 +1015,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/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index c45495bba06..b4fa4ce92f2 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -568,10 +568,9 @@ mod test { assert_eq!(frames(&mut fresh), vec![(None, json!({ "n": 3 }))]); } - /// A refresh restates the value at the last committed update's timestamp, the value's own time, - /// rather than inventing one. + /// A refresh restates the value at the newest timestamp written rather than inventing one. #[test] - fn a_refresh_reuses_the_last_timestamp() { + 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 @@ -593,6 +592,28 @@ mod test { 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 }))]); + } + /// Without a ratio on the track, no join asks for a group, however large the deltas grow. #[test] fn no_ratio_never_refreshes() { diff --git a/rs/moq-json/src/snapshot/producer.rs b/rs/moq-json/src/snapshot/producer.rs index baae1b6efb2..46d5a5c8557 100644 --- a/rs/moq-json/src/snapshot/producer.rs +++ b/rs/moq-json/src/snapshot/producer.rs @@ -89,7 +89,7 @@ impl Producer { /// 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 timestamp of the last update, the value's own time. + /// 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 @@ -300,7 +300,8 @@ struct Inner { /// Watches for a joiner wanting a group past the largest written. refresh: Refresh, - /// The timestamp of the last committed update, which a refresh restates the value at. + /// 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 @@ -377,7 +378,7 @@ impl Inner { track.write(timestamp, &frame)?; let size = frame.payload.len(); frame.commit(); - self.at = timestamp; + self.at = self.at.max(timestamp); Ok(Some(size)) } diff --git a/rs/moq-json/src/window/mod.rs b/rs/moq-json/src/window/mod.rs index 46674d65f6c..0edcb0263a4 100644 --- a/rs/moq-json/src/window/mod.rs +++ b/rs/moq-json/src/window/mod.rs @@ -647,9 +647,9 @@ mod test { ); } - /// A refresh restates the window at the last committed edit's timestamp. + /// A refresh restates the window at the newest timestamp written. #[test] - fn a_refresh_reuses_the_last_timestamp() { + 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)); @@ -672,6 +672,31 @@ mod test { 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() { diff --git a/rs/moq-json/src/window/producer.rs b/rs/moq-json/src/window/producer.rs index 6bb171f0e32..00c51ef2e67 100644 --- a/rs/moq-json/src/window/producer.rs +++ b/rs/moq-json/src/window/producer.rs @@ -96,7 +96,7 @@ impl Producer { /// 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 timestamp of the last edit. Nothing happens before + /// 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 @@ -150,7 +150,8 @@ struct Inner { /// Watches for a joiner wanting a group past the largest written. refresh: Refresh, - /// The timestamp of the last committed edit, which a refresh restates the window at. + /// 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, @@ -169,7 +170,7 @@ impl Inner { // new group because the attempted frame advanced the group-local compression state. track.write(count.at, &frame)?; frame.commit(); - self.at = count.at; + self.at = self.at.max(count.at); Ok(()) } @@ -221,7 +222,7 @@ impl Inner { let frame = encoder.push(value.value)?; track.write(value.at, &frame)?; frame.commit(); - self.at = value.at; + self.at = self.at.max(value.at); Ok(()) } From cf882065227df1453406ecc32cc38fb640e84832 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 11:05:44 -0700 Subject: [PATCH 11/17] test(json): build the timestamp test's config in one expression The merged #5677 test assigned compression after Config::default(), which clippy denies once the ratio argument is gone. Co-Authored-By: Claude Opus 5.5 --- rs/moq-json/src/snapshot/consumer.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/rs/moq-json/src/snapshot/consumer.rs b/rs/moq-json/src/snapshot/consumer.rs index 7f1a0d2df36..040f428d095 100644 --- a/rs/moq-json/src/snapshot/consumer.rs +++ b/rs/moq-json/src/snapshot/consumer.rs @@ -175,8 +175,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(); - 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, From 19b1d15658514d82499e0ff033cb62904e94ec40 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 20:13:27 -0700 Subject: [PATCH 12/17] fix(cli): roll report groups on joiner demand The media reports from #5848 landed on main with the old `delta_ratio` config. Port them like moq-stats: the plain track sets `deltas: false`, the compressed track advertises a refresh ratio of 8, and each write answers a joiner past it with a fresh snapshot group. Co-Authored-By: Claude Opus 5.5 --- rs/moq-cli/src/report.rs | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/rs/moq-cli/src/report.rs b/rs/moq-cli/src/report.rs index 9c6a350b4f5..711547fc6a2 100644 --- a/rs/moq-cli/src/report.rs +++ b/rs/moq-cli/src/report.rs @@ -50,13 +50,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)), }) @@ -75,12 +77,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())); @@ -580,6 +589,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() { From 1c435079c524cf79da34f98af1eb8a84480e51eb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 20:38:50 -0700 Subject: [PATCH 13/17] test(json): flush the demand signal with a microtask, not a timer The refresh tests only wait for the signal's queued microtask, so wait for exactly that instead of a setTimeout tick, matching js/signals' own tests. Co-Authored-By: Claude Opus 5.5 --- js/json/src/snapshot/snapshot.test.ts | 2 +- js/json/src/window/window.test.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 9f9c0eb642a..060c35ca111 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -282,7 +282,7 @@ test("mutate removes a section", async () => { // Let the producer see a demand change, which the signal delivers in a microtask. async function settle(): Promise { - await new Promise((resolve) => setTimeout(resolve, 0)); + await new Promise((resolve) => queueMicrotask(resolve)); } // Publish `{"n":0}` through `{"n":3}`: a 7-byte snapshot and 21 bytes of deltas. diff --git a/js/json/src/window/window.test.ts b/js/json/src/window/window.test.ts index 8b72b928fdd..9a230470eb0 100644 --- a/js/json/src/window/window.test.ts +++ b/js/json/src/window/window.test.ts @@ -226,7 +226,7 @@ async function groups(track: Track.Producer): Promise<[number, number | undefine // Let the producer see a demand change, which the signal delivers in a microtask. async function settle(): Promise { - await new Promise((resolve) => setTimeout(resolve, 0)); + await new Promise((resolve) => queueMicrotask(resolve)); } test("a joiner over the ratio gets a fresh header", async () => { From 211d627c1b1d0fd41c3d34eb102663ad1ac0c92b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 22:53:42 -0700 Subject: [PATCH 14/17] test(ffi): set compress on the refresh test's track info `MoqTrackInfo` gained `compress` in #5928. Co-Authored-By: Claude Opus 5.5 --- rs/moq-ffi/src/test.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 0c4e4ba290f..66e4194f88e 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1187,6 +1187,7 @@ async fn json_snapshot_refreshes_for_a_joiner() { max_age_us: None, refresh: Some(1), timescale: None, + compress: false, }), ) .unwrap(); From c3c9cd3ae98aad0f571092e6c729f5def7cf7277 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 18:20:13 -0700 Subject: [PATCH 15/17] docs(json): a refresh restates at the newest timestamp written Co-Authored-By: Claude Opus 5.5 --- js/json/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/js/json/README.md b/js/json/README.md index 86c0d06fe21..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(); ``` -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 last update's timestamp. 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. +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 From 5465196dfa6459048727db0350338e2dc8745f44 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 02:50:44 -0700 Subject: [PATCH 16/17] fix(json): stage the snapshot baseline until the frame commits A rejected update left its value as the encoder baseline, so a joiner's refresh restated a value that never reached the wire: an oversized one failed again (aborting the JS track, ending Rust refresh loops), and an untimed one on a timed track got published anyway. The next mutate or modify also carried the rejected edit into every later owner's publish. The snapshot encoder now stages each frame's value and applies it on commit, as the window encoder already does, so value() and snapshot() always reflect the last value that reached the wire. Co-Authored-By: Claude Opus 5.5 --- js/json/MIGRATE.md | 2 + js/json/src/snapshot/codec.test.ts | 12 +++ js/json/src/snapshot/encoder.ts | 60 ++++++------ js/json/src/snapshot/producer.ts | 12 +-- js/json/src/snapshot/snapshot.test.ts | 53 ++++++++++ rs/moq-json/MIGRATE.md | 2 + rs/moq-json/src/snapshot/encoder.rs | 135 ++++++++++++++++---------- rs/moq-json/src/snapshot/mod.rs | 77 +++++++++------ rs/moq-json/src/snapshot/producer.rs | 11 +-- 9 files changed, 247 insertions(+), 117 deletions(-) diff --git a/js/json/MIGRATE.md b/js/json/MIGRATE.md index d458e0b9623..87f7a7be48c 100644 --- a/js/json/MIGRATE.md +++ b/js/json/MIGRATE.md @@ -12,6 +12,8 @@ A group no longer rolls on a byte budget: create the track with a `refresh` rati 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/src/snapshot/codec.test.ts b/js/json/src/snapshot/codec.test.ts index 25563559e96..805307e48b3 100644 --- a/js/json/src/snapshot/codec.test.ts +++ b/js/json/src/snapshot/codec.test.ts @@ -306,6 +306,18 @@ test("a resync keeps the value for mutate", () => { 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", () => { diff --git a/js/json/src/snapshot/encoder.ts b/js/json/src/snapshot/encoder.ts index 9739c69d859..f62688666c4 100644 --- a/js/json/src/snapshot/encoder.ts +++ b/js/json/src/snapshot/encoder.ts @@ -63,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. @@ -106,8 +108,8 @@ 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 emitted into the current group, snapshot included: compressed frame sizes when @@ -140,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 { @@ -170,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; @@ -199,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); @@ -215,20 +218,18 @@ export class Encoder { // Compressing first advances the window, but `#snapshot` opens a fresh one, so an // over-budget delta costs only the wasted compression. if (this.#groupBytes + payload.length <= this.#maxGroupBytes) { - this.#last = json; 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); } /** - * Restate the last encoded value as a full snapshot, which must open a new group. + * 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 @@ -238,11 +239,12 @@ export class Encoder { 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 }); + return this.#pend({ payload, keyframe: true }, this.#last); } - // Hand a frame to the caller, marking it unacknowledged until they commit. - #pend(encoded: Encoded): Pending { + // 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,7 +254,9 @@ 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; }, }; } diff --git a/js/json/src/snapshot/producer.ts b/js/json/src/snapshot/producer.ts index a0108f3a18d..638c40e59ad 100644 --- a/js/json/src/snapshot/producer.ts +++ b/js/json/src/snapshot/producer.ts @@ -94,7 +94,8 @@ 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; @@ -159,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 diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 04cc9fa286d..b6357f525f6 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -256,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(); @@ -367,6 +391,35 @@ test("a refresh after an older update starts at the newest timestamp", async () ]); }); +// 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); + + 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("no ratio never refreshes", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); diff --git a/rs/moq-json/MIGRATE.md b/rs/moq-json/MIGRATE.md index 59e44e94233..b5c9e3693f7 100644 --- a/rs/moq-json/MIGRATE.md +++ b/rs/moq-json/MIGRATE.md @@ -12,6 +12,8 @@ A group no longer rolls on a byte budget: create the track with `Info::refresh` 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 and stream `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/src/snapshot/encoder.rs b/rs/moq-json/src/snapshot/encoder.rs index f5198d50ffc..493e3dc49c2 100644 --- a/rs/moq-json/src/snapshot/encoder.rs +++ b/rs/moq-json/src/snapshot/encoder.rs @@ -119,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); } } @@ -152,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(); } } @@ -192,8 +204,8 @@ impl Drop for Pending<'_, T> { 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 @@ -238,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. @@ -264,7 +277,7 @@ impl Encoder { self.resync = true; } - /// Restate the last encoded value as a full snapshot, which must open a new group. + /// 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 @@ -281,20 +294,34 @@ impl Encoder { Ok(Some(Pending { encoder: self, encoded, - committed: false, + edit: Some(Edit::Restate), })) } - /// Encode an already-serialized value as a full snapshot, opening a new group and reseeding the - /// baseline. - 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()); + /// 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 @@ -319,6 +346,19 @@ impl Encoder { } }; + 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 => { @@ -332,10 +372,7 @@ impl Encoder { self.group_bytes = payload.len() as u64; 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, @@ -347,22 +384,22 @@ impl Encoder { 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. @@ -380,7 +417,7 @@ impl Encoder { if next.as_slice() == bytes.as_ref() { return Ok(None); } - return self.snapshot_encoded(Bytes::from(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. @@ -434,19 +471,13 @@ impl Encoder { 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 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, &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: deltas are on and the group @@ -455,12 +486,12 @@ impl Encoder { 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 encode_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(Bytes::from(snapshot)) + self.snapshot_staged(Bytes::from(snapshot)) } } @@ -639,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")); } @@ -1072,14 +1103,14 @@ mod test { // 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}"); } @@ -1223,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 250f27326aa..00e3b2fa8d0 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -600,6 +600,40 @@ mod test { 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() { @@ -914,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 diff --git a/rs/moq-json/src/snapshot/producer.rs b/rs/moq-json/src/snapshot/producer.rs index 46d5a5c8557..e8a49f56272 100644 --- a/rs/moq-json/src/snapshot/producer.rs +++ b/rs/moq-json/src/snapshot/producer.rs @@ -147,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 @@ -374,6 +372,7 @@ 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(); From f66f48eb7ce34690f45a1cb536724d52308b73f6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 08:56:27 -0700 Subject: [PATCH 17/17] test(json): read the refreshed window event as Timed after the merge #6274 made window consumers return each event's frame timestamp, so the refresh test reads .value and checks the restated header's timestamp. Co-Authored-By: Claude Opus 5.5 --- js/json/src/window/window.test.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/js/json/src/window/window.test.ts b/js/json/src/window/window.test.ts index cfdf1acd1f5..df40978a6da 100644 --- a/js/json/src/window/window.test.ts +++ b/js/json/src/window/window.test.ts @@ -267,7 +267,9 @@ test("a window refresh reuses the newest timestamp", async () => { [1, 30], ]); const consumer = new Consumer({ track: track.subscribe() }); - expect(await consumer.next()).toEqual({ push: { index: 1, value: { n: 1 } } }); + 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 () => {