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
175 changes: 135 additions & 40 deletions quest/m1/subscribe-ranges/fetch-range.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,20 +15,28 @@ Split out of dynamic range requests, which replaced `requested_group` with
breaks one API once. Resized from [M] to [L] on 2026-10-24, when the first
attempt ([moq-dev/moq#6722](https://github.com/moq-dev/moq/pull/6722)) found
the questions decided below and landed only the `track_range_filling` benchmark.
The second attempt ([moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545))
landed the bounded-read end on a plain cursor, the parking wire publishers,
the cached-backfill rule, the bounded miss grace, and the unfed moq-transport
copy; what remains is below.

- **Ending a bounded read** (decided 2026-10-20). `recv_group` returns `None`
once every sequence in a bounded window is delivered, dropped, stale, or
unfillable. Today it parks past the window's end on purpose, so an update
can still widen it; a reader that wants more keeps an open range instead.
`Ok(None)` before any group arrives is a miss, which the moq-ffi fetch
wrapper reports as `NotFound`; after one, it is the range's end. A one-range
read surfaces no `NotFetchable` or `Old` result, and a peer's reset with
either names the group dropped. Every fetch boundary already treats
`NotFetchable` as not found (relay HTTP 404, hls `is_cache_miss`, moq-ffi
`map_fetch_error`, moq-c `NOT_FOUND`); a fetched `Old` becomes a miss too,
where relay HTTP answers 500 and moq-c reports `OLD` today. Both stay as wire
stream errors, and `Old` still aborts a cut group mid-read.
The Impact bullet says how to migrate each affected package.
unfillable. Landed for a track's own cache: a `with_range` cap never ends a
read, since it may rise again. A front's logical track (a routed track,
`model/resume.rs`) still parks, because each copy's reader parks and the
routes judge the end. Its `Delivered` counts what is no longer owed as
handed out (`track::Subscriber::skip_ordered`), so it cannot account for the
window alone, and `resume_model` asserts a reader never ends before a route
declares an end, which ending there has to change. `Ok(None)` before any group arrives is a miss, which the
moq-ffi fetch wrapper reports as `NotFound`; after one, it is the range's
end. A one-range read surfaces no `NotFetchable` or `Old` result, and a
peer's reset with either names the group dropped. Every fetch boundary
already treats `NotFetchable` as not found (relay HTTP 404, hls
`is_cache_miss`, moq-ffi `map_fetch_error`, moq-c `NOT_FOUND`); a fetched
`Old` becomes a miss too, where relay HTTP answers 500 and moq-c reports
`OLD` today. Both stay as wire stream errors, and `Old` still aborts a cut
group mid-read. The Impact bullet says how to migrate each affected package.
- A one-range subscription for a cached live group missing the frames its
range starts at needs a head fill. Frame bounds
([moq-dev/moq#6129](https://github.com/moq-dev/moq/pull/6129)) hand such a
Expand All @@ -38,37 +46,117 @@ the questions decided below and landed only the `track_range_filling` benchmark.
read has to request it instead of letting `Lagged` reach the caller.
`fill::Ask` already carries a start frame, so the miss judge can count a
headless slot as a hole for a bounded window.
- **Wire publishers keep parking.** The lite subscriber reads an upstream
FIN as the track's end on a published version. Once `recv_group` ends a
bounded read, the IETF publisher and lite publishers before lite-07 keep
parking on a bounded downstream SUBSCRIBE rather than FIN it, or a peer
reads the range's end as the track's. The lite-07 half already landed in
[moq-dev/moq#6807](https://github.com/moq-dev/moq/pull/6807): a lite-07
publisher FINs a covered bounded subscription without SUBSCRIBE_END, which
ends only the subscription.
- **Wire publishers keep parking** (landed). Every wire publisher reads its
subscription through `track::Subscriber::parked`: the IETF publisher and
lite publishers before lite-07 keep parking on a bounded downstream
SUBSCRIBE rather than FIN it, and a lite-07 publisher FINs a covered bounded
subscription without SUBSCRIBE_END
([moq-dev/moq#6807](https://github.com/moq-dev/moq/pull/6807)) until the
explicit end below removes that FIN.
- **Route recovery keeps a frame start.** `resume::Recover` fetches the rest of
a group from frame N on the new route (`group::Fetch::frame_start`), which a
whole-group range cannot say, so a crate-private fetch stays for it.
- **A miss with no feed frontier** (maintainer, 2026-10-25). A reader asks
fills only below the newest group the live feed produced (decision 2 on
[moq-dev/moq#6123](https://github.com/moq-dev/moq/pull/6123)), so on a track
nothing feeds live, such as the moq-archive reader's or a relay copy no
subscription feeds, `Range::groups(5..6)` asks no fill and parks forever.
While the track has no live feed, holes in a bounded range are misses up to
its end. This asks nothing of a live feed; the rejected options were
treating every bounded range's holes as misses, which asks fills for groups
a live feed has yet to produce, and keeping a by-sequence read beside
subscriptions.
- **Cached backfill is owed** (maintainer, 2026-10-25). A range reader never
reads a group another reader's fill cached today: the arrival walk skips
backfill and the miss judge counts it held, so a second `0..1` read after a
first reader's fill cached group 0 parks with no fill asked. A cached
backfill group inside a reader's window is owed to it like its own fill's
answer, so a relay behaves the same warm or cold. This retires
`fetched_backfill_not_subscribed` and
`refilled_sequence_stays_out_of_subscriptions`, which assert that a
subscriber never sees backfill. Re-filling a cached group was rejected: it
costs an upstream FETCH for a group already in the cache.
- **Ends are signaled, not inferred** (maintainer, 2026-11-01, on
[moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545)): "we should
have a SUBSCRIBE_END message or something to signal the last group of a
track? we were using QUIC FIN to signal that but that prevents updates in the
future, so we should have a signal instead". The follow-up answers, the same
day:
- "do we need a SUBSCRIBE_COVERED? We have SUBSCRIBE_DROP so the peer can
determine that the bounded range has been received? SUBSCRIBE_END (rename
to FINISH?) would signal the final group of the track maybe, but would be
independent of the bounded range?" No new message: a subscriber judges a
bounded range complete from the groups it received, SUBSCRIBE_DROP, the
Range Starts in SUBSCRIBE_OK, and SUBSCRIBE_END. Drops and groups name
absolute sequences, so the subscriber judges against its latest ranges and
an update in flight changes nothing it has counted; the FIN's race with an
unread update goes away. One gap: before SUBSCRIBE_OK a lite-07 publisher
holds back what it gave up (`TrackRun::skipped`) and answers only once a
group stream resolves the start, so a bounded subscription none of whose
groups it can serve gets neither, and only the covered FIN ends it today.
Fix: once such a subscription is covered, the publisher sends SUBSCRIBE_OK
and then the drops it held. Datagrams are left out: they become their own
track kind, which takes no ranges (maintainer, 2026-11-01).
- "Keep stream open": SUBSCRIBE_END (or FINISH) names the track's final group
and no longer FINs the Subscribe Stream, so an update can still reach an
ended track's history. The subscriber FINs once it wants nothing more, and
the publisher FINs in reply. The covered FIN goes too.
- ✅ Rename SUBSCRIBE_END to SUBSCRIBE_FINISH in lite-07 (maintainer,
2026-11-01). It matches TRACKS_FINISH and `track::Producer::finish`, and
"END" would read as closing the stream, which it no longer does.

The settled lite-07 wire design, together:
- SUBSCRIBE_FINISH (formerly SUBSCRIBE_END) names the track's final group and
no longer FINs the Subscribe Stream.
- A covered bounded subscription is not FINed either: the subscriber judges
it complete from the groups it received, SUBSCRIBE_DROP, the Range Starts in
SUBSCRIBE_OK, and SUBSCRIBE_FINISH.
- A publisher that held back SUBSCRIBE_OK (`TrackRun::skipped`) sends it, then
the drops it held, once such a subscription is covered.
- The subscriber FINs the stream once it wants nothing more, and the
publisher FINs in reply.
- Datagrams take no ranges, since they become their own track kind. The
datagram-tracks plan
([moq-dev/moq#7575](https://github.com/moq-dev/moq/pull/7575)) touches
`lite.md` too, and should take this design and the rename as given.

This wire half belongs to [lite-07 ranges](/quest/m1/subscribe-ranges/lite.md)
(Rust and the draft) and [JS ranges](/quest/m1/subscribe-ranges/js.md), not
to this quest. It is recorded here while
[moq-dev/moq#7487](https://github.com/moq-dev/moq/pull/7487) rewrites that
quest, and moves there once it lands.
- **The live edge is told, never inferred** (maintainer, 2026-11-01, on
[moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545)): "If the relay
doesn't know the live edge, it shouldn't say anything. It should be a
separate message if it's async or the OK should block. NEVER use the cache
as the live edge." The OK blocks, since the wire already works that way:
lite-07 SUBSCRIBE_OK carries Largest Group and waits until each Range's
start resolves, a relay's `TrackRun` waits on its source's start
(`track::Subscriber::poll_start`) before answering, and an idle copy reads
nothing until its route answers. The draft's exception for a start past the
publisher's largest position should say that a relay knows that position
only from its upstream's answer (lite-07 ranges' draft change). A reader
asks fills only below the newest group the live feed produced (decision 2
on [moq-dev/moq#6123](https://github.com/moq-dev/moq/pull/6123)), so with
nothing produced it waits for the answer that its own demand's upstream
subscription brings. Earlier (maintainer, 2026-10-25): while a track has no
live feed, holes in a bounded range are misses up to its end, and treating
"no group produced" as "no feed" asks too early
(`subscribe_ranges::sparse_ranges_reach_the_publisher_on_lite07` reads
`[0]` on lite-06). moq-archive needs nothing new: its consumer declares the
newest stored sequence with `start_at`.
- **The session marks a copy unfed** (maintainer, 2026-11-01, on
[moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545); landed). ✅
The session marks a copy it holds no upstream subscription for unfed
(`track::Producer::set_unfed`), from its own state, never from the cache.
A bounded read's holes there are misses up to its end at once, per the
2026-10-25 rule, a refusal is final, and the read takes what the cache holds
in its window even while the copy is idle; an open read still waits for a
feed. The moq-transport subscriber marks a lingering copy unfed, such as one
learned from TRACK_STATUS for a fetch, and keeps a subscription whose ranges
all end below the publisher's reported Largest Object out of the upstream
SUBSCRIBE (`fetch_only.rs`). The rejected alternative, a one-range read always
subscribing so its OK names the edge, broke the fetch-only rule below.
- **Every hole ends** (maintainer, 2026-11-01, on
[moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545)): "uhh the
publisher is supposed to emit the start/end bounds if the subscriber didn't
ask for one? I don't understand, but parking forever is terrible?" A hole is
asked as a miss, refused, or covered by the publisher's bounds, and a
bounded read never parks for good. A hole under the start the publisher
resolved is asked at once, and a refusal there is held while the feed may
still deliver the group late (maintainer, 2026-10-21, on
[moq-dev/moq#6171](https://github.com/moq-dev/moq/pull/6171)). Nothing is
inferred from the first arrival, since a local producer may still write a
lower group (`late_lower_group`). Landed: that hold, and the wait before a
hole with no start under it is asked, last the arrival grace, or
`ledger::GRACE` when neither a budget nor a max age bounds it
(`TrackState::miss_grace`), and a held refusal wakes its reader at its
deadline.
- **Cached backfill is owed** (maintainer, 2026-10-25; landed). A cached
backfill group inside a reader's window is taken as filled, whether or not
the live feed may still deliver it, so a relay behaves the same warm or
cold. Re-filling a cached group was rejected: it costs an upstream FETCH for
a group already in the cache.
- **Relay demand before lite-07** (maintainer, 2026-10-25). A one-range read's
ranges join the track's aggregate, so a relay would put a bounded SUBSCRIBE
upstream where `fetch_group` puts a FETCH. `fetch_only.rs` asserts that a
Expand All @@ -80,7 +168,14 @@ the questions decided below and landed only the `track_range_filling` benchmark.
is one range FETCH on moq-transport, and per-group FETCH is lite-only, until
[lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) land. A bounded
upstream SUBSCRIBE accounted by SUBSCRIBE_START and SUBSCRIBE_DROP was
rejected: it works on lite-05 and later only.
rejected: it works on lite-05 and later only. Landed for a lingering
moq-transport copy whose subscription lies wholly below the reported Largest
Object (the unfed copy above). Still to do: a first request with a bounded
subscription, which SUBSCRIBEs before any TRACK_STATUS names an edge; a
subscription only partly below the edge; and lite before lite-07. A
subscription to a copy no SUBSCRIBE accepts waits for the track's info
today, so this also needs a one-range read to resolve from the info its fill
installs.
- **The fill path goes linear first** (maintainer, 2026-10-25). One-range
reads put every past read on the fill path, which `track_range_filling`
measured as superlinear in range count and span. It is flat since
Expand Down
9 changes: 9 additions & 0 deletions rs/moq-net/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ How to update your code for each breaking change, newest first.

## Unreleased

### A bounded subscription ends once its ranges are read

When every one of a subscription's `ranges` has an end, `track::Subscriber::recv_group` and `track::Ordered::next_group` return `None` once each group in them was handed out, dropped, skipped as stale, or given up as unfillable, instead of waiting for an update to widen the ranges.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
This holds for a track read from its own producer's cache. A track read through an origin's routes, such as a remote broadcast's, still waits past its ranges for now, so a reader there stops once it has the groups it asked for rather than waiting for `None`.
A reader that wants to widen its ranges later keeps one open, such as `Range::groups(n..)`, and narrows its reads with `with_range`, whose cap never ends a read.
A group another reader's fetch or fill cached is now handed to every subscriber whose ranges hold it, not only fetches.
A missing group the live feed may still deliver is waited for at most one second before it is asked of a fill or named dropped, when neither the readers' `max_delay` nor the track's max age bounds the wait. Before, a reader with `max_delay: None` on a track with no max age waited for it until the track ended.
Over moq-transport, a subscription to a copy the session holds no upstream subscription for, such as one only fetched so far, whose ranges all end below the publisher's reported Largest Object, is served by FETCH without subscribing upstream. Each missing group is asked at once and a refusal is final, since nothing else would deliver it.

### `broadcast::Demand` reads like `track::Demand`

Replace `is_used()` with `wanted()`, and `used()`, `unused()`, `poll_used`, and `poll_unused` with a loop over `wanted_changed()` (or `poll_wanted_changed`), which returns the new value each time it changes and errors once the broadcast closes.
Expand Down
3 changes: 2 additions & 1 deletion rs/moq-net/src/ietf/publisher.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1959,7 +1959,8 @@ impl Publisher {
.until_withdrawn(stream, |waiter| subscribing.poll_ok(waiter))
.await?
{
Ok(subscribed) => subscribed,
// A peer reads the end of the subscription as the track's.
Ok(subscribed) => subscribed.parked(),
Err(err) => return Some(Err(err)),
};
drop(subscribing);
Expand Down
29 changes: 26 additions & 3 deletions rs/moq-net/src/ietf/subscriber.rs
Original file line number Diff line number Diff line change
Expand Up @@ -751,6 +751,18 @@ fn largest_group(track: &track::Producer, answer: Option<ietf::Location>) -> Opt
answer.map(|largest| largest.group).max(track.latest_sequence())
}

/// Whether `subscription` needs a live feed for a copy whose publisher reported its Largest
/// Object in group `edge`: one of its ranges is open, counts back from the live edge, or
/// reaches the group the publisher may still be writing. Ranges wholly below it read only
/// history, which fills serve.
fn wants_feed(subscription: &track::Subscription, edge: Option<u64>) -> bool {
if subscription.ranges.is_empty() {
return false;
}
let history = subscription.start().is_some() && subscription.end().zip(edge).is_some_and(|(end, edge)| end <= edge);
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
!history
}

/// A copy with no subscription upstream, kept for fetches and a returning subscriber.
struct Idle {
track: track::Producer,
Expand Down Expand Up @@ -3963,6 +3975,12 @@ impl Subscriber {
/// Keep a copy nobody subscribes to, cache and all, for fetches and a subscriber
/// returning soon: `Some` once one does, to subscribe again, `None` once nobody held
/// it through the linger, or the session ended. A finished copy never subscribes again.
///
/// The session holds no upstream subscription for the copy meanwhile, so it marks the
/// copy unfed: a bounded read's holes are misses at once, which the fills answer. A
/// subscription whose ranges all lie below the Largest Object the publisher reported
/// reads only history, so it is served that way too, as a FETCH would be, rather than
/// subscribing.
async fn linger(
&mut self,
broadcast_path: &Path,
Expand All @@ -3980,10 +3998,11 @@ impl Subscriber {
id
};
let mut linger = crate::time::Deadline::new(&self.runtime);
idle.track.set_unfed(true);
let mut subscribed = idle
.track
.subscription()
.is_some_and(|subscription| !subscription.ranges.is_empty());
.is_some_and(|subscription| wants_feed(&subscription, idle.track.reported_group()));
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
enum Step {
Fill(track::Fill),
Subscribe,
Expand All @@ -4006,7 +4025,7 @@ impl Subscriber {
while let Poll::Ready(Ok(subscription)) = idle.track.poll_subscription_changed(waiter) {
subscribed = subscription
.as_ref()
.is_some_and(|subscription| !subscription.ranges.is_empty());
.is_some_and(|subscription| wants_feed(subscription, idle.track.reported_group()));
}
if subscribed && !idle.finished {
return Poll::Ready(Step::Subscribe);
Expand Down Expand Up @@ -4038,7 +4057,11 @@ impl Subscriber {
);
group_fetches.push(fetch);
}
Step::Subscribe => break true,
Step::Subscribe => {
// Marked before the SUBSCRIBE goes out: a hole may arrive live from here.
idle.track.set_unfed(false);
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
break true;
}
Step::Expired => match idle.track.abort_unwanted(Error::Cancel) {
Ok(()) => {
tracing::debug!(broadcast = %crate::path::Rooted(self.origin.root(), broadcast_path), track = %track_name, "track released (idle)");
Expand Down
3 changes: 2 additions & 1 deletion rs/moq-net/src/lite/publisher.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4003,7 +4003,8 @@ impl TrackRun {
// Apply the initial cap from the original Subscribe. Subsequent updates
// flow through the SUBSCRIBE_UPDATE arm below.
let cap = bounds.groups().end().map_or(Bound::Unbounded, Bound::Excluded);
let track = track.with_range((Bound::Included(floor), cap));
// The FIN of a covered subscription is the wire's to send, below.
let track = track.with_range((Bound::Included(floor), cap)).parked();

let emit_range = ctx.version.has_track_stream();
let datagrams = ctx.version.has_datagrams() && ctx.session.max_datagram_size() > 0;
Expand Down
Loading