From 412fdae9ce4d3623bb829f3465454bb02f222425 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 18:39:10 -0700 Subject: [PATCH 1/5] chore(quest): claim quest/m1/refresh/README.md Quest-Claim: cf41f64c56e31f1e From 26aa90e3ee117fe34610dcbedfcd017703bf976d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 19:01:31 -0700 Subject: [PATCH 2/5] test(json): cover refresh through a two-relay cluster Co-Authored-By: GPT-6 --- Cargo.lock | 1 + doc/concept/moq-lite.md | 27 +++++ quest/m1/refresh/README.md | 43 ++++++-- rs/moq-net/Cargo.toml | 1 + rs/moq-net/tests/integration/refresh.rs | 134 +++++++++++++++++++++++- 5 files changed, 195 insertions(+), 11 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index b8cb020c2fd..a4a8f7d55f0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4990,6 +4990,7 @@ dependencies = [ "libc", "loom", "moq-clock", + "moq-json", "moq-pattern 0.1.2", "num_enum", "rand 0.10.3", diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index ee3f10472ee..79361e3472b 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -327,6 +327,33 @@ Put together, a conference might use: Under light congestion video drops the tail of a group; under heavy congestion video stops and audio lags by at most 500 ms. No protocol change, just knobs. +### Refresh + +A publisher can opt a track into refresh by setting its byte ratio. A new +subscriber asks for a fresh group only when the current group's bytes after +its first frame exceed that ratio times the first frame's size. A ratio of 2, +for example, permits two snapshots' worth of deltas before a join asks for a +new snapshot. Equality does not trigger it, and neither elapsed time nor more +deltas trigger it without a join. + +The request does not hold back cached groups: a joiner may receive the old +group before the publisher answers. The ratio is a refresh trigger, not a cap +on the bytes that joiner downloads. + +The publisher drives the track's `Demand::wanted`: when it passes the largest +group written, open a new group with a keyframe or complete snapshot. A Rust +moq-json snapshot producer answers this by driving its `refresh()` alongside +updates. It restates the current value at its newest source timestamp, with a +new group number. Existing readers continue into that group too. + +Each relay judges a join from its own cache and forwards fresh-group demand +upstream when needed, all the way to the publisher. Preserving the ratio across +sessions requires opt-in moq-lite 07 (`moq-lite-07-wip`) at every hop. Older +moq-lite versions do not carry refresh; moq-transport's dynamic-groups feature +carries it with a ratio of zero, so any join after a delta asks for a new group. +Tracks without a ratio, JSON append streams, and importers that cannot force +keyframes do not use this mechanism. + ## Datagrams Since moq-lite 05, a publisher can send a tiny single-frame group as a QUIC diff --git a/quest/m1/refresh/README.md b/quest/m1/refresh/README.md index 3227037a0a9..30959955f18 100644 --- a/quest/m1/refresh/README.md +++ b/quest/m1/refresh/README.md @@ -47,19 +47,44 @@ Decided with the maintainer on 2026-10-16. - **Order.** Relay requests for dynamic groups (#5708) were promoted to the public `Demand::wanted` and `track::Info::refresh` in #5930, and #6030 carries refresh demand through lite relays. The moq-json producers - remain. + now answer that demand. - **m1.** Replacing `Demand` is a breaking API change, and m1 finishes the planned breaking APIs before the cut. -Work owned by this README, after the children land: +The remaining work is the Goal's download-byte bound. Demand propagation and +the JSON answer work, but a join still receives the cached group while its +request travels upstream. With R=1, a 14-byte snapshot and 64 deltas totaling +503 bytes, a late reader across two relays can download all 517 cached bytes +before the JSON owner answers, rather than about 28 bytes. This was reproduced +with simulated time; it is a counterexample, not behavior to preserve. -- An end-to-end test: a moq-json snapshot track published through a - two-relay cluster, where a late joiner at the far relay receives a fresh - snapshot group once the deltas exceed the ratio, and no fresh group while - they don't. Use simulated time and wire it into CI. -- A short "Refresh" section on the `doc/concept` page that covers groups: - what the ratio means, what a publisher does on `wanted`, and how relays - forward it. No new guide. +The normal integration gate now exercises a real moq-json snapshot producer +and consumer through a publisher link, two clustered relays, and a reader +link. It checks ratios 1 and 2 below, exactly at, and above the threshold; +elapsed time without a join; a fresh full snapshot under a new group number +at the newest source timestamp; and subsequent deltas. It tolerates a stale +prefix without requiring one. The concept page documents the current soft +trigger and its byte-bound limitation. + +Before changing serving behavior, settle how a pending refresh ends: + +- **Recommended: preserve the Goal's bound.** Withhold an oversized cached + prefix for that live join, with explicit terminal behavior when the source + finishes, aborts, or cannot produce the requested group. Do not silently + fall back to the oversized prefix. A warm Rust cursor could start beyond + the current group, but that alone does not cover cold caches that learn + the ratio or size late, or a resume front selecting another route copy. +- **Alternative: accept only a soft trigger.** Keep serving cached content + while requesting a fresh group. This explicitly changes the settled Goal + and drops its R+1 download claim. + +Implement the chosen contract in Rust and matching JS per-reader serving, +without changing existing readers' content or timestamps. Define and test +warm and cold caches, late track info and first-frame size, finish/abort +before the answer, and route-copy replacement while a refresh is pending. +Keep the wire draft and concept docs accurate if withholding becomes part +of the contract. A demand-only fix is insufficient: the current draft says +to request a fresh group, without promising to withhold cached delivery. ## Related diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index 3be1efaaaae..c21e36a8d3a 100644 --- a/rs/moq-net/Cargo.toml +++ b/rs/moq-net/Cargo.toml @@ -50,6 +50,7 @@ criterion = { workspace = true } futures = { workspace = true } # The tests' executor, with simulated time. moq-clock = { path = "../moq-clock", features = ["sim"] } +moq-json = { path = "../moq-json" } serde_json = { workspace = true } # The benches run on tokio. test-util (tokio::time::pause/advance) is test-only and # is NOT supported on wasm, so it must not leak into the normal dependency feature set. diff --git a/rs/moq-net/tests/integration/refresh.rs b/rs/moq-net/tests/integration/refresh.rs index 2c11334e23f..c26c18ea8e4 100644 --- a/rs/moq-net/tests/integration/refresh.rs +++ b/rs/moq-net/tests/integration/refresh.rs @@ -1,7 +1,7 @@ #![cfg(feature = "async")] -//! Refresh joins traverse two real protocol hops, judged independently from each cache. -use crate::support::harness::{MockConnectOptions, connect_mock, spawn}; +//! Refresh joins traverse real protocol hops, judged independently from each cache. +use crate::support::harness::{MockConnectOptions, connect_mock, peer, spawn, subscribed}; use moq_net::{Hop, Version, origin, track}; use std::time::Duration; @@ -11,6 +11,136 @@ fn origin(hop: u64) -> origin::Producer { origin } +/// The JSON owner answers demand across a publisher link, a cluster peer, and a reader link. +/// Existing readers keep their deltas; the late reader can start at a new complete snapshot. +/// This checks refresh propagation and correctness, not a cap on bytes sent before the answer. +#[moq_clock::test] +async fn json_snapshot_refresh_crosses_a_two_relay_cluster() { + use moq_json::snapshot; + use moq_net::{Timed, Timescale, Timestamp}; + use serde_json::{Value, json}; + + for ratio in [1, 2] { + let version = "moq-lite-07-wip".parse().unwrap(); + let source = origin(1); + let a = origin(2); + let b = origin(3); + let reader = origin(4); + let broadcast = source.create_broadcast("room").unwrap(); + let track = broadcast + .create_track( + "state", + track::Info::default() + .with_refresh(ratio) + .with_timescale(Timescale::MILLI), + ) + .unwrap(); + let mut producer = snapshot::Producer::::new(track.clone(), Default::default()); + broadcast.announce(Default::default()).unwrap(); + let mut links = vec![peer(version, &a, &b).await]; + for (upstream, downstream) in [(&source, &a), (&b, &reader)] { + let mut options = MockConnectOptions::new(version); + options.server_publish = Some(upstream.consume()); + options.client_subscribe = Some(downstream.clone()); + links.push(connect_mock(options).await); + } + reader.consume().routed("room").await.unwrap(); + let remote = reader.consume().request_broadcast("room", None).await.unwrap(); + let remote = remote.track("state").unwrap(); + let mut baseline = remote.subscribe(None).await.unwrap(); + assert_eq!(baseline.info().refresh, Some(ratio)); + subscribed(&track).await; + + let at = |n| Timestamp::from_millis(100 + n).unwrap(); + let value = |n| json!({ "n": n, "p": "" }); + let snapshot_bytes = producer.update(Timed::from(&value(0)).at(at(0))).unwrap().unwrap(); + let mut original = baseline.recv_group().await.unwrap().unwrap(); + assert_eq!(original.sequence, 0); + let first = original.read_frame().await.unwrap().unwrap(); + assert_eq!(first.timestamp, Some(at(0))); + assert_eq!(first.payload.len(), snapshot_bytes); + assert_eq!(serde_json::from_slice::(&first.payload).unwrap(), value(0)); + + let mut delta_bytes = 0; + let mut joins = Vec::new(); + for n in 1..=2 * u64::from(ratio) { + delta_bytes += producer.update(Timed::from(&value(n)).at(at(n))).unwrap().unwrap(); + let delta = original.read_frame().await.unwrap().unwrap(); + assert_eq!(delta.timestamp, Some(at(n))); + assert_eq!( + serde_json::from_slice::(&delta.payload).unwrap(), + json!({ "n": n }) + ); + if n == 1 || n == 2 * u64::from(ratio) { + let mut join = + snapshot::Consumer::::new(remote.subscribe(None).await.unwrap(), Default::default()); + let received = join.latest().await.unwrap().unwrap(); + assert_eq!((received.value, received.at), (value(n), Some(at(n)))); + assert!(producer.poll_refresh(&kio::Waiter::noop()).is_pending()); + assert_eq!(track.demand().wanted(), Some(0)); + joins.push(join); + } + } + assert_eq!( + delta_bytes, + ratio as usize * snapshot_bytes, + "equality does not refresh" + ); + + let n = 2 * u64::from(ratio) + 1; + delta_bytes += producer.update(Timed::from(&value(n)).at(at(n))).unwrap().unwrap(); + original.read_frame().await.unwrap().unwrap(); + assert!(delta_bytes > ratio as usize * snapshot_bytes); + // Simulated time passing cannot roll a group, even with deltas over the ratio. + moq_clock::sleep(Duration::from_secs(60)).await; + assert!(producer.poll_refresh(&kio::Waiter::noop()).is_pending()); + assert_eq!(track.demand().wanted(), Some(0)); + + let mut late = remote.subscribe(None).await.unwrap(); + // Poll the new reader while the owner drives refresh: a front does not join its + // serving copy until read. Either a cached prefix or the fresh group may arrive first. + let mut fresh = moq_clock::timeout(Duration::from_secs(1), async { + let (refreshed, group) = futures::join!(producer.refresh(), async { + loop { + let group = late.recv_group().await.unwrap().unwrap(); + if group.sequence > 0 { + break group; + } + } + }); + refreshed.unwrap(); + group + }) + .await + .unwrap(); + assert!( + producer.poll_refresh(&kio::Waiter::noop()).is_pending(), + "answered once" + ); + assert_eq!(fresh.sequence, 1, "new content gets a new group identity"); + let frame = fresh.read_frame().await.unwrap().unwrap(); + assert_eq!(frame.timestamp, Some(at(n)), "refresh preserves the newest source time"); + assert_eq!(serde_json::from_slice::(&frame.payload).unwrap(), value(n)); + assert_eq!(frame.payload.len(), snapshot_bytes); + assert!(fresh.poll_read_frame(&kio::Waiter::noop()).is_pending()); + assert_eq!(baseline.recv_group().await.unwrap().unwrap().sequence, 1); + + producer.update(Timed::from(&value(n + 1)).at(at(n + 1))).unwrap(); + let delta = fresh.read_frame().await.unwrap().unwrap(); + assert_eq!(delta.timestamp, Some(at(n + 1))); + assert_eq!( + serde_json::from_slice::(&delta.payload).unwrap(), + json!({ "n": n + 1 }) + ); + let mut current = snapshot::Consumer::::new(remote.subscribe(None).await.unwrap(), Default::default()); + let received = current.latest().await.unwrap().unwrap(); + assert_eq!((received.value, received.at), (value(n + 1), Some(at(n + 1)))); + assert!(producer.poll_refresh(&kio::Waiter::noop()).is_pending()); + producer.finish().unwrap(); + drop((current, fresh, late, joins, original, baseline, links)); + } +} + #[moq_clock::test] async fn ratio_joins_cross_two_relays() { for name in ["moq-lite-06", "moq-lite-07-wip"] { From 4c6450a92105b64432270595fc6075a30ea8ac9c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 22:38:01 -0700 Subject: [PATCH 3/5] fix(net): settle refresh as a soft trigger A live join over the refresh ratio keeps receiving the cached group while the fresh one is requested. Pin that in the Rust and JS unit tests and the two-relay JSON integration test, drop the byte-bound claims from the API docs and bindings, state it in the lite draft, and finish the refresh quest. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-lite.md | 1 + js/net/src/track.test.ts | 4 +- js/net/src/track.ts | 4 +- py/moq-rs/moq/json.py | 4 +- quest/m1/README.md | 1 - quest/m1/api-audit/README.md | 2 +- quest/m1/compress/README.md | 1 - quest/m1/ietf-extension/README.md | 3 +- quest/m1/refresh/README.md | 91 ------------------------- rs/moq-c/src/api.rs | 4 +- rs/moq-c/src/publish.rs | 6 +- rs/moq-json/src/snapshot/mod.rs | 5 +- rs/moq-net/src/model/track.rs | 10 +-- rs/moq-net/tests/integration/refresh.rs | 27 ++++---- 14 files changed, 39 insertions(+), 124 deletions(-) delete mode 100644 quest/m1/refresh/README.md diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 1529456c7a6..b0375b2c57d 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -1370,6 +1370,7 @@ Common values include `1000` (milliseconds), `1000000` (microseconds), `48000` ( An optional unsigned 32-bit byte ratio, encoded as the ratio plus one; `0` disables refresh. On a live-edge join, a publisher asks for a group beyond every sequence already produced when the newest group's bytes after its first frame exceed the ratio times that first frame's bytes. Joins coalesce until the requested group arrives. +The request does not hold back delivery: the joiner still receives the newest cached group while it is pending. A relay preserves the ratio and evaluates joins against its own cache, forwarding demand in SUBSCRIBE_UPDATE. Versions before lite-07 omit Refresh and Wanted Group; a Track received on those versions never refreshes. diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 2c961e466d1..4c5b59eefce 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -114,7 +114,8 @@ test("the first subscriber of a track with no group wants group 0", () => { subscriber.close(); }); -test("a join over the refresh ratio wants the group after the newest", () => { +// The cached group is served either way: refresh is a request, not a hold. +test("a join over the refresh ratio wants the group after the newest", async () => { for (const [delta, wanted] of [ [0, 0], [3, 0], @@ -124,6 +125,7 @@ test("a join over the refresh ratio wants the group after the newest", () => { refreshGroup(producer, delta); const subscriber = producer.subscribe(); expect(producer.demand().wanted.peek()).toBe(wanted); + expect((await subscriber.recvGroup())?.sequence).toBe(0); subscriber.close(); } }); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 0fccc0d96ce..083ea7416e9 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -127,8 +127,8 @@ export interface Info { * How many times its first frame a group's later stored bytes may grow before a joining * subscriber asks for a new group, or omitted to never ask. A join against a newest group * whose bytes after its first frame exceed this many times the first frame moves - * {@link Demand.wanted} past it, so a late joiner never downloads much more than a - * snapshot or keyframe. `0` asks on any join after a delta. An integer in `0..2^32`. + * {@link Demand.wanted} past it. The joiner still receives the cached group while the new + * one is pending. `0` asks on any join after a delta. An integer in `0..2^32`. */ refresh?: number; /** The original moq-transport publisher's draft, whose timestamps may rewind. @internal */ diff --git a/py/moq-rs/moq/json.py b/py/moq-rs/moq/json.py index f5831ab473e..442e7715884 100644 --- a/py/moq-rs/moq/json.py +++ b/py/moq-rs/moq/json.py @@ -56,8 +56,8 @@ class SnapshotProducer: Each :meth:`update` supersedes the last; a late joiner only sees the newest value, encoded as 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 + join after more than that many snapshots' worth of deltas asks for 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. """ diff --git a/quest/m1/README.md b/quest/m1/README.md index c0bb4fbd6cf..00d67705bda 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -91,7 +91,6 @@ tracks, so per-group stats stop costing cluster announces. - [Binding encoder config](/quest/m1/binding-encoder-config.md) - binding encoders take an exact rational framerate, and the publication track name moves to options only the producers take - [FFI shutdown requests the drain synchronously](/quest/m1/ffi-shutdown-sync.md) - `shutdown()` becomes a sync drain request awaited with `closed()`, so a dropped future can no longer cancel - [moq-transport passthrough](/quest/m1/ietf-extension/README.md) - object IDs, properties, end status, datagram objects, and unknown track properties survive moq-transport -> moq-relay (and a relay cluster) -> moq-transport; moxygen's moq-test sections 1-7 pass nightly, except cases that use a subgroup other than 0 -- [Refresh](/quest/m1/refresh/README.md) - a join asks for a fresh group once the current group's deltas exceed a publisher-advertised byte ratio, at every hop; replaces `Demand::used`/`unused` and moq-json's `delta_ratio` - [Announcement takeover](/quest/m1/announce-takeover.md) - a new independent route explicitly continues instances served through its predecessor, with shared Rust/JS semantics and lite-07 wire - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges with absolute or relative ends, in either order, and replaces FETCH; merged ranges never starve a subscriber; relays fill misses by range, including over moq-transport - [A widened max age re-offers cached groups](/quest/m1/resolved-demand.md) - a warm relay serves a reader with a wider max age the cached groups a cold relay would, with no wire change diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index a223e5ad187..3425cc9f9a3 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -52,7 +52,7 @@ Both are in m1, so the cut waits for them. hang's Rejected in planning: -- Restoring `track::Demand::{used, unused}`: [refresh](/quest/m1/refresh/README.md) +- Restoring `track::Demand::{used, unused}`: refresh decided one `wanted()` signal. - Removing `Audio.Decoder.arrivals()`: moq.dev has a planned consumer waiting on this release. Only the video handle goes diff --git a/quest/m1/compress/README.md b/quest/m1/compress/README.md index 4b94a3b0d9a..d0771ef8227 100644 --- a/quest/m1/compress/README.md +++ b/quest/m1/compress/README.md @@ -86,5 +86,4 @@ This README owns the end-to-end proof and the guide once every child lands: ## Related -- [Refresh](/quest/m1/refresh/README.md) - its byte ratio measures the stored, compressed group - [Front eviction](/quest/m2/unbounded-groups/front-eviction.md) - a compressed group's evicted prefix must refill before a reader can inflate past it diff --git a/quest/m1/ietf-extension/README.md b/quest/m1/ietf-extension/README.md index c52db0029f8..14a9094d7bd 100644 --- a/quest/m1/ietf-extension/README.md +++ b/quest/m1/ietf-extension/README.md @@ -8,7 +8,7 @@ object properties, END_OF_GROUP status objects, datagram object IDs, and unknown track properties intact. Tracks advertising DYNAMIC_GROUPS relay NEW_GROUP_REQUEST back to the original publisher, with redundant requests coalesced. Across the cluster, -[refresh](/quest/m1/refresh/README.md) carries them on native lite-07. +refresh demand carries them on native lite-07. moxygen's moq-test conformance (sections 1-7, except cases that use a subgroup other than 0) passes through moq-relay in a nightly CI job. @@ -86,4 +86,3 @@ Work owned by this README, after the children land: - [#4926](https://github.com/moq-dev/moq/issues/4926) - the declined request for an object-level API; this carries the fields for relays only - [A public model](/quest/m1/public-model/README.md) - these fields are its deliberate exception -- [Refresh](/quest/m1/refresh/README.md) - promotes the dynamic-groups request path to a public byte-ratio API on native lite diff --git a/quest/m1/refresh/README.md b/quest/m1/refresh/README.md deleted file mode 100644 index 30959955f18..00000000000 --- a/quest/m1/refresh/README.md +++ /dev/null @@ -1,91 +0,0 @@ -# [M] Refresh: new groups on demand - -## Goal - -A publisher opts a track in to refresh with a byte ratio R. When a new -subscriber joins and the current group's bytes after its first frame exceed -R times that first frame, the publisher is asked for a fresh group, at the -origin and through every relay hop. Groups no longer roll on a fixed -schedule: a joiner never downloads more than about R + 1 times a snapshot or -keyframe, and existing subscribers stop paying for refreshes nobody needed. - -Boundaries: - -- The criterion is transfer size, not time. A joiner only costs a refresh - once the deltas outweigh the first frame, so refreshes rate-limit - themselves without a timer. -- Joining is the only trigger. There is no explicit subscriber request; a - decoder that lost sync rereads the cached group from its start. -- Non-goals: json stream mode and importers that cannot force a keyframe - (CMAF, TS). - -## Plan - -Decided with the maintainer on 2026-10-16. - -- **Why not IETF semantics as-is.** DYNAMIC_GROUPS is a boolean and - NEW_GROUP_REQUEST carries only a group ID, with no rate limit beyond - "outstanding until Largest Group grows". Reviewers of the draft asked for - a way to say "a recent group is fine". A ratio advertised by the publisher - lets every hop decide that locally from its cache, without app knowledge. -- **A ratio, not a duration.** A time minimum was considered first and - rejected: a fresh json snapshot every second costs every subscriber a full - group, which can be worse than the deltas. Transfer size is the thing - being optimized. A subscriber-weighted rule (refresh when bytes exceed - (N + 1) times the first frame) was rejected because N is per-hop fanout, - so relays would disagree and the publisher could not advertise it. -- **One demand state.** `track::Demand::wanted() -> Option` replaces - `used()` and `unused()`: `None` while unused, `Some(n)` when consumers want - group `n` or later. A producer opens a group whenever `n` passes its - largest. The same signal covers the first subscriber, resuming a paused - encoder, and a refresh. It was preferred over keeping `used()` beside a - new event, which would leave two ways to say the same thing. -- **Names.** `track::Info::refresh: Option` is the ratio, in the same - unit as moq-json's `delta_ratio`, which it replaces. `None` means joins - never trigger groups. It is the only home of the ratio: producers that - receive a created track read it from there. -- **Order.** Relay requests for dynamic groups (#5708) were promoted to - the public `Demand::wanted` and `track::Info::refresh` in #5930, and - #6030 carries refresh demand through lite relays. The moq-json producers - now answer that demand. -- **m1.** Replacing `Demand` is a breaking API change, and m1 finishes the - planned breaking APIs before the cut. - -The remaining work is the Goal's download-byte bound. Demand propagation and -the JSON answer work, but a join still receives the cached group while its -request travels upstream. With R=1, a 14-byte snapshot and 64 deltas totaling -503 bytes, a late reader across two relays can download all 517 cached bytes -before the JSON owner answers, rather than about 28 bytes. This was reproduced -with simulated time; it is a counterexample, not behavior to preserve. - -The normal integration gate now exercises a real moq-json snapshot producer -and consumer through a publisher link, two clustered relays, and a reader -link. It checks ratios 1 and 2 below, exactly at, and above the threshold; -elapsed time without a join; a fresh full snapshot under a new group number -at the newest source timestamp; and subsequent deltas. It tolerates a stale -prefix without requiring one. The concept page documents the current soft -trigger and its byte-bound limitation. - -Before changing serving behavior, settle how a pending refresh ends: - -- **Recommended: preserve the Goal's bound.** Withhold an oversized cached - prefix for that live join, with explicit terminal behavior when the source - finishes, aborts, or cannot produce the requested group. Do not silently - fall back to the oversized prefix. A warm Rust cursor could start beyond - the current group, but that alone does not cover cold caches that learn - the ratio or size late, or a resume front selecting another route copy. -- **Alternative: accept only a soft trigger.** Keep serving cached content - while requesting a fresh group. This explicitly changes the settled Goal - and drops its R+1 download claim. - -Implement the chosen contract in Rust and matching JS per-reader serving, -without changing existing readers' content or timestamps. Define and test -warm and cold caches, late track info and first-frame size, finish/abort -before the answer, and route-copy replacement while a refresh is pending. -Keep the wire draft and concept docs accurate if withholding becomes part -of the contract. A demand-only fix is insufficient: the current draft says -to request a fresh group, without promising to withhold cached delivery. - -## Related - -- [moq-transport passthrough](/quest/m1/ietf-extension/README.md) - its dynamic-groups child is the IETF half this epic promotes diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index aa7170afaa1..9c28c3be3c5 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -428,8 +428,8 @@ pub struct moq_audio_config { #[allow(non_camel_case_types)] pub struct moq_json_snapshot_config { /// 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. + /// group with a full snapshot. When on, a join after more than eight snapshots' worth of + /// deltas asks for 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. diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index b91a258f62a..06d5d627905 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -956,9 +956,9 @@ impl Publish { /// 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. + /// With deltas on, the track carries a refresh ratio of 8: a join after more than eight + /// snapshots' worth of deltas asks for the value restated in a fresh group, which a task + /// answers until the track is finished. pub fn json_snapshot(&mut self, broadcast: Id, name: &str, config: moq_mux::json::Config) -> Result { let refresh = config.deltas.then_some(8); let data = self.data_track(broadcast, name, refresh, |catalog, track| { diff --git a/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index 00e3b2fa8d0..73dc701eb01 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -18,8 +18,9 @@ //! //! 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 +//! open group's deltas outweigh that ratio times its snapshot. The joiner still reads the cached +//! group meanwhile: the ratio limits how often groups roll, not what a joiner downloads. +//! [`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. //! diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 62707ee8125..3e0f9e108c5 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -155,7 +155,7 @@ pub struct Info { /// keyframe) that the deltas after it build on. A joiner reads the newest group from its /// start, so once the deltas outweigh `refresh` times the first frame, a fresh group is /// cheaper: [`Demand::wanted`] moves past the newest group and the publisher opens one. - /// Every hop judges a join against its own cache, which holds the same group. + /// The joiner still receives the cached group while the new one is pending. Every hop judges a join against its own cache, which holds the same group. /// `Some(0)` asks on any join once a delta follows the first frame. /// /// On moq-transport, `Some` is advertised as DYNAMIC_GROUPS, which arrives as `Some(0)`. @@ -15807,15 +15807,17 @@ mod test { assert_eq!(wanted_changed(&mut demand), Some(None)); } - /// A join reads the newest group, unless its bytes after the first frame exceed the - /// ratio times the first frame: then it wants the group after the newest. + /// A join reads the newest group, and once its bytes after the first frame exceed the + /// ratio times the first frame it also wants the group after the newest. The cached group + /// is served either way: refresh is a request, not a hold. #[test] fn a_join_over_the_ratio_wants_a_new_group() { for (delta, wanted) in [(0, 0), (3, 0), (4, 1)] { let producer = track_producer("test", Info::default().with_refresh(1)); refresh_group(&producer, delta); - let _subscriber = producer.subscribe(None); + let mut subscriber = producer.subscribe(None); assert_eq!(producer.demand().wanted(), Some(wanted), "{delta} byte delta"); + assert_eq!(subscriber.assert_group().sequence, 0, "{delta} byte delta"); } } diff --git a/rs/moq-net/tests/integration/refresh.rs b/rs/moq-net/tests/integration/refresh.rs index c26c18ea8e4..886e1d53746 100644 --- a/rs/moq-net/tests/integration/refresh.rs +++ b/rs/moq-net/tests/integration/refresh.rs @@ -12,8 +12,8 @@ fn origin(hop: u64) -> origin::Producer { } /// The JSON owner answers demand across a publisher link, a cluster peer, and a reader link. -/// Existing readers keep their deltas; the late reader can start at a new complete snapshot. -/// This checks refresh propagation and correctness, not a cap on bytes sent before the answer. +/// Existing readers keep their deltas; the late reader receives the cached group, then a new +/// complete snapshot. #[moq_clock::test] async fn json_snapshot_refresh_crosses_a_two_relay_cluster() { use moq_json::snapshot; @@ -98,21 +98,24 @@ async fn json_snapshot_refresh_crosses_a_two_relay_cluster() { let mut late = remote.subscribe(None).await.unwrap(); // Poll the new reader while the owner drives refresh: a front does not join its - // serving copy until read. Either a cached prefix or the fresh group may arrive first. - let mut fresh = moq_clock::timeout(Duration::from_secs(1), async { - let (refreshed, group) = futures::join!(producer.refresh(), async { - loop { - let group = late.recv_group().await.unwrap().unwrap(); - if group.sequence > 0 { - break group; - } - } + // serving copy until read. Refresh is a request, not a hold, so the cached group + // arrives first, whole, and the fresh one follows. + let (mut cached, mut fresh) = moq_clock::timeout(Duration::from_secs(1), async { + let (refreshed, groups) = futures::join!(producer.refresh(), async { + let cached = late.recv_group().await.unwrap().unwrap(); + (cached, late.recv_group().await.unwrap().unwrap()) }); refreshed.unwrap(); - group + groups }) .await .unwrap(); + assert_eq!(cached.sequence, 0, "the cached group is not withheld"); + let mut cached_bytes = 0; + for _ in 0..=n { + cached_bytes += cached.read_frame().await.unwrap().unwrap().payload.len(); + } + assert_eq!(cached_bytes, snapshot_bytes + delta_bytes); assert!( producer.poll_refresh(&kio::Waiter::noop()).is_pending(), "answered once" From db5056769857d1b37cbc842506925ace28acd8f5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 01:16:18 -0700 Subject: [PATCH 4/5] docs(json): drop the remaining bounded-download claims Co-Authored-By: Claude Opus 5.5 --- rs/moq-json/src/snapshot/encoder.rs | 5 +++-- rs/moq-json/src/snapshot/producer.rs | 4 ++-- rs/moq-json/src/window/producer.rs | 4 ++-- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/rs/moq-json/src/snapshot/encoder.rs b/rs/moq-json/src/snapshot/encoder.rs index fcb79a6569b..82ef3301c48 100644 --- a/rs/moq-json/src/snapshot/encoder.rs +++ b/rs/moq-json/src/snapshot/encoder.rs @@ -281,8 +281,9 @@ impl Encoder { /// Restate the last committed value as a full snapshot, which must open a new group. /// /// For a caller that opens groups itself: call it when a joiner wants a fresh group, such as when - /// [`Demand::wanted`](moq_net::track::Demand::wanted) passes the largest group written, so the - /// joiner reads the value without the deltas before it. Returns `None` before the first value, + /// [`Demand::wanted`](moq_net::track::Demand::wanted) passes the largest group written. The new + /// group restates the value without the deltas before it, though that joiner still reads the + /// cached group first. 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 { diff --git a/rs/moq-json/src/snapshot/producer.rs b/rs/moq-json/src/snapshot/producer.rs index e8a49f56272..5b64931b1a5 100644 --- a/rs/moq-json/src/snapshot/producer.rs +++ b/rs/moq-json/src/snapshot/producer.rs @@ -88,8 +88,8 @@ 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 newest timestamp written, so the new group never starts before the last. + /// [`Demand::wanted`](moq_net::track::Demand::wanted)). It is a soft trigger: that joiner still + /// reads the cached group, then the new one. 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 diff --git a/rs/moq-json/src/window/producer.rs b/rs/moq-json/src/window/producer.rs index 00c51ef2e67..7db01078dfb 100644 --- a/rs/moq-json/src/window/producer.rs +++ b/rs/moq-json/src/window/producer.rs @@ -95,8 +95,8 @@ 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 newest timestamp written. Nothing happens before + /// [`Demand::wanted`](moq_net::track::Demand::wanted)). It is a soft trigger: that joiner still + /// reads the cached group, then the new one. 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 From e7633eeb0e11bc73a8645c171d979442f8e4ac82 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 01:30:27 -0700 Subject: [PATCH 5/5] docs: drop refresh download bounds from ffi and video Co-Authored-By: Claude Opus 5.5 --- rs/moq-ffi/src/json.rs | 5 +++-- rs/moq-ffi/src/test.rs | 4 ++-- rs/moq-video/src/encode/cuts.rs | 2 +- rs/moq-video/src/encode/producer.rs | 4 ++-- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/rs/moq-ffi/src/json.rs b/rs/moq-ffi/src/json.rs index fe95f5e9173..ea0541daf87 100644 --- a/rs/moq-ffi/src/json.rs +++ b/rs/moq-ffi/src/json.rs @@ -103,8 +103,9 @@ mod tests { /// 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. +/// A join that finds 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. That joiner +/// still reads the cached group first. #[derive(uniffi::Object)] pub struct MoqJsonSnapshotProducer { inner: Arc>>>, diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 67c72461817..285f7791435 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1150,8 +1150,8 @@ async fn json_snapshot_roundtrip() { assert_eq!(end, None); } -/// An idle snapshot producer restates its value in a fresh group once a joiner would otherwise -/// download more deltas than the track's refresh ratio allows. +/// An idle snapshot producer restates its value in a fresh group once a join finds more deltas +/// than the track's refresh ratio allows. #[tokio::test] async fn json_snapshot_refreshes_for_a_joiner() { let broadcast = MoqBroadcastProducer::new().unwrap(); diff --git a/rs/moq-video/src/encode/cuts.rs b/rs/moq-video/src/encode/cuts.rs index 65748f2f7e3..c8d519a77fd 100644 --- a/rs/moq-video/src/encode/cuts.rs +++ b/rs/moq-video/src/encode/cuts.rs @@ -11,7 +11,7 @@ /// same group and coalesce into it. /// /// There is no spacing between cuts: the refresh ratio already rate-limits joins by the bytes -/// a group holds, and a floor would let a joiner download well past that ratio. +/// a group holds, and a floor would let a group grow well past that ratio. pub(super) struct Cuts { /// The request count already accounted for. requests: u64, diff --git a/rs/moq-video/src/encode/producer.rs b/rs/moq-video/src/encode/producer.rs index d71957a3dda..51c005a6cf0 100644 --- a/rs/moq-video/src/encode/producer.rs +++ b/rs/moq-video/src/encode/producer.rs @@ -39,8 +39,8 @@ use super::encoder::Codec; const DEFAULT_FRAMERATE: Rate = Rate::integer(30); /// The [`track::Info::refresh`](moq_net::track::Info::refresh) ratio a capture advertises: a -/// joiner forces a keyframe once a group's deltas outweigh twice its keyframe, so it downloads -/// at most about three keyframes' worth before it can decode. +/// joiner forces a keyframe once a group's deltas outweigh twice its keyframe, so later joiners +/// start near one. The joiner that asks still reads the cached group meanwhile. /// /// Measured on realtime CBR encodes (two-second GOPs at 2 to 4 Mbps), where a GOP's deltas run /// three to five keyframes: one join a second halves the mean joiner download for 10 to 13%