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
9 changes: 6 additions & 3 deletions doc/concept/layer/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,11 +88,13 @@ If the peer doesn't have the broadcast/track, they will get an error.
Otherwise, the subscription is active and will stay open until closed by the publisher (possibly with an error).

A track is broken into **groups**, each with an increasing ID.
Conceptually, these are join points, and new subscriptions will always start at the latest group.
Conceptually, these are join points, and new subscriptions start at the newest group they can still use.
Groups are delivered independently and potentially out of order, so you should have some logic to reorder or skip during congestion.
A group is closed when finished or aborted with an error (ex. during congestion).

A subscription starts at the latest group by default, but can name any (group, frame) position instead.
A subscription can name a (group, frame) floor, but the floor is not a request: **Subscriber Max Age** is the only thing that asks for data.
Delivery starts at the oldest group at or above the floor within that budget, which is the latest group at the default budget of zero.
A subscriber that buffers is then handed the head of what it can still play instead of only the live edge, and never history it would skip on arrival: one bound decides both.
That is how a subscriber follows a track to a different publisher partway through a group, which matters when the current group may stay open indefinitely (a JSON append log, or a catalog that keeps appending deltas).
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.

Expand Down Expand Up @@ -126,7 +128,8 @@ That age is measured both on the media timeline (a group's first timestamp again
The media timeline keeps a backlog delivered as a burst old, while wall-clock time backstops stalled or empty groups that have no timestamp.
Both ends apply it: the publisher skips a group rather than sending it, and the subscriber skips it again as it reads.
The publisher only ever sees the most tolerant budget across its subscribers, which is why the subscriber applies it too.
Asking for old groups with `Group Start` does not exempt them: a start bounds what you are sent, and a subscriber that wants history has to raise its budget to match.
Asking for old groups with `Group Start` does not exempt them: a floor only bounds what you are sent, and a subscriber that wants history has to raise its budget to match.
That is also why the budget is what decides where delivery starts: the groups worth sending are exactly the ones it would not immediately skip.

The publisher also keeps old groups around for a best-effort **Publisher Max Age** cache window so relays and late subscribers can still fetch them. This defaults to 5 seconds.
The subscriber's max age is bounded by this window: a group can't be waited for longer than it's actually kept around.
Expand Down
24 changes: 15 additions & 9 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,8 @@ Only the subscriber knows whether a partial Group is any use to it, so only the

Frame indices are only meaningful relative to a Group the subscriber has already begun receiving, so:

- A `Frame Start` is meaningless without an absolute `Group Start`; a subscriber requesting the latest group (`Group Start` = 0) MUST send `Frame Start` = 0.
- A `Frame Start` qualifies the group `Group Start` names, group 0 included.
A subscriber that has seen no such group MUST send `Frame Start` = 0, since it cannot number the frames of a group it has not received.
- A `Frame End` is meaningless without a `Group End`; an unbounded subscription (`Group End` = 0) MUST send `Frame End` = 0.

A publisher MUST treat a violation of either rule as a protocol violation and reset the stream.
Expand Down Expand Up @@ -986,21 +987,25 @@ This is a delivery-time preference, not a retention rule: the publisher MAY stil
See the [Expiration](#expiration) section for more information.

**Group Start**:
The first group to deliver.
A value of 0 means the latest group (default).
A non-zero value is the absolute group sequence + 1.
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.
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.
Reaching back is best-effort, not a guarantee that the groups still exist; see `Publisher Max Age` in [TRACK_INFO](#track-info).

**Group End**:
The last group to deliver (inclusive).
A value of 0 means unbounded (default).
A non-zero value is the absolute group sequence + 1.

**Frame Start**:
The index of the first frame to deliver within the start group (see [Positions](#positions)).
The index of the first frame to deliver within the `Group Start` group (see [Positions](#positions)).
A value of 0 means from the start of that group (default), so the group is delivered whole.
Unlike `Group Start` this is a plain absolute index, not the `absolute + 1` form: 0 is both a valid index and the default, so there is no absent case to encode around.
Frames before this index are not delivered, even though the start group itself is.
MUST be 0 when `Group Start` is 0, since the subscriber cannot number the frames of a group it has not seen.
Frames before this index are not delivered, even when delivery begins at that exact group; a start resolved at a later group is always delivered from frame 0.
A subscriber that has received no group MUST send 0, since it cannot number the frames of a group it has not seen.

**Frame End**:
The last frame to deliver (inclusive) within the end group (see [Positions](#positions)).
Expand Down Expand Up @@ -1359,7 +1364,7 @@ The `Message Length` describes the payload size on the wire.
- Added a SETUP `Origin` parameter (0x5): each endpoint declares its Hop ID at session setup, carrying session-wide the identity `Exclude Hop` carried per announce stream, and filtering subscriptions as well as announcements (including sessions that never open an Announce Stream).
- Made advertisement selection per subscriber: a publisher MUST NOT advertise a path containing the subscriber's declared origin and otherwise advertises the best remaining one (a subscriber the serving path flows through receives the best standby instead of nothing), MUST serve subscriptions by the same exclusion, and the actively-carrying cost discount applies only to the serving path. This is how redundant publishers fail over across a mesh.
- Defined same-path advertisements with the same non-zero Epoch as interchangeable content a relay may splice across at a Position. When both Epochs are 0, identity falls back to a shared non-zero first Hop ID; differing or unknown identities never splice.
- Added `Frame Start` and `Frame End` to SUBSCRIBE and SUBSCRIBE_UPDATE, qualifying the start and end group with a frame index so a subscription can begin or end partway through a group. `Frame Start` is a plain index; `Frame End` is the index + 1, matching `Group End`. Both MUST be 0 when the group bound they qualify is absent.
- Added `Frame Start` and `Frame End` to SUBSCRIBE and SUBSCRIBE_UPDATE, qualifying the start and end group with a frame index so a subscription can begin or end partway through a group. `Frame Start` is a plain index qualifying the `Group Start` group; `Frame End` is the index + 1, matching `Group End`, and MUST be 0 when `Group End` is absent.
- Added `Frame Start` and `Frame End` to FETCH, bounding the returned frames within the group. A publisher that cannot serve the full range resets the stream.
- Added `Frame Start` to GROUP, giving the index of the first FRAME on the stream so a partial group is self-describing.
- Added the Positions section defining a (group, frame) position, its lexicographic ordering, and the rule that a partial group is only ever delivered to a subscriber that asked for one. A publisher that cannot serve a group from the requested frame skips it and resolves to a later group, so SUBSCRIBE_OK needs no frame field: the start frame follows from `Group` and the subscriber's own request.
Expand All @@ -1368,6 +1373,7 @@ The `Message Length` describes the payload size on the wire.
- Exempted a ceiling-cost serving path from the actively-carrying cost discount: a relay whose serving path costs the saturation ceiling (primarily a session that received a GOAWAY) advertises the ceiling instead of 0, so the drain propagates downstream instead of being re-masked by each carrying hop. Keyed on the value, not the reason, which does not travel on the wire.
- Added the Error Codes section, defining separate session and stream code spaces and listing the codes moq-lite uses, reused unchanged from moq-transport. Codes 64+ are the application's; 32-63 are reserved and MUST NOT be interpreted, pending a future revision. Previously the codes were unspecified, so an endpoint could neither send one a peer would understand nor safely interpret one it received. Note this renumbers every code an existing implementation sent, and that a stream reset of 0x0 is now INTERNAL_ERROR rather than a cancellation (CANCELLED is 0x1).
- Renamed `Subscriber Max Latency` to `Subscriber Max Age` and `Publisher Max Latency` to `Publisher Max Age`.
- Made `Group Start` an absolute floor (the raw minimum group sequence, default 0) rather than the sequence + 1 with 0 meaning the latest group. The start resolves from `Subscriber Max Age` instead: the oldest group at or above the floor within the budget, so a subscriber that buffers is handed the head of what it can still play. A zero budget still resolves to the latest group, which was the only start the old encoding could ask for by default.

## moq-lite-05
- Renamed ANNOUNCE_INTEREST to ANNOUNCE_REQUEST and ANNOUNCE to ANNOUNCE_BROADCAST.
Expand Down
113 changes: 113 additions & 0 deletions js/hang/src/container/consumer.outoforder.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
import { expect, test } from "bun:test";
import { Group, Time, Track, Varint } from "@moq/net";
import { Consumer } from "./consumer.ts";
import { Format as LegacyFormat } from "./legacy.ts";

// Standalone from consumer.test.ts so it only pulls the Legacy format, not the CMAF decoder.

function encodeLegacyFrame(timestamp: Time.Micro, payload: Uint8Array): Uint8Array {
const tsBytes = Varint.encode(timestamp);
const data = new Uint8Array(tsBytes.byteLength + payload.byteLength);
data.set(tsBytes, 0);
data.set(payload, tsBytes.byteLength);
return data;
}

/** Write one frame into an open group: `millis` on the timeline, tagged `tag`. */
function publishFrame(group: Group.Producer, millis: number, tag: number) {
group.writeFrame({
payload: encodeLegacyFrame(Time.Micro.fromMilli(millis as Time.Milli), new Uint8Array([tag])),
timestamp: Time.Timestamp.fromMillis(millis),
});
}

/** Publish one closed group carrying a single frame at `millis`. */
function publish(track: Track.Producer, sequence: number, millis: number) {
const group = new Group.Producer(sequence);
track.writeGroup(group);
publishFrame(group, millis, sequence);
group.close();
}

/** Every group and frame the consumer will hand over right now, as [group, payload] pairs. */
async function drain(consumer: Consumer): Promise<[number, number | undefined][]> {
const seen: [number, number | undefined][] = [];
for (;;) {
const next = await Promise.race([consumer.next(), new Promise((resolve) => setTimeout(resolve, 50))]);
if (!next) break;
const { group, frame } = next as { group: number; frame?: { payload: Uint8Array } };
seen.push([group, frame?.payload[0]]);
}
return seen;
}

// A publisher serving a subscriber's max age hands over the head of the window alongside
// the live edge, and groups go out newest-first, so the head arrives *after* the group
// that is already playing. Arriving in that order is not a reason to throw it away:
// audio writes into a timestamp-indexed ring and video drops a late frame at render, and the
// subscription's own max age already bounds how far back one can be.
test("out-of-order groups are delivered rather than dropped", async () => {
const track = new Track.Producer("test").accept({ maxAge: 30_000 });
const consumer = new Consumer(track.subscribe({ maxAge: 5000 }), {
format: new LegacyFormat(),
latency: 5000 as Time.Milli,
});

// The live edge lands first, and delivery starts there rather than waiting.
publish(track, 3, 30);
expect((await consumer.next())?.frame?.payload).toEqual(new Uint8Array([3]));

// The window's head follows it. Every group is still within both budgets, so all three
// are handed over even though each sits below the group already delivered.
publish(track, 0, 0);
publish(track, 1, 10);
publish(track, 2, 20);

const delivered = (await drain(consumer)).filter(([, payload]) => payload !== undefined);
expect(delivered).toEqual([
[0, 0],
[1, 1],
[2, 2],
]);

consumer.close();
});

// A below-cursor group may still be downloading when its buffered frames are momentarily
// drained (the decode loop consumes faster than the network delivers). Removing it at that
// instant silently truncates its tail, so removal must wait for the group to finish.
test("a below-cursor group still downloading is not truncated", async () => {
const track = new Track.Producer("test").accept({ maxAge: 30_000 });
const consumer = new Consumer(track.subscribe({ maxAge: 5000 }), {
format: new LegacyFormat(),
latency: 5000 as Time.Milli,
});

// The live edge group arrives first and starts delivery (still open).
const live = new Group.Producer(3);
track.writeGroup(live);
publishFrame(live, 3000, 30);
expect((await consumer.next())?.frame?.payload[0]).toBe(30);

// A backlog group lands below the cursor, one frame at a time (mid-download).
const backlog = new Group.Producer(1);
track.writeGroup(backlog);
publishFrame(backlog, 1000, 10);
const first = await consumer.next();
expect(first?.group).toBe(1);
expect(first?.frame?.payload[0]).toBe(10);

// The consumer finds the group's buffer empty while it is still open. It must wait
// rather than shift the group out, so the second frame still arrives.
const pending = consumer.next();
publishFrame(backlog, 1500, 11);
backlog.close();

const second = (await pending) as { group: number; frame?: { payload: Uint8Array } };
expect(second.group).toBe(1);
expect(second.frame?.payload[0]).toBe(11);

live.close();
track.close();
consumer.close();
});
12 changes: 6 additions & 6 deletions js/hang/src/container/consumer.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -344,26 +344,26 @@ test("Consumer delivers groups in sequence order regardless of arrival order", a
consumer.close();
});

test("Consumer rejects stale groups", async () => {
test("Consumer delivers a group that arrives below the cursor", async () => {
const track = new Track.Producer("test");
const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli });

// Group.Producer 5 arrives first (sets active = 5)
writeGroupWithLegacyFrames(track, 5, [0 as Time.Micro]);
await new Promise((resolve) => setTimeout(resolve, 50));

// Group.Producer 3 is stale
// Group.Producer 3 lands behind it, and Group.Producer 6 ahead of it. Arriving below the
// cursor is not what makes content stale: how far behind the live edge a group may be is
// the subscription's own max age, which `replay` deliberately opens wide here. So all
// three are handed over, in sequence order, since delivery has not passed any of them yet.
writeGroupWithLegacyFrames(track, 3, [100_000 as Time.Micro]);
// Group.Producer 6 is valid
writeGroupWithLegacyFrames(track, 6, [30_000 as Time.Micro]);
track.close();

await new Promise((resolve) => setTimeout(resolve, 100));

const frames = await drainFrames(consumer, 500);
expect(frames).toHaveLength(2);
expect(frames[0].group).toBe(5);
expect(frames[1].group).toBe(6);
expect(frames.map((frame) => frame.group)).toEqual([3, 5, 6]);
consumer.close();
});

Expand Down
41 changes: 20 additions & 21 deletions js/hang/src/container/consumer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -167,21 +167,18 @@ export class Consumer {
this.#active = consumer.sequence;
}

// Normally we drop anything behind the cursor. With an active reset the cursor isn't
// a valid floor (a late new-epoch group can sit below it); defer to the boundary and
// admit ambiguous groups so #runGroup can rule on them once their timestamps arrive.
let drop: boolean;
if (this.#rewind.boundary) {
const verdict = this.#rewind.boundary.bySequence(consumer.sequence);
if (verdict === undefined) drop = false;
else if (verdict) drop = true;
else drop = consumer.sequence < this.#active;
} else {
drop = consumer.sequence < this.#active;
}

if (drop) {
console.warn(`skipping old group: track=${this.#track.name} ${consumer.sequence}`);
// Arriving below the delivery cursor is not a reason to drop a group. Groups are
// sent newest-first, so the head of a subscription arrives after the live edge it
// was served alongside, and both consumers can still place one: audio writes into
// a timestamp-indexed ring, video drops a late frame at render. How far back one
// may be is the subscription's own max age, applied before it ever reaches here.
//
// A group the reset boundary proves reneged is different, and still dropped: it
// belongs to a timeline the publisher withdrew rather than one that arrived late.
// An ambiguous one is admitted so #runGroup can rule on it once its timestamps
// arrive.
if (this.#rewind.boundary?.bySequence(consumer.sequence) === true) {
console.warn(`skipping reneged group: track=${this.#track.name} ${consumer.sequence}`);
consumer.close();
continue;
}
Expand Down Expand Up @@ -589,12 +586,14 @@ export class Consumer {
return { frame, group: seq, discontinuity: this.#rewind.discontinuity, continuous };
}

// Check if the group is done and then remove it.
// A group is removable when #active has advanced past it, OR when
// its #runGroup task has finished (done) and all frames are consumed.
// The latter handles the case where #runGroup finished before
// #active reached this group (e.g. after a latency skip).
if (this.#active > this.#groups[0].consumer.sequence || this.#groups[0].done) {
// Check if the group is done and then remove it. A group is removable only
// once its #runGroup task has finished (done) and all frames are consumed:
// a below-#active group (a backlog group admitted behind the live edge) may
// still be downloading when its buffer momentarily drains, and removing it
// then silently truncates its tail. #runGroup notifies whenever the head
// group gains a frame, so waiting here is woken, and #checkLatency bounds
// how long a stalled head can hold delivery up.
if (this.#groups[0].done) {
if (this.#groups[0].consumer.sequence === this.#active) {
// The cursor moves past this group here rather than in #runGroup's finally
// block whenever the group finished before it became active, so this is the
Expand Down
2 changes: 1 addition & 1 deletion js/net/src/broadcast.ts
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ async function fetchGroup(
options: track.FetchGroupOptions = {},
): Promise<GroupConsumer> {
const subscriber = subscribe(state, name, { priority: options.priority });
hooks.ignoreLatency(subscriber);
hooks.exemptFetch(subscriber);
try {
for (;;) {
const group = await subscriber.recvGroup();
Expand Down
Loading
Loading