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
17 changes: 15 additions & 2 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -1289,6 +1289,7 @@ A value of 0 is a PROTOCOL_VIOLATION, since a subscription that asks for nothing
**Range**:
A span of the Track to deliver, from its `Start` up to its `End`.
The subscription is the union of its Ranges: the publisher delivers each Group inside any of them once, in `Group Order` across all of them, and accounts with SUBSCRIBE_DROP for every Group it will not deliver.
Each Range implicitly takes the next Range ID on the stream, starting at 0, which a [SUBSCRIBE_UPDATE](#subscribe-update) uses to retire it.

**Anchor Type**:
Which fields follow, and what the Anchor names:
Expand All @@ -1312,10 +1313,11 @@ An Absolute `Start` past frame 0 delivers its group from that frame; a start res
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.

## SUBSCRIBE_UPDATE
## SUBSCRIBE_UPDATE {#subscribe-update}
A subscriber can modify a subscription with a SUBSCRIBE_UPDATE message.
A subscriber MAY send multiple SUBSCRIBE_UPDATE messages to update the subscription.
Its Ranges replace the previous ones, growing or shrinking the subscription.
Every field but the Ranges restates the subscription, and the latest one applies.
The Ranges are an edit: the update retires the live Ranges it names by Range ID, then adds its own, each taking the next Range ID.
Lowering a `Start` covers the groups below the old one that the publisher still holds, not only those that arrive later; a group already sent is not sent again.

~~~
Expand All @@ -1324,6 +1326,8 @@ SUBSCRIBE_UPDATE Message {
Subscriber Priority (8)
Group Order (8)
Subscriber Max Age (i)
Remove Count (i)
Range ID (i) ...
Range Count (i)
Range (..) ...
Wanted Group (i)
Expand All @@ -1333,6 +1337,14 @@ SUBSCRIBE_UPDATE Message {
See [SUBSCRIBE](#subscribe) for information about each field.
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.
A Range ID that was never assigned, or is already retired, including earlier in the same list, is a PROTOCOL_VIOLATION.

**Range Count** and **Range**:
The Ranges to add, which may be none.
The live Ranges after the edit MUST NOT be empty, and MUST fit in one SUBSCRIBE: once encoded they take at most 65,535 bytes.
A receiver closes the session with a PROTOCOL_VIOLATION otherwise.

**Wanted Group**:
The newest group the subscriber's live-edge joins want, encoded as the sequence plus one; `0` means none.
Expand Down Expand Up @@ -1865,6 +1877,7 @@ The `Message Length` describes the payload size on the wire.

- 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.
- 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.
- 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 subscription's range bounds datagrams like groups, and FETCH never returns a datagram.
- 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.
- A publisher SHOULD order a datagram among the subscription's streams as if it were its Group's stream, ahead of that stream when both exist. It SHOULD drop a datagram rather than block when the transport has no room for it, where it previously sent one only if the congestion controller could transmit it immediately.
Expand Down
13 changes: 10 additions & 3 deletions js/net/src/lite/publisher.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ import { Publisher } from "./publisher.ts";
import {
decodeSubscribeResponse,
decodeSubscribeResponseMaybe,
LiveRanges,
Subscribe,
type SubscribeEnd,
SubscribeUpdate,
Expand All @@ -42,8 +43,10 @@ function publish(origin: OriginProducer, path: Path.Valid) {
// Scheduling tests intentionally stall groups, so keep latency enforcement out of their scope.
const TEST_MAX_DELAY_MS = Milli(30_000);

// Carries the live ranges a decoded SUBSCRIBE would, so the publisher resolves lite-07 updates.
function replaySubscribe(props: ConstructorParameters<typeof Subscribe>[0]) {
return new Subscribe({ ...props, maxDelay: TEST_MAX_DELAY_MS });
const live = LiveRanges.sent({ ...props, startFrame: props.startFrame ?? 0 });
return new Subscribe({ ...props, maxDelay: TEST_MAX_DELAY_MS, live });
}

function replayUpdate(props: ConstructorParameters<typeof SubscribeUpdate>[0]) {
Expand Down Expand Up @@ -287,7 +290,7 @@ async function groupSendOrders(options: {
try {
for (const [index, sequence] of sequences.entries()) {
if (index === 1 && update !== undefined) {
await replayUpdate({ priority: update }).encode(client.writer, version);
await replayUpdate({ priority: update }).encode(client.writer, version, LiveRanges.sent(msg));
// Wait for the publisher to apply it, rather than assuming it beat the next group.
while (track.subscription.peek()?.priority !== update) await track.subscription.changed();
}
Expand Down Expand Up @@ -752,6 +755,8 @@ async function servedSubscription(

return {
client,
// The ranges the publisher holds, which the client's lite-07 updates edit.
live: LiveRanges.sent(msg),
datagrams: pair.client.datagrams.readable,
track,
serving,
Expand Down Expand Up @@ -938,7 +943,7 @@ for (const version of [Version.DRAFT_06, Version.DRAFT_07]) {
try {
sub.serve(5);
expect(await sub.servedSequence()).toBe(5);
await replayUpdate({ priority: 0, startGroup: 2 }).encode(sub.client.writer, version);
await replayUpdate({ priority: 0, startGroup: 2 }).encode(sub.client.writer, version, sub.live);
await flush();
sub.track.finish();
sub.track.close();
Expand Down Expand Up @@ -1009,13 +1014,15 @@ test.each([Version.DRAFT_06, Version.DRAFT_07])("lite %s: datagrams honor group
await replayUpdate({ priority: 0, startGroup: 0, startFrame: 0, endGroup: 4, endFrame: 0 }).encode(
sub.client.writer,
version,
sub.live,
);
await applied(5);
send([2, 3, 5, 4]);
expect([await recv(), await recv(), await recv()]).toEqual([2, 3, 4]);
await replayUpdate({ priority: 0, startGroup: 6, startFrame: 1, endGroup: 7, endFrame: 0 }).encode(
sub.client.writer,
version,
sub.live,
);
await applied(8);
send([6, 8, 7]);
Expand Down
8 changes: 6 additions & 2 deletions js/net/src/lite/publisher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ import { Probe } from "./probe.ts";
import {
encodeSubscribeResponse,
exclusiveGroupEnd,
type LiveRanges,
type Subscribe,
SubscribeDrop,
SubscribeEnd,
Expand Down Expand Up @@ -222,6 +223,8 @@ type SubscriptionControlOptions = {
reader: Reader;
writer: Writer;
version: Version;
/** The ranges the SUBSCRIBE carried, which each lite-07 update edits. */
live?: LiveRanges;
apply: (update: SubscribeUpdate) => void;
};

Expand Down Expand Up @@ -314,12 +317,12 @@ class SubscriptionControls {
this.#changed.update((value) => value + 1);
}

async #decode({ reader, version, apply, quic }: SubscriptionControlOptions) {
async #decode({ reader, version, live, apply, quic }: SubscriptionControlOptions) {
try {
// Runs until the peer's half ends, even past our own FIN: a lite-07 publisher waits
// for that end, and every other teardown stops the reader.
for (;;) {
const update = await SubscribeUpdate.decodeMaybe(reader, version);
const update = await SubscribeUpdate.decodeMaybe(reader, version, live);
if (!update) break;
apply(update);
this.#update = update;
Expand Down Expand Up @@ -929,6 +932,7 @@ export class Publisher {
reader: stream.reader,
writer: stream.writer,
version: this.version,
live: msg.live,
apply: (update) => {
Object.assign(datagramBounds, {
startGroup: update.startGroup,
Expand Down
3 changes: 2 additions & 1 deletion js/net/src/lite/refresh.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,10 @@ test.each([ALPN_06, ALPN_07_WIP])("refresh joins reach a browser publisher on %s
this: SubscribeUpdate,
writer,
version,
live,
) {
if (this.wantedGroup !== undefined) updates.push(this.wantedGroup);
return encode.call(this, writer, version);
return encode.call(this, writer, version, live);
});
const peers: { abort(): void }[] = [];
try {
Expand Down
75 changes: 63 additions & 12 deletions js/net/src/lite/subscribe.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import {
encodeSubscribeResponse,
exclusiveGroupEnd,
inclusiveGroupEnd,
LiveRanges,
Subscribe,
SubscribeDrop,
SubscribeEnd,
Expand Down Expand Up @@ -57,19 +58,29 @@ async function encodeSubscribe(msg: Subscribe): Promise<void> {

async function encodeMessage(
version: Version,
message: { encode(writer: Writer, version: Version): Promise<void> },
message: { encode(writer: Writer, version: Version, live?: LiveRanges): Promise<void> },
): Promise<Uint8Array> {
const written: Uint8Array[] = [];
const writer = new Writer(
new WritableStream<Uint8Array>({ write: (chunk) => void written.push(new Uint8Array(chunk)) }),
version,
);
await message.encode(writer, version);
await message.encode(writer, version, oldest());
writer.close();
await writer.closed;
return concat(written);
}

/** The live ranges of a SUBSCRIBE that asked for everything: one range, Range ID 0. */
function oldest(): LiveRanges {
return LiveRanges.sent({ startFrame: 0 });
}

/** Decode a SUBSCRIBE_UPDATE that edits {@link oldest}. */
function decodeUpdate(bytes: Uint8Array, version: Version): Promise<SubscribeUpdate> {
return SubscribeUpdate.decode(new Reader(undefined, bytes, version), version, oldest());
}

test("SubscribeOk round-trips priority/groups on draft-04", async () => {
const got = await responseRoundtrip(Version.DRAFT_04, {
ok: new SubscribeOk({ priority: 7, maxDelay: 250, startGroup: 3 }),
Expand Down Expand Up @@ -195,13 +206,11 @@ test("lite-07 carries the span as its only range, exclusive at the end", async (
test("a lite-07 list decodes as the span covering it", async () => {
// Priority, order, and max delay as SubscribeUpdate writes them, then the ranges and
// an absent wanted group.
// Each retires the SUBSCRIBE's one range (Range ID 0) before adding its own.
const head = (await encodeMessage(Version.DRAFT_07, new SubscribeUpdate({ priority: 0 }))).slice(1, 4);
const update = (ranges: number[]) => {
const body = [...head, ...ranges, 0];
return SubscribeUpdate.decode(
new Reader(undefined, new Uint8Array([body.length, ...body]), Version.DRAFT_07),
Version.DRAFT_07,
);
const body = [...head, 1, 0, ...ranges, 0];
return decodeUpdate(new Uint8Array([body.length, ...body]), Version.DRAFT_07);
};

// Groups 2 through 4 and 7 through frame 1 of group 9.
Expand Down Expand Up @@ -330,14 +339,12 @@ test.each(["ascending", "descending"] as const)("lite-07 round-trips a %s group
// The length prefix, the priority byte, then the order.
expect(update[1]).toBe(3 + 128);
expect(update[2]).toBe(order === "ascending" ? 1 : 0);
const decoded = await SubscribeUpdate.decode(new Reader(undefined, update, version), version);
const decoded = await decodeUpdate(update, version);
expect(decoded.order).toBe(order);

const invalid = new Uint8Array(update);
invalid[2] = 2;
await expect(SubscribeUpdate.decode(new Reader(undefined, invalid, version), version)).rejects.toThrow(
ProtocolViolation,
);
await expect(decodeUpdate(invalid, version)).rejects.toThrow(ProtocolViolation);
});

// No earlier wire has `Group Order`, so an ascending subscription falls back to descending,
Expand All @@ -364,7 +371,7 @@ test("wanted group survives lite-07 and disappears on legacy wires", async () =>
for (const wantedGroup of [undefined, 0, 3, Number.MAX_SAFE_INTEGER]) {
const update = new SubscribeUpdate({ priority: 7, wantedGroup });
const encoded = await encodeMessage(version, update);
const decoded = await SubscribeUpdate.decode(new Reader(undefined, encoded, version), version);
const decoded = await decodeUpdate(encoded, version);
expect(decoded.wantedGroup).toBe(version === Version.DRAFT_07 ? wantedGroup : undefined);
}
}
Expand Down Expand Up @@ -394,3 +401,47 @@ for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) {
}
});
}

test("a lite-07 update sends only a changed span, and the publisher resolves the same one", async () => {
const version = Version.DRAFT_07;
const sent = oldest();
const live = oldest();
const send = async (span: { startGroup?: number; endGroup?: number }) => {
const update = new SubscribeUpdate({ priority: 0, ...span });
const written: Uint8Array[] = [];
const writer = new Writer(
new WritableStream<Uint8Array>({ write: (chunk) => void written.push(new Uint8Array(chunk)) }),
version,
);
await update.encode(writer, version, sent);
writer.close();
await writer.closed;
const bytes = concat(written);
const got = await SubscribeUpdate.decode(new Reader(undefined, bytes, version), version, live);
return { bytes, got };
};

// Unchanged: no ids retired and no ranges added.
const same = await send({});
expect([...same.bytes.slice(4, 6)]).toEqual([0, 0]);
// Changed: Range ID 0 retires and the new span takes Range ID 1.
const moved = await send({ startGroup: 4, endGroup: 9 });
expect([moved.got.startGroup, moved.got.endGroup]).toEqual([4, 9]);
expect([...moved.bytes.slice(4, 7)]).toEqual([1, 0, 1]);
const back = await send({ startGroup: 4, endGroup: 9 });
expect([...back.bytes.slice(4, 6)]).toEqual([0, 0]);
const next = await send({});
expect([...next.bytes.slice(4, 6)]).toEqual([1, 1]);

// Only a live Range ID can be retired, and the live set never empties.
const fresh = () => oldest();
const body = (remove: number[], add: number[]) => {
const bytes = [128, 0, 0, remove.length, ...remove, ...add, 0];
return new Uint8Array([bytes.length, ...bytes]);
};
const decode = (bytes: Uint8Array) =>
SubscribeUpdate.decode(new Reader(undefined, bytes, version), version, fresh());
await expect(decode(body([1], [1, 0, 0]))).rejects.toThrow(ProtocolViolation);
await expect(decode(body([0, 0], [1, 0, 0]))).rejects.toThrow(ProtocolViolation);
await expect(decode(body([0], [0]))).rejects.toThrow(ProtocolViolation);
});
Loading
Loading