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: 0 additions & 1 deletion quest/m1/subscribe-ranges/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,6 @@ every sequence delivered or dropped.
- [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - the lite-07 wire, Rust publisher and subscriber, and the draft
- [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md) - range FETCH upstream per missing run, and non-blocking FETCH served downstream
- [JS ranges](/quest/m1/subscribe-ranges/js.md) - `@moq/net` model and lite-07 parity
- [Frame bounds](/quest/m1/subscribe-ranges/frame-bounds.md) - a local subscriber reads only the frames its ranges cover

## Related

Expand Down
5 changes: 3 additions & 2 deletions quest/m1/subscribe-ranges/dynamic.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,9 @@ Decided by the maintainer on 2026-10-20, when the quest was first started

- **Split.** This quest replaces `requested_group`; removing `fetch_group`
is [fetch as a range](/quest/m1/subscribe-ranges/fetch-range.md), so each
PR breaks one API once. That half needs head fills, which
[frame bounds](/quest/m1/subscribe-ranges/frame-bounds.md) provides.
PR breaks one API once. That half needs head fills for a range starting
mid-group, which build on frame bounds
([moq-dev/moq#6129](https://github.com/moq-dev/moq/pull/6129)).
- **Handler shape.** `Dynamic::requested_fill` yields a `track::Fill` naming
one bounded run: `start: Position`, exclusive end group, priority, the most
tolerant budget among its readers, and order. Each reader's cursor still
Expand Down
8 changes: 6 additions & 2 deletions quest/m1/subscribe-ranges/fetch-range.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,14 @@ breaks one API once.
stream errors, and `Old` still aborts a cut group mid-read.
Each affected package gets a `MIGRATE.md` entry.
- A one-range subscription for a cached live group missing the frames its
range starts at needs a head fill, which is why this requires frame bounds.
range starts at needs a head fill. Frame bounds
([moq-dev/moq#6129](https://github.com/moq-dev/moq/pull/6129)) hand such a
group out positioned at the asked frame, so reading the missing head returns
`Error::Lagged` rather than the group being skipped (maintainer,
2026-10-20). Only `fetch_group` requests a head fill today, so the one-range
read has to request it instead of letting `Lagged` reach the caller.
- Benchmark filling beside `track_range_serving`, which covers serving.

## Required

- [Dynamic range requests](/quest/m1/subscribe-ranges/dynamic.md) - `requested_fill` and subscriptions filling their misses
- [Frame bounds](/quest/m1/subscribe-ranges/frame-bounds.md) - head fills for a range starting mid-group
37 changes: 0 additions & 37 deletions quest/m1/subscribe-ranges/frame-bounds.md

This file was deleted.

6 changes: 6 additions & 0 deletions rs/moq-net/src/model/group.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2454,6 +2454,12 @@ impl Consumer {
self.cursor.state.read().wire().cloned()
}

/// Whether the group was relayed from moq-transport, whose Object IDs may not be its frame
/// ordinals.
pub(super) fn relayed(&self) -> bool {
self.cursor.state.read().wire().is_some()
}

/// Read a compressed group's stored DEFLATE slices instead of plain frames, with each
/// frame's inflated size beside it ([`frame::Object::inflated`],
/// [`frame::Consumer::inflated`]), for egress that carries compression. A no-op on a
Expand Down
5 changes: 3 additions & 2 deletions rs/moq-net/src/model/subscription.rs
Original file line number Diff line number Diff line change
Expand Up @@ -75,8 +75,8 @@ pub struct Subscription {
/// for nothing.
///
/// A request to the publisher, aggregated across every live subscriber as the union of
/// their ranges, and this subscriber's read filter: it reads only the groups its own
/// ranges cover, whatever another subscriber widens the union to.
/// their ranges, and this subscriber's read filter: it reads only the groups and frames
/// its own ranges cover, whatever another subscriber widens the union to.
/// [`crate::track::Subscriber::set_groups`] narrows the reads further. See [Local cursor
/// vs wire preference](crate::track::Subscriber#local-cursor-vs-wire-preference).
pub ranges: Vec<Range>,
Expand Down Expand Up @@ -305,6 +305,7 @@ impl Subscription {
/// from the latest group (or none is asked for).
///
/// The form a wire without ranges carries: a floor below which nothing is requested.
#[cfg(any(feature = "async", test))]
// pending: /quest/m1/public-model/serve.md
pub(crate) fn start(&self) -> Option<Position> {
let mut floor: Option<Position> = None;
Expand Down
161 changes: 139 additions & 22 deletions rs/moq-net/src/model/subscription/window.rs
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,23 @@ struct Span {
floored: bool,
}

impl Span {
/// The exclusive end of the groups read now, `None` for none: an unsettled time end
/// reads up to its cap.
fn limit(&self) -> Option<u64> {
match self.end {
End::Before(end) => Some(end),
End::Open => None,
End::Time(time) => time.limit,
}
}

/// Whether group `sequence` is read now.
fn covers(&self, sequence: u64) -> bool {
sequence >= self.start && self.limit().is_none_or(|end| sequence < end)
}
}

#[derive(Clone, Copy, Debug)]
enum End {
/// Before this group.
Expand Down Expand Up @@ -372,16 +389,25 @@ impl Window {
}

/// Whether a datagram is in range, judged on its own and never through a time end's
/// settling: its `timestamp` against each range's times, and its `sequence` against the
/// range's absolute groups and the relative ones resolved so far.
pub fn admits_datagram(&self, sequence: u64, timestamp: Option<Timestamp>) -> bool {
/// settling: its `timestamp` against each range's times, its `sequence` against the
/// range's absolute groups and the relative ones resolved so far, and its `object` ID
/// against the frames that same range covers in its group.
pub fn admits_datagram(&self, sequence: u64, timestamp: Option<Timestamp>, object: u64) -> bool {
let framed = |range: &Range| {
let (start, end) = frames(range, sequence);
object >= start && end.is_none_or(|end| object < end)
};
let Some(timestamp) = timestamp else {
return self.contains(sequence);
return self.pending
|| self
.spans
.iter()
.any(|span| span.covers(sequence) && framed(&self.ranges[span.index]));
};
self.ranges
.iter()
.enumerate()
.filter(|(_, range)| !range.is_empty())
.filter(|(_, range)| !range.is_empty() && framed(range))
.any(|(index, range)| {
// A relative anchor still waiting on a latest group bounds nothing yet.
let span = self.spans.iter().find(|span| span.index == index);
Expand Down Expand Up @@ -459,6 +485,28 @@ impl Window {
all.into_iter().chain(runs.into_iter().flatten())
}

/// The frames of group `sequence` in range: from a start frame up to an exclusive end,
/// `None` through the group's end.
///
/// Only an absolute anchor names a frame, so a group a range starts or ends inside reads
/// part of itself and every other group reads whole. Ranges that cover a group
/// differently read the hull of their frames, since a group is handed out once, as one
/// run of frames. Everything while a relative anchor waits.
pub fn frames(&self, sequence: u64) -> (u64, Option<u64>) {
if self.pending {
return (0, None);
}
let mut hull = None;
for span in self.spans.iter().filter(|span| span.covers(sequence)) {
let (start, end) = frames(&self.ranges[span.index], sequence);
hull = Some(match hull {
None => (start, end),
Some((low, high)) => (start.min(low), end.zip(high).map(|(end, high)| end.max(high))),
});
Comment on lines +502 to +505

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Preserve holes between same-group frame ranges

When two requested ranges cover disjoint portions of the same group, collapsing them to their hull returns frames that neither range requested. For example, ranges [group 4 frame 1, frame 2) and [group 4 frame 5, frame 6) produce bounds 1..6, leaking frames 2 through 4 through both arrival and ordered reads. Preserve the disjoint intervals or filter individual frame reads instead of widening them to a hull.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Declining. A group is handed out once, as one run of frames, so a reader can't skip frames 2 through 4 inside it without a per-frame filter on group::Consumer that nothing else needs. The wire has the same shape: a lite group stream is one contiguous run, so a relay serving these two ranges sends the hull too, and the model matches what a remote subscriber would get. Two ranges splitting one group with a hole is also not a decodable request for media, where frames depend on earlier ones. The frames doc now says why it reads the hull. Datagrams, which carry their own Object ID, are now judged per range (see the other thread), so they do honor the hole.

(Written by Claude Opus 5.5)

}
hull.unwrap_or((0, None))
}

/// The first run of `range` that is in range.
pub fn clip(&self, range: ops::Range<u64>) -> Option<ops::Range<u64>> {
let last = range.end.checked_sub(1).filter(|last| *last >= range.start)?;
Expand Down Expand Up @@ -513,12 +561,7 @@ impl Window {
self.settled = !self.pending && !self.spans.iter().any(|span| matches!(span.end, End::Time(_)));
self.groups = RangeInclusiveSet::new();
for span in &self.spans {
let end = match span.end {
End::Before(end) => Some(end),
End::Open => None,
End::Time(time) => time.limit,
};
let last = match end {
let last = match span.limit() {
Some(end) => match end.checked_sub(1) {
Some(last) if last >= span.start => last,
_ => continue,
Expand All @@ -530,6 +573,21 @@ impl Window {
}
}

/// The frames of group `sequence` that `range` names, if it covers that group: from a start
/// frame up to an exclusive end, `None` through the group's end. Only an absolute anchor
/// names a frame; a head-of-group end covers nothing of its group, so it never gets here.
fn frames(range: &Range, sequence: u64) -> (u64, Option<u64>) {
let start = match range.start {
Anchor::Absolute(start) if start.group == sequence => start.frame,
_ => 0,
};
let end = match range.end {
Some(Anchor::Absolute(end)) if end.group == sequence => Some(end.frame),
_ => None,
};
(start, end)
}

/// The first group a range starts at, and whether it names that group rather than
/// reaching back to the oldest one. `None` while it waits on a latest group.
fn start(anchor: Anchor, latest: Option<u64>, holdings: &impl Holdings) -> Option<(u64, bool)> {
Expand Down Expand Up @@ -722,6 +780,44 @@ mod tests {
assert_eq!((window.floor(), window.end()), (Some(0), Some(0)));
}

/// Only a group an absolute anchor falls inside reads part of itself, and overlapping
/// ranges read the hull of their frames there.
#[test]
fn frames_bound_only_the_groups_an_anchor_falls_inside() {
let at = |group, frame| Anchor::Absolute(Position { group, frame });
let window = Window::new(&[range(at(4, 5), at(6, 3))], None, &Untimed).unwrap();
assert_eq!(window.frames(4), (5, None));
assert_eq!(window.frames(5), (0, None));
assert_eq!(window.frames(6), (0, Some(3)));

// Within one group, both ends bound it.
let window = Window::new(&[range(at(4, 2), at(4, 7))], None, &Untimed).unwrap();
assert_eq!(window.frames(4), (2, Some(7)));

// A second range reaching further either way widens the group to cover both.
let window = Window::new(&[range(at(4, 5), at(4, 7)), range(at(4, 2), at(4, 6))], None, &Untimed).unwrap();
assert_eq!(window.frames(4), (2, Some(7)));
let window = Window::new(&[range(at(4, 5), None), range(at(2, 0), at(4, 3))], None, &Untimed).unwrap();
assert_eq!(window.frames(4), (0, None));

// Relative anchors cover whole groups, and a pending one bounds nothing yet.
let window = Window::new(&[range(Anchor::Relative(1), at(9, 2))], Some(9), &Untimed).unwrap();
assert_eq!((window.frames(8), window.frames(9)), ((0, None), (0, Some(2))));
let window = Window::new(&[range(at(4, 5), None), Range::live()], None, &Untimed).unwrap();
assert_eq!(window.frames(4), (0, None));

// A time end covers whole groups, through its cap while it waits to settle.
let groups = Groups::new([Groups::started(4, 4000), Groups::started(5, 5000), (6, Held::Pending)]);
let window = Window::new(
&[range(at(6, 2), None), range(time(4500), time(5000))],
Some(6),
&groups,
)
.unwrap();
assert!(!window.is_settled());
assert_eq!(window.frames(6), (0, None));
}

/// Relative anchors count back from the latest group, both ends whole groups, and wait
/// for a first group when there is none.
#[test]
Expand Down Expand Up @@ -895,8 +991,8 @@ mod tests {
&Groups::default(),
)
.unwrap();
assert!(window.admits_datagram(9, Some(at(3500))));
assert!(!window.admits_datagram(9, Some(at(3600))));
assert!(window.admits_datagram(9, Some(at(3500)), 0));
assert!(!window.admits_datagram(9, Some(at(3600)), 0));
}

/// Groups whose `racing` one starts past the end after the first time it is asked
Expand Down Expand Up @@ -1000,18 +1096,18 @@ mod tests {
};
let window = Window::new(&[range(time(0), time(5000))], None, &groups).unwrap();
assert_eq!(window.resolved(), vec![Some(Resolved { start: 0, end: Some(2) })]);
assert!(window.admits_datagram(1, Some(at(4000))));
assert!(!window.admits_datagram(1, Some(at(7000))));
assert!(window.admits_datagram(1, Some(at(4000)), 0));
assert!(!window.admits_datagram(1, Some(at(7000)), 0));
}

#[test]
fn a_waiting_window_judges_a_datagram_against_both_times() {
let window = Window::new(&[range(time(3000), time(3500))], None, &Groups::default()).unwrap();
assert!(window.is_pending(), "no group has started");
assert!(!window.admits_datagram(0, Some(at(2900))));
assert!(window.admits_datagram(1, Some(at(3000))));
assert!(window.admits_datagram(2, Some(at(3500))));
assert!(!window.admits_datagram(3, Some(at(3600))));
assert!(!window.admits_datagram(0, Some(at(2900)), 0));
assert!(window.admits_datagram(1, Some(at(3000)), 0));
assert!(window.admits_datagram(2, Some(at(3500)), 0));
assert!(!window.admits_datagram(3, Some(at(3600)), 0));
}

#[test]
Expand All @@ -1023,9 +1119,30 @@ mod tests {
)
.unwrap();
assert!(window.is_pending(), "no group has started");
assert!(window.admits_datagram(9, Some(at(3500))));
assert!(!window.admits_datagram(10, Some(at(3500))));
assert!(!window.admits_datagram(9, Some(at(2900))));
assert!(window.admits_datagram(9, Some(at(3500)), 0));
assert!(!window.admits_datagram(10, Some(at(3500)), 0));
assert!(!window.admits_datagram(9, Some(at(2900)), 0));
}

/// A datagram is in range only when one range admits its sequence, time, and Object ID
/// together, not when each passes a different range.
#[test]
fn a_datagram_is_judged_against_one_range_at_a_time() {
let pos = |group, frame| Anchor::Absolute(Position { group, frame });
let groups = Groups::new([Groups::started(5, 5000)]);
// The time range covers group 5 whole, but only from 5500 on.
let window = Window::new(&[range(pos(5, 1), None), range(time(5500), None)], Some(5), &groups).unwrap();
assert!(!window.admits_datagram(5, Some(at(5000)), 0));
assert!(window.admits_datagram(5, Some(at(5000)), 1));
assert!(window.admits_datagram(5, Some(at(5500)), 0));

// Untimed, two ranges splitting a group admit only the Object IDs each names.
let window = Window::new(&[range(pos(4, 1), pos(4, 2)), range(pos(4, 5), None)], None, &Untimed).unwrap();
assert_eq!(window.frames(4), (1, None), "a group stream reads the hull");
let admitted: Vec<u64> = (0..7)
.filter(|object| window.admits_datagram(4, None, *object))
.collect();
assert_eq!(admitted, vec![1, 5, 6]);
}

#[test]
Expand Down
Loading
Loading