You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
refactor(net): make group delivery order a handle, and move timestamp-based skipping into moq-net #3086
track::Subscriber exposes two delivery orders as two methods on one handle:
recv_group / read_frame walk an arrival index (PlainSubscriber::index)
next_group seeks by sequence (PlainSubscriber::next_sequence)
The cursors are not independent. recv_datagram bumps next_sequence, and read_frame bumps both index and next_sequence. Interleaving the two orders on one subscriber is expressible today and the result is hard to reason about, so the rule lives in doc comments rather than in the type.
Proposal: make the order a handle rather than a method choice, e.g. track::Consumer::ordered() returning a cursor that only yields groups in sequence order, with the arrival-order cursor keeping the plain path. That makes mixing the two unrepresentable instead of merely discouraged, per the Public API Scrutiny rules in CLAUDE.md.
Timestamp-based group skipping
The longer-term goal is to move the group-skipping logic out of moq-mux and into moq-net. Today it lives in rs/moq-mux/src/container/consumer.rs (poll_read), which decides whether to abandon a stalled group by comparing poll_min_timestamp / poll_max_timestamp across buffered groups against a latency budget.
The reason it lives in moq-mux is that those timestamps come from parsing the container format through F: Format. That constraint has weakened: on Lite05+ the wire carries per-frame timestamps at the track's own timescale (TRACK_INFO plus zigzag-delta frame timestamps), so moq-net can read them without knowing anything about the media. That keeps the "the relay does not know anything about media" rule intact.
Open questions before this is designed:
What happens on wires that cannot carry the timescale (pre-Lite05 moq-lite, IETF moq-transport), where timestamps fall back to local monotonic milliseconds? A skip policy keyed on those means something different than one keyed on author timestamps.
Does the skip policy belong on the ordered cursor itself, on Subscription (so the publisher's aggregate sees it), or both?
What does moq-mux keep? Discontinuity marking and the empty-group boundary handling in poll_read are container concerns even if the skip decision moves down.
Context
Split out of the poll_next_in_range fix, which made the sequence-ordered path a BTreeMap seek instead of a full cache scan. That removed the performance argument for treating sequence order as the slower opt-in path; the API argument above stands on its own.
Design settled after a grilling session. This supersedes parts of the original proposal above, most notably the default order is inverted and the ordered wire field is removed rather than reused.
Decisions
Base: dev (already has the max_age rename), building on the poll_next_in_range seek change. One PR lands rs + drafts + js/net together; moq-ffi + bindings + doc/ follow as an immediately stacked PR.
API shape
Subscriber::ordered(self) -> track::Ordered. Consuming self makes mixing the two group cursors unrepresentable. It takes no arguments: the skip budget is Subscription::max_age, the single knob, updatable mid-stream via SubscriberControl.
The plain Subscriber keeps the arrival cursor (recv_group) and datagrams (recv_datagram). Datagrams are unordered and stop bumping any group cursor. The relay forwarders (lite/ietf publishers) and moq-mux stay on the plain handle; mux keeps its pending buffer, rewind detection/classification, duration-based covered skip, discontinuity marking, and empty-group boundary handling for now.
track::Ordered gets next_group (+ poll), its own start_at/end_at, control, finished. Cursor state is a bare u64 plus a seek. The shared facts it needs (per-group min/max frame timestamp and a first-arrival stamp) are maintained on write in track/group state, so the unordered path pays nothing.
read_frame is removed from the track level. Today it is two different functions under one name (Plain: one frame per group then skip; Spliced: drain every frame in sequence). Callers loop next_group() + group read_frame() instead.
Skip semantics (copying moq-mux, at group granularity)
Dual measure per the draft: a group's age is the minimum of its timestamp age and its arrival age; empty groups age by wall clock only.
The reference is the newest group this cursor has observed, not the track live edge, so a catch-up backlog is not nuked on subscribe.
Burst, never discard: cached/arrived groups are always served in order. The budget only refuses to wait on a blocking group when something newer exists (plus the futility rule for gaps that can never fill).
max_age: ZERO stays the default and means: the publisher transmits latest-only when behind and resets stalled non-latest streams, while the cursor bursts whatever already arrived. Note this makes the wire field enforced for the first time; today next_group never time-skips and max_age is enforced nowhere. The migration flags this per caller (moq-json, msf catalog, moq-transcode, libmoq raw all move to ordered()).
Cache
Publisher Max Age is a hard retention ceiling the publisher enforces, so TRACK_INFO never over-promises. Within it, last-access LRU, the byte budget, and origin cache_duration may evict sooner. Subscriber max age never touches retention; it is delivery-only.
Frame-level expiry within a group: rejected. Groups stay the eviction unit.
Wire + draft (draft-lcurley-moq-lite.md)
Rename both fields to Max Age (prose only; encoding unchanged).
Remove ordered entirely: model, Subscription, Info, aggregation, and the lite-06-wip wire. Nothing ever read it to schedule (the priority queue ranks by track priority + group sequence with a fixed policy). Deployed lite-03/04/05 codecs keep the byte hardcoded (write 0, ignore on read). The prioritization section becomes normative newest-first within a track under congestion. The IETF adapter maps to a fixed group order.
Draft changelog records both; validated with just drafts check.
Findings that shaped the design
The relay polls arrival-order groups and datagrams from one &mut Subscriber borrow (poll_recv_next), which is why datagrams went unordered rather than onto the ordered handle.
read_frame had diverging semantics between the Plain and Spliced subscribers, which is why it is removed rather than moved.
Subscription::max_age is aggregated, clamped, and put on the wire today, but enforced by nothing, so ZERO gaining teeth is a real behavior change and is called out above.
The moq-mux covered skip trigger needs per-frame durations, which the wire does not carry, so it stays in mux along with the rest of the container-level policy.
Closing as not planned. The first half (the ordered delivery handle) landed on dev as #3099. The second half, moving timestamp-based group skipping from moq-mux into moq-net, was declined in the quest audit (#3416): moq-mux keeps its own skip because it can rely on frame durations, which moq-net does not have, so the skip policy stays media-side.
Activity
kixelated commentedon Aug 27, 2026
Design settled after a grilling session. This supersedes parts of the original proposal above, most notably the default order is inverted and the
orderedwire field is removed rather than reused.Decisions
Base:
dev(already has themax_agerename), building on thepoll_next_in_rangeseek change. One PR lands rs + drafts + js/net together; moq-ffi + bindings + doc/ follow as an immediately stacked PR.API shape
Subscriber::ordered(self) -> track::Ordered. Consumingselfmakes mixing the two group cursors unrepresentable. It takes no arguments: the skip budget isSubscription::max_age, the single knob, updatable mid-stream viaSubscriberControl.Subscriberkeeps the arrival cursor (recv_group) and datagrams (recv_datagram). Datagrams are unordered and stop bumping any group cursor. The relay forwarders (lite/ietfpublishers) and moq-mux stay on the plain handle; mux keeps itspendingbuffer, rewind detection/classification, duration-basedcoveredskip, discontinuity marking, and empty-group boundary handling for now.track::Orderedgetsnext_group(+ poll), its ownstart_at/end_at,control,finished. Cursor state is a bareu64plus a seek. The shared facts it needs (per-group min/max frame timestamp and a first-arrival stamp) are maintained on write in track/group state, so the unordered path pays nothing.read_frameis removed from the track level. Today it is two different functions under one name (Plain: one frame per group then skip; Spliced: drain every frame in sequence). Callers loopnext_group()+ groupread_frame()instead.Skip semantics (copying moq-mux, at group granularity)
max_age: ZEROstays the default and means: the publisher transmits latest-only when behind and resets stalled non-latest streams, while the cursor bursts whatever already arrived. Note this makes the wire field enforced for the first time; todaynext_groupnever time-skips andmax_ageis enforced nowhere. The migration flags this per caller (moq-json, msf catalog, moq-transcode, libmoq raw all move toordered()).Cache
cache_durationmay evict sooner. Subscriber max age never touches retention; it is delivery-only.Wire + draft (
draft-lcurley-moq-lite.md)orderedentirely: model,Subscription,Info, aggregation, and the lite-06-wip wire. Nothing ever read it to schedule (the priority queue ranks by track priority + group sequence with a fixed policy). Deployed lite-03/04/05 codecs keep the byte hardcoded (write 0, ignore on read). The prioritization section becomes normative newest-first within a track under congestion. The IETF adapter maps to a fixed group order.just drafts check.Findings that shaped the design
&mut Subscriberborrow (poll_recv_next), which is why datagrams went unordered rather than onto the ordered handle.read_framehad diverging semantics between the Plain and Spliced subscribers, which is why it is removed rather than moved.Subscription::max_ageis aggregated, clamped, and put on the wire today, but enforced by nothing, so ZERO gaining teeth is a real behavior change and is called out above.coveredskip trigger needs per-frame durations, which the wire does not carry, so it stays in mux along with the rest of the container-level policy.(written by Claude Fable 5)
kixelated commentedon Sep 5, 2026
Closing as not planned. The first half (the ordered delivery handle) landed on
devas #3099. The second half, moving timestamp-based group skipping from moq-mux into moq-net, was declined in the quest audit (#3416): moq-mux keeps its own skip because it can rely on frame durations, which moq-net does not have, so the skip policy stays media-side.(written by Claude Fable 5.1)