Skip to content
Closed
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
22 changes: 11 additions & 11 deletions doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -140,10 +140,12 @@ its scope can use.

## Subscriptions

A subscriber names a broadcast and track. Delivery starts at the oldest group
it can still use, which at the default budget is the latest one, so every group
must begin at a point a fresh subscriber can decode from (a keyframe, a full
JSON snapshot). Groups can also be fetched by sequence number, which is how the
A subscriber names a broadcast and track. By default delivery starts at the
live edge: the oldest group it can still use, which at the default budget is the
latest one, so every group must begin at a point a fresh subscriber can decode
from (a keyframe, a full JSON snapshot). A resumed subscriber names a floor
instead, where it left off, and can ask for both, in which case the lower start
wins. Groups can also be fetched by sequence number, which is how the
[HLS gateway](/bin/hls) and the relay's [HTTP fetch](/bin/relay/http) serve
history.

Expand All @@ -152,7 +154,6 @@ Each subscription carries the knobs that decide behavior under congestion:
| Knob | Effect |
| --- | --- |
| **Priority** (0..255) | Higher-priority tracks get bandwidth first. Audio above video, base layer above enhancement. |
| **Order** | Which group to send first when several are pending. Newest first for live, oldest first for catch-up. |
| **Max delay** | How far a non-latest group may fall behind the live edge before it is skipped. Zero means "live edge only", and raising it is also what asks for history. |

Max delay is measured on the media timeline, not the wall clock, so a backlog
Expand All @@ -163,8 +164,7 @@ publisher only ever sees the most tolerant budget across its subscribers.

A track is timed or untimed: it declares a timescale or none, and a frame that
doesn't match is refused. No receiver fills in an arrival time. An untimed
group never falls past max delay, so a new subscriber starts at its latest
group unless it names a start. Tracks from moq-lite before 05, or from
group never falls past max delay, so its live edge is the latest group. Tracks from moq-lite before 05, or from
moq-transport without a `TIMESCALE` (every track on drafts 14-16), arrive
untimed. No moq-lite version can declare an untimed track, so on 05 and later
its frames go out stamped with their send time.
Expand All @@ -183,10 +183,10 @@ timestamps and always keeps the newest group. IETF carries the same idea as

Put together, a conference might use:

| Track | Priority | Order | Max delay |
| --- | --- | --- | --- |
| audio | 100 | ascending | 500 ms |
| video | 50 | descending | 2 s |
| Track | Priority | Max delay |
| --- | --- | --- |
| audio | 100 | 500 ms |
| video | 50 | 2 s |

Under light congestion video drops the tail of a group; under heavy congestion
video stops and audio lags by at most 500 ms. No protocol change, just knobs.
Expand Down
51 changes: 34 additions & 17 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@ When a new Group is started, the previous Group is closed and may be dropped for
The duration before an incomplete group is dropped is determined by the application and the publisher/subscriber's latency target.

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.
A subscription starts at the live edge, at a floor Group, or at whichever of the two is lower, 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)).

The subscriber and publisher both indicate their delivery preference:
Expand Down Expand Up @@ -469,7 +469,7 @@ A subscriber opens Subscribe Streams to request a Track.
The subscriber MUST start a Subscribe Stream with a SUBSCRIBE message followed by any number of SUBSCRIBE_UPDATE messages.
The publisher replies with a SUBSCRIBE_OK message once the start group is resolved, followed by a SUBSCRIBE_END message once the subscription ends.
For a live track the publisher MAY withhold SUBSCRIBE_OK until the first matching group resolves the start; if the track has already ended with no matching groups, it sends SUBSCRIBE_END with no preceding SUBSCRIBE_OK.
A requested start past the publisher's largest position is the exception: the publisher MUST send SUBSCRIBE_OK without waiting, with `Group` set to the requested start group, so a subscriber resuming just past what it holds learns where the live feed is from the answer alone (a quiet track may not reach the start for a long time).
A floor past the publisher's largest position without `Live` is the exception: the publisher MUST send SUBSCRIBE_OK without waiting, with `Group` set to the floor's group, so a subscriber resuming just past what it holds learns where the live feed is from the answer alone (a quiet track may not reach the floor for a long time).
A rejection is a stream reset: a publisher that cannot serve the subscription (no such track, an ended broadcast, or any other refusal) MUST promptly reset the stream rather than leave it pending, so a subscriber distinguishes "pending" from "refused" by the reset, not by a timeout.
A route claims capability rather than inventory, so a subscription for a covered path that names nothing is refused this way too.

Expand Down Expand Up @@ -1026,9 +1026,11 @@ SUBSCRIBE Message {
Track Name (s)
Subscriber Priority (8)
Subscriber Max Age (i)
Group Start (i)
Live (8)
Floor (8)
[Group Start (i)]
[Frame Start (i)]
Group End (i)
Frame Start (i)
Frame End (i)
}
~~~
Expand All @@ -1050,14 +1052,25 @@ A value of `0` means the subscriber wants only the latest group in live delivery
This is a delivery-time preference, not a retention rule: the publisher MAY still hold these groups for FETCH or future subscriptions (see `Publisher Max Age` in [TRACK_INFO](#track-info)).
See the [Expiration](#expiration) section for more information.

**Live**:
1 to deliver from the live edge, 0 otherwise.
Any other value is a PROTOCOL_VIOLATION.
The live edge is frame 0 of the oldest group that [Expiration](#expiration) has not expired, so a `Subscriber Max Age` of 0 starts at the latest group, and a subscriber that buffers is handed the head of what it can still play.
On a Track without presentation time, which no age can measure, it is frame 0 of the latest group.
`Live` lowers the floor to the live edge whenever that Position sorts below it, so a floor above the latest group never hides the latest group from a subscription that also asks for `Live`.

**Floor**:
1 when `Group Start` and `Frame Start` follow, 0 when the subscription has no floor.
Any other value is a PROTOCOL_VIOLATION.
A subscription with neither `Live` nor a floor asks for nothing, and the publisher MUST treat it as a PROTOCOL_VIOLATION.

**Group Start**:
The minimum group sequence to deliver: an absolute floor, defaulting to 0 (no floor).
The minimum group sequence to deliver: an absolute 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 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.
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 unless `Live` lowers the floor.
The subscriber is then 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.
Without `Live`, 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**:
Expand All @@ -1067,8 +1080,8 @@ A non-zero value is the absolute group sequence + 1.

**Frame Start**:
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.
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 value of 0 means from the start of that group, so the group is delivered whole.
Frames before this index are not delivered, even when delivery begins at that exact group; a start resolved at a later group, or lowered by `Live`, 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**:
Expand All @@ -1077,7 +1090,7 @@ A value of 0 means the whole group (default).
A non-zero value is the absolute frame index + 1, matching `Group End`.
MUST be 0 when `Group End` is 0, since an unbounded subscription has no end group to qualify.

`Group Start` and `Group End` are offset by 1 only so 0 can mean "absent"; every other group field in this document is a plain absolute sequence.
`Group End` is offset by 1 only so 0 can mean "absent"; every other group field in this document is a plain absolute sequence.

## SUBSCRIBE_UPDATE
A subscriber can modify a subscription with a SUBSCRIBE_UPDATE message.
Expand All @@ -1089,14 +1102,17 @@ SUBSCRIBE_UPDATE Message {
Message Length (i)
Subscriber Priority (8)
Subscriber Max Age (i)
Group Start (i)
Live (8)
Floor (8)
[Group Start (i)]
[Frame Start (i)]
Group End (i)
Frame Start (i)
Frame End (i)
}
~~~

See [SUBSCRIBE](#subscribe) for information about each field.
Every field replaces the subscription's: an update clears the floor with `Floor` 0 and the live edge with `Live` 0, and clearing both is a PROTOCOL_VIOLATION.
Moving `Frame Start` forward within a group that is already being delivered does not retract frames the publisher has already sent; like `Group Start`, it only bounds what the publisher sends from here on.


Expand Down Expand Up @@ -1187,13 +1203,13 @@ Set to 0x0 to indicate a SUBSCRIBE_OK message.

**Group**:
The absolute sequence number of the first group that will be delivered.
It MUST be greater than or equal to the requested start group; any groups in between are unavailable.
A subscriber that requested the latest group learns the resolved sequence here.
It MUST be greater than or equal to the floor's group, unless `Live` lowered it; any groups in between are unavailable.
A subscriber that requested `Live` learns the resolved sequence here.

There is no matching frame field, because the start frame is never in doubt: a partial group is only delivered when it was asked for, so the subscription starts either exactly where it asked or at the beginning of a later group (see [Positions](#positions)).
The subscriber derives the start frame from `Group` and its own request:

- `Group` equals the requested start group: delivery begins at the requested `Frame Start`.
- `Group` equals the floor's group, and `Live` did not lower the floor: delivery begins at the requested `Frame Start`.
- `Group` is greater: delivery begins at frame 0.

The second case is easy to get wrong, so to be explicit: a subscriber that requested group 5 frame 15 and receives `Group` = 6 starts at **frame 0** of group 6, not frame 15.
Expand Down Expand Up @@ -1395,6 +1411,7 @@ The `Message Length` describes the payload size on the wire.
- A GOAWAY recipient MAY keep opening requests on the current session until it has moved to a replacement session; previously it MUST NOT open new streams. The sender SHOULD keep answering them and MAY reset one with GOING_AWAY, which the recipient SHOULD retry on another route.
- Replaced Warm and Cold Route Cost with one static Route Cost in moq-lite-07-wip; lite-06 retains both fields, reading Warm and writing Cold at saturation.
- Made TRACK_INFO Publisher Max Age optional, encoded as milliseconds plus one with zero meaning no limit.
- Added `Live` and `Floor` to SUBSCRIBE and SUBSCRIBE_UPDATE. `Live` delivers from the live edge, lowering the floor when the oldest unexpired group sorts below it. `Group Start` and `Frame Start` are a plain absolute floor, present only when `Floor` is 1. A subscription with neither is a PROTOCOL_VIOLATION. lite-06 reads `Group Start` 0 with `Frame Start` 0 as `Live`, and earlier versions read an absent `Group Start` as `Live`.
- Added `Largest Group` and `Largest Frame` to SUBSCRIBE_OK: the publisher's largest position when it answers, which a subscriber takes as where the live feed is. A publisher MUST answer at once when the requested start is past it. Earlier versions carry no such position, so a subscriber takes the first frame instead.
- Added `Epoch` to ANNOUNCE_START, SUBSCRIBE, TRACK, and FETCH: a UUIDv7 naming the publisher instance, or empty. A path and an Epoch name one Broadcast. A relay MAY move a subscription between routes with the same Epoch, continuing from the first frame the subscriber lacks instead of at a group boundary, and never between routes with different Epochs or none. The newest Epoch wins a path and ends subscriptions to the older one. Replaces the first-hop identity.
- An untimed Track's frames and datagrams carry their send time. lite-05 and lite-06 publishers do the same.
Expand Down
1 change: 1 addition & 0 deletions js/net/src/broadcast.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,7 @@ test("a request exposes the aggregate subscription options", async () => {
expect(request?.subscription).toEqual({
priority: 7,
maxDelay: Milli(250),
live: false,
groups: { start: { included: 0 }, end: { excluded: 30 } },
});
expect(request?.priority).toBe(7);
Expand Down
70 changes: 70 additions & 0 deletions js/net/src/ietf/publisher.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1820,6 +1820,76 @@ test("draft-20: an absolute filter trims the range it serves", async () => {
}
});

/**
* Relative 1 floors demand at the current group. It is not `live` (that asks a relay for
* the retained window) and not an unfiltered start at group 0.
*/
test("draft-20: relative 1 floors demand at the current group", async () => {
const fx = fixture();
const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI });
for (let i = 0; i < 3; i++) writeGroup(track, 1);

const { client } = await runSubscribe(
fx,
new Subscribe({
requestId: 7n,
trackNamespace: Path.from("test"),
trackName: "video",
subscriberPriority: 0,
filter: { kind: "relative", groups: 1n },
}),
);

try {
expect(track.subscription.peek()).toMatchObject({
live: false,
groups: { start: { included: 2 } },
});

const served = await nextUni(fx.uni);
if (!served) throw new Error("the current group was never served");
expect(await readGroup(served)).toEqual({
sequence: 2,
firstObject: true,
endOfGroup: true,
objects: [{ id: 0, payload: "2.0" }],
});
} finally {
fx.close();
client.close();
}
});

/**
* Draft-20 unfiltered stays a floor at group 0, the retained cache, not `live`.
*/
test("draft-20: an unfiltered subscription floors demand at the origin", async () => {
const fx = fixture();
const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI });
writeGroup(track, 1);

const { client } = await runSubscribe(
fx,
new Subscribe({
requestId: 7n,
trackNamespace: Path.from("test"),
trackName: "video",
subscriberPriority: 0,
filter: { kind: "unfiltered" },
}),
);

try {
expect(track.subscription.peek()).toMatchObject({
live: false,
groups: { start: { included: 0 } },
});
} finally {
fx.close();
client.close();
}
});

/**
* The draft's own current-group join: a Next Object subscription for the live tail, plus a
* StartGroup=1 fill for the head already published. The two must meet exactly, so the head
Expand Down
19 changes: 12 additions & 7 deletions js/net/src/ietf/publisher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -401,12 +401,17 @@ export class Publisher {

// The wire request tells an upstream what we need; the cursor is what actually
// trims this subscriber, since the producer fans every cached group out to every
// sink regardless. An absent start joins at the latest group, which is what
// moq-lite means by joining a live track. The range's end is the inclusive last
// group; the model's `endGroup` is exclusive.
// sink regardless. A resolved start is a floor, including relative 1 at the
// current group. That is not `live` (this serving budget would ask a relay for
// the retained window) and not an unfiltered {0, 0}. An absent start, a relative
// filter before any group exists, is still the live edge: there is no group to
// floor at yet. The range's end is the inclusive last group; the model's
// `endGroup` is exclusive.
const live = !range.start;
track.update({
priority,
maxDelay: Milli(Varint.MAX_U53),
live,
groups: {
start: range.start ? { included: Number(range.start.group) } : undefined,
end: range.end ? { included: Number(range.end.group) } : undefined,
Expand Down Expand Up @@ -1638,11 +1643,11 @@ function subscribeRange(msg: Subscribe, edge: LiveEdge, version: IetfVersion): S
/** The Locations a single Location Filter selects, resolved against the live edge. */
function filterRange(filter: Filter.Filter, edge: LiveEdge): ServeRange {
switch (filter.kind) {
// No restriction. moq-lite starts at the beginning of the latest group, which is the
// join point it is built around; a subscription passes objects as they are published,
// so an absent filter is not a request to replay history.
// Every Object, which the draft defines as an open ended absolute {0, 0}: the same
// start an explicit one asks for. A relay folding `live` into a floor sends it to
// reach back over what its readers may still use, and filters locally.
case "unfiltered":
return {};
return { start: { group: 0n, object: 0n } };
// `{Largest.Group, Largest.Object + 1}`. Everything below it, including the already
// published head of the current group, is outside the requested range, so the join is
// mid-group by construction. The draft pairs this with a fill when the subscriber
Expand Down
4 changes: 2 additions & 2 deletions js/net/src/integration.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -171,8 +171,6 @@ test("integration: lite subscription options and updates reach the publisher", a
})();

const remote = wireOf(client).consume(Path.from("test"));
// A floor of 1, not 0: a pre-06 wire folds a vacuous floor of 0 back to absent, since
// its encoding of group 0 means "replay from the beginning" instead.
const subscriber = remote.track("video").subscribe({
priority: 3,
maxDelay: Milli(250),
Expand All @@ -182,6 +180,7 @@ test("integration: lite subscription options and updates reach the publisher", a
expect(producer.subscription.peek()).toEqual({
priority: 3,
maxDelay: Milli(250),
live: false,
groups: { start: { included: 1 }, end: { excluded: 9 } },
});

Expand All @@ -194,6 +193,7 @@ test("integration: lite subscription options and updates reach the publisher", a
expect(await updated).toEqual({
priority: 8,
maxDelay: Milli(500),
live: false,
groups: { start: { included: 2 }, end: { excluded: 12 } },
});

Expand Down
6 changes: 6 additions & 0 deletions js/net/src/internal.ts
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,12 @@ export function groupBounds(groups: Groups = {}): { start: number; end?: number
return { start: bound(groups.start, true) ?? 0, end: bound(groups.end, false) };
}

/** Where a read cursor starts: the floor, lowered by `live` to the live edge `edge`. */
export function liveStart(live: boolean, floor: number | undefined, edge: number): number {
if (!live) return floor ?? 0;
return floor === undefined ? edge : Math.min(floor, edge);
}

/**
* The announce-interest prefix a scope needs on a prefix-shaped wire: its literal head.
* The peer echoes every suffix beneath it, and the caller filters what arrives.
Expand Down
Loading
Loading