Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

27 changes: 27 additions & 0 deletions doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 3 additions & 1 deletion js/net/src/track.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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],
Expand All @@ -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();
}
});
Expand Down
4 changes: 2 additions & 2 deletions js/net/src/track.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
Expand Down
4 changes: 2 additions & 2 deletions py/moq-rs/moq/json.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""

Expand Down
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion quest/m1/api-audit/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 0 additions & 1 deletion quest/m1/compress/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
3 changes: 1 addition & 2 deletions quest/m1/ietf-extension/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
66 changes: 0 additions & 66 deletions quest/m1/refresh/README.md

This file was deleted.

4 changes: 2 additions & 2 deletions rs/moq-c/src/api.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 3 additions & 3 deletions rs/moq-c/src/publish.rs
Original file line number Diff line number Diff line change
Expand Up @@ -956,9 +956,9 @@ impl Publish {
/// state; a late joiner only sees the newest value. The catalog entry (`json.tracks.<name>`,
/// `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<Id, Error> {
let refresh = config.deltas.then_some(8);
let data = self.data_track(broadcast, name, refresh, |catalog, track| {
Expand Down
5 changes: 3 additions & 2 deletions rs/moq-ffi/src/json.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<std::sync::Mutex<Option<moq_mux::json::Snapshot<Value, Extra>>>>,
Expand Down
4 changes: 2 additions & 2 deletions rs/moq-ffi/src/test.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
5 changes: 3 additions & 2 deletions rs/moq-json/src/snapshot/encoder.rs
Original file line number Diff line number Diff line change
Expand Up @@ -281,8 +281,9 @@ impl<T> Encoder<T> {
/// 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<Option<Pending<'_, T>>> {
let bytes = match &self.last {
Expand Down
5 changes: 3 additions & 2 deletions rs/moq-json/src/snapshot/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
kixelated marked this conversation as resolved.
Resolved
//! [`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.
//!
Expand Down
4 changes: 2 additions & 2 deletions rs/moq-json/src/snapshot/producer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,8 @@ impl<T: Serialize> Producer<T> {
///
/// 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
Expand Down
4 changes: 2 additions & 2 deletions rs/moq-json/src/window/producer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,8 @@ impl<T> Producer<T> {
///
/// 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
Expand Down
1 change: 1 addition & 0 deletions rs/moq-net/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
10 changes: 6 additions & 4 deletions rs/moq-net/src/model/track.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
kixelated marked this conversation as resolved.
Resolved
/// `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)`.
Expand Down Expand Up @@ -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");
}
}

Expand Down
Loading
Loading