Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
dee3093
feat(moq-net): enforce the subscriber latency budget
kixelated Aug 15, 2026
ca7cf0c
fix(moq-net): revalidate the drift anchor and count frame-level skips
kixelated Aug 16, 2026
5d800e1
fix(moq-net): stop the requested end from capping the local live edge
kixelated Aug 16, 2026
8783a69
fix(moq-net): address latency enforcement review
kixelated Aug 16, 2026
66e4e02
fix(moq-mux): adapt latency test to optional rendition
kixelated Aug 17, 2026
c700bbc
fix(moq-net): complete latency enforcement
kixelated Aug 17, 2026
3ac6bf3
fix(moq-net): expire handed-out stale groups
kixelated Aug 17, 2026
9ac4085
fix(moq-net): preserve latency across route changes
kixelated Aug 17, 2026
65e2280
fix(moq-net): settle handed-out group expiry
kixelated Aug 17, 2026
30f63bb
fix(moq-net): close zero-latency gaps
kixelated Aug 17, 2026
a069d95
fix(moq-net): expire in-flight frame reads
kixelated Aug 17, 2026
16a9bf4
fix(moq-net): preserve protocol latency semantics
kixelated Aug 17, 2026
25873f3
fix(moq-net): bound IETF latency fallback
kixelated Aug 17, 2026
f7f95ea
fix(moq-net): align IETF fallback across languages
kixelated Aug 17, 2026
5dc992c
fix(moq-net): expire transport-blocked group streams
kixelated Aug 17, 2026
aaa6801
fix(moq-net): enforce latency during group startup
kixelated Aug 17, 2026
a9fc6bb
fix(moq-net): exclude fetches from live drift
kixelated Aug 17, 2026
c8b3c04
refactor(moq-net): store group visibility
kixelated Aug 17, 2026
62ccb83
fix(moq-relay): expose stale Prometheus counters
kixelated Aug 17, 2026
cfcc1a5
fix(moq-net): preserve clean group completion
kixelated Aug 17, 2026
86afbb8
fix(moq-mux): inherit initial subscription latency
kixelated Aug 17, 2026
91d69eb
fix(moq-net): wake on new presentation edges
kixelated Aug 17, 2026
0ebf511
fix(moq-net): expire blocked final payloads
kixelated Aug 17, 2026
8158a55
fix(moq-net): only expire a group whose read would park
kixelated Aug 18, 2026
a901ba9
fix(moq-net): measure drift from the reader, and end a drained group
kixelated Aug 18, 2026
880b4f5
fix(moq-net): box the largest subscribe state
kixelated Aug 18, 2026
7171b99
docs(contributing): ask PRs to flag wire behavior, not just API
kixelated Aug 18, 2026
21e7b9e
test(moq-mux): set the test latency where a caller sets it
kixelated Aug 18, 2026
7b8c8cb
test(moq-mux): name the replay-window helper after what it asks for
kixelated Aug 18, 2026
a73c5d7
fix(moq-mux): give the TS export's SI track the export's replay window
kixelated Aug 19, 2026
a583c8d
fix(moq-net): keep a budget-ended group ended
kixelated Aug 19, 2026
1d966e4
fix(moq-net): don't serve legacy lite peers at the live edge
kixelated Aug 19, 2026
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
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Keep the body short and structured, not narrated:

- **Summary**: a few bullets on what changed and why. For a bug fix, state the root cause (see Root Cause First in [CLAUDE.md](CLAUDE.md)).
- **Public API changes**: every new/renamed/removed/signature-changed `pub` item in `rs/moq-*` and `js/*`, with breaking ones called out per [Branch Targeting](#branch-targeting). Distinguish genuinely public surface from `pub(crate)`/private.
- **Wire behavior changes**: what a *peer* observes differently, even when no signature moved and the encoding is byte-identical. A change to which content gets delivered, when a stream is reset rather than FIN'd (and with which error code), what a default now implies, or when a message is sent, is something another implementation has to match, and it is invisible in an API diff. Say what the old and new behavior are and which side decides. New/changed encodings additionally need the matching `drafts/` update in the same PR, per [Cross-Package Sync](CLAUDE.md#cross-package-sync).
- **Test plan**: what was run and verified.
- If you skip a [Cross-Package Sync](CLAUDE.md#cross-package-sync) row, say why.

Expand Down Expand Up @@ -57,7 +58,7 @@ CodeRabbit reviews PRs automatically, but it has an hourly quota and runs out of

Reply to review comments as you address them, saying what changed or why you disagree, so the reviewer doesn't have to diff the branch to find out. Replies are GitHub prose like any other, so they carry the [AI Contributions](#ai-contributions) marker.

When reviewing a PR, always include the same public API changes list described above, and call out anything breaking per [Branch Targeting](#branch-targeting).
When reviewing a PR, always include the same public API and wire behavior lists described above, and call out anything breaking per [Branch Targeting](#branch-targeting). Wire behavior is the easier of the two to miss, since nothing in the diff's signatures flags it: read for what a peer would now see, not just for what the types say.

## Releases

Expand Down
20 changes: 18 additions & 2 deletions doc/bin/relay/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -400,14 +400,16 @@ counterpart no traffic can flow, so the entry is dropped:
"broadcasts": 1, "broadcasts_closed": 0,
"subscriptions": 5, "subscriptions_closed": 2,
"fetches": 3,
"bytes": 12345, "frames": 678, "groups": 9, "datagrams": 2
"bytes": 12345, "frames": 678, "groups": 9, "datagrams": 2,
"stale": { "bytes": 456, "frames": 23, "groups": 4, "datagrams": 0 }
},
"anon/foo": {
"announced": 1, "announced_closed": 0, "announced_bytes": 8,
"broadcasts": 1, "broadcasts_closed": 0,
"subscriptions": 2, "subscriptions_closed": 0,
"fetches": 0,
"bytes": 234, "frames": 12, "groups": 1, "datagrams": 0
"bytes": 234, "frames": 12, "groups": 1, "datagrams": 0,
"stale": { "bytes": 0, "frames": 0, "groups": 0, "datagrams": 0 }
}
}
```
Expand All @@ -417,40 +419,54 @@ Field semantics:
- `announced` / `announced_closed`: cumulative count of every broadcast
announce/unannounce event on this `(tier, role)` slot, regardless of
whether any subscription happened. Use this for "all known broadcasts".

- `announced_bytes`: cumulative broadcast-name length summed over each
model-visible announce and unannounce of this broadcast. It counts the name,
not the encoded message size, so a broadcast isn't charged for hop chains or
framing overhead (and the count is the same across protocol versions).
Separate from `bytes`, which is media payload. Announce control traffic that
never enters the model (auth-rejected or unmatched-prefix announcements) is
not counted.

- `broadcasts` / `broadcasts_closed`: per-(broadcast, session)
subscription sentinel. The first active subscription a peer session
opens for a broadcast bumps `broadcasts`; the last one it closes bumps
`broadcasts_closed`. Summed across sessions, `broadcasts -
broadcasts_closed` is the number of distinct sessions currently
subscribed to the broadcast (i.e. viewers on the egress side), which is
typically what billing and UI want.

- `subscriptions` / `subscriptions_closed`: cumulative count of
track-level subscriptions opened and dropped.

- `fetches`: cumulative one-shot group fetches requested by a calling session,
counted once per coalesced fetch when the request is issued, so a fetch that
resolves to "not found" still counts. It is separate from `subscriptions` and
the viewer sentinel; the fetched payload still flows into `bytes` / `frames` /
`groups`.

- `bytes` / `frames` / `groups`: cumulative payload counters, bumped as
groups/frames are read out of the model on the egress side and written into
it on the ingress side. Egress bytes are counted when read out of the model
(into the QUIC send path), so bytes read but lost to a mid-group stream reset
still count. For a fan-out egress reader (e.g. an HLS/DASH muxer) this is
bytes read once per segment at the broadcast origin, not per downstream HTTP
client.

- `datagrams`: cumulative single-frame groups delivered over an unreliable QUIC
datagram (moq-lite-05+ on a datagram-capable transport). A subset of `groups`:
each datagram also counts there, and its payload in `frames` / `bytes`. Counted
when the datagram enters or leaves the model, so an egress datagram dropped by
congestion or an oversized body still counts.

- `stale`: cumulative `{ bytes, frames, groups, datagrams }` skipped because the
content drifted further behind the live edge than the subscriber's latency
budget allows, so the relay never put it on the wire. These are disjoint from
the top-level payload counters, which remain the backwards-compatible shape for
delivered content. A steady rate here means subscribers are consistently behind
the live edge, which is normal for a real-time subscription during congestion
and a problem for one that asked to tolerate more.

The session tracks (`sessions.json` and any `<tier>/sessions.json`) instead map
each auth root to a `{ sessions, sessions_closed }` snapshot. `sessions`
bumps when a session authenticated under that root connects and
Expand Down
5 changes: 4 additions & 1 deletion doc/bin/relay/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,10 @@ cluster topology endpoint below.
### GET /metrics

Prometheus text exposition of this node's own traffic counters (bytes, frames,
groups, subscriptions, viewers, sessions), split by `tier` and `role`.
groups, subscriptions, viewers, sessions), split by `tier` and `role`. Content
skipped after drifting beyond a subscriber's latency budget is exposed through
`moq_relay_stale_bytes_total`, `moq_relay_stale_frames_total`,
`moq_relay_stale_groups_total`, and `moq_relay_stale_datagrams_total`.

Alongside them are the TCP listeners' accept-loop counters, which are how a node
that has stopped accepting connections says so:
Expand Down
6 changes: 6 additions & 0 deletions doc/concept/layer/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,12 @@ Each Subscription consists of a few properties:
- **Group Order**: The order in which groups are delivered. Defaults to descending; higher IDs are delivered first.
- **Subscriber Max Latency**: The maximum age of a non-latest group before it is skipped. Defaults to zero, so stale groups are skipped immediately.

That age is measured both on the media timeline (a group's first timestamp against the newest stamped one) and by wall-clock arrival time, and either limit can expire the group.
The media timeline keeps a backlog delivered as a burst old, while wall-clock time backstops stalled or empty groups that have no timestamp.
Both ends apply it: the publisher skips a group rather than sending it, and the subscriber skips it again as it reads.
The publisher only ever sees the most tolerant budget across its subscribers, which is why the subscriber applies it too.
Asking for old groups with `Group Start` does not exempt them: a start bounds what you are sent, and a subscriber that wants history has to raise its budget to match.

The publisher also keeps old groups around for a best-effort **Publisher Max Latency** cache window so relays and late subscribers can still fetch them. This defaults to 5 seconds.
The subscriber's maximum latency is bounded by this window: a group can't be waited for longer than it's actually kept around.

Expand Down
15 changes: 8 additions & 7 deletions py/moq-rs/tests/test_local.py
Original file line number Diff line number Diff line change
Expand Up @@ -621,7 +621,7 @@ async def test_raw_multiple_frames():
consumer = origin.consume()

async for announcement in consumer.announced():
raw_consumer = await announcement.broadcast.subscribe_track("commands")
raw_consumer = await announcement.broadcast.subscribe_track("commands", moq.Subscription(latency_max_ms=1_000))

messages = [
b'{"cmd": "led", "arm": "left", "led": "THUMB", "state": 1}',
Expand All @@ -646,7 +646,7 @@ async def test_raw_producer_consume_direct():
"""Consume a raw track directly from the producer, no origin/broadcast plumbing."""
broadcast = moq.BroadcastProducer()
track = broadcast.publish_track("direct")
consumer = track.consume()
consumer = track.consume(moq.Subscription(latency_max_ms=1_000))

track.write_frame(b"hello", 0)
track.write_frame(b"world", 0)
Expand Down Expand Up @@ -702,7 +702,7 @@ async def test_raw_group_sequence():
consumer = origin.consume()

async for announcement in consumer.announced():
raw_consumer = await announcement.broadcast.subscribe_track("seq")
raw_consumer = await announcement.broadcast.subscribe_track("seq", moq.Subscription(latency_max_ms=1_000))

sent_sequences = []
for i in range(3):
Expand Down Expand Up @@ -733,8 +733,9 @@ async def test_default_iteration_is_sequence_order():
broadcast = origin.create_broadcast("track/ordering")
raw = broadcast.publish_track("ordering")

seq_consumer = raw.consume()
arr_consumer = raw.consume()
subscription = moq.Subscription(latency_max_ms=1_000)
seq_consumer = raw.consume(subscription)
arr_consumer = raw.consume(subscription)

for sequence in (5, 3):
group = raw.create_group(sequence)
Expand Down Expand Up @@ -787,7 +788,7 @@ async def test_read_frame_one_per_group():
"""read_frame() returns the first frame of each successive group."""
broadcast = moq.BroadcastProducer()
track = broadcast.publish_track("status")
consumer = track.consume()
consumer = track.consume(moq.Subscription(latency_max_ms=1_000))

track.write_frame(b"ready", 0)
track.write_frame(b"running", 0)
Expand Down Expand Up @@ -831,7 +832,7 @@ async def test_read_frame_skips_remaining_frames_in_group():
"""read_frame() only returns the first frame of a multi-frame group."""
broadcast = moq.BroadcastProducer()
track = broadcast.publish_track("mixed")
consumer = track.consume()
consumer = track.consume(moq.Subscription(latency_max_ms=1_000))

group = track.append_group()
group.write_frame(b"first", 0)
Expand Down
10 changes: 7 additions & 3 deletions rs/hang/examples/subscribe.rs
Original file line number Diff line number Diff line change
Expand Up @@ -74,12 +74,16 @@ async fn run_subscribe(consumer: moq_net::origin::Consumer) -> anyhow::Result<()
);

// Subscribe to the video track.
let latency = moq_mux::Latency::max(Duration::from_millis(500));
let track_consumer = broadcast
.track(name)?
.subscribe(moq_net::track::Subscription::default().with_priority(1))
.subscribe(
moq_net::track::Subscription::default()
.with_priority(1)
.with_latency(latency),
)
.await?;
let mut ordered = moq_mux::container::Consumer::new(track_consumer, moq_mux::catalog::hang::Container::Legacy)
.with_latency(moq_mux::Latency::max(Duration::from_millis(500)));
let mut ordered = moq_mux::container::Consumer::new(track_consumer, moq_mux::catalog::hang::Container::Legacy);

// Read frames in latency-bounded presentation order.
while let Some(frame) = ordered.read().await? {
Expand Down
26 changes: 26 additions & 0 deletions rs/kio/src/weak.rs
Original file line number Diff line number Diff line change
Expand Up @@ -275,6 +275,32 @@ impl<T> ConsumerWeak<T> {
}
}

/// Poll the shared state with a closure, exactly as [`Consumer::poll`] does.
///
/// Available here so a watcher can register for changes without joining the
/// consumer count, which is what [`Producer::unused`](crate::Producer::unused)
/// keys off.
pub fn poll<F, R>(&self, waiter: &Waiter, mut f: F) -> Poll<Result<R, Ref<'_, T>>>
where
F: FnMut(&Ref<'_, T>) -> Poll<R>,
{
let state = self.state.lock();
let consumer_state = Ref { state };

if let Poll::Ready(res) = f(&consumer_state) {
return Poll::Ready(Ok(res));
}

if consumer_state.state.closed {
return Poll::Ready(Err(consumer_state));
}

let mut state = consumer_state.state;
waiter.register(&mut state.waiters_value);

Poll::Pending
}

/// Returns `true` if the channel has been closed.
pub fn is_closed(&self) -> bool {
self.state.lock().closed
Expand Down
16 changes: 12 additions & 4 deletions rs/libmoq/src/consume.rs
Original file line number Diff line number Diff line change
Expand Up @@ -379,9 +379,13 @@ impl Consume {
let res = async move {
let track = broadcast
.track(&name)?
.subscribe(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.video))
.subscribe(
moq_net::track::Subscription::default()
.with_priority(hang::catalog::PRIORITY.video)
.with_latency(latency),
)
.await?;
let track = moq_mux::container::Consumer::new(track, container).with_latency(latency);
let track = moq_mux::container::Consumer::new(track, container);
Self::run_track(on_frame, track, channel.1).await
}
.await;
Expand Down Expand Up @@ -428,9 +432,13 @@ impl Consume {
let res = async move {
let track = broadcast
.track(&name)?
.subscribe(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.audio))
.subscribe(
moq_net::track::Subscription::default()
.with_priority(hang::catalog::PRIORITY.audio)
.with_latency(latency),
)
.await?;
let track = moq_mux::container::Consumer::new(track, container).with_latency(latency);
let track = moq_mux::container::Consumer::new(track, container);
Self::run_track(on_frame, track, channel.1).await
}
.await;
Expand Down
13 changes: 12 additions & 1 deletion rs/libmoq/src/test.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1144,12 +1144,23 @@ fn raw_track_publish_consume() {
let consume = request_broadcast(origin, path);

let frame_cb = Callback::new();
// This round trip verifies every published frame. Allow the first group to
// finish draining if the second becomes visible while the callback runs.
let subscription = moq_subscription {
priority: 0,
ordered: false,
latency_max_ms: 1_000,
group_start: 0,
group_start_valid: false,
group_end: 0,
group_end_valid: false,
};
let consumer = id(unsafe {
moq_consume_track(
consume,
track_name.as_ptr() as *const c_char,
track_name.len(),
std::ptr::null(),
&subscription,
Some(channel_callback),
frame_cb.ptr,
)
Expand Down
12 changes: 10 additions & 2 deletions rs/moq-audio/src/decode/consumer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -50,13 +50,17 @@ impl Consumer {
let name = name.into();
let track = broadcast
.track(&name)?
.subscribe(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.audio))
.subscribe(
moq_net::track::Subscription::default()
.with_priority(hang::catalog::PRIORITY.audio)
.with_latency(config.latency),
)
.await?;
// The catalog says how the track is framed, and it is not always the legacy
// wire: `moq import fmp4` publishes CMAF. Reading a moof+mdat fragment as a
// varint timestamp plus a payload decodes to garbage rather than failing.
let container = moq_mux::catalog::hang::Container::try_from(&catalog.container)?;
let track = moq_mux::container::Consumer::new(track, container).with_latency(config.latency);
let track = moq_mux::container::Consumer::new(track, container);

Ok(Self {
decoder,
Expand Down Expand Up @@ -170,23 +174,27 @@ mod tests {
async fn reads_the_container_the_catalog_declares() {
let mut broadcast = moq_net::broadcast::Info::new().produce();
let track = broadcast.create_track("audio", hang::container::track_info()).unwrap();
let observed = track.clone();
let subscriber = broadcast.consume();

let mut catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Pcm, 48_000, 1);
catalog.container = hang::catalog::Container::Loc;

let mut producer = moq_mux::container::Producer::new(track, moq_mux::catalog::hang::Container::Loc);
let latency = moq_mux::Latency::max(std::time::Duration::from_millis(250));
let mut consumer = Consumer::new(
&subscriber,
&catalog,
"audio",
Config {
format: Format::F32,
latency,
..Config::new()
},
)
.await
.unwrap();
assert_eq!(observed.subscription().unwrap().latency, latency);

let samples = [0.25f32, -0.5, 0.75, -1.0];
let payload: Vec<u8> = samples.iter().flat_map(|sample| sample.to_le_bytes()).collect();
Expand Down
3 changes: 2 additions & 1 deletion rs/moq-audio/src/decode/decoder.rs
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,8 @@ pub struct Config {
pub channels: Option<u32>,
/// How far playback may drift from the live edge before skipping a stalled group.
///
/// Forwarded to [`moq_mux::container::Consumer::with_latency`]. Defaults to
/// Applied to the initial transport subscription and inherited by
/// [`moq_mux::container::Consumer`]. Defaults to
/// [`Latency::REAL_TIME`](moq_mux::Latency::REAL_TIME), which skips aggressively.
/// Set [`Latency::max`](moq_mux::Latency::max) to the playout buffer you can
/// tolerate (typically tens to a few hundred ms) for the best
Expand Down
4 changes: 4 additions & 0 deletions rs/moq-audio/tests/roundtrip.rs
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,10 @@ async fn opus_round_trip_48k_stereo() {
let cfg = snapshot.audio.renditions.get("audio").expect("audio rendition");
let mut config = decode::Config::default();
config.format = Format::F32;
// The whole clip is encoded before anything decodes it. The default REAL_TIME
// budget is enforced on the subscription, so without a tolerance the decoder would
// take the live edge and drop the rest of the batch.
config.latency = moq_mux::Latency::max(Duration::from_secs(30));
let mut consumer = decode::Consumer::new(&broadcast_consumer, cfg, "audio", config)
.await
.unwrap();
Expand Down
8 changes: 6 additions & 2 deletions rs/moq-bench/src/connection.rs
Original file line number Diff line number Diff line change
Expand Up @@ -412,6 +412,10 @@ mod tests {
}
}

fn replay() -> track::Subscription {
track::Subscription::default().with_latency(moq_net::Latency::max(Duration::from_secs(30)))
}

/// A produced group must start with the JSON keyframe describing the rolled
/// parameters, followed by `group_size` zeroed payload frames.
#[tokio::test]
Expand All @@ -429,7 +433,7 @@ mod tests {
// Advance past one full group (keyframe + 2 payload) into the next.
tokio::time::advance(Duration::from_millis(350)).await;

let mut sub = consumer.track(TRACK).unwrap().subscribe(None).await.unwrap();
let mut sub = consumer.track(TRACK).unwrap().subscribe(replay()).await.unwrap();
let mut group = sub.next_group().await.unwrap().expect("a group");

let keyframe = group.read_frame().await.unwrap().expect("keyframe");
Expand Down Expand Up @@ -464,7 +468,7 @@ mod tests {
let task = tokio::spawn(produce(0, "bench/test".into(), rolled(10, 4, 0), track, stats.clone()));
tokio::time::advance(Duration::from_millis(250)).await;

let mut sub = consumer.track(TRACK).unwrap().subscribe(None).await.unwrap();
let mut sub = consumer.track(TRACK).unwrap().subscribe(replay()).await.unwrap();
let mut group = sub.next_group().await.unwrap().expect("a group");

// Just the keyframe, then the group ends.
Expand Down
Loading
Loading