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: 2 additions & 0 deletions drafts/draft-lcurley-moq-ietf.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ 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 @@ -265,6 +266,7 @@ 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: 8 additions & 0 deletions drafts/draft-lcurley-moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,7 @@ 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 @@ -2132,6 +2133,7 @@ FETCH Message {
Subscriber Max Age (i)
Group Sequence (i)
Frame Start (i)
Start Byte (i)
Frame End (i)
}
~~~
Expand Down Expand Up @@ -2160,6 +2162,11 @@ 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 @@ -2457,6 +2464,7 @@ 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
22 changes: 20 additions & 2 deletions js/net/src/lite/fetch.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -87,8 +87,9 @@ test("Fetch decodes the optional delay offset before converting to milliseconds"
await w.u8(0);
await w.u62(delay + 1n);
await w.u62(42n);
await w.u53(0);
await w.u53(0);
await w.u53(0); // start frame
await w.u53(0); // start byte
await w.u53(0); // through the end
}),
);
const decoded = Fetch.decode(new Reader(undefined, encoded, version), version);
Expand All @@ -99,3 +100,20 @@ 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: 20 additions & 5 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 { hasFetchMaxDelay, hasFrameBounds, Version } from "./version.ts";
import { hasByteStart, hasFetchMaxDelay, hasFrameBounds, Version } from "./version.ts";

function guardFetch(version: Version) {
switch (version) {
Expand All @@ -32,6 +32,12 @@ 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 @@ -47,6 +53,7 @@ export class Fetch {
maxDelay,
group,
startFrame = 0,
startByte = 0,
endFrame,
}: {
broadcast: Path.Valid;
Expand All @@ -57,6 +64,7 @@ export class Fetch {
maxDelay?: number;
group: bigint;
startFrame?: number;
startByte?: number;
endFrame?: number;
}) {
this.broadcast = broadcast;
Expand All @@ -67,6 +75,7 @@ export class Fetch {
this.maxDelay = maxDelay;
this.group = group;
this.startFrame = startFrame;
this.startByte = startByte;
this.endFrame = endFrame;
}

Expand All @@ -80,13 +89,17 @@ 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)) {
await w.u53(this.startFrame);
await w.u53(this.endFrame !== undefined ? this.endFrame + 1 : 0);
} else if (this.startFrame !== 0 || this.endFrame !== undefined) {
if (!hasFrameBounds(version) && (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 @@ -103,6 +116,7 @@ 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 @@ -117,6 +131,7 @@ export class Fetch {
maxDelay,
group,
startFrame,
startByte,
endFrame: endFrame > 0 ? endFrame - 1 : undefined,
});
}
Expand Down
25 changes: 17 additions & 8 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 } from "../payload.ts";
import { readSize, sendPayload, sendPayloadFrom } 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 @@ -279,7 +279,10 @@ type ServeGroup = {
};

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

/** What the serving loop takes from the subscribe stream instead of serving a group. */
type Control =
Expand Down Expand Up @@ -1415,6 +1418,7 @@ 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 @@ -2476,8 +2480,10 @@ export class Publisher {
async #runFetchGroup(
group: group.Consumer,
stream: Writer,
{ stamp, compress, start: startFrame, end: endFrame }: ServeFetch,
{ stamp, compress, start: startFrame, byte, 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 @@ -2502,11 +2508,14 @@ export class Publisher {
prevTs = ts;
}

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);
// 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));
}
}

Expand Down
6 changes: 6 additions & 0 deletions js/net/src/lite/version.ts
Original file line number Diff line number Diff line change
Expand Up @@ -311,6 +311,12 @@ 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: 15 additions & 4 deletions js/net/src/payload.ts
Original file line number Diff line number Diff line change
Expand Up @@ -73,13 +73,24 @@ export async function sendPayload(
write: (chunk: Uint8Array) => Promise<unknown>,
closed: Promise<void>,
): Promise<void> {
for (let sent = 0; ; ) {
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; ; ) {
const chunk = await hooks.readFrameChunk(chunks, closed);
if (!(chunk instanceof Uint8Array)) {
if (sent < chunks.size) throw new Error("stream closed mid-frame");
if (read < chunks.size) throw new Error("stream closed mid-frame");
return;
}
sent += chunk.byteLength;
await write(chunk);
const from = Math.max(0, skip - read);
read += chunk.byteLength;
if (from < chunk.byteLength) await write(chunk.subarray(from));
}
}
85 changes: 53 additions & 32 deletions quest/m3/unbounded-groups/byte-holes.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,40 @@ Moved to m3 2026-11-12 (maintainer, /quest-audit), with its epic: the cut does n

Decided 2026-11-05 (maintainer, /quest-audit): ✅ the byte offset rides
FETCH's frame start plus the group header, not a SUBSCRIBE range end.
SUBSCRIBE ranges are whole groups since 2026-11-03
(Lite-07 FETCH is single-group only,
[moq-dev/moq#8616](https://github.com/moq-dev/moq/pull/8616) and
[moq-dev/moq#7675](https://github.com/moq-dev/moq/pull/7675)), and flights
ride lite FETCH since [moq-dev/moq#7944](https://github.com/moq-dev/moq/pull/7944).
This waits for that quest.

Decided 2026-11-13 (maintainer, /quest-complete):

- ✅ The byte stays crate-private until a public API needs it (rejected: add
`Position::byte` now, about 90 literals across moq-net, moq-archive, and
moq-ffi). `Position` also names subscribe ranges and largest locations,
where a byte means nothing.
- ✅ [moq-dev/moq#8699](https://github.com/moq-dev/moq/pull/8699) merges its
slice alone, and this quest keeps the rest (rejected: grow that PR to the
whole quest).

Landed in [moq-dev/moq#8699](https://github.com/moq-dev/moq/pull/8699), the
first slice:

- Lite-07 FETCH carries a `Start Byte` after `Frame Start`, in Rust, JS, and the
lite draft. The response's first frame states its full size and carries only
its bytes from there. A FETCH response has no header, so this needed no
group-header field.
- A group copy can start partway into a frame: `group::Bounds::byte` keeps the
rest of that frame aside as the copy's `Lead`, outside the frame log. Every
whole-frame read finds that frame missing (`Lagged`). Only
`group::Consumer::at` with `poll_next_frame_at` reads it, from a byte at or
past the copy's start.
- Route failover mid-frame (`frame::Consumer`'s `Recover`) asks for only the
missing suffix by byte. Its integration regression is
`rs/moq-net/tests/integration/byte_holes.rs`, with a 5 MiB frame. A frame
larger than the 32 MB tail waits on the frame cap below.
- Rust readers already had a chunked payload read
(`frame::Consumer::read_chunk`), so nothing was added.
- The byte stays crate-private (`group::Fetch::byte_start`, the fill's start).
Public `Position` did not gain a field, since nothing public reads a byte
position yet.

What remains:

- Segments are `frame::SEGMENT` (1 MiB) long, so segment `i` always holds
bytes from `i * SEGMENT`, and a completed chain is `frame::Payload::Chain`.
Expand All @@ -39,36 +67,29 @@ This waits for that quest.
stays one `Bytes` at any size, so evicting part of it needs it split into
segment slices, whose memory frees only once every slice drops, or copied
into segments.

- `Position` gains a byte offset within the frame. A lite FETCH carries it
beside its `frame_start`, and so does a group stream header. A
stream that starts mid-frame still states the frame's full size. Older
lite versions and moq-transport start flights only at frame or object
boundaries. A reader inside a shed object refreshes or is `Evicted` there.
- Every sealed segment is evictable under the same policy as front frames,
including one a reader is on. A reader keeps its current segment alive
through its own reference, as prefetched frames are today. That memory
is bounded by readers times one segment, not by the cache. Only the
writer's open segment stays resident. A reader at a shed segment boards
a flight that starts at its `(frame, byte)`.
- Route failover mid-frame (`frame::Consumer`'s `Recover`) requests only
the missing suffix by byte, instead of refetching the frame from its
start. Cover it with a regression: a route fails partway through a frame
larger than the 32 MB tail.
- Update `drafts/draft-lcurley-moq-lite.md` and run `just drafts check`.
Also drop the 32 MiB interop cap in `drafts/draft-lcurley-moq-e2ee.md` if
it no longer follows from a model limit.
- Rust readers get a chunked payload read, so a frame larger than memory
never has to be collected whole. [moq-dev/moq#6628](https://github.com/moq-dev/moq/pull/6628)
kept its segments internal. JS already has its chunked read
(`nextFrame` and `readChunk`, from
[moq-dev/moq#7411](https://github.com/moq-dev/moq/pull/7411)); its wire
half is in [JS byte holes](/quest/m3/unbounded-groups/js-byte-holes.md).
is bounded by readers times one segment, not by the cache. A reader holding
a `Payload::Chain` holds every segment through its `Arc<[Bytes]>` today, so
the chain has to hand a reader one segment at a time. Only the writer's open
segment stays resident. A reader at a shed segment boards a flight that
starts at its `(frame, byte)`: `FillState::fly` and `group::Bounds` already
carry the byte, and the flight's copy starts with a `Lead`.
- A group stream that starts mid-frame (a relay holding only a group's tail,
once segments shed) carries the byte offset in the lite wip GROUP header
beside `Frame Start`, and still states the frame's full size. Older lite
versions and moq-transport start only at frame or object boundaries. A
reader inside a shed object refreshes or is `Evicted` there.
- `MAX_CACHE_BYTES` stops capping a frame (`group::Producer::open_frame` and
`open_lead` refuse a larger one today). Then extend the failover regression
to a frame larger than the 32 MB tail.
- Drop the 32 MiB interop cap in `drafts/draft-lcurley-moq-e2ee.md` if it no
longer follows from a model limit, and run `just drafts check`.
- Test a frame several times the 32 MB tail through a relay chain: a late
joiner reads it whole through a flight, and memory stays near 32 MB per
copy.

Public API: `Position` gains a byte field, frames gain a chunked read, and
`MAX_CACHE_BYTES` stops capping a frame.
Wire: a byte offset on the current lite wip's FETCH frame start and group
header.
Public API: `Position` gains a byte field only once a public reader needs a
byte position, and `MAX_CACHE_BYTES` stops capping a frame. Wire: a byte
offset on the current lite wip's group header.
Loading