Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
52055eb
chore(quest): claim quest/m1/subscribe-ranges/js.md
kixelated Nov 3, 2026
f5f3a75
feat(net): JS track requests serve the groups readers miss
kixelated Nov 3, 2026
cf1290e
test(net): cover JS fills in-process and from a native CLI FETCH
kixelated Nov 3, 2026
3dcf441
feat(net): name fill internals, wake a closed handle's wait, skip buf…
kixelated Nov 3, 2026
895bc15
Merge origin/main: port fills to bigint sequences; a fetch miss asks …
kixelated Nov 3, 2026
3da8e78
chore(net): API report for bigint fill sequences
kixelated Nov 3, 2026
b2cf099
fix(net): join a fill still out without a handle, and wake an ordered…
kixelated Nov 3, 2026
585dd47
fix(net): wait on any fill the budget still wants, keep asked misses …
kixelated Nov 3, 2026
52816b0
Merge remote-tracking branch 'origin/main' into t3/0a3f92f0
kixelated Nov 3, 2026
88bf464
Merge remote-tracking branch 'origin/main' into t3/0a3f92f0
kixelated Nov 3, 2026
a3fd02a
fix(net): a fill owes each reader only the groups it reads, as Rust's…
kixelated Nov 3, 2026
1601b43
Merge remote-tracking branch 'origin/main' into t3/0a3f92f0
kixelated Nov 3, 2026
d11f34b
fix(net): wake an arrival-order read its stale fill hole releases, an…
kixelated Nov 3, 2026
d73ee68
Merge remote-tracking branch 'origin/main' into t3/0a3f92f0
kixelated Nov 3, 2026
f40c1d6
fix(net): withdraw a fill's unread groups for good, clip a reader's w…
kixelated Nov 3, 2026
cdbcb85
fix(net): a widening asks withdrawn groups afresh, not through the ev…
kixelated Nov 3, 2026
16f1bd8
Merge remote-tracking branch 'origin/main' into t3/0a3f92f0
kixelated Nov 3, 2026
1d17294
Merge base into pr-7696 and resolve hook and quest conflicts
Nov 3, 2026
80474d0
quest: delete js.md now that its content moved to lite.md
pullfrog[bot] Nov 3, 2026
c93c2f9
Merge origin/main: keep js.md deleted and move #7675's JS leftovers t…
kixelated Nov 4, 2026
a385e1f
fix(net): wake readers when a handler opens, give up stale fill runs,…
kixelated Nov 4, 2026
69cfadd
Merge remote-tracking branch 'origin/main' into t3/0a3f92f0
kixelated Nov 4, 2026
797db03
Merge branch 'quest/m1/subscribe-ranges/js' of github.com:moq-dev/moq…
kixelated Nov 4, 2026
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
1 change: 1 addition & 0 deletions doc/lib/js/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ publication.announce();
- **One send estimate per connection.** `Bandwidth.Allocator` divides it by track priority, max-min fair within a tier. An idle track claims nothing, though its reservation still reads the share it would get. Publishers reserve against it so their targets sum to the estimate. A connection samples the estimate from its transport only while a reservation reads it, so receive-only and lingering connections do no stats work, and the first reservation after none reads `undefined` until one fresh snapshot lands. A transport that cannot report one is never sampled and reads `undefined`: the WebSocket fallback, WebRTC, and WebTransport without `getStats()` (shipping Chromium and Safari).
- **List a broadcast's tracks.** `for await (const event of broadcast.tracks())` reports each track the broadcast lists (`added`, with its `Track.Info`), one `synced`, then `added` and `removed` as tracks come and go, until the broadcast ends; leaving the loop stops listing. Over a session it needs `moq-lite-07-wip`, syncs at once with what this side holds, and the peer's tracks follow as `added`. A track served only on request is never listed. See [discovery](/concept/moq-lite#discovery).
- **One track per name.** Concurrent subscriptions share one request and producer. `createTrack` on a name with a request still queued answers it. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a track that replaces it, created or requested, starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups by writing its first group with an explicit sequence. Sequences are `bigint`, so every ID the wire carries fits, past 2^53 included: `track.createGroup(5n)`, `{ absolute: 10n }`. Frame indices and relative anchors stay `number`.
- **Serve history on request.** `track.requests()` opens a handle that serves the groups readers miss: ones their ranges name below the newest group written that the cache no longer holds, or never did. Each run of misses arrives as a `Track.Fill` from `await requests.requestedFill()`, shared by every reader missing it. `accept(sequence)` it into the cache and write the group's frames as first published, `dropGroups(start, end)` what the source lacks (sequences are `bigint`), and serve `wanted()` until it is `undefined`: a reader that leaves or narrows stops wanting its groups. `close()` the fill when done; whatever is still wanted is named dropped. A `fetchGroup` of an uncached group asks the handle at once, even for a group not written yet, which a live write then answers; with no handle open it fails with `NotFound`, as in Rust, and a reader's miss is given up. A reader only asks for what its `delay.max` still wants, so a reader at the live edge never asks. This serves lite FETCH and lite-07 ranged subscriptions from the same track, as Rust's `requests()` does.
- **Timing is per track, with no default.** A track that declares a `timescale` carries a `timestamp` on every frame; one without is [untimed](/concept/moq-lite#subscriptions) and its frames carry none. Omitting it means untimed, as in Rust. Nothing stamps a frame for you: the publisher passes the timestamp, and the `Timed` type (`{ value, at }`) carries one into the `@moq/json` producers.
- **A subscription's `delay` is a `Track.Delay { min, max }`, as in Rust.** Staleness is `delay.max`: it counts from a group's successor, by media time and by wall clock, whichever reaches it first. `delay.min` is the target latency, carried on moq-lite 07; a peer that cannot carry it leaves it `null` (not stated). Passing the old `maxAge` or `maxDelay` key throws a `TypeError` naming `delay.max`. The publisher's own staleness bound is the separate `Track.Info.maxAge`, which caps `delay.max` and fetches.
- **The cache keeps an idle group for 30 seconds.** A track evicts a group nothing has written for 30 seconds, matching the Rust cache's default expiry; a live track's newest group is exempt until a newer one arrives, unless it failed. Neither `Track.Info.maxAge` nor `delay.max` changes that window: they only decide which cached groups a reader still receives.
Expand Down
23 changes: 23 additions & 0 deletions js/net/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -630,6 +630,22 @@ export namespace Track {
priority?: number;
signal?: AbortSignal;
}
export class Fill {
[Symbol.dispose](): void;
accept(sequence: bigint, info?: Partial<Track.Info>): Group.Producer;
close(): void;
dropGroups(start: bigint, end: bigint): void;
readonly end: bigint;
isWanted(sequence: bigint): boolean;
get maxDelay(): Milli | null;
get order(): Track.Order;
get priority(): number;
refuseGroups(start: bigint, end: bigint, error: Error): void;
readonly start: bigint;
unwanted(sequence: bigint): Promise<void>;
wanted(): bigint | undefined;
wantedChanged(): Promise<bigint | undefined>;
}
export interface Groups {
end?: Track.Bound;
start?: Track.Bound;
Expand Down Expand Up @@ -684,6 +700,7 @@ export namespace Track {
largest(): Track.Position | undefined;
readonly name: string;
get priority(): number;
requests(): Track.Requests;
subscribe(options?: Track.Subscription): Track.Subscriber;
get subscription(): Signals.Getter<Track.Subscription | undefined>;
writeFrame(frame: Group.Frame): void;
Expand All @@ -700,6 +717,12 @@ export namespace Track {
reject(err: Error): void;
get subscription(): Readonly<Track.Subscription>;
}
export class Requests {
[Symbol.dispose](): void;
close(): void;
get name(): string;
requestedFill(): Promise<Track.Fill | undefined>;
}
export class Subscriber {
close(abort?: Error): void;
get closed(): Signals.GetPromise<Error | null>;
Expand Down
10 changes: 8 additions & 2 deletions js/net/src/broadcast.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -620,9 +620,11 @@ test("close rejects a still-pending track request so its subscriber unblocks", a
// A fetch parks for a group that has yet to be published, which is what the consuming wire
// layer's coalescing relies on. The publisher's fill deliberately does not use this path: it
// wants a group that already exists, and waiting for one that is gone would never return.
test("a fetch waits for a group still to come", async () => {
test("a fetch of a group still to come asks the request handler, and the write answers it", async () => {
const broadcast = new BroadcastProducer();
const track = broadcast.createTrack("video", { timescale: Timescale.MILLI });
// As in Rust, the miss goes to the handler at once; without one it would be NotFound.
const requests = track.requests();

const pending = wireOf(broadcast).fetchGroup("video", 1n);

Expand All @@ -638,6 +640,7 @@ test("a fetch waits for a group still to come", async () => {
expect(group.sequence).toBe(1n);
expect(await group.readString()).toBe("1");

requests.close();
broadcast.close();
});

Expand All @@ -664,7 +667,9 @@ test("fetch maxDelay tightens the publisher's maxAge without changing omission",

test("aborting a fetch rejects with the signal's reason", async () => {
const broadcast = new BroadcastProducer();
broadcast.createTrack("video", { timescale: Timescale.MILLI });
const track = broadcast.createTrack("video", { timescale: Timescale.MILLI });
// A request handler keeps the miss pending until the abort.
const requests = track.requests();

const early = new Error("early");
await expect(wireOf(broadcast).fetchGroup("video", 0n, { signal: AbortSignal.abort(early) })).rejects.toBe(early);
Expand All @@ -675,6 +680,7 @@ test("aborting a fetch rejects with the signal's reason", async () => {
controller.abort(late);
await expect(pending).rejects.toBe(late);

requests.close();
broadcast.close();
});

Expand Down
64 changes: 48 additions & 16 deletions js/net/src/broadcast.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
* @module
*/
import { type GetPromise, Once, Signal } from "@moq/signals";
import { NotFound, StreamCode, StreamError } from "./error.ts";
import { NotFound, StreamCode, StreamError, toStreamCode } from "./error.ts";
import type { Consumer as GroupConsumer } from "./group.ts";
import type { Route } from "./hop.ts";
import type * as Instance from "./instance.ts";
Expand Down Expand Up @@ -214,39 +214,71 @@ function largest(state: BroadcastState, name: string): track.Position | undefine
return producer && hooks.cachedLargest(producer);
}

// Serve a group from the local retained window by subscribing and scanning to the
// requested sequence. The default for a produced broadcast; the consuming wire layer
// overrides it to fetch over the network (or to reject when the transport has no FETCH).
// Fetch one group as a one-range subscription: the cached group at once, or else one the track's
// {@link track.Requests} handler answers, asked at once whether the group was written yet or not,
// as the Rust `fetch_group` does. A group the producer writes meanwhile answers it too. With no
// handler open, a miss fails at once with `NotFound`. The default for a produced broadcast; the
// consuming wire layer overrides it to fetch over the network (or to reject when the transport has
// no FETCH).
async function fetchGroup(
state: BroadcastState,
name: string,
sequence: bigint,
options: track.FetchGroupOptions = {},
): Promise<GroupConsumer> {
options.signal?.throwIfAborted();
const subscriber = subscribe(state, name, { ...track.Subscription.default(), priority: options.priority });
const subscriber = subscribe(state, name, {
...track.Subscription.default(),
priority: options.priority,
ranges: [{ start: { absolute: sequence }, end: { absolute: sequence + 1n } }],
});
hooks.fetchBudget(subscriber, options.maxDelay);
try {
// Judged in this turn when the track is known, so a cached group is taken before anything
// else can change it. A track requested on demand opens its handler once accepted, so its
// miss is judged then.
let asked = hooks.askFetch(subscriber, sequence);
if (asked === "pending") {
await untilAborted(subscriber.info(), options.signal);
asked = hooks.askFetch(subscriber, sequence);
}
if (asked !== true) throw new NotFound(`group ${sequence}`);
for (;;) {
const group = await untilAborted(subscriber.recvGroup(), options.signal);
if (!group) throw new NotFound(`group ${sequence}`);
if (group.sequence === sequence) {
// Close the subscription when the returned group finishes, not now: an
// in-progress group must keep receiving frames for its lifetime (mirrors
// Rust poll_fetch). Also fires if the caller closes the group early.
void group.closed.then(() => subscriber.close());
return group;
const recv = hooks.tryRecvGroup(subscriber, true);
switch (recv.kind) {
case "group":
// Close the subscription when the returned group finishes, not now: an
// in-progress group must keep receiving frames for its lifetime (mirrors
// Rust poll_fetch). Also fires if the caller closes the group early.
void recv.group.closed.then(() => subscriber.close());
return recv.group;
case "drop":
// A fill's refusal says why; anything else given up is just gone.
if (toStreamCode(recv.error) === StreamCode.Old) throw new NotFound(`group ${sequence}`);
throw recv.error;
case "error":
throw recv.error;
case "done":
throw new NotFound(`group ${sequence}`);
}

group.close();
if (group.sequence > sequence) throw new NotFound(`group ${sequence}`);
await untilAborted(changed(subscriber), options.signal);
}
} catch (err) {
subscriber.close();
throw err;
}
}

// Settles once a read of `subscriber` may go differently.
function changed(subscriber: track.Subscriber): Promise<void> {
return new Promise((resolve) => {
const dispose = hooks.groupChanged(subscriber, () => {
dispose();
resolve();
});
});
}

// Remove and return the request queued for `name`, if no handler has taken it yet.
function takeQueued(state: BroadcastState, name: string): track.Request | undefined {
const queued = state.requested.peek().find((request) => request.name === name);
Expand Down
Loading
Loading