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
2 changes: 0 additions & 2 deletions drafts/draft-lcurley-moq-ietf.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,6 @@ A Group Stream, FETCH response, or datagram is read with the Version of its trac
# Group Streams {#group}
When the extension is negotiated, a Group Stream carries a Group State after the GROUP message, and an Object Record before each FRAME.
A FETCH response carries the same, with the Group State first.
A FETCH for a track with a Version MUST NOT set a non-zero `Start Byte`, since an Object Record names a whole object; a publisher MUST reset the response with a PROTOCOL_VIOLATION otherwise.

~~~
Group Stream {
Expand Down Expand Up @@ -266,7 +265,6 @@ A high, distinctive value is used to avoid collisions with the low values {{moql

## Since draft-lcurley-moq-ietf-00 (in progress)

- A FETCH for a track with a Version never starts partway into a frame.
- A relay never restates the Max Age as MAX_CACHE_DURATION, and a sealed MAX_CACHE_DURATION is advisory.
- Preserve relayed track timestamps and their unchecked MoQ Transport provenance across negotiated hops. Without the extension a relay serves them as native moq-lite timestamps rather than untimed.
- Initial version.
Expand Down
8 changes: 0 additions & 8 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,6 @@ A subscriber that has received frames 0 through `N-1` of group `G` and wants the

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 subscriber that has received the first `B` bytes of frame `N` FETCHes `G` from frame `N` with a `Start Byte` of `B`, so a frame read partway on one publisher continues on another without sending its first bytes again.

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.
Expand Down Expand Up @@ -2240,7 +2239,6 @@ FETCH Message {
Subscriber Max Age (i)
Group Sequence (i)
Frame Start (i)
Start Byte (i)
Frame End (i)
}
~~~
Expand Down Expand Up @@ -2269,11 +2267,6 @@ The sequence number of the group to fetch.
The index of the first frame to return within the group (see [Positions](#positions)).
A plain absolute index; 0 means the start of the group (default).

**Start Byte**:
The offset of the first payload byte to return within the frame at `Frame Start`; 0 means the whole frame (default).
The first FRAME of the response still states that frame's full size, and carries only its payload from `Start Byte` on; later frames are whole.
A non-zero `Start Byte` at or past the frame's size is a protocol violation, since the rest of a frame is never empty, and so is a non-zero `Start Byte` on a Track whose `Compression` is not none, since a compressed frame inflates only from its first byte, or on a Track carrying a MoqTransport Version under the `ietf` extension, whose object records name whole objects.

**Frame End**:
The last frame to return (inclusive), encoded as the absolute frame index + 1.
A value of 0 means through the end of the group (default).
Expand Down Expand Up @@ -2578,7 +2571,6 @@ An application-specific payload.
- 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.
- 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.
- Added `Start Byte` to FETCH, after `Frame Start`: the response's first frame states its full size and carries only its payload from that byte, so a frame read partway on one publisher continues on another from where it stopped.
- 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
18 changes: 0 additions & 18 deletions js/net/src/lite/fetch.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,6 @@ test("Fetch decodes the optional delay offset before converting to milliseconds"
await w.u62(delay + 1n);
await w.u62(42n);
await w.u53(0); // start frame
await w.u53(0); // start byte
await w.u53(0); // through the end
}),
);
Expand All @@ -101,20 +100,3 @@ test("Fetch decodes the optional delay offset before converting to milliseconds"
unsafe.maxDelay = Number.MAX_SAFE_INTEGER + 1;
await expect(encode(version, unsafe)).rejects.toThrow(RangeError);
});

test("Fetch carries a start byte only on draft-07, beside its start frame", async () => {
const partway = () =>
new Fetch({
broadcast: Path.from("room/1"),
track: "video",
priority: 3,
group: 42n,
startFrame: 2,
startByte: 1 << 20,
endFrame: 5,
});
const got = await roundtrip(Version.DRAFT_07, partway());
expect([got.startFrame, got.startByte, got.endFrame]).toEqual([2, 1 << 20, 5]);
await expect(encode(Version.DRAFT_06, partway())).rejects.toThrow("start byte");
expect((await roundtrip(Version.DRAFT_06, sample())).startByte).toBe(0);
});
25 changes: 5 additions & 20 deletions js/net/src/lite/fetch.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import * as Duration from "./duration.ts";
import { decodeNode, decodePin, encodeNode, encodePin } from "./instance.ts";
import * as Message from "./message.ts";
import { fromWire, toWire } from "./priority.ts";
import { hasByteStart, hasFetchMaxDelay, hasFrameBounds, Version } from "./version.ts";
import { hasFetchMaxDelay, hasFrameBounds, Version } from "./version.ts";

function guardFetch(version: Version) {
switch (version) {
Expand Down Expand Up @@ -34,12 +34,6 @@ export class Fetch {
/** Index of the first frame to return; 0 is the start of the group. Lite-06+. */
startFrame: number;

/**
* Offset of the first byte to return within frame {@link startFrame}; 0 is the whole
* frame. The response still states that frame's full size. Lite-07+.
*/
startByte: number;

/**
* Index of the last frame to return (inclusive), or undefined for through the end
* of the group. Lite-06+.
Expand All @@ -56,7 +50,6 @@ export class Fetch {
maxDelay,
group,
startFrame = 0,
startByte = 0,
endFrame,
}: {
broadcast: Path.Valid;
Expand All @@ -68,7 +61,6 @@ export class Fetch {
maxDelay?: number;
group: bigint;
startFrame?: number;
startByte?: number;
endFrame?: number;
}) {
this.broadcast = broadcast;
Expand All @@ -80,7 +72,6 @@ export class Fetch {
this.maxDelay = maxDelay;
this.group = group;
this.startFrame = startFrame;
this.startByte = startByte;
this.endFrame = endFrame;
}

Expand All @@ -94,17 +85,13 @@ export class Fetch {
else if (this.maxDelay !== undefined) throw new Error("fetch maxDelay not supported for this version");
await w.u62(this.group);

if (!hasFrameBounds(version) && (this.startFrame !== 0 || this.endFrame !== undefined)) {
if (hasFrameBounds(version)) {
await w.u53(this.startFrame);
await w.u53(this.endFrame !== undefined ? this.endFrame + 1 : 0);
} else if (this.startFrame !== 0 || this.endFrame !== undefined) {
// The peer would serve the whole group, including frames we excluded.
throw new Error("frame bounds not supported for this version");
}
if (!hasByteStart(version) && this.startByte !== 0) {
// The peer would resend the frame from its start, misaligning the reader.
throw new Error("fetch start byte not supported for this version");
}
if (hasFrameBounds(version)) await w.u53(this.startFrame);
if (hasByteStart(version)) await w.u53(this.startByte);
if (hasFrameBounds(version)) await w.u53(this.endFrame !== undefined ? this.endFrame + 1 : 0);
}

static async #decode(r: Reader, version: Version): Promise<Fetch> {
Expand All @@ -121,7 +108,6 @@ export class Fetch {
}

const startFrame = await r.u53();
const startByte = hasByteStart(version) ? await r.u53() : 0;
const endFrame = await r.u53();
if (endFrame > 0 && endFrame - 1 < startFrame) {
throw new Error("fetch frame range ends before it starts");
Expand All @@ -137,7 +123,6 @@ export class Fetch {
maxDelay,
group,
startFrame,
startByte,
endFrame: endFrame > 0 ? endFrame - 1 : undefined,
});
}
Expand Down
25 changes: 8 additions & 17 deletions js/net/src/lite/publisher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ import {
} from "../internal.ts";
import type { Consumer as OriginConsumer } from "../origin.ts";
import * as Path from "../path.ts";
import { readSize, sendPayload, sendPayloadFrom } from "../payload.ts";
import { readSize, sendPayload } from "../payload.ts";
import { Priority, sendOrder } from "../priority.ts";
import { rescale } from "../rescale.ts";
import { concat, encodeVarint, type Reader, type Stream, type StreamVersion, Writer } from "../stream.ts";
Expand Down Expand Up @@ -276,10 +276,7 @@ type ServeGroup = {
};

/** What serving fetched frames needs beyond the group and destination stream. */
type ServeFetch = Omit<ServeGroup, "sub"> & {
/** The byte frame `start` is served from: only its rest follows its full-size header. */
byte: number;
};
type ServeFetch = Omit<ServeGroup, "sub">;

/** What the serving loop takes from the subscribe stream instead of serving a group. */
type Control =
Expand Down Expand Up @@ -1389,7 +1386,6 @@ export class Publisher {
stamp: stamping(this.version, info),
compress: info.compress,
start: msg.startFrame,
byte: msg.startByte,
end: msg.endFrame,
});
console.debug(`fetch done: broadcast=${msg.broadcast} track=${msg.track} group=${msg.group}`);
Expand Down Expand Up @@ -2431,10 +2427,8 @@ export class Publisher {
async #runFetchGroup(
group: group.Consumer,
stream: Writer,
{ stamp, compress, start: startFrame, byte, end: endFrame }: ServeFetch,
{ stamp, compress, start: startFrame, end: endFrame }: ServeFetch,
) {
// A compressed frame inflates only from its first byte; no subscriber asks for less.
if (byte > 0 && compress) throw new Error("a compressed frame is served whole");
// The response carries no header, so the receiver numbers the first frame it gets
// as `startFrame`. Skipping the head here is the only thing keeping those numbers
// honest; a group that ends before we reach it can't be served at all.
Expand All @@ -2459,14 +2453,11 @@ export class Publisher {
prevTs = ts;
}

// The first frame states its full size, then carries only the bytes from `byte`.
const skip = index === startFrame ? byte : 0;
const size = readSize(read);
// A non-zero start byte names a byte of the frame, so the rest is never empty.
if (skip > 0 && skip >= size) throw new Error(`fetch start byte ${skip} not within the frame's ${size}`);
await stream.write(frameHeader(stream.version, delta, read.inflated, size, hasLengthFirst(this.version)));
if (read.chunks) await sendPayloadFrom(read.chunks, skip, (chunk) => stream.write(chunk), stream.closed);
else if (frame.payload.length > skip) await stream.write(frame.payload.subarray(skip));
await stream.write(
frameHeader(stream.version, delta, read.inflated, readSize(read), hasLengthFirst(this.version)),
);
if (read.chunks) await sendPayload(read.chunks, (chunk) => stream.write(chunk), stream.closed);
else if (frame.payload.length > 0) await stream.write(frame.payload);
}
}

Expand Down
6 changes: 0 additions & 6 deletions js/net/src/lite/version.ts
Original file line number Diff line number Diff line change
Expand Up @@ -311,12 +311,6 @@ export function hasRanges(version: Version): boolean {
}
}

/** Whether FETCH carries a Start Byte within its first frame, so a reader cut off partway
* through a frame asks for only the rest of it. Added in lite-07. */
export function hasByteStart(version: Version): boolean {
return hasFetchMaxDelay(version);
}

/** Whether FETCH carries the subscriber's optional max delay. Added in lite-07; an earlier
* fetch is bounded by the publisher's max age alone. */
export function hasFetchMaxDelay(version: Version): boolean {
Expand Down
19 changes: 4 additions & 15 deletions js/net/src/payload.ts
Original file line number Diff line number Diff line change
Expand Up @@ -76,24 +76,13 @@ export async function sendPayload(
write: (chunk: Uint8Array) => Promise<unknown>,
closed: Promise<void>,
): Promise<void> {
return sendPayloadFrom(chunks, 0, write, closed);
}

/** {@link sendPayload}, writing only the bytes from offset `skip` on. */
export async function sendPayloadFrom(
chunks: frame.Consumer,
skip: number,
write: (chunk: Uint8Array) => Promise<unknown>,
closed: Promise<void>,
): Promise<void> {
for (let read = 0; ; ) {
for (let sent = 0; ; ) {
const chunk = await hooks.readFrameChunk(chunks, closed);
if (!(chunk instanceof Uint8Array)) {
if (read < chunks.size) throw new Error("stream closed mid-frame");
if (sent < chunks.size) throw new Error("stream closed mid-frame");
return;
}
const from = Math.max(0, skip - read);
read += chunk.byteLength;
if (from < chunk.byteLength) await write(chunk.subarray(from));
sent += chunk.byteLength;
await write(chunk);
}
}
30 changes: 0 additions & 30 deletions quest/m2/fetch-start-byte.md

This file was deleted.

1 change: 0 additions & 1 deletion quest/m2/lite07-finalize.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,6 @@ would need a breaking release had it landed right after the cut:
- [Lite-07 by start](/quest/m2/time-addressing/lite07.md) - lite-07 carries group starts, previous-start links, GROUP_END, and time bounds instead of sequence numbers
- [@moq/net by start](/quest/m2/time-addressing/js.md) - JS speaks the same lite-07 wire
- [Warm routes on the wire](/quest/m2/warm-routes-wire.md) - removes WARM_* and SUBSCRIBE's `Warm` byte from lite-07
- [FETCH Start Byte](/quest/m2/fetch-start-byte.md) - removes FETCH's byte offset into a half-read frame
- [Subscriber Min Age](/quest/m2/subscriber-min-age.md) - removes SUBSCRIBE's minimum age, which nothing reads

## Related
Expand Down
33 changes: 20 additions & 13 deletions quest/m3/unbounded-groups/README.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,37 @@
# Unbounded groups and frames
# Unbounded groups

## Goal

Groups and frames have no fixed size cap. `MAX_GROUP_FRAMES` is already gone
Groups have no fixed size cap. `MAX_GROUP_FRAMES` is already gone
([moq-dev/moq#6993](https://github.com/moq-dev/moq/pull/6993)), and
`MAX_CACHE_BYTES` (32 MB) stops capping groups and frames and instead bounds
how much of a group's live tail is held. A group sheds whole frames from its
front once its tail passes 32 MB, or sooner when the shared cache pool is over
budget, so one long group never grows without bound even on a relay with no
cache capacity set. A reader or FETCH that reaches a shed front is served by a
`MAX_CACHE_BYTES` (32 MB) stops capping groups and instead bounds how much of
a group's live tail is held. A group sheds whole frames from its front once
its tail passes 32 MB, or sooner when the shared cache pool is over budget,
so one long group never grows without bound even on a relay with no cache
capacity set. A reader or FETCH that reaches a shed front is served by a
flight, a separate paced copy filled from upstream or the publisher's own
refill handler; failing that, it asks for a new group (refresh), and otherwise
it gets `Evicted`. Readers never fail just because a group got big. The
motivating workloads are long-lived single groups (data/log tracks, audio,
window timelines), video with very long GOPs, and file transfers where a frame
is a whole file.
window timelines) and video with very long GOPs.

The hot write and read path for ordinary groups does not regress.

Non-goals: pinning memory for slow readers, byte-precise refill over
moq-transport, and starting a reader mid-group at whatever the cache still
holds (a tail join).
moq-transport, starting a reader mid-group at whatever the cache still
holds (a tail join), and frames over 32 MiB in Rust or mid-frame resume.

## Plan

Decided 2026-11-15 (maintainer, on
[moq-dev/moq#8837](https://github.com/moq-dev/moq/pull/8837)): ✅ delete Byte
holes (rejected: keep it parked). No consumer sends frames over 32 MiB, so a
Rust frame stays capped at `MAX_CACHE_BYTES` and mid-frame resume is out until
one does. JS byte holes, which only mirrored it for `@moq/net`, went with it. A frame cut off partway on a route failure is
refetched whole and the reader skips what it read (`frame::Consumer`'s
`Recover`). The decisions below on byte positions, segment shedding, and the
byte offset on the lite wip are history until then.

Decided 2026-11-05 (maintainer, /quest-plan), on the open questions of
[moq-dev/moq#7944](https://github.com/moq-dev/moq/pull/7944), which landed
flights:
Expand Down Expand Up @@ -152,8 +160,7 @@ Decided 2026-10-16 (maintainer interview):
- The byte offset goes on the current lite wip version (lite-07-wip today);
the lite-07 cut does not wait on it. Decided 2026-10-27 (maintainer): wire
quests target whichever wip is current when they land, so
[Byte holes](/quest/m3/unbounded-groups/byte-holes.md) waits only on Front
eviction and Flights. If lite-07 is cut first, lite-07 peers start flights
Byte holes waited only on Front eviction and Flights. If lite-07 is cut first, lite-07 peers start flights
only at frame boundaries, over lite-07's transport frame offsets, which
allow a fill to start without the shed prefix (decided 2026-10-25,
maintainer: the application API stays whole-group).
Expand Down
Loading