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
8 changes: 7 additions & 1 deletion doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,9 +191,15 @@ 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. |
| **Order** | Which group to send first when several are pending. Newest first for live (the default), oldest first for catch-up. Needs moq-lite 07 or moq-transport; older moq-lite always sends newest first. |
| **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. |

Order only decides what goes first, never what is skipped, so catching up oldest
first needs a max delay that covers the backlog. When a relay serves subscribers of
both orders from one upstream subscription, it asks upstream for newest first, and
still sends each subscriber its groups in that subscriber's own order. Over
moq-transport the upstream order is fixed by whichever subscriber arrived first.

Max delay is measured on the media timeline, not the wall clock, so a backlog
delivered as a burst is still late while a congestion stall never expires
anything on its own. Both ends apply it: the publisher skips a group rather
Expand Down
24 changes: 17 additions & 7 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,7 @@ Both bounds may be refined to a Frame within their Group, so a subscription can

The subscriber and publisher both indicate their delivery preference:
- `Priority` indicates if Track A should be transmitted instead of Track B.
- `Group Order` indicates if the newest or oldest pending Group of a Track should be transmitted first.
- `Subscriber Max Age` indicates how far a non-latest Group may fall behind the latest Group before it is dropped from live delivery; `Publisher Max Age` indicates the maximum age before a non-latest Group is dropped from the publisher's cache.

The combination of these preferences enables the most important content to arrive during network degradation while still respecting encoding dependencies.
Expand Down Expand Up @@ -578,7 +579,7 @@ How these streams get transmitted over the network is very important, and yet ha

## Prioritization
The Publisher and Subscriber both exchange a `Priority` value, which determines which Track should be transmitted next.
Group order within a Track is fixed: newest first.
The subscriber's `Group Order` determines which Group within the Track is transmitted next.

A publisher SHOULD attempt to transmit streams based on these rules.
This depends on the QUIC implementation and it may not be possible to get fine-grained control.
Expand Down Expand Up @@ -616,12 +617,14 @@ ali/video: subscriber_priority=1 publisher_priority=1
The subscriber priority takes precedence, so the subscriber can likewise full-screen Ali's window by raising the subscriber priority of Ali's tracks above Bob's.

### Group Order
Within a Track, a publisher SHOULD transmit the newest Group first.
Under congestion this sheds the backlog rather than the live edge, which is what a Group boundary exists to make possible.
Within a subscription, a publisher SHOULD transmit pending Groups in the subscriber's `Group Order`: newest first when descending (the default), oldest first when ascending.
Descending sheds the backlog rather than the live edge under congestion, which is what a Group boundary exists to make possible; ascending drains a backlog in sequence order, for catch-up.

There is no field to invert it.
A subscriber that wants Groups in sequence order gets them by reading in sequence order: reordering is a local decision, it costs the network nothing, and encoding it on the wire only lets one subscriber's preference reach a Track that a relay is fanning out to many.
Such a subscriber SHOULD raise its `Subscriber Max Age` so the Groups it intends to read in order are still being delivered when it reaches them.
`Group Order` only orders transmission; it never decides whether a Group is delivered, which is [Expiration](#expiration)'s job.
An ascending subscriber SHOULD raise its `Subscriber Max Age` so the backlog it intends to drain is not expired first.

A relay serving several subscriptions from one upstream subscription SHOULD request descending upstream unless every one of them is ascending, so a live subscriber is never held behind another's backlog.
Each downstream subscription is still transmitted in its own `Group Order`.

A subscriber MUST support gaps and out-of-order delivery regardless.

Expand Down Expand Up @@ -1088,6 +1091,7 @@ SUBSCRIBE Message {
Epoch (b)
Track Name (s)
Subscriber Priority (8)
Group Order (8)
Subscriber Max Age (i)
Group Start (i)
Group End (i)
Expand All @@ -1105,6 +1109,11 @@ The priority of the subscription within the session, represented as a u8.
The publisher SHOULD transmit *higher* values first during congestion.
See the [Prioritization](#prioritization) section for more information.

**Group Order**:
Which pending Group the publisher SHOULD transmit first: descending (0x0), newest first, or ascending (0x1), oldest first.
Any other value is a PROTOCOL_VIOLATION.
See the [Group Order](#group-order) section for more information.

**Subscriber Max Age**:
The subscriber's preference, in milliseconds, for how long a non-latest group may remain in flight before being considered stale and dropped from live delivery.
The publisher SHOULD reset (at the QUIC level) Group Streams for groups whose age relative to the latest group exceeds this duration.
Expand Down Expand Up @@ -1151,6 +1160,7 @@ The start and end group can be changed in either direction (growing or shrinking
SUBSCRIBE_UPDATE Message {
Message Length (i)
Subscriber Priority (8)
Group Order (8)
Subscriber Max Age (i)
Group Start (i)
Group End (i)
Expand Down Expand Up @@ -1538,6 +1548,7 @@ The `Message Length` describes the payload size on the wire.

## moq-lite-07

- Added `Group Order` to SUBSCRIBE and SUBSCRIBE_UPDATE: descending (0x0, the previous fixed order) or ascending (0x1). A relay requests descending upstream unless every subscription it serves is ascending.
- Listed the shared INVALID_REQUEST_ID (0x4) session code used by moq-transport drafts 14 through 16.

- SUBSCRIBE_OK `Group` names where delivery starts when the subscription resolves, which need not be the first group sent. It is not a new floor. A subscriber does not wait for a group between the requested floor and it, but a publisher still delivers one that arrives later within Subscriber Max Age.
Expand Down Expand Up @@ -1720,7 +1731,6 @@ Some of these fields occur in multiple messages.

- Request ID
- Track Alias
- Group Order
- Filter Type
- StartObject
- Expires
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 @@ -416,6 +416,7 @@ test("a request exposes the aggregate subscription options", async () => {
expect(request?.subscription).toEqual({
priority: 7,
maxDelay: Milli(250),
order: "descending",
groups: { start: { included: 0 }, end: { excluded: 30 } },
});
expect(request?.priority).toBe(7);
Expand Down
100 changes: 100 additions & 0 deletions js/net/src/ietf/ietf.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2152,3 +2152,103 @@ for (const version of [Version.DRAFT_14, Version.DRAFT_15, Version.DRAFT_16]) {
expect(params.groupOrder).toBe(0);
});
}

// Caller-selected SUBSCRIBE group order, on both wire shapes: draft-14's inline u8 and
// the draft-15+ message parameter.
test.each([
["v14", Version.DRAFT_14],
["v20", Version.DRAFT_20],
] as const)("Subscribe %s: group order defaults to descending", async (_name, version) => {
const msg = new Subscribe.Subscribe({
requestId: 1n,
trackNamespace: Path.from("test"),
trackName: "video",
subscriberPriority: 128,
});
expect(msg.groupOrder).toBe("descending");

const encoded = await encodeVersioned(msg, version);
const decoded = await decodeVersioned(encoded, Subscribe.Subscribe.decode, version);
expect(decoded.groupOrder).toBe("descending");
});

test.each([
["v14", Version.DRAFT_14],
["v20", Version.DRAFT_20],
] as const)("Subscribe %s: a caller can request ascending group order", async (_name, version) => {
const msg = new Subscribe.Subscribe({
requestId: 1n,
trackNamespace: Path.from("test"),
trackName: "video",
subscriberPriority: 128,
groupOrder: "ascending",
});

const encoded = await encodeVersioned(msg, version);

// Differential, not a byte search: `toContain(1)` would pass on requestId 1n
// alone. Encode the same message as descending and require that exactly one
// byte moved, from 0x02 to 0x01.
const descending = await encodeVersioned(
new Subscribe.Subscribe({
requestId: 1n,
trackNamespace: Path.from("test"),
trackName: "video",
subscriberPriority: 128,
groupOrder: "descending",
}),
version,
);
expect(encoded.length).toBe(descending.length);
const differing = [...encoded].flatMap((byte, i) => (byte === descending[i] ? [] : [i]));
expect(differing).toHaveLength(1);
expect(encoded[differing[0]]).toBe(Subscribe.GroupOrder.Ascending);
expect(descending[differing[0]]).toBe(Subscribe.GroupOrder.Descending);

const decoded = await decodeVersioned(encoded, Subscribe.Subscribe.decode, version);
expect(decoded.groupOrder).toBe("ascending");
});

// Draft-14 carries GROUP_ORDER as an inline u8 rather than a message parameter, so 0 ("no
// preference") is reachable there from a peer. It decodes as descending rather than surfacing
// as a third value the model has to handle, and anything past 2 is refused.
test("Subscribe v14: an inline group order of 0 decodes as descending", async () => {
const msg = new Subscribe.Subscribe({
requestId: 1n,
trackNamespace: Path.from("test"),
trackName: "video",
subscriberPriority: 128,
});
const encoded = await encodeVersioned(msg, Version.DRAFT_14);

// Rewrite the encoded inline order byte, which no encoder of ours emits as 0 or 3.
const orderAt = encoded.lastIndexOf(Subscribe.GroupOrder.Descending);
const zeroed = new Uint8Array(encoded);
zeroed[orderAt] = Subscribe.GroupOrder.Default;
const decoded = await decodeVersioned(zeroed, Subscribe.Subscribe.decode, Version.DRAFT_14);
expect(decoded.groupOrder).toBe("descending");

const invalid = new Uint8Array(encoded);
invalid[orderAt] = 3;
await expect(decodeVersioned(invalid, Subscribe.Subscribe.decode, Version.DRAFT_14)).rejects.toThrow(/group order/);
});

// Draft-15 still lets a GROUP_ORDER parameter of 0 through, and it means the same.
test("Subscribe v15: a group order parameter of 0 decodes as descending", async () => {
const msg = new Subscribe.Subscribe({
requestId: 1n,
trackNamespace: Path.from("test"),
trackName: "video",
subscriberPriority: 128,
groupOrder: "ascending",
});
const encoded = await encodeVersioned(msg, Version.DRAFT_15);

// The parameter's value is the byte after its id, 0x22.
const orderAt = encoded.findIndex((byte, i) => byte === 0x22 && encoded[i + 1] === Subscribe.GroupOrder.Ascending);
expect(orderAt).toBeGreaterThan(-1);
const zeroed = new Uint8Array(encoded);
zeroed[orderAt + 1] = Subscribe.GroupOrder.Default;
const decoded = await decodeVersioned(zeroed, Subscribe.Subscribe.decode, Version.DRAFT_15);
expect(decoded.groupOrder).toBe("descending");
});
30 changes: 29 additions & 1 deletion js/net/src/ietf/publisher.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ import { PublishDone } from "./publish.ts";
import { PublishNamespace, PublishNamespaceUpdate } from "./publish_namespace.ts";
import { Publisher } from "./publisher.ts";
import { RequestError, RequestOk } from "./request.ts";
import { Subscribe, SubscribeOk, SubscribeUpdate, Unsubscribe } from "./subscribe.ts";
import { GroupOrder, Subscribe, SubscribeOk, SubscribeUpdate, Unsubscribe } from "./subscribe.ts";
import { SubscribeNamespace, SubscribeNamespaceEntry, SubscribeNamespaceEntryDone } from "./subscribe_namespace.ts";
import { TrackStatusRequest } from "./track.ts";
import { ALPN, type IetfVersion, Version } from "./version.ts";
Expand Down Expand Up @@ -2173,6 +2173,34 @@ test("draft-20: an opt-out peer gets no track properties", async () => {
}
});

/**
* Through draft-15 SUBSCRIBE_OK restates the order the subscription is served in; later
* drafts announce the publisher's default, newest first.
*/
test.each([
[Version.DRAFT_14, GroupOrder.Ascending],
[Version.DRAFT_15, GroupOrder.Ascending],
[Version.DRAFT_17, GroupOrder.Descending],
] as const)("%s: SUBSCRIBE_OK announces the served order", async (version, announced) => {
const fx = fixture(version);
fx.broadcast.createTrack("video", { timescale: Timescale.MILLI });

const { client, ok } = await runSubscribe(
fx,
new Subscribe({
requestId: 7n,
trackNamespace: Path.from("test"),
trackName: "video",
subscriberPriority: 0,
groupOrder: "ascending",
}),
);
expect(ok.properties.groupOrder).toBe(announced);

fx.close();
client.close();
});

/**
* Drafts 14-16 cannot send TIMESCALE, so a subscribed group carries no Timestamp even though
* the track has units. Draft-17 declares the units and stamps the object.
Expand Down
Loading
Loading