From 52055eba81e6070e34b79265b2996a731bf20ac8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 23:35:25 -0800 Subject: [PATCH 01/13] chore(quest): claim quest/m1/subscribe-ranges/js.md Quest-Claim: 9bbea71fb3cce5b8 From f5f3a75d1ecea056a5f736de2617d15f80e68a54 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 23:49:52 -0800 Subject: [PATCH 02/13] feat(net): JS track requests serve the groups readers miss Co-Authored-By: Claude Opus 5.5 --- js/net/src/broadcast.ts | 53 +++-- js/net/src/fill.ts | 484 ++++++++++++++++++++++++++++++++++++++++ js/net/src/track.ts | 159 ++++++++++++- 3 files changed, 676 insertions(+), 20 deletions(-) create mode 100644 js/net/src/fill.ts diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index 4c1d7ababea..4eac0e856af 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -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"; @@ -214,9 +214,10 @@ 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 one the track's +// {@link track.Requests} fills, or `NotFound` once the track can no longer deliver it. A group +// not written yet waits for the producer. 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, @@ -224,22 +225,32 @@ async function fetchGroup( options: track.FetchGroupOptions = {}, ): Promise { 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 + 1 } }], + }); hooks.fetchBudget(subscriber, options.maxDelay); try { 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(); @@ -247,6 +258,16 @@ async function fetchGroup( } } +// Settles once a read of `subscriber` may go differently. +function changed(subscriber: track.Subscriber): Promise { + 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); diff --git a/js/net/src/fill.ts b/js/net/src/fill.ts new file mode 100644 index 00000000000..9f37ba9deb8 --- /dev/null +++ b/js/net/src/fill.ts @@ -0,0 +1,484 @@ +/** + * Serving the groups a track's readers miss: the on-demand request surface. Mirrors the Rust + * `track::Requests` and `track::Fill` (`rs/moq-net/src/model/track/fill.rs`). + * + * A reader misses a group its ranges name that the track no longer caches, or never did, below + * the newest group the producer wrote: nothing above it is a miss, since it arrives live. While a + * {@link Requests} handle is open, each run of misses queues a {@link Fill} for it to serve, and + * readers missing the same groups join the one fill rather than asking twice. With none open, a + * miss is given up as it always was. + * + * @module + */ +import { Milli } from "@moq/clock"; +import { type GetPromise, Signal } from "@moq/signals"; +import { NotFound } from "./error.ts"; +import type { Producer as GroupProducer } from "./group.ts"; +import { insertRun, NO_MAX_DELAY, type Run, runGaps } from "./internal.ts"; +import type { Info, Order } from "./track.ts"; + +/** What the fills need from the track they serve. Package-internal. */ +export interface FillTrack { + /** The track's name. */ + readonly name: string; + /** Insert group `sequence` into the cache, committing `info` first if the track has none. */ + accept(sequence: number, info: Partial | undefined): GroupProducer; + /** Record `[start, end)` as never to be delivered. */ + drop(start: number, end: number, error: Error): void; + /** Whether the track still caches group `sequence`, not failed. */ + holds(sequence: number): boolean; + /** Whether the track closed, so nothing more can be served. */ + closed(): boolean; + /** Settles once the track closes. */ + readonly released: GetPromise; +} + +/** A reader waiting on fills. Package-internal. */ +export interface Asker { + /** The parts of `[start, end)` it still reads. */ + wants(start: number, end: number): Run[]; + /** Its delivery priority. */ + priority(): number; + /** Its age budget in milliseconds: `Infinity` for none, so the publisher's alone bounds it. */ + maxDelay(): number; + /** Which end it reads first. */ + order(): Order; + /** Stop waiting for `[start, end)`, which a fill refused with `error`, without asking again. */ + refuse(start: number, end: number, error: Error): void; +} + +// The fill operations a handle runs against the state it came from; assigned in its static block. +let fillOps: { + accept(state: FillState, pending: Pending, sequence: number, info: Partial | undefined): GroupProducer; + drop(state: FillState, pending: Pending, start: number, end: number): void; + refuse(state: FillState, pending: Pending, start: number, end: number, error: Error): void; + settle(state: FillState, pending: Pending): void; + name(state: FillState): string; +}; + +// One fill: a run of groups some readers miss, until each is answered or nobody wants it. +class Pending { + readonly start: number; + readonly end: number; + readonly askers = new Set(); + // The groups answered: accepted, delivered live, dropped, or refused. + readonly resolved: Run[] = []; + // Still in the queue, not yet handed to a handler. + queued = true; + // Withdrawn or settled: owes nothing more. + done = false; + // Bumped on every change to what the fill owes, for its handler to wake on. + readonly revision = new Signal(0); + + constructor(start: number, end: number) { + this.start = start; + this.end = end; + } + + bump(): void { + this.revision.update((revision) => revision + 1); + } + + // The parts of `[start, end)` within the fill that are still unanswered. + unresolved(start = this.start, end = this.end): Run[] { + if (this.done) return []; + return runGaps(this.resolved, Math.max(start, this.start), Math.min(end, this.end)); + } + + // The parts of `[start, end)` still unanswered that a reader still reads. + owed(start = this.start, end = this.end): Run[] { + const owed: Run[] = []; + for (const gap of this.unresolved(start, end)) { + for (const asker of this.askers) { + for (const run of asker.wants(gap.start, gap.end)) insertRun(owed, run.start, run.end); + } + } + return owed; + } +} + +/** + * The fills of one track: what its readers miss, queued for its {@link Requests} handles. + * Package-internal; a producer owns one. + */ +export class FillState { + readonly #track: FillTrack; + #handlers = 0; + #queue: Pending[] = []; + readonly #queued = new Signal(0); + readonly #pending = new Set(); + + constructor(track: FillTrack) { + this.#track = track; + void track.released.then(() => this.#release()); + } + + /** Whether a handler is open to serve a miss now. */ + get serving(): boolean { + return this.#handlers > 0 && !this.#track.closed(); + } + + /** Ask for `[start, end)` for `asker`, joining the fills already bringing part of it. */ + ask(start: number, end: number, asker: Asker): void { + if (!this.serving || start >= end) return; + let missing: Run[] = [{ start, end }]; + for (const pending of this.#pending) { + const unresolved = pending.unresolved(start, end); + if (unresolved.length === 0) continue; + if (!pending.askers.has(asker)) { + pending.askers.add(asker); + pending.bump(); + } + for (const run of unresolved) missing = missing.flatMap((gap) => subtract(gap, run)); + } + for (const gap of missing) { + const pending = new Pending(gap.start, gap.end); + pending.askers.add(asker); + this.#pending.add(pending); + this.#queue.push(pending); + } + if (missing.length > 0) this.#queued.update((revision) => revision + 1); + } + + /** The first sequence of `[start, end)` a fill still owes `asker`. */ + owed(start: number, end: number, asker: Asker): number | undefined { + return this.covered(start, end, asker)[0]?.start; + } + + /** The parts of `[start, end)` a fill `asker` joined still owes, in order. */ + covered(start: number, end: number, asker: Asker): Run[] { + const covered: Run[] = []; + for (const pending of this.#pending) { + if (!pending.askers.has(asker)) continue; + for (const run of pending.unresolved(start, end)) insertRun(covered, run.start, run.end); + } + return covered; + } + + /** `asker` left: the fills it alone waited on are withdrawn. */ + leave(asker: Asker): void { + for (const pending of this.#pending) { + if (!pending.askers.delete(asker)) continue; + this.#judge(pending); + } + } + + /** What `asker` reads changed: a fill nobody reads any more is withdrawn. */ + moved(asker: Asker): void { + for (const pending of this.#pending) { + if (pending.askers.has(asker)) this.#judge(pending); + } + } + + /** Group `sequence` landed in the cache, through a fill or live: it is answered. */ + arrived(sequence: number): void { + for (const pending of this.#pending) this.#resolve(pending, sequence, sequence + 1); + } + + /** Open a handler. */ + addHandler(): void { + this.#handlers++; + } + + /** Close a handler. The last one leaving names every queued miss dropped, as with none open. */ + removeHandler(): void { + this.#handlers--; + if (this.#handlers > 0) return; + for (const pending of this.#queue.splice(0)) this.#settle(pending); + } + + /** The next queued fill, or `undefined` once the track closes with none queued. */ + async next(): Promise { + for (;;) { + const pending = this.#queue.shift(); + if (pending) { + pending.queued = false; + return pending; + } + if (this.#track.closed()) return undefined; + await Signal.race(this.#queued, this.#track.released); + } + } + + // Withdraw `pending` once no reader still reads any of what it owes. + #judge(pending: Pending): void { + if (pending.done) return; + if (pending.owed().length > 0) { + pending.bump(); + return; + } + this.#finish(pending); + } + + // Record `[start, end)` of `pending` answered. + #resolve(pending: Pending, start: number, end: number): void { + const unresolved = pending.unresolved(start, end); + if (unresolved.length === 0) return; + for (const run of unresolved) insertRun(pending.resolved, run.start, run.end); + if (pending.unresolved().length === 0) this.#finish(pending); + else pending.bump(); + } + + // Answer what `pending` still owes as dropped, then forget it. + #settle(pending: Pending): void { + for (const run of pending.owed()) this.#track.drop(run.start, run.end, new NotFound(`group ${run.start}`)); + this.#finish(pending); + } + + // Forget `pending`: it owes nothing more. + #finish(pending: Pending): void { + if (pending.done) return; + pending.done = true; + this.#pending.delete(pending); + if (pending.queued) this.#queue.splice(this.#queue.indexOf(pending), 1); + pending.bump(); + } + + #release(): void { + this.#queue = []; + for (const pending of this.#pending) this.#finish(pending); + this.#queued.update((revision) => revision + 1); + } + + static { + fillOps = { + accept: (state, pending, sequence, info) => { + if (sequence < pending.start || sequence >= pending.end) { + throw new RangeError(`group ${sequence} is outside the fill ${pending.start}..${pending.end}`); + } + if (pending.resolved.some((run) => run.start <= sequence && sequence < run.end)) { + throw new Error(`group ${sequence} was already answered`); + } + if (state.#track.holds(sequence)) throw new Error(`duplicate group: sequence=${sequence}`); + // Landing in the cache answers it, as `arrived` records. + return state.#track.accept(sequence, info); + }, + drop: (state, pending, start, end) => { + for (const run of pending.owed(start, end)) { + state.#track.drop(run.start, run.end, new NotFound(`group ${run.start}`)); + } + state.#resolve(pending, start, end); + }, + refuse: (state, pending, start, end, error) => { + for (const gap of pending.unresolved(start, end)) { + for (const asker of pending.askers) { + for (const run of asker.wants(gap.start, gap.end)) asker.refuse(run.start, run.end, error); + } + } + state.#resolve(pending, start, end); + }, + settle: (state, pending) => state.#settle(pending), + name: (state) => state.#track.name, + }; + } +} + +// The parts of `gap` outside `run`. +function subtract(gap: Run, run: Run): Run[] { + return [ + { start: gap.start, end: Math.min(gap.end, run.start) }, + { start: Math.max(gap.start, run.end), end: gap.end }, + ].filter((part) => part.start < part.end); +} + + +// Constructs the public handles from within this module; assigned in their static blocks. +let makeFill: (state: FillState, pending: Pending) => Fill; +let makeRequests: (state: FillState) => Requests; + +/** A {@link Requests} handle on `state`. Package-internal: a producer's `requests()` calls it. */ +export function requestsOf(state: FillState): Requests { + return makeRequests(state); +} + +/** + * Serves the groups a track's readers miss: from {@link Producer.requests}. Mirrors the Rust + * `track::Requests`. + * + * Most tracks never serve old content, so this lives on its own handle rather than the producer: + * a publisher backed by storage opens one to serve groups its live cache no longer holds, or + * never held. While at least one is open, a reader missing a run of groups queues a {@link Fill} + * here; with none open, the miss is given up. {@link close} it once done. + * + * @public + */ +export class Requests { + #state: FillState; + #closed = false; + + private constructor(state: FillState) { + this.#state = state; + state.addHandler(); + } + + static { + makeRequests = (state) => new Requests(state); + } + + /** The track's name, unique within its broadcast. */ + get name(): string { + return fillOps.name(this.#state); + } + + /** + * Wait until readers miss a run of groups, returning the {@link Fill} to serve. Resolves + * `undefined` once the track closes with nothing queued, or this handle is closed. + */ + async requestedFill(): Promise { + if (this.#closed) return undefined; + const pending = await this.#state.next(); + if (!pending) return undefined; + return makeFill(this.#state, pending); + } + + /** + * Stop serving. The last handle closing names every miss still queued dropped, so its + * readers stop waiting; a fill already handed out keeps its own handle. Idempotent. + */ + close(): void { + if (this.#closed) return; + this.#closed = true; + this.#state.removeHandler(); + } + + [Symbol.dispose](): void { + this.close(); + } +} + +/** + * A run of groups readers miss, from {@link Requests.requestedFill}: `start` up to the exclusive + * `end`. Mirrors the Rust `track::Fill`. + * + * Its {@link priority}, {@link maxDelay}, and {@link order} follow its readers as they change, so + * read them as each group is served. Call {@link accept} for each group the source has, writing + * its frames into the returned producer, and {@link dropGroups} for those it does not. Readers + * that leave, or narrow their ranges past a group, stop wanting it: serve {@link wanted} until it + * is `undefined`, which {@link wantedChanged} waits on. {@link close} the fill once done; closing + * names whatever is still wanted dropped rather than leaving its readers waiting. + * + * Groups keep their sequence, so an accepted group should hold the frames, payloads, and + * boundaries it had when it was first published: a fill replays the track, never a new version. + * + * @public + */ +export class Fill { + /** The first group to fill. */ + readonly start: number; + /** The exclusive end group. */ + readonly end: number; + + #state: FillState; + #pending: Pending; + // The value `wantedChanged` last returned, or unset before it returned any. + #prev?: { wanted: number | undefined }; + + private constructor(state: FillState, pending: Pending) { + this.#state = state; + this.#pending = pending; + this.start = pending.start; + this.end = pending.end; + } + + static { + makeFill = (state, pending) => new Fill(state, pending); + } + + /** The most urgent delivery priority among the readers waiting on it now. */ + get priority(): number { + let priority: number | undefined; + for (const asker of this.#pending.askers) priority = Math.max(priority ?? asker.priority(), asker.priority()); + return priority ?? 0; + } + + /** + * The most tolerant age budget among the readers waiting on it now, or `null` for none: the + * publisher's {@link Info.maxAge} alone bounds it. Each reader still enforces its own. + */ + get maxDelay(): Milli | null { + let max = 0; + for (const asker of this.#pending.askers) max = Math.max(max, asker.maxDelay()); + return max < NO_MAX_DELAY ? Milli(max) : null; + } + + /** Which end to fill first now: `"descending"`, newest first, if any reader asks it. */ + get order(): Order { + for (const asker of this.#pending.askers) if (asker.order() === "descending") return "descending"; + return this.#pending.askers.size > 0 ? "ascending" : "descending"; + } + + /** Whether a reader still waits for group `sequence` from this fill. Once false, it stays false. */ + isWanted(sequence: number): boolean { + return this.#pending.owed(sequence, sequence + 1).length > 0; + } + + /** + * The next group still owed in the fill's {@link order}: a reader still reads it, and it was + * neither answered nor delivered live since it was asked. `undefined` once none is, so stop + * serving the fill. + */ + wanted(): number | undefined { + const owed = this.#pending.owed(); + if (owed.length === 0) return undefined; + return this.order === "ascending" ? owed[0].start : (owed.at(-1) as Run).end - 1; + } + + /** + * {@link wanted} once it differs from what this handle last returned: at once on the first + * call, then on each change. So `for (let at = await fill.wantedChanged(); at !== undefined; + * at = await fill.wantedChanged())` serves each group as it becomes owed, and ends once the + * fill is answered or withdrawn. + */ + async wantedChanged(): Promise { + for (;;) { + const wanted = this.wanted(); + if (!this.#prev || this.#prev.wanted !== wanted) { + this.#prev = { wanted }; + return wanted; + } + await this.#pending.revision.changed(); + } + } + + /** Resolves once no reader waits for group `sequence` from this fill, so stop serving it. */ + async unwanted(sequence: number): Promise { + while (this.isWanted(sequence)) await this.#pending.revision.changed(); + } + + /** + * Insert group `sequence` into the track's cache, handing it to the readers waiting on it, + * and return the producer to write its frames into. `info` commits the track's {@link Info} + * if it has none yet. Throws a `RangeError` outside the fill, and an error if the group was + * already answered or cached, or the track is closed. + */ + accept(sequence: number, info?: Partial): GroupProducer { + return fillOps.accept(this.#state, this.#pending, sequence, info); + } + + /** + * Name `[start, end)` as never to be delivered: the source does not have them. Readers stop + * waiting for them, and the track records them so nobody asks again. Only the groups a reader + * still reads count; the rest of the fill was never owed. + */ + dropGroups(start: number, end: number): void { + fillOps.drop(this.#state, this.#pending, start, end); + } + + /** + * Refuse `[start, end)` with `error` without saying the source lost them, as when serving them + * failed for now. The readers waiting now stop waiting and get `error`; a later reader asks + * again. + */ + refuseGroups(start: number, end: number, error: Error): void { + fillOps.refuse(this.#state, this.#pending, start, end, error); + } + + /** Done serving: whatever a reader still wants is named dropped. Idempotent. */ + close(): void { + fillOps.settle(this.#state, this.#pending); + } + + [Symbol.dispose](): void { + this.close(); + } +} diff --git a/js/net/src/track.ts b/js/net/src/track.ts index f429235ce5a..0e70b82bdc9 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -17,6 +17,7 @@ import { TooFarBehind, toStreamCode, } from "./error.ts"; +import { type Asker, FillState, type Requests, requestsOf } from "./fill.ts"; import { datagramSlice, type Stored, sliceView } from "./flate/group.ts"; import { type Frame, type Consumer as GroupConsumer, Producer as GroupProducer } from "./group.ts"; import type { IetfVersion } from "./ietf/version.ts"; @@ -58,6 +59,7 @@ import { import { type Broadcast as BroadcastWire, registerTrackConsumer } from "./wire.ts"; export type { Datagram } from "./datagram.ts"; +export { Fill, Requests } from "./fill.ts"; // The group a non-blocking read takes, skipping drops and throwing the track's error; // `undefined` when nothing is deliverable now. @@ -574,6 +576,13 @@ export class Consumer { } } +// The parts of sorted, disjoint `runs` inside `[start, end)`. +function intersect(runs: readonly Run[], start: number, end: number): Run[] { + return runs + .map((run) => ({ start: Math.max(run.start, start), end: Math.min(run.end, end) })) + .filter((run) => run.start < run.end); +} + // The index of the first timeline group at or after `sequence`. function timelineIndex(timeline: readonly { sequence: number }[], sequence: number): number { let lo = 0; @@ -613,6 +622,8 @@ function bufferInsert(groups: GroupConsumer[], group: GroupConsumer): void { class TrackState { /** The producer fanning into this sink, so a subscriber can mint a sibling of itself. */ producer?: Producer; + /** This sink's reader as the producer's fills know it, once it asked one. */ + asker?: Asker; groups = new Signal([]); // Sequences the upstream publisher gave up, with the error each was given up with: an // incoming SUBSCRIBE_DROP or a producer cut. Kept apart from the cache so reclaim cannot @@ -749,6 +760,8 @@ let startsOf: (producer: Producer) => readonly Start[]; let goneAt: (producer: Producer, sequence: number) => number | undefined; // Actual object metadata outlives cached payloads, unlike empty group heads in model largest. let objectLargest: (producer: Producer) => Position | undefined; +// The fills serving the producer's misses; assigned in its static block. +let fillsOf: (producer: Producer) => FillState; // The sequence-order cursor lives inside `Subscriber` (it shares the group buffer and the // drift anchor with the arrival cursor), so `Ordered` reaches it through this bridge, @@ -897,6 +910,8 @@ export class Producer { #served?: { start?: number | null; requested?: number }; // Only copies fed by a wire subscription owe missing groups. #subscribed = false; + // The misses its readers asked of a {@link Requests} handle. + #fills: FillState; // The sequences the live feed delivered, as a group or a datagram: what a pending tail is // judged by. Eviction never touches it. A gap folds away a subscription's grace after a // later arrival opened it, as the session's tail does, so this holds only the gaps still @@ -906,6 +921,17 @@ export class Producer { constructor(name: string) { this.name = name; this.#demand = makeDemand(name, this.#wanted, this.#state); + this.#fills = new FillState({ + name, + accept: (sequence, info) => { + if (info !== undefined && this.#state.info.peek() === undefined) this.accept(info); + return this.#createGroup(sequence, 0); + }, + drop: (start, end, error) => this.#drop(start, end, error), + holds: (sequence) => cachedHolds(this, sequence), + closed: () => this.#state.closed.peek() !== undefined, + released: this.#state.closed, + }); } static { @@ -944,6 +970,7 @@ export class Producer { hooks.reportedLargest = (producer, largest) => producer.#advanceObject(largest); hooks.reportedGroup = (producer, group) => producer.#advanceLargest({ group, frame: 0 }); objectLargest = (producer) => producer.#objectLargest; + fillsOf = (producer) => producer.#fills; cachedHolds = (producer, sequence) => { const entry = producer.#cached.get(sequence); return entry !== undefined && !(entry.group.closed.peek() instanceof Error); @@ -1143,6 +1170,22 @@ export class Producer { return this.#demand; } + /** + * Open a {@link Requests} handle serving the groups readers miss: ones their ranges name that + * the cache no longer holds, or never did, below the newest group written. Most producers + * never need one; a publisher backed by storage opens one to serve its history. Mirrors the + * Rust `Producer::requests`. + * + * While one is open, each run of misses queues a {@link Fill}, which readers missing the same + * groups share; with none open, a miss is given up and {@link Consumer.fetchGroup} of an + * uncached group fails with `NotFound`. A reader only asks for what its budget still wants, + * so a reader at the live edge never asks. The track stays one track: answered groups land + * in its cache, and every reader of it sees them. + */ + requests(): Requests { + return requestsOf(this.#fills); + } + // A subscriber joined at the live edge: ask for a group past every sequence written when // the newest group's bytes after its first frame exceed the refresh ratio times the first // frame. @@ -1195,6 +1238,7 @@ export class Producer { const abort = c instanceof Error ? c : undefined; forward(); this.#sinks.delete(sink); + if (sink.asker) this.#fills.leave(sink.asker); this.#updateSubscription(); // Update demand: once the last subscriber leaves, the consumer wire (watching // {@link Demand.wanted}) tears the upstream down instead of downloading to nobody. @@ -1489,6 +1533,7 @@ export class Producer { } this.#cache.push(entry); this.#cached.set(group.sequence, entry); + this.#fills.arrived(group.sequence); this.#advance(group.sequence, true); this.#arrive(group.sequence); this.#state.latest = Math.max(this.#state.latest ?? 0, group.sequence); @@ -2025,9 +2070,16 @@ export class Subscriber { // out earlier can outlive this subscriber, as one a resumed reader still writes from a copy // it let go of, and its budget still runs from its successor's arrival. #arrivals?: { sequence: number; arrived: Instant }[]; + // The misses this reader asked a fill for, each judged once, and those asked again after the + // answer was evicted before this reader took it, which is never repeated: a slow reader's + // refills cannot evict each other without bound. Mirrors the Rust `Misses`. + #asked: Run[] = []; + #refilled: Run[] = []; #drift(): Drift { - const { end } = this.#cursor.peek(); + // A fetch judges its group against the whole track, as the Rust `fetch_group` does: a + // newer group outside its one-group window still supersedes it. + const end = this.#fetchBudget === undefined ? this.#cursor.peek().end : undefined; const timeline = this.#state.timeline; let presentation: { sequence: number; timestamp: Timestamp } | undefined; const info = this.#state.info.peek(); @@ -2037,7 +2089,7 @@ export class Subscriber { // stamped group's latest frame: walk back from the cap to the first one. for (let i = (end === undefined ? timeline.length : timelineIndex(timeline, end)) - 1; i >= 0; i--) { const group = timeline[i]; - if (group.closed.peek() instanceof Error || !this.#window.contains(group.sequence)) continue; + if (group.closed.peek() instanceof Error || !this.#judges(group.sequence)) continue; const timestamp = hooks.groupTimestamp(group); if (timestamp === undefined) continue; presentation = { sequence: group.sequence, timestamp: hooks.groupLatest(group) ?? timestamp }; @@ -2075,6 +2127,12 @@ export class Subscriber { return this.#after(sequence, end, () => true); } + // Whether group `sequence` counts toward the drift edge: inside the window, or anywhere for a + // fetch. + #judges(sequence: number): boolean { + return this.#fetchBudget !== undefined || this.#window.contains(sequence); + } + // The first servable group after `sequence` below `end` that `counts`. #after( sequence: number, @@ -2085,7 +2143,7 @@ export class Subscriber { for (let i = timelineIndex(timeline, sequence + 1); i < timeline.length; i++) { const successor = timeline[i]; if (end !== undefined && successor.sequence >= end) break; - if (successor.closed.peek() instanceof Error || !this.#window.contains(successor.sequence)) continue; + if (successor.closed.peek() instanceof Error || !this.#judges(successor.sequence)) continue; if (counts(successor)) return successor; } return undefined; @@ -2407,6 +2465,84 @@ export class Subscriber { start: Math.max(local.start, this.#window.floor() ?? 0), end: end === undefined ? local.end : Math.min(local.end ?? end, end), }); + // A fill this reader alone waited on for a group it no longer reads is withdrawn. + const producer = this.#state.producer; + if (this.#state.asker && producer) fillsOf(producer).moved(this.#state.asker); + } + + // The parts of `[start, end)` this reader still reads: inside its cursor and window, and not + // handed out. + #wants(start: number, end: number): Run[] { + if (this.#closed || this.#state.closed.peek() !== undefined) return []; + const cursor = this.#cursor.peek(); + const from = Math.max(start, cursor.start); + const to = cursor.end === undefined ? end : Math.min(end, cursor.end); + return this.#window.runs(from, to).flatMap((run) => this.#delivered.gaps(run.start, run.end)); + } + + // This reader as the producer's fills know it. + #askerOf(): Asker { + this.#state.asker ??= { + wants: (start, end) => this.#wants(start, end), + priority: () => this.#state.update.peek()?.priority ?? 0, + maxDelay: () => this.#drift().budget, + order: () => this.#state.update.peek()?.order ?? "descending", + refuse: (start, end, error) => this.#state.drops.update((drops) => insertDrop(drops, start, end, error)), + }; + return this.#state.asker; + } + + // Ask the producer's fills for the misses in `[start, end)`: groups this reader reads below + // the newest one received that the cache does not hold and nobody gave up. A run whose newest + // group the budget already convicts is not asked, so a reader at the live edge never asks. + // Returns the first sequence a fill still owes this reader. Mirrors the Rust `Misses::judge`. + #askFills(start: number, end: number, drift: Drift): number | undefined { + const producer = this.#state.producer; + if (this.#resume || !producer || this.#closed) return undefined; + const fills = fillsOf(producer); + if (fills.serving) { + const asker = this.#askerOf(); + const timeline = this.#state.timeline; + const drops = this.#state.drops.peek(); + for (const run of this.#wants(start, Math.min(end, this.#state.received.peek()))) { + for (const open of runGaps(drops, run.start, run.end)) { + let next = open.start; + for (let i = timelineIndex(timeline, open.start); i < timeline.length; i++) { + const group = timeline[i]; + if (group.sequence >= open.end) break; + // A failed copy holds nothing to read, so it is missed like an evicted one. + if (group.closed.peek() instanceof Error) continue; + this.#askMiss(next, group.sequence, drift, asker); + next = group.sequence + 1; + } + this.#askMiss(next, open.end, drift, asker); + } + } + } + const asker = this.#state.asker; + return asker && fills.owed(start, end, asker); + } + + // Ask a fill for the missed run `[start, end)`, unless its newest group is stale: what was + // never asked, and once more what was asked but is missed again. + #askMiss(start: number, end: number, drift: Drift, asker: Asker): void { + if (start >= end || this.#staleAt(end - 1, drift)) return; + const fills = fillsOf(this.#state.producer as Producer); + // Asked before and missed again, unless a fill still brings it: its answer was evicted + // before this reader took it. + const again = intersect(this.#asked, start, end).flatMap((run) => + runGaps(this.#refilled, run.start, run.end).flatMap((refill) => + runGaps(fills.covered(refill.start, refill.end, asker), refill.start, refill.end), + ), + ); + for (const gap of runGaps(this.#asked, start, end)) { + insertRun(this.#asked, gap.start, gap.end); + fills.ask(gap.start, gap.end, asker); + } + for (const refill of again) { + insertRun(this.#refilled, refill.start, refill.end); + fills.ask(refill.start, refill.end, asker); + } } // Whether a held group waits on the local cap rising: one past it may still be read. A @@ -2448,6 +2584,10 @@ export class Subscriber { #drained(taken: readonly Delivered[]): boolean { const end = this.#window.end(); if (end === undefined) return false; + // A fill still owes a group it reads. + const drift = this.#drift(); + const filling = this.#askFills(this.#window.floor() ?? 0, end, drift); + if (filling !== undefined && !this.#staleAt(filling, drift, true)) return false; const held = this.#state.groups.peek(); const received = this.#state.received.peek(); const drops = this.#state.drops.peek(); @@ -2990,6 +3130,9 @@ export class Subscriber { if (closed instanceof Error) return { kind: "error", error: closed }; // A clean close completes this range, retaining groups a later cap raise can read. if (closed !== undefined) return { kind: "done" }; + // Nothing buffered: ask a fill for what this reader misses, and wait while one owes it. + const filling = this.#askFills(start, end ?? Number.POSITIVE_INFINITY, drift); + if (filling !== undefined && !this.#staleAt(filling, drift, true)) return { kind: "idle" }; // A bounded window ends once nothing in it is left to deliver, as in Rust. if (this.#exhausted()) return { kind: "done" }; if (!this.#complete() || this.#starting(groups)) return { kind: "idle" }; @@ -3213,7 +3356,12 @@ export class Subscriber { owed = owedGroup(producer, run.start, run.end); if (owed) break; } - if (!owed || this.#staleAt(owed.sequence, drift, true)) return false; + if (!owed) { + // A fill still owes a group below, which lands as a group does. + const filling = this.#askFills(start, end, drift); + return filling !== undefined && !this.#staleAt(filling, drift, true); + } + if (this.#staleAt(owed.sequence, drift, true)) return false; if (owed.folds !== undefined) this.#wakeAt(owed.folds); this.#state.waitingOrdered = true; return true; @@ -3289,6 +3437,9 @@ export class Subscriber { if (closed instanceof Error) return { kind: "error", error: closed }; // A clean close completes this range, retaining groups a later cap raise can read. if (closed !== undefined) return { kind: "done" }; + // Nothing buffered: ask a fill for what this reader misses, and wait while one owes it. + const filling = this.#askFills(start, cursor.end ?? Number.POSITIVE_INFINITY, drift); + if (filling !== undefined && !this.#staleAt(filling, drift, true)) return { kind: "idle" }; const end = this.#state.end.peek(); if (this.#exhausted()) return { kind: "done" }; if ( From cf1290e7c44a6af46294cea7b915175a28a70625 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 00:00:19 -0800 Subject: [PATCH 03/13] test(net): cover JS fills in-process and from a native CLI FETCH Co-Authored-By: Claude Opus 5.5 --- doc/lib/js/net.md | 1 + js/net/src/fill.test.ts | 451 +++++++++++++++++++++++++ js/net/src/fill.ts | 31 +- js/net/src/track.ts | 18 +- test/interop/README.md | 5 +- test/interop/clients/js-native/tail.ts | 38 ++- test/interop/interop.sh | 24 +- 7 files changed, 544 insertions(+), 24 deletions(-) create mode 100644 js/net/src/fill.test.ts diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 307f5bffa71..d4b6203981b 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -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. - **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. +- **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, 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. With no handle open, a miss is given up and a `fetchGroup` of an uncached group fails with `NotFound`. 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`. Publisher retention is the separate `Track.Info.maxAge`. - **Subscription defaults.** `Track.Subscription.default()` returns the default subscription, whose zero `delay.max` skips a superseded group at once; calling `subscribe()` with no options means the same. An omitted `delay` field means the same zero; `max: null` sets no subscriber limit. diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts new file mode 100644 index 00000000000..1a7ea707963 --- /dev/null +++ b/js/net/src/fill.test.ts @@ -0,0 +1,451 @@ +import { expect, test } from "bun:test"; +import { Milli, yieldNow } from "@moq/clock"; +import { Producer as BroadcastProducer } from "./broadcast.ts"; +import { accept as acceptSession, connect as connectSession } from "./connection/index.ts"; +import { NotFound, StreamCode, StreamError, toStreamCode } from "./error.ts"; +import type { Consumer as GroupConsumer } from "./group.ts"; +import * as Lite from "./lite/index.ts"; +import { createMockTransportPair } from "./mock.ts"; +import { Producer as OriginProducer } from "./origin.ts"; +import * as Path from "./path.ts"; +import { Timescale, Timestamp } from "./time.ts"; +import type { Fill, Producer, Requests, Subscription } from "./track.ts"; +import { wireOf } from "./wire.ts"; + +const enc = new TextEncoder(); +const dec = new TextDecoder(); + +// The archive an in-memory responder serves: each group's frames, by sequence. +type Archive = Map; + +// Serve every fill from `archive` until the track closes, dropping what it lacks. Returns the +// fills it took, so a test can count them. +function respond(requests: Requests, archive: Archive): Fill[] { + const fills: Fill[] = []; + void (async () => { + for (let fill = await requests.requestedFill(); fill; fill = await requests.requestedFill()) { + fills.push(fill); + serve(fill, archive); + } + })(); + return fills; +} + +function serve(fill: Fill, archive: Archive): void { + for (let sequence = fill.wanted(); sequence !== undefined; sequence = fill.wanted()) { + const frames = archive.get(sequence); + if (!frames) { + fill.dropGroups(sequence, sequence + 1); + continue; + } + const group = fill.accept(sequence); + for (const frame of frames) group.writeFrame({ payload: enc.encode(frame) }); + group.finish(); + } + fill.close(); +} + +async function frames(group: GroupConsumer): Promise { + const out: string[] = []; + for (let frame = await group.readFrame(); frame; frame = await group.readFrame()) + out.push(dec.decode(frame.payload)); + return out; +} + +// Read `reader` until it ends, closing each group. +async function drain(reader: { recvGroup(): Promise }): Promise { + try { + for (let group = await reader.recvGroup(); group; group = await reader.recvGroup()) group.close(); + } catch { + // Closed by the test. + } +} + +// A track whose first write is group `first`, so every group below it was never cached here. +function resumed(first: number): { broadcast: BroadcastProducer; track: Producer } { + const broadcast = new BroadcastProducer(); + const track = broadcast.createTrack("video"); + const group = track.createGroup(first); + group.writeFrame({ payload: enc.encode(`live ${first}`) }); + group.finish(); + return { broadcast, track }; +} + +const history: Subscription = { ranges: [{ start: { absolute: 0 } }], delay: { max: null }, order: "ascending" }; + +test("fill: a fetch of a group never cached is served by the request handler, byte for byte", async () => { + const { broadcast, track } = resumed(5); + const requests = track.requests(); + const fills = respond(requests, new Map([[2, ["a", "b", "c"]]])); + + const group = await wireOf(broadcast).fetchGroup("video", 2); + expect(group.sequence).toBe(2); + expect(await frames(group)).toEqual(["a", "b", "c"]); + expect(fills.map((fill) => [fill.start, fill.end])).toEqual([[2, 3]]); + + // Now cached: a second fetch asks nothing. + const again = await wireOf(broadcast).fetchGroup("video", 2); + expect(await frames(again)).toEqual(["a", "b", "c"]); + expect(fills.length).toBe(1); + + requests.close(); + broadcast.close(); +}); + +test("fill: an empty group replays as empty, and a missing one fails the fetch with NotFound", async () => { + const { broadcast, track } = resumed(5); + const requests = track.requests(); + respond(requests, new Map([[1, []]])); + + const empty = await wireOf(broadcast).fetchGroup("video", 1); + expect(await frames(empty)).toEqual([]); + await expect(wireOf(broadcast).fetchGroup("video", 3)).rejects.toBeInstanceOf(NotFound); + + requests.close(); + broadcast.close(); +}); + +test("fill: without a handler, a fetch of an uncached group fails at once", async () => { + const { broadcast } = resumed(5); + await expect(wireOf(broadcast).fetchGroup("video", 2)).rejects.toBeInstanceOf(NotFound); + broadcast.close(); +}); + +test("fill: concurrent fetches of one group share one fill", async () => { + const { broadcast, track } = resumed(5); + const requests = track.requests(); + const a = wireOf(broadcast).fetchGroup("video", 3); + const b = wireOf(broadcast).fetchGroup("video", 3); + + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + expect([fill.start, fill.end]).toEqual([3, 4]); + // The second fetch joined it rather than queueing its own. + await yieldNow(); + const queued = await Promise.race([requests.requestedFill(), yieldNow().then(() => "none")]); + expect(queued).toBe("none"); + + serve(fill, new Map([[3, ["x"]]])); + const [first, second] = await Promise.all([a, b]); + expect(await frames(first)).toEqual(["x"]); + expect(await frames(second)).toEqual(["x"]); + + requests.close(); + broadcast.close(); +}); + +test("fill: a fetch cancelled while its fill awaits a reply withdraws the fill", async () => { + const { broadcast, track } = resumed(5); + const requests = track.requests(); + const controller = new AbortController(); + const fetching = wireOf(broadcast).fetchGroup("video", 2, { signal: controller.signal }); + + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + expect(await fill.wantedChanged()).toBe(2); + expect(fill.isWanted(2)).toBe(true); + + const reason = new Error("left"); + controller.abort(reason); + await expect(fetching).rejects.toBe(reason); + expect(await fill.wantedChanged()).toBeUndefined(); + expect(fill.isWanted(2)).toBe(false); + // Nothing reads it, so closing the withdrawn fill records nothing. + fill.close(); + const later = wireOf(broadcast).fetchGroup("video", 2); + const refill = await requests.requestedFill(); + expect(refill?.start).toBe(2); + if (refill) serve(refill, new Map([[2, ["late"]]])); + expect(await frames(await later)).toEqual(["late"]); + + requests.close(); + broadcast.close(); +}); + +test("fill: a reader reaching back for history gets the misses filled in order", async () => { + const { broadcast, track } = resumed(4); + const requests = track.requests(); + const fills = respond( + requests, + new Map([ + [0, ["g0"]], + [1, ["g1"]], + [3, ["g3"]], + ]), + ); + + const reader = track.subscribe(history); + const ordered = reader.ordered(); + const seen: [number, string[]][] = []; + for (let i = 0; i < 4; i++) { + const group = await ordered.nextGroup(); + if (!group) break; + seen.push([group.sequence, await frames(group)]); + } + // Group 2 is missing from the archive, so it is dropped and the cursor moves past it. + expect(seen).toEqual([ + [0, ["g0"]], + [1, ["g1"]], + [3, ["g3"]], + [4, ["live 4"]], + ]); + expect(fills.map((fill) => [fill.start, fill.end])).toEqual([[0, 4]]); + + reader.close(); + requests.close(); + broadcast.close(); +}); + +test("fill: a bounded reader ends once its fill answers every group", async () => { + const { broadcast, track } = resumed(4); + const requests = track.requests(); + respond(requests, new Map([[1, ["g1"]]])); + + const reader = track.subscribe({ + ranges: [{ start: { absolute: 0 }, end: { absolute: 3 } }], + delay: { max: null }, + }); + const got: number[] = []; + for (let group = await reader.recvGroup(); group; group = await reader.recvGroup()) got.push(group.sequence); + expect(got).toEqual([1]); + + requests.close(); + broadcast.close(); +}); + +test("fill: a reader at the live edge asks nothing", async () => { + const { broadcast, track } = resumed(4); + const requests = track.requests(); + const reader = track.subscribe(); + expect((await reader.recvGroup())?.sequence).toBe(4); + const queued = await Promise.race([requests.requestedFill(), yieldNow().then(() => "none")]); + expect(queued).toBe("none"); + + reader.close(); + requests.close(); + broadcast.close(); +}); + +test("fill: closing a fill drops what is still wanted, and closing the handler drops what is queued", async () => { + const { broadcast, track } = resumed(5); + const requests = track.requests(); + const a = wireOf(broadcast).fetchGroup("video", 1); + const fill = await requests.requestedFill(); + fill?.close(); + await expect(a).rejects.toBeInstanceOf(NotFound); + + const b = wireOf(broadcast).fetchGroup("video", 3); + await yieldNow(); + requests.close(); + await expect(b).rejects.toBeInstanceOf(NotFound); + // The last handler left, so a miss fails at once again. + await expect(wireOf(broadcast).fetchGroup("video", 2)).rejects.toBeInstanceOf(NotFound); + + broadcast.close(); +}); + +test("fill: a refusal fails the readers waiting now, and a later reader asks again", async () => { + const { broadcast, track } = resumed(5); + const requests = track.requests(); + const waiting = wireOf(broadcast).fetchGroup("video", 2); + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + const refusal = new StreamError(StreamCode.Cancel, { message: "storage busy" }); + fill.refuseGroups(2, 3, refusal); + fill.close(); + await expect(waiting).rejects.toBe(refusal); + + const later = wireOf(broadcast).fetchGroup("video", 2); + const again = await requests.requestedFill(); + expect(again?.start).toBe(2); + if (again) serve(again, new Map([[2, ["ok"]]])); + expect(await frames(await later)).toEqual(["ok"]); + + requests.close(); + broadcast.close(); +}); + +test("fill: a fill names the most urgent priority and loosest budget among its readers", async () => { + const { broadcast, track } = resumed(5); + const requests = track.requests(); + const low = track.subscribe({ ...history, priority: 1, delay: { max: Milli(60_000) } }); + void drain(low); + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + expect([fill.start, fill.end]).toEqual([0, 5]); + expect(fill.priority).toBe(1); + expect(fill.maxDelay).toBe(Milli(60_000)); + expect(fill.order).toBe("ascending"); + + const high = track.subscribe({ ...history, priority: 7, order: "descending" }); + void drain(high); + await yieldNow(); + expect(fill.priority).toBe(7); + expect(fill.maxDelay).toBeNull(); + expect(fill.order).toBe("descending"); + expect(fill.wanted()).toBe(4); + + low.close(); + high.close(); + await yieldNow(); + expect(fill.wanted()).toBeUndefined(); + + fill.close(); + requests.close(); + broadcast.close(); +}); + +test("fill: a group arriving live answers the fill", async () => { + const broadcast = new BroadcastProducer(); + const track = broadcast.createTrack("video"); + const requests = track.requests(); + const late = track.createGroup(3); + late.finish(); + const fetching = wireOf(broadcast).fetchGroup("video", 1); + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + + // The producer writes it itself before the handler gets to it. + const live = track.createGroup(1); + live.writeFrame({ payload: enc.encode("live") }); + live.finish(); + expect(fill.wanted()).toBeUndefined(); + expect(() => fill.accept(1)).toThrow(); + expect(await frames(await fetching)).toEqual(["live"]); + + fill.close(); + requests.close(); + broadcast.close(); +}); + +test("fill: a cache-miss fetch of a dynamic track serves the one track the broadcast already has", async () => { + const broadcast = new BroadcastProducer(); + // Pulled first, so the broadcast serves tracks on demand. + const pulled = wireOf(broadcast).requested(); + const fetching = wireOf(broadcast).fetchGroup("video", 1); + const request = await pulled; + if (!request) throw new Error("no track request"); + const track = request.accept(); + const requests = track.requests(); + const group = track.createGroup(4); + group.finish(); + + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + serve(fill, new Map([[1, ["one"]]])); + expect(await frames(await fetching)).toEqual(["one"]); + + // A second miss and a live reader land on the same producer, not a second request. + const second = wireOf(broadcast).fetchGroup("video", 2); + const queued = await Promise.race([wireOf(broadcast).requested(), yieldNow().then(() => "none")]); + expect(queued).toBe("none"); + const refill = await requests.requestedFill(); + if (refill) serve(refill, new Map([[2, ["two"]]])); + expect(await frames(await second)).toEqual(["two"]); + + requests.close(); + broadcast.close(); +}); + +// A browser publisher's history, read by a peer over a session: lite FETCH on every lite version +// with one, and lite-07's ranged SUBSCRIBE. +const url = new URL("https://localhost:4443/test"); + +async function session(alpn: string) { + const pair = createMockTransportPair(alpn); + const origin = new OriginProducer(); + const [client, server] = await Promise.all([ + connectSession({ url, transport: pair.client }), + acceptSession({ transport: pair.server, url, publish: origin.consume() }), + ]); + const publication = origin.createBroadcast(Path.from("archive")); + publication.announce(); + const broadcast = publication.broadcast; + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + // Groups 0 to 2 were published before this producer existed. + const live = track.createGroup(3); + live.writeFrame({ payload: enc.encode("live 3"), timestamp: Timestamp.fromMillis(3000) }); + live.finish(); + const requests = track.requests(); + const fills: Fill[] = []; + void (async () => { + for (let fill = await requests.requestedFill(); fill; fill = await requests.requestedFill()) { + fills.push(fill); + for (let sequence = fill.wanted(); sequence !== undefined; sequence = fill.wanted()) { + if (sequence === 1) { + fill.dropGroups(1, 2); + continue; + } + const group = fill.accept(sequence); + group.writeFrame({ + payload: enc.encode(`old ${sequence}`), + timestamp: Timestamp.fromMillis(sequence * 1000), + }); + group.finish(); + } + fill.close(); + } + })(); + const remote = wireOf(client).consume(Path.from("archive")); + return { + remote, + fills, + close() { + remote.close(); + requests.close(); + broadcast.close(); + client.abort(); + server.abort(); + origin.close(); + }, + }; +} + +test.each([Lite.ALPN_05, Lite.ALPN_06, Lite.ALPN_07_WIP])( + "fill: %s FETCH reads a group the publisher never cached, and NotFound for one it lacks", + async (alpn) => { + const peer = await session(alpn); + try { + const group = await peer.remote.track("video").fetchGroup(2); + const frame = await group.readFrame(); + expect(dec.decode(frame?.payload)).toBe("old 2"); + expect(frame?.timestamp?.asMillis()).toBe(2000); + expect(await group.readFrame()).toBeUndefined(); + + const missing = await peer.remote + .track("video") + .fetchGroup(1) + .then( + () => undefined, + (err: unknown) => err, + ); + expect(toStreamCode(missing)).toBe(StreamCode.NotFound); + } finally { + peer.close(); + } + }, +); + +test("fill: a lite-07 ranged subscription reads history the publisher never cached", async () => { + const peer = await session(Lite.ALPN_07_WIP); + try { + const reader = peer.remote.track("video").subscribe({ + ranges: [{ start: { absolute: 0 }, end: { absolute: 4 } }], + delay: { max: null }, + order: "ascending", + }); + const got: [number, string[]][] = []; + for (let group = await reader.recvGroup(); group; group = await reader.recvGroup()) { + got.push([group.sequence, await frames(group)]); + } + got.sort(([a], [b]) => a - b); + expect(got).toEqual([ + [0, ["old 0"]], + [2, ["old 2"]], + [3, ["live 3"]], + ]); + reader.close(); + } finally { + peer.close(); + } +}); diff --git a/js/net/src/fill.ts b/js/net/src/fill.ts index 9f37ba9deb8..3f90e7851e1 100644 --- a/js/net/src/fill.ts +++ b/js/net/src/fill.ts @@ -14,10 +14,18 @@ import { Milli } from "@moq/clock"; import { type GetPromise, Signal } from "@moq/signals"; import { NotFound } from "./error.ts"; import type { Producer as GroupProducer } from "./group.ts"; -import { insertRun, NO_MAX_DELAY, type Run, runGaps } from "./internal.ts"; +import { insertRun, NO_MAX_DELAY, runGaps } from "./internal.ts"; import type { Info, Order } from "./track.ts"; -/** What the fills need from the track they serve. Package-internal. */ +// A half-open run of group sequences, as `internal.ts` has it, kept local so the published +// declarations never reach the package internals. +type Run = { start: number; end: number }; + +/** + * What the fills need from the track they serve. + * + * @internal + */ export interface FillTrack { /** The track's name. */ readonly name: string; @@ -33,7 +41,11 @@ export interface FillTrack { readonly released: GetPromise; } -/** A reader waiting on fills. Package-internal. */ +/** + * A reader waiting on fills. + * + * @internal + */ export interface Asker { /** The parts of `[start, end)` it still reads. */ wants(start: number, end: number): Run[]; @@ -98,8 +110,10 @@ class Pending { } /** - * The fills of one track: what its readers miss, queued for its {@link Requests} handles. - * Package-internal; a producer owns one. + * The fills of one track: what its readers miss, queued for its {@link Requests} handles. A + * producer owns one. + * + * @internal */ export class FillState { readonly #track: FillTrack; @@ -281,12 +295,15 @@ function subtract(gap: Run, run: Run): Run[] { ].filter((part) => part.start < part.end); } - // Constructs the public handles from within this module; assigned in their static blocks. let makeFill: (state: FillState, pending: Pending) => Fill; let makeRequests: (state: FillState) => Requests; -/** A {@link Requests} handle on `state`. Package-internal: a producer's `requests()` calls it. */ +/** + * A {@link Requests} handle on `state`, for a producer's `requests()`. + * + * @internal + */ export function requestsOf(state: FillState): Requests { return makeRequests(state); } diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 0e70b82bdc9..8f10db16a43 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -2523,6 +2523,15 @@ export class Subscriber { return asker && fills.owed(start, end, asker); } + // The lowest group a fill still brings this reader, asking for what it misses first. + #filling(): number | undefined { + const producer = this.#state.producer; + if (this.#resume || !producer || !fillsOf(producer).serving) return undefined; + const drift = this.#drift(); + const filling = this.#askFills(this.#cursor.peek().start, Number.POSITIVE_INFINITY, drift); + return filling !== undefined && !this.#staleAt(filling, drift) ? filling : undefined; + } + // Ask a fill for the missed run `[start, end)`, unless its newest group is stale: what was // never asked, and once more what was asked but is missed again. #askMiss(start: number, end: number, drift: Drift, asker: Asker): void { @@ -2627,8 +2636,13 @@ export class Subscriber { if (subscriber.#resume) return subscriber.#resume.start(); const producer = subscriber.#state.producer; const start = producer && sourceStart(producer); - if (start === undefined || start === "pending") return start; - return Math.max(start, subscriber.#cursor.peek().start); + if (start === "pending") return start; + const floor = start === undefined ? undefined : Math.max(start, subscriber.#cursor.peek().start); + // The lowest group a fill brings this reader starts it too, as the Rust `poll_start` + // has it: a group arriving first must not give up the history being filled below it. + const filling = subscriber.#filling(); + if (filling === undefined) return floor; + return floor === undefined ? filling : Math.min(floor, filling); }; hooks.tryRecvGroup = (subscriber, dispositions) => subscriber.#tryRecvGroup(dispositions); hooks.parked = (subscriber) => { diff --git a/test/interop/README.md b/test/interop/README.md index a27339deb80..03eaaf3895f 100644 --- a/test/interop/README.md +++ b/test/interop/README.md @@ -53,7 +53,10 @@ exactly groups 0 through 3, and a clean end at 4. Rust-to-Rust always runs. Sele native JS adds both Rust-to-JS and JS-to-Rust under that runtime, so `--all` covers Node and Bun. The current CLI also FETCHes group 1 of a finished track from the Rust publisher and each selected native JS runtime, requires exactly its three objects, each -with its own bytes, and closes under the relay idle-out check. +with its own bytes, and closes under the relay idle-out check. Each native JS runtime also serves +that FETCH from history (`CLI FETCH history`): its publisher writes only group 3 live and answers +groups 0 through 2, which it never cached, from an in-memory responder on `track.requests()`. A +moq-transport pass skips it, since JavaScript does not route an IETF FETCH to the responder yet. A late-join lane runs Rust-to-Rust and Rust/Node/Bun in both directions. The publisher writes the first two objects of group 0 before any subscriber exists and leaves the group diff --git a/test/interop/clients/js-native/tail.ts b/test/interop/clients/js-native/tail.ts index 11e1a90c23d..cca64b166fd 100644 --- a/test/interop/clients/js-native/tail.ts +++ b/test/interop/clients/js-native/tail.ts @@ -5,7 +5,8 @@ * moq-transport subscription starts at the largest group rather than at the range asked for, so * it must read a contiguous run of groups through the last one. `compress` publishes a compressed * track with several frames, one empty, in each group. `cached` publishes every group before - * announcing, for a FETCH of a past group. `late` writes the head of group 0 before announcing and + * announcing, for a FETCH of a past group. `history` writes only the last group live and serves the + * ones below it, never cached, from an in-memory responder on `track.requests()`. `late` writes the head of group 0 before announcing and * the rest only once the harness relays that the subscriber read it, so a join that skips the head * stalls rather than racing the publisher. * @@ -32,27 +33,28 @@ const join = mode === "join" || mode === "status"; const datagram = mode === "datagram"; const status = mode === "status"; const cached = mode === "cached"; +const history = mode === "history"; const late = mode === "late"; if ( !url || !path || !["publish", "subscribe"].includes(role) || - ![undefined, "drop", "join", "compress", "datagram", "status", "cached", "late"].includes(mode) + ![undefined, "drop", "join", "compress", "datagram", "status", "cached", "history", "late"].includes(mode) ) { throw new Error( - "usage: tail.ts publish|subscribe URL BROADCAST [VERSION [drop|join|compress|datagram|status|cached|late]]", + "usage: tail.ts publish|subscribe URL BROADCAST [VERSION [drop|join|compress|datagram|status|cached|history|late]]", ); } /** * The frames of each group. A compressed track spans several frames, one empty, per window. - * `cached` and `late` give every frame its own bytes, so a FETCH or join that drops, repeats, or + * `cached`, `history`, and `late` give every frame its own bytes, so a FETCH or join that drops, repeats, or * reorders one fails. */ function frames(sequence: number): Uint8Array[] { if (compress) return [new Uint8Array(BYTES / 2).fill(sequence), new Uint8Array(0), new Uint8Array(BYTES / 2).fill(sequence)]; - if (cached || late) return [0, 1, 2].map((index) => new Uint8Array(BYTES / 4).fill(sequence * 16 + index)); + if (cached || history || late) return [0, 1, 2].map((index) => new Uint8Array(BYTES / 4).fill(sequence * 16 + index)); return [new Uint8Array(BYTES).fill(sequence)]; } @@ -71,6 +73,29 @@ function write(track: Moq.Track.Producer) { track.finish(); } +/** + * Write only the last group, and serve the groups below it from an in-memory responder: this + * producer never cached them, as one resumed past its storage would not have. + */ +function serveHistory(track: Moq.Track.Producer) { + track.finishAt({ group: GROUPS, frame: 0 }); + const live = track.createGroup(GROUPS - 1); + for (const payload of frames(GROUPS - 1)) live.writeFrame({ payload }); + live.finish(); + const requests = track.requests(); + void (async () => { + for (let fill = await requests.requestedFill(); fill; fill = await requests.requestedFill()) { + for (let sequence = fill.wanted(); sequence !== undefined; sequence = fill.wanted()) { + const group = fill.accept(sequence); + for (const payload of frames(sequence)) group.writeFrame({ payload }); + group.finish(); + console.error(`history served ${sequence}`); + } + fill.close(); + } + })(); +} + /** Read one whole group, checking every frame's bytes, and report when the `late` head is in. */ async function read(group: Moq.Group.Consumer) { for (const [index, want] of frames(group.sequence).entries()) { @@ -95,6 +120,7 @@ try { const broadcast = broadcastPublication.broadcast; const track = broadcast.createTrack("tail", { compress, ...(status ? { priority: 2 } : {}) }); if (cached) write(track); + if (history) serveHistory(track); let head: Moq.Group.Producer | undefined; if (late) { head = track.appendGroup(); @@ -114,7 +140,7 @@ try { } track.finish(); track.close(); - } else if (!status && !cached) { + } else if (!status && !cached && !history) { const demand = track.demand(); while (demand.wanted.peek() === undefined) await demand.wanted.changed(); if (datagram) { diff --git a/test/interop/interop.sh b/test/interop/interop.sh index 42fbdf34eaa..362669a6782 100755 --- a/test/interop/interop.sh +++ b/test/interop/interop.sh @@ -504,6 +504,7 @@ plan_pass() { for runtime in js-native-node js-native-bun; do needs "$runtime" || continue record "not run" case="CLI FETCH" publisher="$runtime" subscriber=rust + record "not run" case="CLI FETCH history" publisher="$runtime" subscriber=rust record "not run" case="late join" publisher=rust subscriber="$runtime" record "not run" case="late join" publisher="$runtime" subscriber=rust record "not run" case=tail publisher=rust subscriber="$runtime" @@ -2034,12 +2035,16 @@ run_late_pair() { # This checkout's CLI FETCHes a past group of a finished track, under the same relay close check as # live readers. Every object has its own bytes, so a FETCH that drops, repeats, or reorders one fails. +# The `history` mode (native JS only) serves the group from the publisher's request handler: it +# was never in its cache. run_fetch_round() { - local pub="$1" name="fetch-$1" fifo="$LOGS/fetch-ack" broadcast="fetch-$1-$$-$RANDOM" pid from version + local pub="$1" mode="${2:-cached}" pid from version + local name="fetch-$1${2:+-$2}" fifo="$LOGS/fetch-ack" broadcast="fetch-$1-$$-$RANDOM" + local label="CLI FETCH${2:+ $2}" local started=$SECONDS why="" - local cell=(case="CLI FETCH" publisher="$pub" subscriber=rust log="$LOGS/$name-pub.log") + local cell=(case="$label" publisher="$pub" subscriber=rust log="$LOGS/$name-pub.log") if is_broken "$pub"; then - echo " FAIL CLI FETCH $pub (client unavailable)" + echo " FAIL $label $pub (client unavailable)" record fail "${cell[@]}" detail="client unavailable" overall=1 return @@ -2048,7 +2053,7 @@ run_fetch_round() { from=$(relay_next_line) mkfifo "$fifo" exec 9<>"$fifo" - harness_spawn "$name-pub" "$LOGS/$name-pub.log" run_tail_publisher "$fifo" "$pub" publish "$broadcast" "$(token_url --publish "$(publish_grant "$broadcast")")" "$version" cached + harness_spawn "$name-pub" "$LOGS/$name-pub.log" run_tail_publisher "$fifo" "$pub" publish "$broadcast" "$(token_url --publish "$(publish_grant "$broadcast")")" "$version" "$mode" pid="$HARNESS_PID" if timeout -k 3 "$TIMEOUT" "$MOQ" --connect "$(token_url --subscribe "$(subscribe_grant "$broadcast")")" ${version:+--connect-version "$version"} \ --broadcast "$broadcast" fetch tail --group 1 --json >"$LOGS/$name.json" && @@ -2062,15 +2067,15 @@ PYCODE printf 'clean end\n' >&9 harness_wait "$pid" || true if grep -qx 'tail acknowledged' "$LOGS/$name-pub.log"; then - echo " PASS CLI FETCH $pub (group 1; 3 objects)" + echo " PASS $label $pub (group 1; 3 objects)" else - echo " FAIL CLI FETCH $pub (publisher did not acknowledge)" + echo " FAIL $label $pub (publisher did not acknowledge)" why="publisher did not acknowledge" overall=1 cat "$LOGS/$name-pub.log" fi else - echo " FAIL CLI FETCH $pub" + echo " FAIL $label $pub" why="incorrect or missing FETCH payload" overall=1 cat "$LOGS/$name-pub.log" @@ -2416,7 +2421,10 @@ run_tails() { echo "=== CLI FETCH close ===" run_fetch_round rust for runtime in js-native-node js-native-bun; do - ! needs "$runtime" || run_fetch_round "$runtime" + needs "$runtime" || continue + run_fetch_round "$runtime" + # A moq-transport FETCH is not served from the request handler yet. + [[ "$(pinned_version)" == moq-transport-* ]] || run_fetch_round "$runtime" history done echo "=== late join ===" run_late_pair rust rust From 3dcf441ed45345649838db4c378a685318a8fee9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 00:03:18 -0800 Subject: [PATCH 04/13] feat(net): name fill internals, wake a closed handle's wait, skip buffered datagrams Co-Authored-By: Claude Opus 5.5 --- js/net/api/index.api.md | 23 ++++++++++ js/net/src/fill.ts | 22 +++++---- js/net/src/track.ts | 16 ++++--- quest/m1/subscribe-ranges/js.md | 63 ++++++++++++++------------ test/interop/clients/js-native/tail.ts | 3 +- 5 files changed, 83 insertions(+), 44 deletions(-) diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index b56597dcd5b..f0c0b4415a4 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -626,6 +626,22 @@ export namespace Track { priority?: number; signal?: AbortSignal; } + export class Fill { + [Symbol.dispose](): void; + accept(sequence: number, info?: Partial): Group.Producer; + close(): void; + dropGroups(start: number, end: number): void; + readonly end: number; + isWanted(sequence: number): boolean; + get maxDelay(): Milli | null; + get order(): Track.Order; + get priority(): number; + refuseGroups(start: number, end: number, error: Error): void; + readonly start: number; + unwanted(sequence: number): Promise; + wanted(): number | undefined; + wantedChanged(): Promise; + } export interface Groups { end?: Track.Bound; start?: Track.Bound; @@ -680,6 +696,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; writeFrame(frame: Group.Frame): void; @@ -696,6 +713,12 @@ export namespace Track { reject(err: Error): void; get subscription(): Readonly; } + export class Requests { + [Symbol.dispose](): void; + close(): void; + get name(): string; + requestedFill(): Promise; + } export class Subscriber { close(abort?: Error): void; get closed(): Signals.GetPromise; diff --git a/js/net/src/fill.ts b/js/net/src/fill.ts index 3f90e7851e1..2d3470fe1dc 100644 --- a/js/net/src/fill.ts +++ b/js/net/src/fill.ts @@ -201,16 +201,20 @@ export class FillState { for (const pending of this.#queue.splice(0)) this.#settle(pending); } - /** The next queued fill, or `undefined` once the track closes with none queued. */ - async next(): Promise { + /** + * The next queued fill, or `undefined` once the track closes with none queued or `closed`, the + * asking handle's, is set. + */ + async next(closed: Signal): Promise { for (;;) { + if (closed.peek()) return undefined; const pending = this.#queue.shift(); if (pending) { pending.queued = false; return pending; } if (this.#track.closed()) return undefined; - await Signal.race(this.#queued, this.#track.released); + await Signal.race(this.#queued, this.#track.released, closed); } } @@ -321,7 +325,7 @@ export function requestsOf(state: FillState): Requests { */ export class Requests { #state: FillState; - #closed = false; + #closed = new Signal(false); private constructor(state: FillState) { this.#state = state; @@ -339,11 +343,11 @@ export class Requests { /** * Wait until readers miss a run of groups, returning the {@link Fill} to serve. Resolves - * `undefined` once the track closes with nothing queued, or this handle is closed. + * `undefined` once the track closes with nothing queued, or this handle closes, even while + * it waits. */ async requestedFill(): Promise { - if (this.#closed) return undefined; - const pending = await this.#state.next(); + const pending = await this.#state.next(this.#closed); if (!pending) return undefined; return makeFill(this.#state, pending); } @@ -353,8 +357,8 @@ export class Requests { * readers stop waiting; a fill already handed out keeps its own handle. Idempotent. */ close(): void { - if (this.#closed) return; - this.#closed = true; + if (this.#closed.peek()) return; + this.#closed.set(true); this.#state.removeHandler(); } diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 8f10db16a43..f3373b6e9f1 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -2496,16 +2496,21 @@ export class Subscriber { // the newest one received that the cache does not hold and nobody gave up. A run whose newest // group the budget already convicts is not asked, so a reader at the live edge never asks. // Returns the first sequence a fill still owes this reader. Mirrors the Rust `Misses::judge`. - #askFills(start: number, end: number, drift: Drift): number | undefined { + #askFills(start: number, end: number, drift?: Drift): number | undefined { const producer = this.#state.producer; if (this.#resume || !producer || this.#closed) return undefined; const fills = fillsOf(producer); if (fills.serving) { + drift ??= this.#drift(); const asker = this.#askerOf(); const timeline = this.#state.timeline; - const drops = this.#state.drops.peek(); + // A datagram still buffered took its sequence, so no group is missed there; the Rust + // fetch names it `NotFetchable`. + const gone = [...this.#state.drops.peek()]; + for (const datagram of this.#state.datagrams.peek()) + insertRun(gone, datagram.sequence, datagram.sequence + 1); for (const run of this.#wants(start, Math.min(end, this.#state.received.peek()))) { - for (const open of runGaps(drops, run.start, run.end)) { + for (const open of runGaps(gone, run.start, run.end)) { let next = open.start; for (let i = timelineIndex(timeline, open.start); i < timeline.length; i++) { const group = timeline[i]; @@ -2594,9 +2599,8 @@ export class Subscriber { const end = this.#window.end(); if (end === undefined) return false; // A fill still owes a group it reads. - const drift = this.#drift(); - const filling = this.#askFills(this.#window.floor() ?? 0, end, drift); - if (filling !== undefined && !this.#staleAt(filling, drift, true)) return false; + const filling = this.#askFills(this.#window.floor() ?? 0, end); + if (filling !== undefined && !this.#staleAt(filling, this.#drift(), true)) return false; const held = this.#state.groups.peek(); const received = this.#state.received.peek(); const drops = this.#state.drops.peek(); diff --git a/quest/m1/subscribe-ranges/js.md b/quest/m1/subscribe-ranges/js.md index 1ed038aeeff..d6b9da2812c 100644 --- a/quest/m1/subscribe-ranges/js.md +++ b/quest/m1/subscribe-ranges/js.md @@ -59,36 +59,43 @@ wire FINs a covered bounded subscription without SUBSCRIBE_END, and the JS subscriber reopens demand it no longer covers on the same track, as the Rust copy does. +Landed in [moq-dev/moq#7696](https://github.com/moq-dev/moq/pull/7696): the +on-demand request surface and `fetchGroup`. `track.Producer.requests()` opens a +`Track.Requests` handle, the Rust `Producer::requests`; while one is open, a +reader's misses (groups its ranges name below the newest written that the +cache does not hold, and its budget still wants) queue a `Track.Fill` that +readers missing the same groups join. A fill is an owned handle: `accept`, +`dropGroups`, `refuseGroups`, `wanted`, and `close`, which names what is still +wanted dropped. With no handle open a miss is given up, as before. A produced +broadcast's `fetchGroup` is a one-range subscription on it, judging staleness +against the whole track as the Rust `fetch_group` does, and the lite-07 +SUBSCRIBE_START names the lowest group a fill brings, as the Rust `poll_start` +does. Lite FETCH and lite-07 ranged SUBSCRIBE serve history from it, covered +in-process and by the `CLI FETCH history` interop lane. + What remains: -- **On-demand request surface.** Decided in the 2026-10-05 audit: the producer - half of JavaScript FETCH folds in here, so - `@moq/net`'s on-demand request surface takes range requests from the start - instead of the per-group `requested_group` shape Rust replaced with - `requested_fill`. IETF FETCH dispatch onto it is - [on-demand JavaScript FETCH](/quest/m1/js-fetch-on-demand.md). - - Expose an owned request handle rather than a storage callback; dropping a - request refuses it rather than leaving the subscriber waiting. Preserve - group sequence, frame boundaries, payload bytes, and track properties. - Storage, retention, and media catalog interpretation stay outside `js/net`. - - One logical dynamic track per broadcast and name: a cache-miss request - never creates a duplicate live producer. - - Verify with an in-memory responder, without OPFS or an archive writer: a - browser publisher serves a native subscriber after a group is evicted or - was never cached, covering exact replay, empty and missing groups, - concurrent requests, and cancellation while awaiting a reply. -- **`fetchGroup`.** Becomes a one-range subscription on the request surface - above, or is removed. -- **Fills.** Mirror Rust's rule from [#7168](https://github.com/moq-dev/moq/pull/7168) - (decided 2026-10-29, maintainer): give up a run below a start already - resolved under a budget at least as loose as the reader's, and on a pre-06 - wire fill below the start only when the reader names a floor. `js/net` - requests no fills today, so nothing over-fetches yet; this keeps it that way - once it does. With fills, a bounded read also mirrors Rust's head fill - ([moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): it hands out - a cached group missing its first frames only once a fill answers from frame - 0, and gives one whose fill is refused up as a miss. Until then a JS reader - counts a hole the feed no longer owes as given up, with no fill asked. +- **Received copies fill.** A JavaScript subscriber session serves its copy's + misses by asking upstream, the Rust lite subscriber's `requested_fill` loop, + so a JS relay or reader fills what its copy missed. Today no handle can reach + a received copy, so nothing over-fetches. When it does, mirror Rust's rule + from [#7168](https://github.com/moq-dev/moq/pull/7168) (decided 2026-10-29, + maintainer): give up a run below a start already resolved under a budget at + least as loose as the reader's, and on a pre-06 wire fill below the start + only when the reader names a floor. A bounded read also mirrors Rust's head + fill ([moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): it hands + out a cached group missing its first frames only once a fill answers from + frame 0, and gives one whose fill is refused up as a miss. Until then a JS + reader counts a hole the feed no longer owes as given up, with no fill asked. +- **Time lookups.** The Rust `Fill::time` asks a handler for the group + containing a time start no held group resolves. A JS time anchor still + resolves from the groups the track holds alone, reaching back to the oldest. +- **Lite-07 SUBSCRIBE_FINISH.** Mirror it once + [moq-dev/moq#7675](https://github.com/moq-dev/moq/pull/7675) lands, as the + paragraph above says. + +IETF FETCH dispatch onto the request surface is +[on-demand JavaScript FETCH](/quest/m1/js-fetch-on-demand.md). Ranges stay whole groups ([moq-dev/moq#6465](https://github.com/moq-dev/moq/pull/6465)), so the group model keeps refusing a nonzero lite `frameStart` as a protocol diff --git a/test/interop/clients/js-native/tail.ts b/test/interop/clients/js-native/tail.ts index cca64b166fd..fae3614c39a 100644 --- a/test/interop/clients/js-native/tail.ts +++ b/test/interop/clients/js-native/tail.ts @@ -54,7 +54,8 @@ if ( function frames(sequence: number): Uint8Array[] { if (compress) return [new Uint8Array(BYTES / 2).fill(sequence), new Uint8Array(0), new Uint8Array(BYTES / 2).fill(sequence)]; - if (cached || history || late) return [0, 1, 2].map((index) => new Uint8Array(BYTES / 4).fill(sequence * 16 + index)); + if (cached || history || late) + return [0, 1, 2].map((index) => new Uint8Array(BYTES / 4).fill(sequence * 16 + index)); return [new Uint8Array(BYTES).fill(sequence)]; } From 3da8e780e3f73fff4823751a5214c6d355381e91 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 09:55:10 -0800 Subject: [PATCH 05/13] chore(net): API report for bigint fill sequences Co-Authored-By: Claude Opus 5.5 --- js/net/api/index.api.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index 58ce27dc2be..4e809ab0f7e 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -631,19 +631,19 @@ export namespace Track { } export class Fill { [Symbol.dispose](): void; - accept(sequence: number, info?: Partial): Group.Producer; + accept(sequence: bigint, info?: Partial): Group.Producer; close(): void; - dropGroups(start: number, end: number): void; - readonly end: number; - isWanted(sequence: number): boolean; + 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: number, end: number, error: Error): void; - readonly start: number; - unwanted(sequence: number): Promise; - wanted(): number | undefined; - wantedChanged(): Promise; + refuseGroups(start: bigint, end: bigint, error: Error): void; + readonly start: bigint; + unwanted(sequence: bigint): Promise; + wanted(): bigint | undefined; + wantedChanged(): Promise; } export interface Groups { end?: Track.Bound; From b2cf0999c43c2b200cf28a4be97624682e90bb0e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 10:05:45 -0800 Subject: [PATCH 06/13] fix(net): join a fill still out without a handle, and wake an ordered read its stale hole releases Co-Authored-By: Claude Opus 5.5 --- js/net/src/fill.test.ts | 51 ++++++++++++++++++++++++++++++++++++++++- js/net/src/fill.ts | 24 +++++++++++++++---- js/net/src/track.ts | 34 +++++++++++++++++---------- 3 files changed, 92 insertions(+), 17 deletions(-) diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index 32035d7e846..1a142a6f8d5 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -1,5 +1,5 @@ import { expect, test } from "bun:test"; -import { Milli, yieldNow } from "@moq/clock"; +import { Manual, Milli, Nano, yieldNow } from "@moq/clock"; import { Producer as BroadcastProducer } from "./broadcast.ts"; import { accept as acceptSession, connect as connectSession } from "./connection/index.ts"; import { NotFound, StreamCode, StreamError, toStreamCode } from "./error.ts"; @@ -356,6 +356,55 @@ test("fill: a group arriving live answers the fill", async () => { broadcast.close(); }); +test("fill: an ordered reader stops waiting on an unanswered fill once its budget convicts the hole", async () => { + const clock = new Manual(); + const installed = clock.install(); + try { + const { broadcast, track } = resumed(5n); + const requests = track.requests(); + const reader = track.subscribe({ + ranges: [{ start: { absolute: 0n } }], + delay: { max: Milli(1000) }, + order: "ascending", + }); + const next = reader.ordered().nextGroup(); + // The handler takes the fill for the missing groups and never answers. + const fill = await requests.requestedFill(); + expect([fill?.start, fill?.end]).toEqual([0n, 5n]); + + // Group 5 arrived when the reader asked, so its budget gives up the holes below a second on. + await clock.advance(Nano.fromMilli(Milli(1001))); + expect((await next)?.sequence).toBe(5n); + + fill?.close(); + reader.close(); + requests.close(); + broadcast.close(); + } finally { + installed.close(); + } +}); + +test("fill: a reader joins a fill still served after its handler's handle closed", async () => { + const { broadcast, track } = resumed(5n); + const requests = track.requests(); + const first = wireOf(broadcast).fetchGroup("video", 2n); + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + requests.close(); + + // The fill is still out, so a second fetch joins it rather than failing at once. + const second = wireOf(broadcast).fetchGroup("video", 2n); + await yieldNow(); + serve(fill, new Map([[2n, ["shared"]]])); + expect(await frames(await first)).toEqual(["shared"]); + expect(await frames(await second)).toEqual(["shared"]); + // With the fill answered and no handle open, a new miss fails at once again. + await expect(wireOf(broadcast).fetchGroup("video", 3n)).rejects.toBeInstanceOf(NotFound); + + broadcast.close(); +}); + test("fill: a group the track gives up elsewhere answers the fill", async () => { const { broadcast, track } = resumed(5n); const requests = track.requests(); diff --git a/js/net/src/fill.ts b/js/net/src/fill.ts index 6ccd16f69c5..910b3892b1a 100644 --- a/js/net/src/fill.ts +++ b/js/net/src/fill.ts @@ -133,9 +133,19 @@ export class FillState { return this.#handlers > 0 && !this.#track.closed(); } - /** Ask for `[start, end)` for `asker`, joining the fills already bringing part of it. */ - ask(start: bigint, end: bigint, asker: Asker): void { - if (!this.serving || start >= end) return; + /** Whether a fill is out that a reader could join, handler or not. */ + get active(): boolean { + return this.#pending.size > 0; + } + + /** + * Ask for `[start, end)` for `asker`: join the fills already bringing part of it, and queue the + * rest while a handler is open, as the Rust `FillState::join` does. Returns the parts now + * asked, in order. + */ + ask(start: bigint, end: bigint, asker: Asker): Run[] { + if (start >= end || this.#track.closed()) return []; + const asked: Run[] = []; let missing: Run[] = [{ start, end }]; for (const pending of this.#pending) { const unresolved = pending.unresolved(start, end); @@ -144,15 +154,21 @@ export class FillState { pending.askers.add(asker); pending.bump(); } - for (const run of unresolved) missing = missing.flatMap((gap) => subtract(gap, run)); + for (const run of unresolved) { + insertRun(asked, run.start, run.end); + missing = missing.flatMap((gap) => subtract(gap, run)); + } } + if (this.#handlers === 0) return asked; for (const gap of missing) { const pending = new Pending(gap.start, gap.end); pending.askers.add(asker); this.#pending.add(pending); this.#queue.push(pending); + insertRun(asked, gap.start, gap.end); } if (missing.length > 0) this.#queued.update((revision) => revision + 1); + return asked; } /** The first sequence of `[start, end)` a fill still owes `asker`. */ diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 747e0b23263..2ee58eff6b6 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -2510,7 +2510,8 @@ export class Subscriber { const producer = this.#state.producer; if (this.#resume || !producer || this.#closed) return undefined; const fills = fillsOf(producer); - if (fills.serving) { + // A fill already out can be joined even once its handler's handle closed. + if (fills.serving || fills.active) { drift ??= this.#drift(); const asker = this.#askerOf(); const timeline = this.#state.timeline; @@ -2546,18 +2547,20 @@ export class Subscriber { if (!producer) return false; if (this.#state.info.peek() === undefined && this.#state.closed.peek() === undefined) return "pending"; if (cachedHolds(producer, sequence)) return true; - const fills = fillsOf(producer); - if (!fills.serving) return false; if (this.#state.datagrams.peek().some((datagram) => datagram.sequence === sequence)) return false; + // Joins a fill already bringing it, handler or not; asks a new one only while one is open. + const asked = fillsOf(producer).ask(sequence, sequence + 1n, this.#askerOf()); + if (asked.length === 0) return false; insertRun(this.#asked, sequence, sequence + 1n); - fills.ask(sequence, sequence + 1n, this.#askerOf()); return true; } // The lowest group a fill still brings this reader, asking for what it misses first. #filling(): bigint | undefined { const producer = this.#state.producer; - if (this.#resume || !producer || !fillsOf(producer).serving) return undefined; + if (this.#resume || !producer) return undefined; + const fills = fillsOf(producer); + if (!fills.serving && !fills.active) return undefined; const drift = this.#drift(); const filling = this.#askFills(this.#cursor.peek().start, UNBOUNDED, drift); return filling !== undefined && !this.#staleAt(filling, drift) ? filling : undefined; @@ -2575,13 +2578,13 @@ export class Subscriber { runGaps(fills.covered(refill.start, refill.end, asker), refill.start, refill.end), ), ); + // Only what a fill took counts as asked: with no handler open, a miss no fill covers is + // left to ask once one opens. for (const gap of runGaps(this.#asked, start, end)) { - insertRun(this.#asked, gap.start, gap.end); - fills.ask(gap.start, gap.end, asker); + for (const run of fills.ask(gap.start, gap.end, asker)) insertRun(this.#asked, run.start, run.end); } for (const refill of again) { - insertRun(this.#refilled, refill.start, refill.end); - fills.ask(refill.start, refill.end, asker); + for (const run of fills.ask(refill.start, refill.end, asker)) insertRun(this.#refilled, run.start, run.end); } } @@ -3402,9 +3405,12 @@ export class Subscriber { if (owed) break; } if (!owed) { - // A fill still owes a group below, which lands as a group does. + // A fill still owes a group below, which lands as a group does. Its staleness deadline + // wakes the cursor too, so a fill that never answers cannot pin it. const filling = this.#askFills(start, end, drift); - return filling !== undefined && !this.#staleAt(filling, drift, true); + if (filling === undefined || this.#staleAt(filling, drift, true)) return false; + this.#state.waitingOrdered = true; + return true; } if (this.#staleAt(owed.sequence, drift, true)) return false; if (owed.folds !== undefined) this.#wakeAt(owed.folds); @@ -3484,7 +3490,11 @@ export class Subscriber { if (closed !== undefined) return { kind: "done" }; // Nothing buffered: ask a fill for what this reader misses, and wait while one owes it. const filling = this.#askFills(start, cursor.end ?? UNBOUNDED, drift); - if (filling !== undefined && !this.#staleAt(filling, drift, true)) return { kind: "idle" }; + if (filling !== undefined && !this.#staleAt(filling, drift, true)) { + // Its staleness deadline wakes the cursor, as for any owed hole. + this.#state.waitingOrdered = true; + return { kind: "idle" }; + } const end = this.#state.end.peek(); if (this.#exhausted()) return { kind: "done" }; if ( From 585dd4782d76518c0d281ece6ecad448dc313460 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 11:35:49 -0800 Subject: [PATCH 07/13] fix(net): wait on any fill the budget still wants, keep asked misses to the live span, plan the history lane only where it runs Co-Authored-By: Claude Opus 5.5 --- js/net/src/fill.test.ts | 49 +++++++++++++++++++++++++++++++++++++++++ js/net/src/fill.ts | 5 ----- js/net/src/track.ts | 35 +++++++++++++++++++---------- test/interop/interop.sh | 3 ++- 4 files changed, 74 insertions(+), 18 deletions(-) diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index 1a142a6f8d5..74578fe2943 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -385,6 +385,55 @@ test("fill: an ordered reader stops waiting on an unanswered fill once its budge } }); +test("fill: a bounded reader keeps waiting on a fresh fill once an older one goes stale", async () => { + const clock = new Manual(); + const installed = clock.install(); + try { + const broadcast = new BroadcastProducer(); + const track = broadcast.createTrack("video"); + const write = (sequence: bigint) => { + const group = track.createGroup(sequence); + group.writeFrame({ payload: enc.encode(`live ${sequence}`) }); + group.finish(); + }; + // Holes 0-1 wait on group 2, which arrives first; holes 3-4 on group 5, half a second later. + write(2n); + await clock.advance(Nano.fromMilli(Milli(500))); + write(5n); + const requests = track.requests(); + const reader = track.subscribe({ + ranges: [{ start: { absolute: 0n }, end: { absolute: 6n } }], + delay: { max: Milli(1000) }, + }); + expect((await reader.recvGroup())?.sequence).toBe(2n); + expect((await reader.recvGroup())?.sequence).toBe(5n); + const next = reader.recvGroup(); + const fills: Fill[] = []; + for (let i = 0; i < 2; i++) { + const fill = await requests.requestedFill(); + if (fill) fills.push(fill); + } + expect(fills.map((fill) => [fill.start, fill.end])).toEqual([ + [0n, 2n], + [3n, 5n], + ]); + + // Holes 0-1 are past the budget now, but 3-4 are not: the read waits on them. + await clock.advance(Nano.fromMilli(Milli(600))); + const late = fills[1].accept(3n); + late.writeFrame({ payload: enc.encode("old 3") }); + late.finish(); + expect((await next)?.sequence).toBe(3n); + + for (const fill of fills) fill.close(); + expect(await reader.recvGroup()).toBeUndefined(); + requests.close(); + broadcast.close(); + } finally { + installed.close(); + } +}); + test("fill: a reader joins a fill still served after its handler's handle closed", async () => { const { broadcast, track } = resumed(5n); const requests = track.requests(); diff --git a/js/net/src/fill.ts b/js/net/src/fill.ts index 910b3892b1a..c1c284eea99 100644 --- a/js/net/src/fill.ts +++ b/js/net/src/fill.ts @@ -171,11 +171,6 @@ export class FillState { return asked; } - /** The first sequence of `[start, end)` a fill still owes `asker`. */ - owed(start: bigint, end: bigint, asker: Asker): bigint | undefined { - return this.covered(start, end, asker)[0]?.start; - } - /** The parts of `[start, end)` a fill `asker` joined still owes, in order. */ covered(start: bigint, end: bigint, asker: Asker): Run[] { const covered: Run[] = []; diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 2ee58eff6b6..6ebf0e411f0 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -2505,7 +2505,8 @@ export class Subscriber { // Ask the producer's fills for the misses in `[start, end)`: groups this reader reads below // the newest one received that the cache does not hold and nobody gave up. A run whose newest // group the budget already convicts is not asked, so a reader at the live edge never asks. - // Returns the first sequence a fill still owes this reader. Mirrors the Rust `Misses::judge`. + // Returns the first sequence a fill still owes this reader whose budget still wants it, arming + // the wakeup for when that changes. Mirrors the Rust `Misses::judge`. #askFills(start: bigint, end: bigint, drift?: Drift): bigint | undefined { const producer = this.#state.producer; if (this.#resume || !producer || this.#closed) return undefined; @@ -2514,6 +2515,14 @@ export class Subscriber { if (fills.serving || fills.active) { drift ??= this.#drift(); const asker = this.#askerOf(); + // Keep only what this reader still reads, as the Rust `Misses` clips what it judged to + // the window: a group handed out, forgotten past the budget, or outside the window is + // never asked again, so these stay within the live span. A window moving back over a + // clipped group asks it once more, as in Rust. + if (this.#asked.length > 0) this.#asked = this.#asked.flatMap((run) => this.#wants(run.start, run.end)); + if (this.#refilled.length > 0) { + this.#refilled = this.#refilled.flatMap((run) => this.#wants(run.start, run.end)); + } const timeline = this.#state.timeline; // A datagram still buffered took its sequence, so no group is missed there; the Rust // fetch names it `NotFetchable`. @@ -2536,7 +2545,14 @@ export class Subscriber { } } const asker = this.#state.asker; - return asker && fills.owed(start, end, asker); + if (!asker) return undefined; + // Every group of an owed run waits on the same successor, so its newest judges the run; + // a stale run gives way to a later one the budget still wants. + for (const run of fills.covered(start, end, asker)) { + drift ??= this.#drift(); + if (!this.#staleAt(run.end - 1n, drift, true)) return run.start; + } + return undefined; } // Ask a fill for a fetch's group at once, written yet or not, as the Rust `fetch_group` queues @@ -2562,8 +2578,7 @@ export class Subscriber { const fills = fillsOf(producer); if (!fills.serving && !fills.active) return undefined; const drift = this.#drift(); - const filling = this.#askFills(this.#cursor.peek().start, UNBOUNDED, drift); - return filling !== undefined && !this.#staleAt(filling, drift) ? filling : undefined; + return this.#askFills(this.#cursor.peek().start, UNBOUNDED, drift); } // Ask a fill for the missed run `[start, end)`, unless its newest group is stale: what was @@ -2628,8 +2643,7 @@ export class Subscriber { const end = this.#window.end(); if (end === undefined) return false; // A fill still owes a group it reads. - const filling = this.#askFills(this.#window.floor() ?? 0n, end); - if (filling !== undefined && !this.#staleAt(filling, this.#drift(), true)) return false; + if (this.#askFills(this.#window.floor() ?? 0n, end) !== undefined) return false; const held = this.#state.groups.peek(); const received = this.#state.received.peek(); const drops = this.#state.drops.peek(); @@ -3179,8 +3193,7 @@ export class Subscriber { // A clean close completes this range, retaining groups a later cap raise can read. if (closed !== undefined) return { kind: "done" }; // Nothing buffered: ask a fill for what this reader misses, and wait while one owes it. - const filling = this.#askFills(start, end ?? UNBOUNDED, drift); - if (filling !== undefined && !this.#staleAt(filling, drift, true)) return { kind: "idle" }; + if (this.#askFills(start, end ?? UNBOUNDED, drift) !== undefined) return { kind: "idle" }; // A bounded window ends once nothing in it is left to deliver, as in Rust. if (this.#exhausted()) return { kind: "done" }; if (!this.#complete() || this.#starting(groups)) return { kind: "idle" }; @@ -3407,8 +3420,7 @@ export class Subscriber { if (!owed) { // A fill still owes a group below, which lands as a group does. Its staleness deadline // wakes the cursor too, so a fill that never answers cannot pin it. - const filling = this.#askFills(start, end, drift); - if (filling === undefined || this.#staleAt(filling, drift, true)) return false; + if (this.#askFills(start, end, drift) === undefined) return false; this.#state.waitingOrdered = true; return true; } @@ -3489,8 +3501,7 @@ export class Subscriber { // A clean close completes this range, retaining groups a later cap raise can read. if (closed !== undefined) return { kind: "done" }; // Nothing buffered: ask a fill for what this reader misses, and wait while one owes it. - const filling = this.#askFills(start, cursor.end ?? UNBOUNDED, drift); - if (filling !== undefined && !this.#staleAt(filling, drift, true)) { + if (this.#askFills(start, cursor.end ?? UNBOUNDED, drift) !== undefined) { // Its staleness deadline wakes the cursor, as for any owed hole. this.#state.waitingOrdered = true; return { kind: "idle" }; diff --git a/test/interop/interop.sh b/test/interop/interop.sh index 362669a6782..c72716871aa 100755 --- a/test/interop/interop.sh +++ b/test/interop/interop.sh @@ -504,7 +504,8 @@ plan_pass() { for runtime in js-native-node js-native-bun; do needs "$runtime" || continue record "not run" case="CLI FETCH" publisher="$runtime" subscriber=rust - record "not run" case="CLI FETCH history" publisher="$runtime" subscriber=rust + # run_tails skips it on moq-transport, so only plan it where it runs. + [[ "$VERSION" == moq-transport-* ]] || record "not run" case="CLI FETCH history" publisher="$runtime" subscriber=rust record "not run" case="late join" publisher=rust subscriber="$runtime" record "not run" case="late join" publisher="$runtime" subscriber=rust record "not run" case=tail publisher=rust subscriber="$runtime" From a3fd02a060a1c217e5cf5d5b120d88eb88a3eccd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 12:08:20 -0800 Subject: [PATCH 08/13] fix(net): a fill owes each reader only the groups it reads, as Rust's Join::held Co-Authored-By: Claude Opus 5.5 --- js/net/src/fill.test.ts | 48 +++++++++++++++++++++++++++++++++++++++++ js/net/src/fill.ts | 10 +++++++-- 2 files changed, 56 insertions(+), 2 deletions(-) diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index 74578fe2943..24ef54fd458 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -434,6 +434,54 @@ test("fill: a bounded reader keeps waiting on a fresh fill once an older one goe } }); +test("fill: a reader joining a wider fill is owed only its own ranges", async () => { + const { broadcast, track } = resumed(10n); + const requests = track.requests(); + const wide = track.subscribe({ + ranges: [{ start: { absolute: 0n }, end: { absolute: 10n } }], + delay: { max: null }, + order: "ascending", + }); + void drain(wide); + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + expect([fill.start, fill.end]).toEqual([0n, 10n]); + + // A narrower reader joins the same fill for 2 and 7 alone. + const narrow = track.subscribe({ + ranges: [ + { start: { absolute: 2n }, end: { absolute: 3n } }, + { start: { absolute: 7n }, end: { absolute: 8n } }, + ], + delay: { max: null }, + order: "ascending", + }); + const got: bigint[] = []; + const done = (async () => { + for (let group = await narrow.recvGroup(); group; group = await narrow.recvGroup()) { + got.push(group.sequence); + group.close(); + } + })(); + await yieldNow(); + expect(await Promise.race([requests.requestedFill(), yieldNow().then(() => "none")])).toBe("none"); + + for (const sequence of [2n, 7n]) { + const group = fill.accept(sequence); + group.writeFrame({ payload: enc.encode(`old ${sequence}`) }); + group.finish(); + } + // The wide reader still waits on the rest of the fill; the narrow one has all it reads. + await done; + expect(got).toEqual([2n, 7n]); + expect(fill.wanted()).toBe(0n); + + fill.close(); + wide.close(); + requests.close(); + broadcast.close(); +}); + test("fill: a reader joins a fill still served after its handler's handle closed", async () => { const { broadcast, track } = resumed(5n); const requests = track.requests(); diff --git a/js/net/src/fill.ts b/js/net/src/fill.ts index c1c284eea99..49468392269 100644 --- a/js/net/src/fill.ts +++ b/js/net/src/fill.ts @@ -171,12 +171,18 @@ export class FillState { return asked; } - /** The parts of `[start, end)` a fill `asker` joined still owes, in order. */ + /** + * The parts of `[start, end)` a fill `asker` joined still owes it, in order: only what it still + * reads, as the Rust `Join::held` holds, so a wider fill shared with other readers owes it + * nothing outside its own ranges. + */ covered(start: bigint, end: bigint, asker: Asker): Run[] { const covered: Run[] = []; for (const pending of this.#pending) { if (!pending.askers.has(asker)) continue; - for (const run of pending.unresolved(start, end)) insertRun(covered, run.start, run.end); + for (const gap of pending.unresolved(start, end)) { + for (const run of asker.wants(gap.start, gap.end)) insertRun(covered, run.start, run.end); + } } return covered; } From d11f34be2a2cb8e3428b71cafef7878a13b997fc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 12:17:54 -0800 Subject: [PATCH 09/13] fix(net): wake an arrival-order read its stale fill hole releases, and tell a fill's handler what a hand-out withdrew Co-Authored-By: Claude Opus 5.5 --- js/net/src/fill.test.ts | 59 +++++++++++++++++++++++++++++++++++++++++ js/net/src/track.ts | 18 ++++++++++--- 2 files changed, 74 insertions(+), 3 deletions(-) diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index 24ef54fd458..421bc1ce33c 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -385,6 +385,65 @@ test("fill: an ordered reader stops waiting on an unanswered fill once its budge } }); +test("fill: an arrival-order reader stops waiting on an unanswered fill once its budget convicts the hole", async () => { + const clock = new Manual(); + const installed = clock.install(); + try { + const { broadcast, track } = resumed(5n); + track.finish(); + const requests = track.requests(); + const reader = track.subscribe({ ranges: [{ start: { absolute: 0n } }], delay: { max: Milli(1000) } }); + expect((await reader.recvGroup())?.sequence).toBe(5n); + const next = reader.recvGroup(); + const fill = await requests.requestedFill(); + expect([fill?.start, fill?.end]).toEqual([0n, 5n]); + + // The fill never answers; the holes go past the budget, and the finished track ends the read. + await clock.advance(Nano.fromMilli(Milli(1001))); + expect(await next).toBeUndefined(); + + fill?.close(); + requests.close(); + broadcast.close(); + } finally { + installed.close(); + } +}); + +test("fill: a handler hears that a reader stopped wanting what it handed out past", async () => { + const clock = new Manual(); + const installed = clock.install(); + try { + const { broadcast, track } = resumed(5n); + const requests = track.requests(); + const reader = track.subscribe({ + ranges: [{ start: { absolute: 0n } }], + delay: { max: Milli(1000) }, + order: "ascending", + }); + const next = reader.ordered().nextGroup(); + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + expect(await fill.wantedChanged()).toBe(0n); + const changed = fill.wantedChanged(); + const unwanted = fill.unwanted(0n); + + // Past the budget the reader takes group 5, leaving the holes below it for good. + await clock.advance(Nano.fromMilli(Milli(1001))); + expect((await next)?.sequence).toBe(5n); + expect(await changed).toBeUndefined(); + await unwanted; + expect(fill.isWanted(0n)).toBe(false); + + fill.close(); + reader.close(); + requests.close(); + broadcast.close(); + } finally { + installed.close(); + } +}); + test("fill: a bounded reader keeps waiting on a fresh fill once an older one goes stale", async () => { const clock = new Manual(); const installed = clock.install(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 6ebf0e411f0..eafc3ad87f4 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -2085,6 +2085,9 @@ export class Subscriber { // refills cannot evict each other without bound. Mirrors the Rust `Misses`. #asked: Run[] = []; #refilled: Run[] = []; + // The last read waited on a fill, so the staleness deadline it armed wakes the next one: a + // fill that never answers cannot pin a reader in either order. + #fillWait = false; #drift(): Drift { // A fetch judges its group against the whole track, as the Rust `fetch_group` does: a @@ -2307,6 +2310,10 @@ export class Subscriber { this.#skipped.delete(sequence); if (this.#resume) this.#resume.forgetPastBudget(this.#delivered); else this.#forgetPastBudget(this.#delivered); + // What it hands out, and forgets below it, it no longer wants from a fill: tell the fills + // it joined, as a move of its bounds does, so their handlers stop serving it. + const producer = this.#state.producer; + if (this.#state.asker && producer) fillsOf(producer).moved(this.#state.asker); } // Forget the gaps in `delivered` below each group past this subscriber's budget now, whether @@ -2550,7 +2557,9 @@ export class Subscriber { // a stale run gives way to a later one the budget still wants. for (const run of fills.covered(start, end, asker)) { drift ??= this.#drift(); - if (!this.#staleAt(run.end - 1n, drift, true)) return run.start; + if (this.#staleAt(run.end - 1n, drift, true)) continue; + this.#fillWait = true; + return run.start; } return undefined; } @@ -3134,6 +3143,7 @@ export class Subscriber { if (this.#resume) return this.#tryResumed(false, dispositions); const refused = this.#settle(); if (refused) return { kind: "error", error: refused }; + this.#fillWait = false; const groups = this.#state.groups.peek(); const { start, end } = this.#cursor.peek(); const old = () => new StreamError(StreamCode.Old, { message: "group is past the budget" }); @@ -3294,8 +3304,9 @@ export class Subscriber { // A datagram shares the sequence namespace, so it can fill the owed hole. this.#state.datagrams.changed(fn), ); - // A bounded window ends once the feed stops owing its last hole, which only time decides. - else if (this.#window.end() !== undefined) dispose.push(this.#wall.revision.changed(fn)); + // A bounded window ends once the feed stops owing its last hole, which only time decides, + // and a fill's hole stops holding a read once the budget convicts it. + else if (this.#window.end() !== undefined || this.#fillWait) dispose.push(this.#wall.revision.changed(fn)); return () => { for (const close of dispose) close(); }; @@ -3463,6 +3474,7 @@ export class Subscriber { const refused = this.#settle(); if (refused) return { kind: "error", error: refused }; this.#state.waitingOrdered = false; + this.#fillWait = false; const groups = this.#state.groups.peek(); const cursor = this.#cursor.peek(); let start = max(cursor.start, this.#nextSequence); From f40c1d651acfb6e647e1b96c67e7eb6fae86e2fd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 12:32:39 -0800 Subject: [PATCH 10/13] fix(net): withdraw a fill's unread groups for good, clip a reader's wants to its sequence cursor, and wake handlers on an order change Co-Authored-By: Claude Opus 5.5 --- js/net/src/fill.test.ts | 71 +++++++++++++++++++++++++++++++++++++++++ js/net/src/fill.ts | 17 +++++++--- js/net/src/track.ts | 39 +++++++++++++++++----- 3 files changed, 115 insertions(+), 12 deletions(-) diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index 421bc1ce33c..8afc1fc75d3 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -541,6 +541,77 @@ test("fill: a reader joining a wider fill is owed only its own ranges", async () broadcast.close(); }); +test("fill: a group no reader reads any more stays withdrawn, and widening back asks a new fill", async () => { + const { broadcast, track } = resumed(5n); + const requests = track.requests(); + const ranges = (start: bigint) => [{ start: { absolute: start }, end: { absolute: 5n } }]; + const reader = track.subscribe({ ranges: ranges(0n), delay: { max: null }, order: "ascending" }); + void drain(reader); + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + expect([fill.start, fill.end]).toEqual([0n, 5n]); + + reader.update({ ranges: ranges(3n), delay: { max: null }, order: "ascending" }); + expect(fill.isWanted(1n)).toBe(false); + expect(fill.wanted()).toBe(3n); + + // Widening back does not revive the group in this fill: the handler may have stopped on it. + reader.update({ ranges: ranges(0n), delay: { max: null }, order: "ascending" }); + await yieldNow(); + expect(fill.isWanted(1n)).toBe(false); + const again = await requests.requestedFill(); + expect([again?.start, again?.end]).toEqual([0n, 3n]); + + again?.close(); + fill.close(); + reader.close(); + requests.close(); + broadcast.close(); +}); + +test("fill: what a reader's sequence cursor passes, a fill no longer owes it", async () => { + const { broadcast, track } = resumed(5n); + const requests = track.requests(); + const reader = track.subscribe(history); + // A logical reader that already holds what lies below the floor raises its copy's cursor. + expect(hooks.tryNextGroup(reader, 0n).kind).toBe("idle"); + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + expect(fill.wanted()).toBe(0n); + const changed = fill.wantedChanged(); + await changed; + const next = fill.wantedChanged(); + + hooks.tryNextGroup(reader, 3n); + expect(await next).toBe(3n); + expect(fill.isWanted(1n)).toBe(false); + + fill.close(); + reader.close(); + requests.close(); + broadcast.close(); +}); + +test("fill: a reader changing only its order wakes the handler", async () => { + const { broadcast, track } = resumed(5n); + const requests = track.requests(); + const reader = track.subscribe(history); + void drain(reader); + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + expect(await fill.wantedChanged()).toBe(0n); + const changed = fill.wantedChanged(); + + reader.update({ ...history, order: "descending" }); + expect(await changed).toBe(4n); + expect(fill.order).toBe("descending"); + + fill.close(); + reader.close(); + requests.close(); + broadcast.close(); +}); + test("fill: a reader joins a fill still served after its handler's handle closed", async () => { const { broadcast, track } = resumed(5n); const requests = track.requests(); diff --git a/js/net/src/fill.ts b/js/net/src/fill.ts index 49468392269..38f0f1cc5b0 100644 --- a/js/net/src/fill.ts +++ b/js/net/src/fill.ts @@ -76,6 +76,9 @@ class Pending { readonly askers = new Set(); // The groups answered: accepted, delivered live, dropped, or refused. readonly resolved: Run[] = []; + // The groups no reader read any more at some point: withdrawn for good, so a handler that + // stopped serving one is never asked for it again. A reader widening back asks a new fill. + readonly withdrawn: Run[] = []; // Still in the queue, not yet handed to a handler. queued = true; // Withdrawn or settled: owes nothing more. @@ -92,10 +95,12 @@ class Pending { this.revision.update((revision) => revision + 1); } - // The parts of `[start, end)` within the fill that are still unanswered. + // The parts of `[start, end)` within the fill still unanswered and not withdrawn. unresolved(start = this.start, end = this.end): Run[] { if (this.done) return []; - return runGaps(this.resolved, max(start, this.start), min(end, this.end)); + return runGaps(this.resolved, max(start, this.start), min(end, this.end)).flatMap((gap) => + runGaps(this.withdrawn, gap.start, gap.end), + ); } // The parts of `[start, end)` still unanswered that a reader still reads. @@ -241,10 +246,14 @@ export class FillState { } } - // Withdraw `pending` once no reader still reads any of what it owes. + // Withdraw what no reader reads any more for good, and `pending` once that is all of it. #judge(pending: Pending): void { if (pending.done) return; - if (pending.owed().length > 0) { + const owed = pending.owed(); + for (const gap of pending.unresolved()) { + for (const run of runGaps(owed, gap.start, gap.end)) insertRun(pending.withdrawn, run.start, run.end); + } + if (owed.length > 0) { pending.bump(); return; } diff --git a/js/net/src/track.ts b/js/net/src/track.ts index eafc3ad87f4..8f88f328f72 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -2088,6 +2088,9 @@ export class Subscriber { // The last read waited on a fill, so the staleness deadline it armed wakes the next one: a // fill that never answers cannot pin a reader in either order. #fillWait = false; + // Bumped whenever the fills this reader joined are rejudged, which may withdraw groups it reads + // again by the time it looks (a narrowing undone in one turn moves no signal), so it asks anew. + #fillMoves = new Signal(0); #drift(): Drift { // A fetch judges its group against the whole track, as the Rust `fetch_group` does: a @@ -2312,8 +2315,23 @@ export class Subscriber { else this.#forgetPastBudget(this.#delivered); // What it hands out, and forgets below it, it no longer wants from a fill: tell the fills // it joined, as a move of its bounds does, so their handlers stop serving it. + this.#fillsMoved(); + } + + // What this reader wants from the fills it joined may have narrowed: rejudge them, so their + // handlers hear it. + #fillsMoved(): void { const producer = this.#state.producer; - if (this.#state.asker && producer) fillsOf(producer).moved(this.#state.asker); + if (!this.#state.asker || !producer) return; + fillsOf(producer).moved(this.#state.asker); + this.#fillMoves.update((moves) => moves + 1); + } + + // Raise the sequence cursor to `floor`: what lies below it is passed for good. + #raiseNext(floor: bigint | undefined): void { + if (floor === undefined || floor <= this.#nextSequence) return; + this.#nextSequence = floor; + this.#fillsMoved(); } // Forget the gaps in `delivered` below each group past this subscriber's budget now, whether @@ -2483,16 +2501,15 @@ export class Subscriber { end: end === undefined ? local.end : min(local.end ?? end, end), }); // A fill this reader alone waited on for a group it no longer reads is withdrawn. - const producer = this.#state.producer; - if (this.#state.asker && producer) fillsOf(producer).moved(this.#state.asker); + this.#fillsMoved(); } - // The parts of `[start, end)` this reader still reads: inside its cursor and window, and not - // handed out. + // The parts of `[start, end)` this reader still reads: inside its cursor and window, not + // handed out, and not passed by the sequence cursor, which never goes back. #wants(start: bigint, end: bigint): Run[] { if (this.#closed || this.#state.closed.peek() !== undefined) return []; const cursor = this.#cursor.peek(); - const from = max(start, cursor.start); + const from = max(max(start, cursor.start), this.#nextSequence); const to = cursor.end === undefined ? end : min(end, cursor.end); return this.#window.runs(from, to).flatMap((run) => this.#delivered.gaps(run.start, run.end)); } @@ -2733,11 +2750,11 @@ export class Subscriber { return subscriber.#window.starts(from); }; hooks.tryNextGroup = (subscriber, floor) => { - subscriber.#nextSequence = max(subscriber.#nextSequence, floor ?? 0n); + subscriber.#raiseNext(floor); return subscriber.#tryNextGroup(); }; hooks.peekGroup = (subscriber, ordered, floor) => { - if (ordered) subscriber.#nextSequence = max(subscriber.#nextSequence, floor ?? 0n); + if (ordered) subscriber.#raiseNext(floor); return subscriber.#peekGroup(ordered); }; hooks.forgetPastBudget = (subscriber, delivered) => subscriber.#forgetPastBudget(delivered); @@ -3283,6 +3300,7 @@ export class Subscriber { const dispose = [ this.#state.groups.changed(fn), this.#state.drops.changed(fn), + this.#fillMoves.changed(fn), this.#state.startChanged.changed(fn), // A group starting may settle a time end, or move the cap it holds reads back with. ...(this.#window.settled ? [] : [this.#state.timelineChanged.changed(fn)]), @@ -3495,6 +3513,8 @@ export class Subscriber { // scanning: one pass walks a whole backlog off rather than replaying it. if (this.#staleAt(group.sequence, drift)) { this.#pass(groups, index); + // The cursor passed what lies below it, which a fill no longer owes this reader. + this.#fillsMoved(); // Holes below a skipped group are undeliverable, even ones the wall clock // still spares because their successor arrived late. start = this.#nextSequence; @@ -3633,8 +3653,11 @@ export class Subscriber { update(options: Subscription) { const subscription = subscriptionDefaults(options); const replaced = !sameRanges(subscription.ranges ?? [], this.#window.ranges); + const reordered = subscription.order !== this.#state.update.peek()?.order; this.#state.update.set(subscription); if (replaced) this.#resolve(); + // A fill's order follows its readers, so its handler wakes to serve the new first group. + else if (reordered) this.#fillsMoved(); } } From cdbcb85b16e61f023e9f1febb1fb1ac42b7c7fbf Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 12:41:44 -0800 Subject: [PATCH 11/13] fix(net): a widening asks withdrawn groups afresh, not through the eviction refill Co-Authored-By: Claude Opus 5.5 --- js/net/src/fill.test.ts | 9 +++++++++ js/net/src/track.ts | 23 +++++++++++++++-------- 2 files changed, 24 insertions(+), 8 deletions(-) diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index 8afc1fc75d3..da5c268785d 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -562,6 +562,15 @@ test("fill: a group no reader reads any more stays withdrawn, and widening back const again = await requests.requestedFill(); expect([again?.start, again?.end]).toEqual([0n, 3n]); + // Each narrowing and widening back asks anew, never spending the refill an eviction gets. + reader.update({ ranges: ranges(3n), delay: { max: null }, order: "ascending" }); + reader.update({ ranges: ranges(0n), delay: { max: null }, order: "ascending" }); + await yieldNow(); + expect(again?.isWanted(1n)).toBe(false); + const third = await requests.requestedFill(); + expect([third?.start, third?.end]).toEqual([0n, 3n]); + + third?.close(); again?.close(); fill.close(); reader.close(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 8f88f328f72..f69022d4890 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -2323,10 +2323,24 @@ export class Subscriber { #fillsMoved(): void { const producer = this.#state.producer; if (!this.#state.asker || !producer) return; + // At once, before the fills withdraw what it no longer reads: a widening back asks those + // groups afresh, never through the one refill an evicted answer is allowed. + this.#clipAsked(); fillsOf(producer).moved(this.#state.asker); this.#fillMoves.update((moves) => moves + 1); } + // Keep what this reader asked within what it still reads, as the Rust `Misses` clips what it + // judged to the window: a group handed out, forgotten past the budget, passed, or outside the + // window is never asked again, so these stay within the live span. A window moving back over a + // clipped group asks it once more, as in Rust. + #clipAsked(): void { + if (this.#asked.length > 0) this.#asked = this.#asked.flatMap((run) => this.#wants(run.start, run.end)); + if (this.#refilled.length > 0) { + this.#refilled = this.#refilled.flatMap((run) => this.#wants(run.start, run.end)); + } + } + // Raise the sequence cursor to `floor`: what lies below it is passed for good. #raiseNext(floor: bigint | undefined): void { if (floor === undefined || floor <= this.#nextSequence) return; @@ -2539,14 +2553,7 @@ export class Subscriber { if (fills.serving || fills.active) { drift ??= this.#drift(); const asker = this.#askerOf(); - // Keep only what this reader still reads, as the Rust `Misses` clips what it judged to - // the window: a group handed out, forgotten past the budget, or outside the window is - // never asked again, so these stay within the live span. A window moving back over a - // clipped group asks it once more, as in Rust. - if (this.#asked.length > 0) this.#asked = this.#asked.flatMap((run) => this.#wants(run.start, run.end)); - if (this.#refilled.length > 0) { - this.#refilled = this.#refilled.flatMap((run) => this.#wants(run.start, run.end)); - } + this.#clipAsked(); const timeline = this.#state.timeline; // A datagram still buffered took its sequence, so no group is missed there; the Rust // fetch names it `NotFetchable`. From 80474d0150572a830c225d98a658b92a7fbf8c54 Mon Sep 17 00:00:00 2001 From: "pullfrog[bot]" <226033991+pullfrog[bot]@users.noreply.github.com> Date: Tue, 3 Nov 2026 22:22:46 +0000 Subject: [PATCH 12/13] quest: delete js.md now that its content moved to lite.md --- quest/m1/subscribe-ranges/js.md | 29 ----------------------- quest/m1/subscribe-ranges/lite07-fetch.md | 1 - 2 files changed, 30 deletions(-) delete mode 100644 quest/m1/subscribe-ranges/js.md diff --git a/quest/m1/subscribe-ranges/js.md b/quest/m1/subscribe-ranges/js.md deleted file mode 100644 index 26d3a191a9d..00000000000 --- a/quest/m1/subscribe-ranges/js.md +++ /dev/null @@ -1,29 +0,0 @@ -# [M] JS ranges - -## Goal - -Finish the explicit-end cleanup in `@moq/net`. The range request surface and -fills landed in [moq-dev/moq#7696](https://github.com/moq-dev/moq/pull/7696). - -## Plan - -Lite-07 bounded completion follows -[Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md)' explicit end, which -[moq-dev/moq#7675](https://github.com/moq-dev/moq/pull/7675) brought to JS -alongside Rust: neither SUBSCRIBE_END nor a covered bounded subscription closes -the Subscribe Stream. The JS publisher keeps reading updates and answers a held -start with SUBSCRIBE_START and its held drops once no group can resolve it, and -the JS subscriber FINs once its tail settles past SUBSCRIBE_END, judging it only -after SUBSCRIBE_START. - -What remains: - -- **The explicit end's leftovers.** Rename SUBSCRIBE_END to SUBSCRIBE_FINISH in - `js/net`, as Rust and the draft did, and delete the subscriber's covered-FIN - path (`#parkCovered`, `#demandCovered`, the `short` reopen), which no lite-07 - publisher triggers any more. - -## Related - -- [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - the Rust lite-07 range fill this mirrors -- [Lite-07 FETCH is single-group only](/quest/m1/subscribe-ranges/lite07-fetch.md) - follows this and Lite-07 ranges diff --git a/quest/m1/subscribe-ranges/lite07-fetch.md b/quest/m1/subscribe-ranges/lite07-fetch.md index b7a24ed03c5..3c45c1fc960 100644 --- a/quest/m1/subscribe-ranges/lite07-fetch.md +++ b/quest/m1/subscribe-ranges/lite07-fetch.md @@ -41,4 +41,3 @@ their frame. ## Required - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - Rust fills multi-group ranges through the subscription -- [JS ranges](/quest/m1/subscribe-ranges/js.md) - JS reads and serves ranges, so its multi-group reads need no FETCH From a385e1f0f707fd359d789650b8482a6f94804ac4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 16:33:34 -0800 Subject: [PATCH 13/13] fix(net): wake readers when a handler opens, give up stale fill runs, and keep datagram sequences out of fills as the track holds them Co-Authored-By: Claude Opus 5.5 --- js/net/src/fill.test.ts | 50 ++++++++++++++++++++++++++++++++++++++ js/net/src/fill.ts | 12 ++++++++-- js/net/src/track.ts | 53 +++++++++++++++++++++++++++++++++-------- 3 files changed, 103 insertions(+), 12 deletions(-) diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index da5c268785d..d1b17886121 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -401,6 +401,9 @@ test("fill: an arrival-order reader stops waiting on an unanswered fill once its // The fill never answers; the holes go past the budget, and the finished track ends the read. await clock.advance(Nano.fromMilli(Milli(1001))); expect(await next).toBeUndefined(); + // The reader gave the stale holes up, so the handler hears it no longer waits on them. + expect(fill?.wanted()).toBeUndefined(); + expect(fill?.isWanted(0n)).toBe(false); fill?.close(); requests.close(); @@ -621,6 +624,53 @@ test("fill: a reader changing only its order wakes the handler", async () => { broadcast.close(); }); +test("fill: a reader parked on a miss asks once a handler opens", async () => { + const { broadcast, track } = resumed(5n); + const reader = track.subscribe(history); + // It reads the live group and parks for the next; nobody could take its miss below. + expect((await reader.recvGroup())?.sequence).toBe(5n); + const next = reader.recvGroup(); + await yieldNow(); + + // A handler opening wakes it to ask. + const requests = track.requests(); + const fill = await requests.requestedFill(); + expect([fill?.start, fill?.end]).toEqual([0n, 5n]); + if (fill) serve(fill, new Map([[0n, ["old 0"]]])); + expect((await next)?.sequence).toBe(0n); + + reader.close(); + requests.close(); + broadcast.close(); +}); + +test("fill: a sequence the track's datagram took is never asked, even once a reader read it", async () => { + const broadcast = new BroadcastProducer(); + const track = broadcast.createTrack("video"); + // Subscribed first: a datagram is not replayed to a later reader. + const reader = track.subscribe(history); + track.insertDatagram(2n, undefined, enc.encode("datagram 2")); + const group = track.createGroup(5n); + group.writeFrame({ payload: enc.encode("live 5") }); + group.finish(); + // The reader takes the datagram out of its own buffer; the track still holds it. + expect((await reader.recvDatagram())?.sequence).toBe(2n); + + const requests = track.requests(); + const ordered = reader.ordered(); + void ordered.nextGroup(); + const fills = [await requests.requestedFill(), await requests.requestedFill()]; + expect(fills.map((fill) => [fill?.start, fill?.end])).toEqual([ + [0n, 2n], + [3n, 5n], + ]); + + for (const fill of fills) fill?.close(); + reader.close(); + requests.close(); + broadcast.close(); +}); + test("fill: a reader joins a fill still served after its handler's handle closed", async () => { const { broadcast, track } = resumed(5n); const requests = track.requests(); diff --git a/js/net/src/fill.ts b/js/net/src/fill.ts index 38f0f1cc5b0..8350b652dbe 100644 --- a/js/net/src/fill.ts +++ b/js/net/src/fill.ts @@ -11,7 +11,7 @@ * @module */ import { Milli } from "@moq/clock"; -import { type GetPromise, Signal } from "@moq/signals"; +import { type GetPromise, type Getter, Signal } from "@moq/signals"; import { NotFound } from "./error.ts"; import type { Producer as GroupProducer } from "./group.ts"; import { insertRun, NO_MAX_DELAY, runGaps } from "./internal.ts"; @@ -127,6 +127,8 @@ export class FillState { #queue: Pending[] = []; readonly #queued = new Signal(0); readonly #pending = new Set(); + // Bumped as each handler opens, so readers parked on a miss nobody could take ask again. + readonly #opened = new Signal(0); constructor(track: FillTrack) { this.#track = track; @@ -217,9 +219,15 @@ export class FillState { for (const pending of this.#pending) this.#resolve(pending, start, end); } - /** Open a handler. */ + /** Bumped as each handler opens: a reader parked on a miss watches it to ask again. */ + get opened(): Getter { + return this.#opened; + } + + /** Open a handler, waking the readers parked on a miss to ask it. */ addHandler(): void { this.#handlers++; + this.#opened.update((opened) => opened + 1); } /** Close a handler. The last one leaving names every queued miss dropped, as with none open. */ diff --git a/js/net/src/track.ts b/js/net/src/track.ts index aadbda486b7..74c246c66f7 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -772,6 +772,8 @@ let goneAt: (producer: Producer, sequence: bigint) => bigint | undefined; let objectLargest: (producer: Producer) => Position | undefined; // The fills serving the producer's misses; assigned in its static block. let fillsOf: (producer: Producer) => FillState; +// The sequences of the newest datagrams the producer holds; assigned in its static block. +let heldDatagrams: (producer: Producer) => readonly bigint[]; // The sequence-order cursor lives inside `Subscriber` (it shares the group buffer and the // drift anchor with the arrival cursor), so `Ordered` reaches it through this bridge, @@ -922,6 +924,10 @@ export class Producer { #subscribed = false; // The misses its readers asked of a {@link Requests} handle. #fills: FillState; + // The sequences of the newest datagrams, as many as a reader buffers: the track's own record + // that a datagram took them, like the Rust track's datagram buffer, which a reader reading its + // copy does not empty. A fill never asks for one. + #datagramSequences: bigint[] = []; // The sequences the live feed delivered, as a group or a datagram: what a pending tail is // judged by. Eviction never touches it. A gap folds away a subscription's grace after a // later arrival opened it, as the session's tail does, so this holds only the gaps still @@ -981,6 +987,7 @@ export class Producer { hooks.reportedGroup = (producer, group) => producer.#advanceLargest({ group, frame: 0 }); objectLargest = (producer) => producer.#objectLargest; fillsOf = (producer) => producer.#fills; + heldDatagrams = (producer) => producer.#datagramSequences; cachedHolds = (producer, sequence) => { const entry = producer.#cached.get(sequence); return entry !== undefined && !(entry.group.closed.peek() instanceof Error); @@ -1691,6 +1698,8 @@ export class Producer { this.#advance(sequence, false); this.#arrive(sequence); this.#finishLargest(sequence); + if (this.#datagramSequences.length === MAX_DATAGRAMS) this.#datagramSequences.shift(); + this.#datagramSequences.push(sequence); for (const sink of this.#sinks) { sink.received.set(this.#received); const queued = slice ? Object.assign(sliceView(timestamp, slice), { sequence }) : datagram; @@ -2087,6 +2096,9 @@ export class Subscriber { // refills cannot evict each other without bound. Mirrors the Rust `Misses`. #asked: Run[] = []; #refilled: Run[] = []; + // Fill-owed runs this reader gave up once its budget convicted them: never wanted again, so + // the fills withdraw them and their handlers hear, as the Rust `Misses` gives up a stale run. + #givenUp: Run[] = []; // The last read waited on a fill, so the staleness deadline it armed wakes the next one: a // fill that never answers cannot pin a reader in either order. #fillWait = false; @@ -2337,6 +2349,7 @@ export class Subscriber { // window is never asked again, so these stay within the live span. A window moving back over a // clipped group asks it once more, as in Rust. #clipAsked(): void { + if (this.#givenUp.length > 0) this.#givenUp = this.#givenUp.flatMap((run) => this.#reads(run.start, run.end)); if (this.#asked.length > 0) this.#asked = this.#asked.flatMap((run) => this.#wants(run.start, run.end)); if (this.#refilled.length > 0) { this.#refilled = this.#refilled.flatMap((run) => this.#wants(run.start, run.end)); @@ -2522,7 +2535,7 @@ export class Subscriber { // The parts of `[start, end)` this reader still reads: inside its cursor and window, not // handed out, and not passed by the sequence cursor, which never goes back. - #wants(start: bigint, end: bigint): Run[] { + #reads(start: bigint, end: bigint): Run[] { if (this.#closed || this.#state.closed.peek() !== undefined) return []; const cursor = this.#cursor.peek(); const from = max(max(start, cursor.start), this.#nextSequence); @@ -2530,6 +2543,13 @@ export class Subscriber { return this.#window.runs(from, to).flatMap((run) => this.#delivered.gaps(run.start, run.end)); } + // What this reader still wants from a fill: what it reads, less what it gave up as stale. + #wants(start: bigint, end: bigint): Run[] { + const reads = this.#reads(start, end); + if (this.#givenUp.length === 0) return reads; + return reads.flatMap((run) => runGaps(this.#givenUp, run.start, run.end)); + } + // This reader as the producer's fills know it. #askerOf(): Asker { this.#state.asker ??= { @@ -2557,11 +2577,11 @@ export class Subscriber { const asker = this.#askerOf(); this.#clipAsked(); const timeline = this.#state.timeline; - // A datagram still buffered took its sequence, so no group is missed there; the Rust - // fetch names it `NotFetchable`. + // A datagram the track still holds took its sequence, so no group is missed there, as + // the Rust judge skips its track's datagram buffer; the Rust fetch names it + // `NotFetchable`. const gone = [...this.#state.drops.peek()]; - for (const datagram of this.#state.datagrams.peek()) - insertRun(gone, datagram.sequence, datagram.sequence + 1n); + for (const sequence of heldDatagrams(producer)) insertRun(gone, sequence, sequence + 1n); for (const run of this.#wants(start, min(end, this.#state.received.peek()))) { for (const open of runGaps(gone, run.start, run.end)) { let next = open.start; @@ -2580,14 +2600,24 @@ export class Subscriber { const asker = this.#state.asker; if (!asker) return undefined; // Every group of an owed run waits on the same successor, so its newest judges the run; - // a stale run gives way to a later one the budget still wants. + // a stale run is given up, and gives way to a later one the budget still wants. + let owed: bigint | undefined; + const stale: Run[] = []; for (const run of fills.covered(start, end, asker)) { drift ??= this.#drift(); - if (this.#staleAt(run.end - 1n, drift, true)) continue; + if (this.#staleAt(run.end - 1n, drift, true)) { + stale.push(run); + continue; + } this.#fillWait = true; - return run.start; + owed = run.start; + break; } - return undefined; + if (stale.length > 0) { + for (const run of stale) insertRun(this.#givenUp, run.start, run.end); + this.#fillsMoved(); + } + return owed; } // Ask a fill for a fetch's group at once, written yet or not, as the Rust `fetch_group` queues @@ -2598,7 +2628,7 @@ export class Subscriber { if (!producer) return false; if (this.#state.info.peek() === undefined && this.#state.closed.peek() === undefined) return "pending"; if (cachedHolds(producer, sequence)) return true; - if (this.#state.datagrams.peek().some((datagram) => datagram.sequence === sequence)) return false; + if (heldDatagrams(producer).includes(sequence)) return false; // Joins a fill already bringing it, handler or not; asks a new one only while one is open. const asked = fillsOf(producer).ask(sequence, sequence + 1n, this.#askerOf()); if (asked.length === 0) return false; @@ -3306,10 +3336,13 @@ export class Subscriber { for (const close of resumed) close(); }; } + const producer = this.#state.producer; const dispose = [ this.#state.groups.changed(fn), this.#state.drops.changed(fn), this.#fillMoves.changed(fn), + // A handler opening takes a miss nobody could ask before. + ...(producer ? [fillsOf(producer).opened.changed(fn)] : []), this.#state.startChanged.changed(fn), // A group starting may settle a time end, or move the cap it holds reads back with. ...(this.#window.settled ? [] : [this.#state.timelineChanged.changed(fn)]),