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
4 changes: 2 additions & 2 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -500,7 +500,7 @@ A subscriber MUST support gaps and out-of-order delivery regardless.

## Expiration
Expiration governs when an older group is dropped.
The publisher SHOULD reset Group Streams for non-latest groups whose age relative to the latest group exceeds `Subscriber Max Age` (see [SUBSCRIBE](#subscribe)); the subscriber MAY also locally drop such groups.
The publisher SHOULD reset Group Streams for non-latest groups whose age relative to the latest group reaches `Subscriber Max Age` (see [SUBSCRIBE](#subscribe), and the age definition below); the subscriber MAY also locally drop such groups.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Use the inclusive expiration threshold throughout the draft

This now specifies expiration when age reaches Subscriber Max Age, but the Subscriber Max Age field definition still says a publisher resets groups only when their age exceeds the duration (draft-lcurley-moq-lite.md:969-972). At exact equality, including the important zero-budget case, implementations following the field definition can retain a group that the normative Expiration section and both implementations consider expired. Update the field definition to use the same inclusive threshold.

Useful? React with 👍 / 👎.

Expiration only removes the group from live delivery; the publisher MAY still retain it for FETCH or new subscriptions until its age exceeds `Publisher Max Age` (see [TRACK_INFO](#track-info)).

It is not crucial to aggressively expire groups thanks to [prioritization](#prioritization), but a lower priority group still consumes RAM, bandwidth, and potentially flow control.
Expand Down Expand Up @@ -978,7 +978,7 @@ See the [Expiration](#expiration) section for more information.
The minimum group sequence to deliver: an absolute floor, defaulting to 0 (no floor).

A floor is not a request; `Subscriber Max Age` is the only thing that asks for data.
The publisher SHOULD start at the oldest group at or above the floor whose age (relative to the latest group, measured from its first frame) is within `Subscriber Max Age`, and MUST NOT deliver an older one.
The publisher SHOULD start at the oldest group at or above the floor that [Expiration](#expiration) has not expired, and MUST NOT deliver an older one.
A `Subscriber Max Age` of 0 therefore starts at the latest group, since every older group is already stale.
A subscriber that buffers is then handed the head of what it can still play instead of only the live edge, and is never sent history it would discard on arrival: the same bound decides what to start at and what to expire, so the two cannot disagree.
A floor above the latest group simply waits there: that is a resumed subscription naming where it left off.
Expand Down
16 changes: 13 additions & 3 deletions js/json/src/snapshot/consumer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -35,10 +35,20 @@ export class Consumer<T> {
*/
async next(): Promise<T | undefined> {
for (;;) {
// A newer group supersedes everything the current one still holds: it restarts
// from a full snapshot, so switching mid-group loses nothing but stale state
// (mirrors the Rust consumer, which drains to the newest group every poll).
if (this.#group !== undefined) {
const latest = this.#track.latest();
if (latest !== undefined && latest > this.#group.sequence) {
this.#group.close();
this.#group = undefined;
}
}

if (!this.#group) {
// Collapse the retained backlog: every group restarts from a full snapshot, so
// older groups only hold superseded state. Jump the cursor to the newest
// buffered group instead of replaying each one (mirrors the Rust consumer).
// Collapse the retained backlog: older groups only hold superseded state, so
// jump the cursor to the newest buffered group instead of replaying each one.
const latest = this.#track.latest();
if (latest !== undefined) this.#track.startAt(latest);
// Advance to the next group with a higher sequence number (skipping late arrivals).
Expand Down
31 changes: 26 additions & 5 deletions js/json/src/snapshot/snapshot.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ test("a cut makes the next update a snapshot group", async () => {

// The ratio would have kept every update in one group; the cut rolled it anyway. The replacement
// opens with a full snapshot, so it is one frame rather than a delta appended to the first group.
expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }))).toEqual([2, 1]);
expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }).ordered())).toEqual([2, 1]);
expect((await drain(track.subscribe({ maxAge: REPLAY_LATENCY }))).at(-1)).toEqual({ a: 1, b: 3 });
});

Expand All @@ -57,7 +57,7 @@ test("a cut republishes an unchanged value", async () => {
producer.update({ a: 1 });
producer.finish();

expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }))).toEqual([1, 1]);
expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }).ordered())).toEqual([1, 1]);
});

test("a cut opens no replacement group", async () => {
Expand All @@ -68,7 +68,7 @@ test("a cut opens no replacement group", async () => {
producer.finish();

// Cutting closes the open group and stops there: no empty group for a consumer to advance into.
expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }))).toEqual([1]);
expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }).ordered())).toEqual([1]);
});

test("a cut is idempotent", async () => {
Expand All @@ -86,7 +86,7 @@ test("a cut is idempotent", async () => {
producer.update({ a: 2 });
producer.finish();

expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }))).toEqual([1, 1]);
expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }).ordered())).toEqual([1, 1]);
});

test("a cut is inert without deltas", async () => {
Expand All @@ -99,7 +99,7 @@ test("a cut is inert without deltas", async () => {
producer.update({ a: 2 });
producer.finish();

expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }))).toEqual([1, 1]);
expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }).ordered())).toEqual([1, 1]);
});

test("deltas off: a snapshot group per change", async () => {
Expand Down Expand Up @@ -127,6 +127,27 @@ test("deltaRatio 0 disables deltas, like off", async () => {
expect(await structure(track.subscribe({ maxAge: REPLAY_LATENCY }).ordered())).toEqual([1, 1]);
});

// A consumer holding a group must jump when a newer snapshot group rolls: the
// buffered deltas in the held group only reconstruct superseded state, and every
// group restarts from a full snapshot (mirrors the Rust consumer, which drains to
// the newest group on every poll).
test("a held group is abandoned when a newer snapshot group rolls", async () => {
const track = new Track.Producer("test");
// A tiny ratio forces the update after any delta to roll a fresh snapshot group.
const producer = new Producer<Value>({ track, deltaRatio: 0.001 });
const consumer = new Consumer<Value>(track.subscribe({ maxAge: REPLAY_LATENCY }));

producer.update({ a: 1 });
expect(await consumer.next()).toEqual({ a: 1 });

// A delta lands in the held group, then the ratio rolls a new snapshot group.
producer.update({ a: 2 });
producer.update({ a: 3 });
producer.finish();

expect(await consumer.next()).toEqual({ a: 3 });
});

test("live consumer sees each update", async () => {
const track = new Track.Producer("test");
const producer = new Producer<Value>({ track });
Expand Down
17 changes: 17 additions & 0 deletions js/net/src/track.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,23 @@ test("the latency budget skips a buffered timeline only on the arrival cursor",
expect((await ordered.nextGroup())?.sequence).toBe(2);
});

// An unstamped immediate successor leaves a group's reach unbounded: a later stamped
// group proves nothing about where the successor will begin, and shrinking the bound
// is the unsafe direction.
test("an unstamped immediate successor leaves reach unbounded", async () => {
const producer = new TrackProducer("test").accept({ maxAge: 5000 });
const track = producer.subscribe();

producer.writeFrame({ payload: enc.encode("0"), timestamp: Timestamp.fromMillis(0) });
producer.appendGroup(); // seq 1 stalls before its first frame
producer.writeFrame({ payload: enc.encode("2"), timestamp: Timestamp.fromMillis(10_000) });

// Group 1's reach is group 2's start, a full edge behind: stale at zero budget.
// Group 0's reach is unknown until group 1 presents its first frame, so it is kept.
expect((await track.recvGroup())?.sequence).toBe(0);
expect((await track.recvGroup())?.sequence).toBe(2);
});

// The ordered frame helpers share the burst contract: a buffered backlog is drained
// in full rather than discarded for age.
test("ordered frame reads drain a stale backlog", async () => {
Expand Down
62 changes: 30 additions & 32 deletions js/net/src/track.ts
Original file line number Diff line number Diff line change
Expand Up @@ -722,32 +722,21 @@ export class Subscriber {
#drift(): {
budget: number;
presentation?: { sequence: number; timestamp: Timestamp };
suffix: { sequence: number; reach: number }[];
end?: number;
} {
const { end } = this.#cursor.peek();
let presentation: { sequence: number; timestamp: Timestamp } | undefined;
const suffix: { sequence: number; reach: number }[] = [];
for (const { group } of this.#state.timeline.values()) {
if (end !== undefined && group.sequence > end) continue;
if (group.closed.peek() instanceof Error) continue;
// The edge wants the newest content that exists, so it takes the newest
// stamped group's latest frame.
const timestamp = hooks.groupTimestamp(group);
if (timestamp !== undefined) {
// The table bounds a candidate's reach, so it wants where each group
// begins; the edge wants the newest content that exists, so it takes the
// newest group's latest frame.
suffix.push({ sequence: group.sequence, reach: timestamp.asMillis() });
if (!presentation || group.sequence > presentation.sequence) {
presentation = { sequence: group.sequence, timestamp: hooks.groupLatest(group) ?? timestamp };
}
if (timestamp !== undefined && (!presentation || group.sequence > presentation.sequence)) {
presentation = { sequence: group.sequence, timestamp: hooks.groupLatest(group) ?? timestamp };
}
}

// Sequence order, so a candidate's immediate successor is one lookup away.
// Deliberately not a minimum over later groups: timestamps need not rise with
// sequence, and taking the minimum would shrink the bound, which is the unsafe
// direction. Only the immediate successor bounds a group.
suffix.sort((a, b) => a.sequence - b.sequence);

const requested = this.#state.update.peek()?.maxAge ?? 0;
const retained = this.#state.info.peek()?.maxAge;
return {
Expand All @@ -757,24 +746,28 @@ export class Subscriber {
: Math.min(requested, retained)
: Number.POSITIVE_INFINITY,
presentation,
suffix,
end,
};
}

// The furthest presentation time the group at `sequence` could still reach: where its
// immediate successor begins, or undefined when nothing follows it yet. An upper bound,
// deliberately: a frame's duration is not on the wire, so a group's own last timestamp
// says where it starts presenting, not where it ends. Only a successor's start proves
// the predecessor cannot run past it.
static #reach(suffix: { sequence: number; reach: number }[], sequence: number): number | undefined {
let lo = 0;
let hi = suffix.length;
while (lo < hi) {
const mid = (lo + hi) >> 1;
if (suffix[mid].sequence <= sequence) lo = mid + 1;
else hi = mid;
// immediate servable successor begins, or undefined when nothing proves where it
// stops. An upper bound, deliberately: a frame's duration is not on the wire, so a
// group's own last timestamp says where it starts presenting, not where it ends.
// Only the *immediate* successor counts: timestamps need not rise with sequence (a
// rewind reorders them), so a later stamped group proves nothing about where an
// unstamped successor will begin, and shrinking the bound is the unsafe direction.
// An unstamped successor leaves the reach unbounded until it presents a frame.
#reach(sequence: number, end?: number): number | undefined {
let successor: GroupConsumer | undefined;
for (const { group } of this.#state.timeline.values()) {
if (group.sequence <= sequence) continue;
if (end !== undefined && group.sequence > end) continue;
if (group.closed.peek() instanceof Error) continue;
if (!successor || group.sequence < successor.sequence) successor = group;
}
return suffix[lo]?.reach;
if (!successor) return undefined;
return hooks.groupTimestamp(successor)?.asMillis();
}

// Whether the drift budget says to give up on `group`.
Expand All @@ -798,13 +791,13 @@ export class Subscriber {
drift: {
budget: number;
presentation?: { sequence: number; timestamp: Timestamp };
suffix: { sequence: number; reach: number }[];
end?: number;
},
): boolean {
const candidate = this.#state.timeline.get(group.sequence);
if (candidate?.group !== group) return false;

const reach = Subscriber.#reach(drift.suffix, group.sequence);
const reach = this.#reach(group.sequence, drift.end);
return (
drift.presentation !== undefined &&
drift.presentation.sequence > group.sequence &&
Expand Down Expand Up @@ -1267,7 +1260,12 @@ export class Ordered {
}

/**
* Read the next frame across groups, discarding older groups.
* Read the next frame across groups, in sequence order.
*
* Rides the same cursor as {@link nextGroup} and shares this handle's contract: a
* buffered backlog is drained in full, however old it is, never discarded for age.
* A consumer that wants only the freshest content should jump via {@link latest}
* and {@link startAt} rather than expect frame reads to skip ahead.
* Treat the returned frame bytes as read-only; they are shared with other consumers.
*/
readFrame(): Promise<Frame | undefined> {
Expand Down
30 changes: 18 additions & 12 deletions rs/moq-net/src/model/resume.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1533,10 +1533,16 @@ impl Subscriber {
/// rather than read, so a candidate a poll does not deliver stays where it was,
/// and a cap lowered between polls never strands a group behind a segment cursor
/// that had already stepped past it.
///
/// `deliver` marks the caller as the one handing the group out, which stamps the
/// winner's cache entry. A nested seek passes `false`: its candidate may lose at
/// the level above, and a loser re-seeked every poll must not be shielded from
/// eviction.
fn poll_seek(
&mut self,
floor: u64,
end: Option<u64>,
deliver: bool,
waiter: &kio::Waiter,
) -> Poll<Result<Option<group::Consumer>>> {
self.poll_sync(waiter);
Expand All @@ -1562,16 +1568,12 @@ impl Subscriber {
}

let seg = &mut self.segments[index];
// A boundary behind the floor can never serve this cursor again;
// release its inner subscription rather than holding demand open.
if seg.last_group().is_some_and(|last| last < floor)
&& let SubState::Active(sub) = &mut seg.sub
{
let count = match sub.poll_finished(waiter) {
Poll::Ready(count) => count.ok(),
Poll::Pending => None,
};
seg.complete(count);
// A boundary behind the floor has nothing to serve this poll. A pure
// skip, deliberately: the floor can come back down (a lowered
// `start_at` with nothing delivered yet), so the segment must not be
// completed or otherwise committed past its cache.
if seg.last_group().is_some_and(|last| last < floor) {
continue;
}

let cap = min_some(end, seg.last_group());
Expand Down Expand Up @@ -1605,6 +1607,10 @@ impl Subscriber {

if let Some((index, group)) = best {
let sequence = group.sequence;
// Delivery is a cache access; a candidate merely considered is not.
if deliver {
group.cache_refresh();
}
// A copy continuing a group already handed out splices into it rather
// than surfacing again; step past it and look for the next sequence.
match self.hand_out(index, group) {
Expand Down Expand Up @@ -1780,7 +1786,7 @@ impl Subscriber {
/// handed-out group's reads may block. See [`Self::poll_seek`].
pub fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll<Result<Option<group::Consumer>>> {
let floor = self.next_sequence.max(self.min_sequence);
let Some(group) = ready!(self.poll_seek(floor, self.end_sequence, waiter))? else {
let Some(group) = ready!(self.poll_seek(floor, self.end_sequence, true, waiter))? else {
return Poll::Ready(Ok(None));
};
self.next_sequence = self.next_sequence.max(group.sequence.saturating_add(1));
Expand All @@ -1798,7 +1804,7 @@ impl Subscriber {
) -> Poll<Result<Option<group::Consumer>>> {
let floor = floor.max(self.min_sequence);
let end = min_some(end, self.end_sequence);
self.poll_seek(floor, end, waiter)
self.poll_seek(floor, end, false, waiter)
}

/// Return the next group with a higher sequence than any previously returned.
Expand Down
Loading
Loading