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 de0b9e42508..9387e38071e 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -328,6 +328,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/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 3227037a0a9..00000000000 --- a/quest/m1/refresh/README.md +++ /dev/null @@ -1,66 +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 - remain. -- **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: - -- 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. - -## 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-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-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/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-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 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/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 2c11334e23f..886e1d53746 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,139 @@ 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 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; + 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. 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(); + 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" + ); + 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"] { 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%