Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
e273645
chore(quest): claim quest/m2/subscribe-ranges/lite07-fetch.md
kixelated Nov 13, 2026
de827f8
feat(net)!: lite-07 SUBSCRIBE anchors name a group, not a frame
kixelated Nov 13, 2026
8a386b5
feat(net)!: JS and the draft read lite-07 ranges as whole groups
kixelated Nov 13, 2026
f21fb9e
wip(net): JS lite-07 fills ride the copy's subscription
kixelated Nov 13, 2026
ed4a866
fix(net): JS recoveries judge by the fills' budget and stay quiet onc…
kixelated Nov 13, 2026
8cee771
fix(net): a Rust recovery takes a SUBSCRIBE_SKIP inside its groups
kixelated Nov 13, 2026
df20b32
chore(quest): finish lite07-fetch, with lint fixes
kixelated Nov 13, 2026
d2ae4f2
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 13, 2026
80d2f6a
fix(net): a JS recovery asks with no max delay, as Rust does
kixelated Nov 13, 2026
9f0c186
style(net): biome format
kixelated Nov 13, 2026
1f84db2
Merge remote-tracking branch 'origin/main' into t3/subscribe-ranges-l…
kixelated Nov 13, 2026
c955dd8
fix(net): a JS recovery coalesces its refusals and wakes the held FIN…
kixelated Nov 13, 2026
19bbef1
fix(net): JS fill waits release on a lost race, and recovery refusals…
kixelated Nov 13, 2026
6d041ed
Merge remote-tracking branch 'origin/main' into t3/lite07-fetch-merge…
kixelated Nov 13, 2026
e1571ce
fix(net): scope recovery refusals and priority to the held fills, end…
kixelated Nov 13, 2026
85017f0
fix(net): a loss refusal also ends with its fills, recorded on the tr…
kixelated Nov 13, 2026
84fd5b7
fix(net): a recovery still out answers the fills owing what it alread…
kixelated Nov 13, 2026
1cb0984
fix(net): a recovery hands each refusal to the fills once
kixelated Nov 13, 2026
70c94b5
fix(net): a recovery stops covering the groups it refused and handed …
kixelated Nov 13, 2026
1fd077a
fix(net): a fill asks no group it already holds a refusal for
kixelated Nov 13, 2026
b18505d
fix(net): rebuild recovery coverage from those still out
kixelated Nov 13, 2026
93015ce
fix(net): a repeated stale drop waits on its recovery, refusals trim …
kixelated Nov 13, 2026
71b8619
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 14, 2026
3be0e92
quest: live-history-demand no longer waits on the lite-07 FETCH quest…
kixelated Nov 14, 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
38 changes: 13 additions & 25 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ The duration before an incomplete group is dropped is determined by the applicat

Every subscription is scoped to a single Track.
A subscription starts at a configurable Group (defaulting to the latest) and continues until a configurable end Group or until either the publisher or subscriber cancels the subscription.
Both bounds may be refined to a Frame within their Group, so a subscription can start or stop partway through a Group rather than only on a Group boundary (see [Positions](#positions)).
A subscription reads whole Groups; a FETCH reads one Group, or a slice of one (see [Positions](#positions)).

The subscriber and publisher both indicate their delivery preference:
- `Priority` indicates if Track A should be transmitted instead of Track B.
Expand Down Expand Up @@ -194,7 +194,7 @@ The contents are opaque to the moq-lite layer.

Frames within a Group are numbered from 0 in the order they were produced.
This index is not transmitted per frame; it is implied by position within the Group, anchored by the [GROUP](#group) message's `Frame Start`.
A Group Stream normally starts at frame 0, but MAY start later when the publisher only holds (or was only asked for) part of the Group.
A Group Stream normally starts at frame 0.

Each frame of a timed Track carries a presentation timestamp expressed in the Track's `Timescale` (see [TRACK_INFO](#track-info)), used by the moq-lite layer for [expiration](#expiration) decisions.
A Track without a `Timescale` is untimed: its frames carry no timestamp.
Expand All @@ -207,22 +207,16 @@ A relay serves a Track's timestamps on as it received them, including ones it di
A Position is a (Group Sequence, Frame Index) pair identifying one frame within a Track.
Positions order lexicographically: by group first, then by frame within the group.

SUBSCRIBE and FETCH bound their delivery by Position rather than by Group alone.
A SUBSCRIBE Range's Absolute anchors name Positions (see [SUBSCRIBE](#subscribe)), and FETCH carries a `Frame Start` and `Frame End` within its group; a frame index of 0 at the start, or an absent end frame, is the whole group.

The bounds are chosen so that two subscriptions abut exactly.
A Range starts at its start Position and stops just before its end Position, so a subscriber that has received frames 0 through `N-1` of group `G` and wants the remainder starts a Range at (`G`, `N`).
Ending the first subscription's Range at (`G`, `N`) covers exactly the complement with no gap and no overlap: the two requests carry the *same* numbers on the wire.
SUBSCRIBE reads whole Groups: a Range's Absolute Anchors name Groups (see [SUBSCRIBE](#subscribe)), so a subscription never starts or stops partway through one.
FETCH reads one Group, or a slice of one: its `Frame Start` and `Frame End` bound the returned frames, and a frame index of 0 at the start, or an absent end frame, is the whole Group.
A subscriber that has received frames 0 through `N-1` of group `G` and wants the rest FETCHes `G` from frame `N` and subscribes from Group `G+1`, so the two requests cover the Track with no gap and no overlap.

This is what lets a subscriber move a Track to a different publisher partway through a Group instead of waiting for the next Group to start, which matters for Tracks whose current Group may stay open indefinitely.
A Group can therefore be assembled from more than one publisher: each contributes a disjoint run of frames, and the subscriber concatenates them in index order.

A partial Group is only ever delivered to a subscriber that asked for one.
A publisher that cannot serve a Group from the frame the subscription names MUST skip that Group entirely and resolve the subscription to a later one, rather than deliver the part it holds.
The resolved start is therefore always either exactly the requested Position or the beginning of a later Group, never some third Position the subscriber did not choose.

A partial Group is only ever delivered to a subscriber that asked for one with FETCH, or as the [continuation](#yield) of a paused Group.
A publisher that holds only part of a Group a subscription covers names it in a [SUBSCRIBE_DROP](#subscribe-drop) rather than deliver the part it holds.
A Group is the unit of decodability: its earlier Frames may carry a keyframe or compression state the later Frames need.
A subscriber MAY start a Range at any frame index, whether or not it retains the earlier Frames.

# Flow
This section outlines the flow of messages within a moq-lite session.
Expand Down Expand Up @@ -889,7 +883,6 @@ A Group MAY contain zero FRAME messages, potentially indicating a gap in the tra
A frame MAY contain an empty payload, potentially indicating a gap in the group.

The GROUP message's `Frame Start` gives the index of the first FRAME on the stream, so a stream carrying only part of a Group is self-describing.
It is redundant with the subscription's own start Position in the steady state, and carried anyway because a SUBSCRIBE_UPDATE that moves the bound races the Group Streams already in flight: the two travel on different streams with no ordering between them, so the receiver would otherwise have to guess which bound a given Group Stream was opened under.

A publisher MUST NOT send two Group Streams for the same Group Sequence on one subscription, except to re-offer a Group whose stream it reset (see [SUBSCRIBE_DROP](#subscribe-drop)), or to [continue](#yield) one.
The re-offer can arrive before that reset: a subscriber holds a Group Stream for a sequence whose earlier stream is still arriving unread until that stream ends, then discards it if the earlier stream completed the Group, or reads it if the earlier stream was reset.
Expand Down Expand Up @@ -1634,7 +1627,6 @@ Range {
Anchor {
Anchor Type (i)
[Group Sequence (i)]
[Frame Index (i)]
[Groups Back (i)]
[Timestamp (i)]
}
Expand Down Expand Up @@ -1685,7 +1677,7 @@ Each Range implicitly takes the next Range ID on the stream, starting at 0, whic
Which fields follow, and what the Anchor names:

- None (0x0): no fields. As a `Start`, the oldest Group (no floor); as an `End`, the live edge (unbounded).
- Absolute (0x1): `Group Sequence` and `Frame Index`, a Position. A `Start` delivers from it and an `End` stops just before it.
- Absolute (0x1): `Group Sequence`. A `Start` delivers from that Group and an `End` stops just before it.
- Relative (0x2): `Groups Back`, the Group that many before the latest, 0 being the latest. Included as an `End`.
- Time (0x3): `Timestamp`, the Group containing that presentation time in the Track's `Timescale` (see [TRACK_INFO](#track-info)). Included as an `End`. On an untimed Track it is refused with TIMESTAMP_MISMATCH.

Expand All @@ -1704,9 +1696,7 @@ A subscriber that buffers is then handed the head of what it can still play inst
A floor above the latest group simply waits there: that is a resumed subscription naming where it left off.
Reaching back is best-effort, not a guarantee that the groups still exist; see `Publisher Max Age` in [TRACK_INFO](#track-info).

An Absolute `Start` past frame 0 delivers its group from that frame; a start resolved at a later group is always delivered from frame 0.
A subscriber MAY name any start frame, as described in [Positions](#positions).
An Absolute `End` past frame 0 delivers its group up to that frame.
A Range covers whole Groups; a subscriber reads a slice of a Group with FETCH (see [Positions](#positions)).

## SUBSCRIBE_UPDATE {#subscribe-update}
A subscriber can modify a subscription with a SUBSCRIBE_UPDATE message.
Expand Down Expand Up @@ -1737,7 +1727,6 @@ SUBSCRIBE_UPDATE Message {

See [SUBSCRIBE](#subscribe) for information about each field.
An `Update` no larger than the previous one only confuses the subscriber's own accounting of stale drops; the publisher echoes the latest value it read.
Moving a `Start` forward within a group that is already being delivered does not retract frames the publisher has already sent; it only bounds what the publisher sends from here on.

**Remove Count** and **Range ID**:
The live Ranges to retire.
Expand Down Expand Up @@ -1979,7 +1968,6 @@ A subscriber takes it as where the live feed is: a relay holding groups from an
One per Range of the SUBSCRIBE, in Range ID order: the Group where the Range's delivery starts, plus one, so a subscriber learns where a Relative or Time Anchor landed.
0 means the Range has no Group to deliver, including one an update retired before the answer.
The Range's Groups from this one are owed as described in [SUBSCRIBE_DROP](#subscribe-drop); an earlier one is not, though it MAY still arrive.
A Range whose `Range Start` is its requested start Group begins at the requested frame, and otherwise at frame 0 (see [Positions](#positions)).
A subscriber MUST treat a `Range Start Count` other than the SUBSCRIBE's `Range Count` as a PROTOCOL_VIOLATION.
A Range an update adds has its start reported by [SUBSCRIBE_STARTED](#subscribe-started) instead, even one added before SUBSCRIBE_OK.

Expand Down Expand Up @@ -2328,8 +2316,8 @@ A subscriber MUST handle gaps, potentially caused by congestion.
**Frame Start**:
The index of the first FRAME message on this stream within the group (see [Positions](#positions)).
A plain absolute index; 0 means the stream carries the group from its beginning, which is the common case.
A non-zero value means the leading frames are not on this stream, either because the subscription started partway into this group or because the publisher only holds part of it.
The subscriber MUST NOT assume it will receive the missing frames on another stream; they are a gap unless a separate subscription or FETCH covers them, or the stream [continues](#yield) a paused Group.
A non-zero value means the leading frames are not on this stream.
The subscriber MUST NOT assume it will receive the missing frames on another stream; they are a gap unless a FETCH covers them, or the stream [continues](#yield) a paused Group.


## FRAME
Expand Down Expand Up @@ -2452,10 +2440,10 @@ An application-specific payload.

### Subscriptions {#changelog-07-subscribe}

- Replaced `Group Start`, `Group End`, `Frame Start`, and `Frame End` in SUBSCRIBE and SUBSCRIBE_UPDATE with a non-empty list of Ranges. Each end is an Anchor: none, an absolute Position (exclusive as an end), a count of Groups back from the latest, or a presentation time.
- Replaced `Group Start`, `Group End`, `Frame Start`, and `Frame End` in SUBSCRIBE and SUBSCRIBE_UPDATE with a non-empty list of Ranges of whole Groups. Each end is an Anchor: none, an absolute Group (exclusive as an end), a count of Groups back from the latest, or a presentation time.
- Added `Group Order` to SUBSCRIBE and SUBSCRIBE_UPDATE: descending (0x0, the previous fixed order) or ascending (0x1).
- Added an optional `Subscriber Min Age` to SUBSCRIBE and SUBSCRIBE_UPDATE, the subscriber's target latency, encoded as milliseconds plus one with zero meaning not stated. A relay forwards the smallest stated value.
- SUBSCRIBE may start at any frame, including when the subscriber no longer holds the prefix.
- FETCH reads one Group or a slice of one, and SUBSCRIBE reads whole Groups: a read starting partway through a Group FETCHes it. A publisher holding only part of a Group a subscription covers drops it.
- A SUBSCRIBE_UPDATE that lowers a `Start` covers the groups below the old start that the publisher still holds, not only those that arrive later. A group already sent is not sent again.
- Replaced SUBSCRIBE_OK `Group` with a `Range Start` per Range: the Group where that Range's delivery starts, including at a Relative or Time Anchor, from which its Groups are owed.
- Each Range takes an implicit Range ID, and SUBSCRIBE_UPDATE edits the live Ranges instead of restating them: `Remove Count` Range IDs to retire, then the Ranges to add. The live Ranges must stay non-empty and fit in one SUBSCRIBE. A Range resolves its Anchors once, however many updates leave it live.
Expand Down
9 changes: 6 additions & 3 deletions js/net/src/fill.ts
Original file line number Diff line number Diff line change
Expand Up @@ -384,8 +384,11 @@ export class FillState {

/** The still-wanted runs of a fill, in ascending order. @internal */
export let wantedRuns: (fill: Fill) => Run[];
/** Wait for a change to the groups or readers of a fill. @internal */
export let fillChanged: (fill: Fill) => Promise<unknown>;
/**
* Wait for a change to the groups or readers of a fill, which a lost {@link race} releases.
* @internal
*/
export let fillChanged: (fill: Fill) => GetPromise<unknown>;
/**
* The budget in milliseconds an OLD answer was judged under, and whether that is the publisher's
* max age, which binds every reader, rather than the request's own budget.
Expand Down Expand Up @@ -514,7 +517,7 @@ export class Fill {
static {
makeFill = (state, pending) => new Fill(state, pending);
wantedRuns = (fill) => fill.#pending.owed();
fillChanged = (fill) => Promise.resolve(fill.#pending.revision.changed());
fillChanged = (fill) => Signal.race(fill.#pending.revision);
rejectGroups = (fill, start, end, error, judged) => {
if (toStreamCode(error) !== StreamCode.Old) {
fill.refuseGroups(start, end, error);
Expand Down
2 changes: 1 addition & 1 deletion js/net/src/ietf/subscriber.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1205,7 +1205,7 @@ export class Subscriber {
while (!receiving) {
if (!wantedRuns(fill).some((run) => run.start < until && run.end > start))
throw new StreamError(StreamCode.Cancel);
await untilAborted(fillChanged(fill), active);
await untilAborted(Promise.resolve(fillChanged(fill)), active);
}
await untilAborted(receiving.unwanted(), active);
throw new StreamError(StreamCode.Cancel);
Expand Down
5 changes: 5 additions & 0 deletions js/net/src/internal.ts
Original file line number Diff line number Diff line change
Expand Up @@ -661,6 +661,8 @@ export const hooks: {
* by `track.ts`.
*/
arrivingGroup: (producer: Producer, sequence: bigint) => Arriving | undefined;
/** The cached groups of `[start, end)` still arriving, by sequence, costing what the cache holds. Assigned by `track.ts`. */
arrivingIn: (producer: Producer, start: bigint, end: bigint) => bigint[];
/** The producer's largest reported location and its subsequent changes. */
producerLargest: (producer: Producer) => Getter<Position | undefined>;

Expand Down Expand Up @@ -1229,6 +1231,9 @@ export const hooks: {
arrivingGroup: () => {
throw new Error("track.ts not loaded");
},
arrivingIn: () => {
throw new Error("track.ts not loaded");
},
succeedGroup: () => {
throw new Error("group.ts not loaded");
},
Expand Down
45 changes: 26 additions & 19 deletions js/net/src/lite/copy_fill.test.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
// A received copy asks its publisher for the groups its readers miss, over lite FETCH, as the Rust
// lite subscriber's `FillServeRun` does, or on lite-07 for a reader with no budget, by run on a
// SUBSCRIBE of its own, as its `Recovery` does: below where the copy's feed started, by the copy's
// start rule, and inside the copy, once it evicted what it received.
// lite subscriber's `FillServeRun` does, or on lite-07 for more than one group, through its
// subscription's ranges, as its `RangeFills` does, and on a SUBSCRIBE of its own for what that
// subscription already delivered, as its `Recovery` does: below where the copy's feed started, by
// the copy's start rule, and inside the copy, once it evicted what it received.
import { expect, test } from "bun:test";
import { Duration, Elapsed, Manual, sleep, timeout } from "@moq/clock";
import { DEFAULT_EXPIRY } from "../cache.ts";
Expand Down Expand Up @@ -127,10 +128,11 @@ test("copy fill: lite-07 fills below a start resolved from the budget, as far as
expect((await narrow.recvGroup())?.sequence).toBe(3n);
const before = peer.fetches();

// The copy cannot tell which budget picked its start, so it fills what this one reaches.
// The copy cannot tell which budget picked its start, so it fills what this one reaches,
// through its subscription's ranges rather than a stream of its own.
const wide = peer.remote.track("video").subscribe(WIDE);
expect(sorted(await take(wide, 5))).toEqual(ALL);
expect(peer.fetches()).toBeGreaterThan(before);
expect(peer.fetches()).toBe(before);
narrow.close();
wide.close();
} finally {
Expand Down Expand Up @@ -370,10 +372,10 @@ test("copy fill: a filled group nobody holds any more stops downloading", async
}
});

// Lite-07: a filled group whose stream the publisher yielded, then gave up, ends with the fill's
// drop naming it with the group's own error, as one on a subscription does, rather than waiting
// paused on a continuation that never comes.
test("copy fill: a yielded group the fill's drop names ends", async () => {
// Lite-07: a filled group whose stream the publisher yielded, then gave up, ends with the drop the
// copy's subscription, which the fill rides, names it with: the group's own error, rather than
// waiting paused on a continuation that never comes.
test("copy fill: a yielded group its subscription's drop names ends", async () => {
const clock = new Manual();
const installed = clock.install();
const pair = createMockTransportPair(Lite.ALPN_07_WIP);
Expand All @@ -384,8 +386,9 @@ test("copy fill: a yielded group the fill's drop names ends", async () => {
]);
const publication = origin.route(Path.from("room"));
const track = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null });
write(track.createGroup(1n), 1n, "live");
// The archive answers group 0 with one frame and keeps it open, so its stream is still open.
write(track.createGroup(2n), 2n, "live");
// The archive answers group 0 with one frame and keeps it open, so its stream is still open, and
// group 1 whole.
const requests = track.requests();
const fills: Fill[] = [];
const archived = (async () => {
Expand All @@ -394,32 +397,36 @@ test("copy fill: a yielded group the fill's drop names ends", async () => {
fills.push(fill);
const group = fill.accept(0n);
group.writeFrame({ payload: enc.encode("old 0"), timestamp: Timestamp.fromMillis(0) });
write(fill.accept(1n), 1n, "old");
return group;
})();
const remote = wireOf(client).consume(Path.from("room"));
try {
const reader = remote.track("video").subscribe({ ranges: [{ start: { relative: 0n } }] });
const live = await reader.ordered().nextGroup();
expect(live?.sequence).toBe(1n);
expect(dec.decode((await live?.readFrame())?.payload)).toBe("live 1");
expect(live?.sequence).toBe(2n);
expect(dec.decode((await live?.readFrame())?.payload)).toBe("live 2");
expect(await live?.readFrame()).toBeUndefined();
live?.close();
// Two groups, so the fill rides the subscription's ranges.
const history = remote
.track("video")
.subscribe({ ...WIDE, ranges: [{ start: { absolute: 0n }, end: { absolute: 1n } }] });
.subscribe({ ...WIDE, ranges: [{ start: { absolute: 0n }, end: { absolute: 2n } }] });
const group = await history.recvGroup();
expect(group?.sequence).toBe(0n);
expect(dec.decode((await group?.readFrame())?.payload)).toBe("old 0");
const source = await archived;

// The session resets the group's stream to make room, and the group is gone before a new
// stream could continue it, so the publisher drops it on the fill's subscription.
// The live stream has finished. The archive may be served on both the fill and
// the copy's expanded feed, so reset every stream still serving it.
// stream could continue it, so the publisher drops it on the subscription the fill rides.
const one = await history.recvGroup();
expect(one?.sequence).toBe(1n);
while (await one?.readFrame());
// The live stream has finished, so the archived group's is the only one still open.
await clock.advance(Duration.ZERO);
const open = lines(pair.server).streams.list();
expect(open.length).toBeGreaterThan(0);
for (const stream of open) stream.preempt();
expect(open.length).toBe(1);
open[0]?.preempt();
source.abort(new StreamError(StreamCode(70), { message: "gone" }));

// Still paused without it, which the deadline, fired once every pending task settled,
Expand Down
Loading