diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 427d045f134..0b10f7e8b08 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. A connection samples the estimate from its transport only while a reservation reads it, so receive-only and lingering connections do no stats work, and the first reservation after none reads `undefined` until one fresh snapshot lands. A transport that cannot report one is never sampled and reads `undefined`: the WebSocket fallback, WebRTC, and WebTransport without `getStats()` (shipping Chromium and Safari). - **List a broadcast's tracks.** `for await (const event of broadcast.tracks())` reports each track the broadcast lists (`added`, with its `Track.Info`), one `synced`, then `added` and `removed` as tracks come and go, until the broadcast ends; leaving the loop stops listing. Over a session it needs `moq-lite-07-wip`, syncs at once with what this side holds, and the peer's tracks follow as `added`. A track served only on request is never listed. See [discovery](/concept/moq-lite#discovery). - **One track per name.** Concurrent subscriptions share one request and producer. `createTrack` on a name with a request still queued answers it. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a track that replaces it, created or requested, starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups by writing its first group with an explicit sequence. Sequences are `bigint`, so every ID the wire carries fits, past 2^53 included: `track.createGroup(5n)`, `{ absolute: 10n }`. Frame indices and relative anchors stay `number`. +- **Serve history on request.** `track.requests()` opens a handle that serves the groups readers miss: ones their ranges name below the newest group written that the cache no longer holds, or never did. Each run of misses arrives as a `Track.Fill` from `await requests.requestedFill()`, shared by every reader missing it. `accept(sequence)` it into the cache and write the group's frames as first published, `dropGroups(start, end)` what the source lacks (sequences are `bigint`), and serve `wanted()` until it is `undefined`: a reader that leaves or narrows stops wanting its groups. `close()` the fill when done; whatever is still wanted is named dropped. A `fetchGroup` of an uncached group asks the handle at once, even for a group not written yet, which a live write then answers; with no handle open it fails with `NotFound`, as in Rust, and a reader's miss is given up. A reader only asks for what its `delay.max` still wants, so a reader at the live edge never asks. This serves lite FETCH and lite-07 ranged subscriptions from the same track, as Rust's `requests()` does. - **Timing is per track, with no default.** A track that declares a `timescale` carries a `timestamp` on every frame; one without is [untimed](/concept/moq-lite#subscriptions) and its frames carry none. Omitting it means untimed, as in Rust. Nothing stamps a frame for you: the publisher passes the timestamp, and the `Timed` type (`{ value, at }`) carries one into the `@moq/json` producers. - **A subscription's `delay` is a `Track.Delay { min, max }`, as in Rust.** Staleness is `delay.max`: it counts from a group's successor, by media time and by wall clock, whichever reaches it first. `delay.min` is the target latency, carried on moq-lite 07; a peer that cannot carry it leaves it `null` (not stated). Passing the old `maxAge` or `maxDelay` key throws a `TypeError` naming `delay.max`. The publisher's own staleness bound is the separate `Track.Info.maxAge`, which caps `delay.max` and fetches. - **The cache keeps an idle group for 30 seconds.** A track evicts a group nothing has written for 30 seconds, matching the Rust cache's default expiry; a live track's newest group is exempt until a newer one arrives, unless it failed. Neither `Track.Info.maxAge` nor `delay.max` changes that window: they only decide which cached groups a reader still receives. diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index fd6dcb62248..1f88caaaaa9 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -630,6 +630,22 @@ export namespace Track { priority?: number; signal?: AbortSignal; } + export class Fill { + [Symbol.dispose](): void; + accept(sequence: bigint, info?: Partial): Group.Producer; + close(): void; + dropGroups(start: bigint, end: bigint): void; + readonly end: bigint; + isWanted(sequence: bigint): boolean; + get maxDelay(): Milli | null; + get order(): Track.Order; + get priority(): number; + refuseGroups(start: bigint, end: bigint, error: Error): void; + readonly start: bigint; + unwanted(sequence: bigint): Promise; + wanted(): bigint | undefined; + wantedChanged(): Promise; + } export interface Groups { end?: Track.Bound; start?: Track.Bound; @@ -684,6 +700,7 @@ export namespace Track { largest(): Track.Position | undefined; readonly name: string; get priority(): number; + requests(): Track.Requests; subscribe(options?: Track.Subscription): Track.Subscriber; get subscription(): Signals.Getter; writeFrame(frame: Group.Frame): void; @@ -700,6 +717,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/broadcast.test.ts b/js/net/src/broadcast.test.ts index fb79b3c930a..9522bf4f73c 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -620,9 +620,11 @@ test("close rejects a still-pending track request so its subscriber unblocks", a // A fetch parks for a group that has yet to be published, which is what the consuming wire // layer's coalescing relies on. The publisher's fill deliberately does not use this path: it // wants a group that already exists, and waiting for one that is gone would never return. -test("a fetch waits for a group still to come", async () => { +test("a fetch of a group still to come asks the request handler, and the write answers it", async () => { const broadcast = new BroadcastProducer(); const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + // As in Rust, the miss goes to the handler at once; without one it would be NotFound. + const requests = track.requests(); const pending = wireOf(broadcast).fetchGroup("video", 1n); @@ -638,6 +640,7 @@ test("a fetch waits for a group still to come", async () => { expect(group.sequence).toBe(1n); expect(await group.readString()).toBe("1"); + requests.close(); broadcast.close(); }); @@ -664,7 +667,9 @@ test("fetch maxDelay tightens the publisher's maxAge without changing omission", test("aborting a fetch rejects with the signal's reason", async () => { const broadcast = new BroadcastProducer(); - broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + // A request handler keeps the miss pending until the abort. + const requests = track.requests(); const early = new Error("early"); await expect(wireOf(broadcast).fetchGroup("video", 0n, { signal: AbortSignal.abort(early) })).rejects.toBe(early); @@ -675,6 +680,7 @@ test("aborting a fetch rejects with the signal's reason", async () => { controller.abort(late); await expect(pending).rejects.toBe(late); + requests.close(); broadcast.close(); }); diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index d56f93fe3a1..c45a2a6ba25 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,12 @@ function largest(state: BroadcastState, name: string): track.Position | undefine return producer && hooks.cachedLargest(producer); } -// Serve a group from the local retained window by subscribing and scanning to the -// requested sequence. The default for a produced broadcast; the consuming wire layer -// overrides it to fetch over the network (or to reject when the transport has no FETCH). +// Fetch one group as a one-range subscription: the cached group at once, or else one the track's +// {@link track.Requests} handler answers, asked at once whether the group was written yet or not, +// as the Rust `fetch_group` does. A group the producer writes meanwhile answers it too. With no +// handler open, a miss fails at once with `NotFound`. The default for a produced broadcast; the +// consuming wire layer overrides it to fetch over the network (or to reject when the transport has +// no FETCH). async function fetchGroup( state: BroadcastState, name: string, @@ -224,22 +227,41 @@ 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 + 1n } }], + }); hooks.fetchBudget(subscriber, options.maxDelay); try { + // Judged in this turn when the track is known, so a cached group is taken before anything + // else can change it. A track requested on demand opens its handler once accepted, so its + // miss is judged then. + let asked = hooks.askFetch(subscriber, sequence); + if (asked === "pending") { + await untilAborted(subscriber.info(), options.signal); + asked = hooks.askFetch(subscriber, sequence); + } + if (asked !== true) throw new NotFound(`group ${sequence}`); for (;;) { - const group = await untilAborted(subscriber.recvGroup(), options.signal); - if (!group) throw new NotFound(`group ${sequence}`); - if (group.sequence === sequence) { - // Close the subscription when the returned group finishes, not now: an - // in-progress group must keep receiving frames for its lifetime (mirrors - // Rust poll_fetch). Also fires if the caller closes the group early. - void group.closed.then(() => subscriber.close()); - return group; + const recv = hooks.tryRecvGroup(subscriber, true); + switch (recv.kind) { + case "group": + // Close the subscription when the returned group finishes, not now: an + // in-progress group must keep receiving frames for its lifetime (mirrors + // Rust poll_fetch). Also fires if the caller closes the group early. + void recv.group.closed.then(() => subscriber.close()); + return recv.group; + case "drop": + // A fill's refusal says why; anything else given up is just gone. + if (toStreamCode(recv.error) === StreamCode.Old) throw new NotFound(`group ${sequence}`); + throw recv.error; + case "error": + throw recv.error; + case "done": + throw new NotFound(`group ${sequence}`); } - - group.close(); - if (group.sequence > sequence) throw new NotFound(`group ${sequence}`); + await untilAborted(changed(subscriber), options.signal); } } catch (err) { subscriber.close(); @@ -247,6 +269,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.test.ts b/js/net/src/fill.test.ts new file mode 100644 index 00000000000..d1b17886121 --- /dev/null +++ b/js/net/src/fill.test.ts @@ -0,0 +1,843 @@ +import { expect, test } from "bun:test"; +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"; +import type { Consumer as GroupConsumer } from "./group.ts"; +import { hooks } from "./internal.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 + 1n); + 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: bigint): { 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: 0n } }], 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(5n); + const requests = track.requests(); + const fills = respond(requests, new Map([[2n, ["a", "b", "c"]]])); + + const group = await wireOf(broadcast).fetchGroup("video", 2n); + expect(group.sequence).toBe(2n); + expect(await frames(group)).toEqual(["a", "b", "c"]); + expect(fills.map((fill) => [fill.start, fill.end])).toEqual([[2n, 3n]]); + + // Now cached: a second fetch asks nothing. + const again = await wireOf(broadcast).fetchGroup("video", 2n); + 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(5n); + const requests = track.requests(); + respond(requests, new Map([[1n, []]])); + + const empty = await wireOf(broadcast).fetchGroup("video", 1n); + expect(await frames(empty)).toEqual([]); + await expect(wireOf(broadcast).fetchGroup("video", 3n)).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(5n); + await expect(wireOf(broadcast).fetchGroup("video", 2n)).rejects.toBeInstanceOf(NotFound); + broadcast.close(); +}); + +test("fill: without a handler, a fetch of a group not written yet fails at once, as in Rust", async () => { + const { broadcast } = resumed(5n); + await expect(wireOf(broadcast).fetchGroup("video", 9n)).rejects.toBeInstanceOf(NotFound); + broadcast.close(); +}); + +test("fill: a fetch of a group about to be written asks the handler at once, and the write answers it", async () => { + const { broadcast, track } = resumed(5n); + const requests = track.requests(); + const fetching = wireOf(broadcast).fetchGroup("video", 7n); + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + expect([fill.start, fill.end]).toEqual([7n, 8n]); + expect(fill.wanted()).toBe(7n); + + // The producer gets there before the handler answers: the live write is the answer. + const group = track.createGroup(7n); + group.writeFrame({ payload: enc.encode("written") }); + group.finish(); + expect(fill.wanted()).toBeUndefined(); + expect(await frames(await fetching)).toEqual(["written"]); + + fill.close(); + requests.close(); + broadcast.close(); +}); + +test("fill: a fetch of a group not written yet that the handler lacks fails with NotFound", async () => { + const { broadcast, track } = resumed(5n); + const requests = track.requests(); + const fills = respond(requests, new Map()); + await expect(wireOf(broadcast).fetchGroup("video", 9n)).rejects.toBeInstanceOf(NotFound); + expect(fills.map((fill) => [fill.start, fill.end])).toEqual([[9n, 10n]]); + requests.close(); + broadcast.close(); +}); + +test("fill: concurrent fetches of one group share one fill", async () => { + const { broadcast, track } = resumed(5n); + const requests = track.requests(); + const a = wireOf(broadcast).fetchGroup("video", 3n); + const b = wireOf(broadcast).fetchGroup("video", 3n); + + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + expect([fill.start, fill.end]).toEqual([3n, 4n]); + // 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([[3n, ["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(5n); + const requests = track.requests(); + const controller = new AbortController(); + const fetching = wireOf(broadcast).fetchGroup("video", 2n, { signal: controller.signal }); + + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + expect(await fill.wantedChanged()).toBe(2n); + expect(fill.isWanted(2n)).toBe(true); + + const reason = new Error("left"); + controller.abort(reason); + await expect(fetching).rejects.toBe(reason); + expect(await fill.wantedChanged()).toBeUndefined(); + expect(fill.isWanted(2n)).toBe(false); + // Nothing reads it, so closing the withdrawn fill records nothing. + fill.close(); + const later = wireOf(broadcast).fetchGroup("video", 2n); + const refill = await requests.requestedFill(); + expect(refill?.start).toBe(2n); + if (refill) serve(refill, new Map([[2n, ["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(4n); + const requests = track.requests(); + const fills = respond( + requests, + new Map([ + [0n, ["g0"]], + [1n, ["g1"]], + [3n, ["g3"]], + ]), + ); + + const reader = track.subscribe(history); + const ordered = reader.ordered(); + const seen: [bigint, 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([ + [0n, ["g0"]], + [1n, ["g1"]], + [3n, ["g3"]], + [4n, ["live 4"]], + ]); + expect(fills.map((fill) => [fill.start, fill.end])).toEqual([[0n, 4n]]); + + reader.close(); + requests.close(); + broadcast.close(); +}); + +test("fill: a bounded reader ends once its fill answers every group", async () => { + const { broadcast, track } = resumed(4n); + const requests = track.requests(); + respond(requests, new Map([[1n, ["g1"]]])); + + const reader = track.subscribe({ + ranges: [{ start: { absolute: 0n }, end: { absolute: 3n } }], + delay: { max: null }, + }); + const got: bigint[] = []; + for (let group = await reader.recvGroup(); group; group = await reader.recvGroup()) got.push(group.sequence); + expect(got).toEqual([1n]); + + requests.close(); + broadcast.close(); +}); + +test("fill: a reader at the live edge asks nothing", async () => { + const { broadcast, track } = resumed(4n); + const requests = track.requests(); + const reader = track.subscribe(); + expect((await reader.recvGroup())?.sequence).toBe(4n); + 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(5n); + const requests = track.requests(); + const a = wireOf(broadcast).fetchGroup("video", 1n); + const fill = await requests.requestedFill(); + fill?.close(); + await expect(a).rejects.toBeInstanceOf(NotFound); + + const b = wireOf(broadcast).fetchGroup("video", 3n); + 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", 2n)).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(5n); + const requests = track.requests(); + const waiting = wireOf(broadcast).fetchGroup("video", 2n); + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + const refusal = new StreamError(StreamCode.Cancel, { message: "storage busy" }); + fill.refuseGroups(2n, 3n, refusal); + fill.close(); + await expect(waiting).rejects.toBe(refusal); + + const later = wireOf(broadcast).fetchGroup("video", 2n); + const again = await requests.requestedFill(); + expect(again?.start).toBe(2n); + if (again) serve(again, new Map([[2n, ["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(5n); + 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([0n, 5n]); + 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(4n); + + 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(3n); + late.finish(); + const fetching = wireOf(broadcast).fetchGroup("video", 1n); + 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(1n); + live.writeFrame({ payload: enc.encode("live") }); + live.finish(); + expect(fill.wanted()).toBeUndefined(); + expect(() => fill.accept(1n)).toThrow(); + expect(await frames(await fetching)).toEqual(["live"]); + + fill.close(); + requests.close(); + 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: 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(); + // 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(); + 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(); + 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 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 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]); + + // 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(); + 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 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(); + 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(); + const fetching = wireOf(broadcast).fetchGroup("video", 2n); + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + expect(fill.wanted()).toBe(2n); + + // An upstream SUBSCRIBE_DROP, say: the handler is no longer asked for it. + const cut = new StreamError(StreamCode.Cancel, { message: "cut upstream" }); + hooks.dropTrackGroups(track, 2n, 3n, cut); + expect(fill.wanted()).toBeUndefined(); + await expect(fetching).rejects.toBe(cut); + + 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", 1n); + const request = await pulled; + if (!request) throw new Error("no track request"); + const track = request.accept(); + const requests = track.requests(); + const group = track.createGroup(4n); + group.finish(); + + const fill = await requests.requestedFill(); + if (!fill) throw new Error("no fill"); + serve(fill, new Map([[1n, ["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", 2n); + 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([[2n, ["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(3n); + 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 === 1n) { + fill.dropGroups(1n, 2n); + continue; + } + const group = fill.accept(sequence); + group.writeFrame({ + payload: enc.encode(`old ${sequence}`), + timestamp: Timestamp.fromMillis(Number(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(2n); + 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(1n) + .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: 0n }, end: { absolute: 4n } }], + delay: { max: null }, + order: "ascending", + }); + const got: [bigint, 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 ? -1 : a > b ? 1 : 0)); + expect(got).toEqual([ + [0n, ["old 0"]], + [2n, ["old 2"]], + [3n, ["live 3"]], + ]); + reader.close(); + } finally { + peer.close(); + } +}); diff --git a/js/net/src/fill.ts b/js/net/src/fill.ts new file mode 100644 index 00000000000..8350b652dbe --- /dev/null +++ b/js/net/src/fill.ts @@ -0,0 +1,552 @@ +/** + * 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, 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"; +import type { Info, Order } from "./track.ts"; +import { checkSequence, max, min } from "./util/sequence.ts"; + +// 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: bigint; end: bigint }; + +/** + * What the fills need from the track they serve. + * + * @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: bigint, info: Partial | undefined): GroupProducer; + /** Record `[start, end)` as never to be delivered. */ + drop(start: bigint, end: bigint, error: Error): void; + /** Whether the track still caches group `sequence`, not failed. */ + holds(sequence: bigint): 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. + * + * @internal + */ +export interface Asker { + /** The parts of `[start, end)` it still reads. */ + wants(start: bigint, end: bigint): 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: bigint, end: bigint, 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: bigint, info: Partial | undefined): GroupProducer; + drop(state: FillState, pending: Pending, start: bigint, end: bigint): void; + refuse(state: FillState, pending: Pending, start: bigint, end: bigint, 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: bigint; + readonly end: bigint; + 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. + done = false; + // Bumped on every change to what the fill owes, for its handler to wake on. + readonly revision = new Signal(0); + + constructor(start: bigint, end: bigint) { + this.start = start; + this.end = end; + } + + bump(): void { + this.revision.update((revision) => revision + 1); + } + + // 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)).flatMap((gap) => + runGaps(this.withdrawn, gap.start, gap.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. A + * producer owns one. + * + * @internal + */ +export class FillState { + readonly #track: FillTrack; + #handlers = 0; + #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; + 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(); + } + + /** 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); + if (unresolved.length === 0) continue; + if (!pending.askers.has(asker)) { + pending.askers.add(asker); + pending.bump(); + } + 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 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 gap of pending.unresolved(start, end)) { + for (const run of asker.wants(gap.start, gap.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: bigint): void { + for (const pending of this.#pending) this.#resolve(pending, sequence, sequence + 1n); + } + + /** `[start, end)` was given up, by a fill or otherwise: nobody waits for it from a fill. */ + dropped(start: bigint, end: bigint): void { + for (const pending of this.#pending) this.#resolve(pending, start, end); + } + + /** 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. */ + 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 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, closed); + } + } + + // 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; + 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; + } + this.#finish(pending); + } + + // Record `[start, end)` of `pending` answered. + #resolve(pending: Pending, start: bigint, end: bigint): 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: min(gap.end, run.start) }, + { start: 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`, for a producer's `requests()`. + * + * @internal + */ +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 = new Signal(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 closes, even while + * it waits. + */ + async requestedFill(): Promise { + const pending = await this.#state.next(this.#closed); + 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.peek()) return; + this.#closed.set(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: bigint; + /** The exclusive end group. */ + readonly end: bigint; + + #state: FillState; + #pending: Pending; + // The value `wantedChanged` last returned, or unset before it returned any. + #prev?: { wanted: bigint | 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: bigint): boolean { + checkSequence(sequence); + return this.#pending.owed(sequence, sequence + 1n).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(): bigint | 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 - 1n; + } + + /** + * {@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: bigint): Promise { + checkSequence(sequence); + 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: bigint, info?: Partial): GroupProducer { + checkSequence(sequence); + 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: bigint, end: bigint): void { + checkSequence(start); + checkSequence(end); + 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: bigint, end: bigint, error: Error): void { + checkSequence(start); + checkSequence(end); + 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/internal.ts b/js/net/src/internal.ts index 00c8e3766c1..0f503cff677 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -615,6 +615,12 @@ export const hooks: { groupChanged: (subscriber: Subscriber, fn: () => void) => Dispose; /** Apply a FETCH reader budget without inheriting SUBSCRIBE's zero default. */ fetchBudget: (subscriber: Subscriber, maxDelay: Milli | undefined) => void; + /** + * A fetch's group `sequence`, before it reads: `true` once it is cached or asked of a fill, + * written yet or not, as the Rust `fetch_group` queues one; `false` with no handler to ask; + * `"pending"` while the track awaits its accept, which opens its handler. + */ + askFetch: (subscriber: Subscriber, sequence: bigint) => boolean | "pending"; /** * Bind a group to its track's info, so a frame whose timestamp doesn't `rescale` to the track * is refused. Throws `TimestampMismatch` if a buffered frame already disagrees. @@ -855,6 +861,9 @@ export const hooks: { fetchBudget: () => { throw new Error("track.ts not loaded"); }, + askFetch: () => { + throw new Error("track.ts not loaded"); + }, writeDatagram: () => { throw new Error("track.ts not loaded"); }, diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index b1c2141c219..89ed83f74fd 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -1171,7 +1171,9 @@ export class Publisher { } finally { hold.abort(); } - // A group that has not arrived yet holds this FETCH's slot until the requester leaves. + // A group the track does not cache goes to its request handler at once, written yet + // or not, as in Rust; with none open it is NotFound. A pending answer holds this + // FETCH's slot until the requester leaves. group = await front.track(msg.track).fetchGroup(msg.group, { priority: msg.priority, maxDelay: msg.maxDelay, diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 31c098ccddc..6b23ae0951e 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -361,6 +361,9 @@ test("a fork continues its open group across a route failure after its parent cl const b = new BroadcastProducer(); const ta = copy(a); const tb = copy(b); + // A refetch from route a, should the failure land before b serves, waits on a's request + // handler rather than failing at once. + const pending = ta.producer.requests(); const front = new Front(); front.serve(a.consume()); const parent = front.consumer.track("seq").subscribe(); @@ -380,6 +383,7 @@ test("a fork continues its open group across a route failure after its parent cl expect(dec.decode((await group.readFrame())?.payload)).toBe("0.2"); expect(await group.readFrame()).toBeUndefined(); } finally { + pending.close(); parent.close(); fork.close(); front.consumer.close(); @@ -1224,6 +1228,9 @@ for (const fails of [true, false]) { const b = new BroadcastProducer(); const ta = copy(a); const tb = copy(b); + // Neither route has the rest of group 0: request handlers hold a refetch from a, should the + // failure land before b serves, and from b until b drops it. + const pending = [ta.producer.requests(), tb.producer.requests()]; const stalled = ta.write(0n, 1, false); front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe({ delay: { max: Milli(60_000) } }); @@ -1242,6 +1249,7 @@ for (const fails of [true, false]) { hooks.dropTrackGroups(tb.producer, 0n, 1n, cut); await expect(read).rejects.toBe(cut); + for (const handler of pending) handler.close(); sub.close(); front.consumer.close(); a.close(); @@ -1905,6 +1913,9 @@ test("a fetched group that fails on the route still serving waits for the next r const b = new BroadcastProducer(); const ta = copy(a); const tb = copy(b); + // Route a's request handler holds the refetch of its failed group open, as Rust's tests do + // with `requests()`: without one, a miss there is NotFound at once. + const pending = ta.producer.requests(); const failing = ta.write(5n, 1, false); front.serve(a.consume()); const group = await front.consumer.track("seq").fetchGroup(5n); @@ -1922,6 +1933,7 @@ test("a fetched group that fails on the route still serving waits for the next r expect(dec.decode((await read)?.payload)).toBe("5.1"); expect(await group.readFrame()).toBeUndefined(); + pending.close(); front.consumer.close(); a.close(); b.close(); @@ -1933,6 +1945,8 @@ test("a group handed out already failed with its route still continues on the ne const b = new BroadcastProducer(); const ta = copy(a); const tb = copy(b); + // Route a's request handler holds the refetch of its failed group open until the next route. + const pending = ta.producer.requests(); front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe(); // The old route fails group 0 before the reader takes it. @@ -1947,6 +1961,7 @@ test("a group handed out already failed with its route still continues on the ne front.serve(b.consume()); expect(dec.decode((await read)?.payload)).toBe("0.1"); + pending.close(); sub.close(); front.consumer.close(); a.close(); @@ -2128,8 +2143,8 @@ test("a fetch still out on the old route moves to the new one", async () => { const front = new Front(); const a = new BroadcastProducer(); const b = new BroadcastProducer(); - // a has the track but not group 5 yet, so its fetch waits. - a.createTrack("seq"); + // a has the track but not group 5 yet, so its fetch waits on a's request handler. + const pending = a.createTrack("seq").requests(); const tb = copy(b); tb.write(5n); front.serve(a.consume()); @@ -2139,6 +2154,7 @@ test("a fetch still out on the old route moves to the new one", async () => { const group = await fetching; expect(dec.decode((await group.readFrame())?.payload)).toBe("5.0"); + pending.close(); group.close(); front.consumer.close(); a.close(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index cac4583b0f0..74c246c66f7 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"; @@ -44,7 +45,7 @@ import { import { CACHE_EXPIRY, grace, Ledger } from "./ledger.ts"; import { rescale } from "./rescale.ts"; import { Timescale, type Timestamp } from "./time.ts"; -import { checkSequence, max, min } from "./util/sequence.ts"; +import { checkSequence, max, min, UNBOUNDED } from "./util/sequence.ts"; import { type Holdings, hasTime, @@ -61,6 +62,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. @@ -584,6 +586,13 @@ export class Consumer { } } +// The parts of sorted, disjoint `runs` inside `[start, end)`. +function intersect(runs: readonly Run[], start: bigint, end: bigint): Run[] { + return runs + .map((run) => ({ start: max(run.start, start), end: 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: bigint }[], sequence: bigint): number { let lo = 0; @@ -623,6 +632,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 @@ -759,6 +770,10 @@ let startsOf: (producer: Producer) => readonly Start[]; let goneAt: (producer: Producer, sequence: bigint) => bigint | 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 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, @@ -907,6 +922,12 @@ export class Producer { #served?: { start?: bigint | null; requested?: bigint }; // 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 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 @@ -916,6 +937,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 { @@ -954,6 +986,8 @@ 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; + heldDatagrams = (producer) => producer.#datagramSequences; cachedHolds = (producer, sequence) => { const entry = producer.#cached.get(sequence); return entry !== undefined && !(entry.group.closed.peek() instanceof Error); @@ -1029,6 +1063,8 @@ export class Producer { // once the stream's reset lands; one that finished here stays whole. #drop(start: bigint, end: bigint, error: Error, open = false): void { if (start >= end) return; + // A fill no longer owes what the track gave up. + this.#fills.dropped(start, end); for (const state of [this.#state, ...this.#sinks]) { state.drops.update((drops) => insertDrop(drops, start, end, error)); } @@ -1152,6 +1188,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. @@ -1204,6 +1256,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. @@ -1498,6 +1551,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 = max(this.#state.latest ?? 0n, group.sequence); @@ -1644,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; @@ -2035,9 +2091,25 @@ 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: bigint; 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[] = []; + // 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; + // 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 { - 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: bigint; timestamp: Timestamp } | undefined; const info = this.#state.info.peek(); @@ -2047,7 +2119,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 }; @@ -2085,6 +2157,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: bigint): boolean { + return this.#fetchBudget !== undefined || this.#window.contains(sequence); + } + // The first servable group after `sequence` below `end` that `counts`. #after( sequence: bigint, @@ -2095,7 +2173,7 @@ export class Subscriber { for (let i = timelineIndex(timeline, sequence + 1n); 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; @@ -2249,6 +2327,40 @@ 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. + 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) 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.#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)); + } + } + + // 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 @@ -2417,6 +2529,143 @@ export class Subscriber { start: max(local.start, this.#window.floor() ?? 0n), 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. + this.#fillsMoved(); + } + + // 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. + #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); + 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)); + } + + // 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 ??= { + 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 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; + const fills = fillsOf(producer); + // 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(); + this.#clipAsked(); + const timeline = this.#state.timeline; + // 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 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; + 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 + 1n; + } + this.#askMiss(next, open.end, drift, asker); + } + } + } + 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 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)) { + stale.push(run); + continue; + } + this.#fillWait = true; + owed = run.start; + break; + } + 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 + // one; a group the live feed writes meanwhile answers it. `false` with no handler to ask, or + // for a sequence a buffered datagram took; `"pending"` until the track is accepted. + #askFetch(sequence: bigint): boolean | "pending" { + const producer = this.#state.producer; + if (!producer) return false; + if (this.#state.info.peek() === undefined && this.#state.closed.peek() === undefined) return "pending"; + if (cachedHolds(producer, sequence)) return true; + 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; + insertRun(this.#asked, sequence, sequence + 1n); + 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) return undefined; + const fills = fillsOf(producer); + if (!fills.serving && !fills.active) return undefined; + const drift = this.#drift(); + 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 + // never asked, and once more what was asked but is missed again. + #askMiss(start: bigint, end: bigint, drift: Drift, asker: Asker): void { + if (start >= end || this.#staleAt(end - 1n, 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), + ), + ); + // 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)) { + for (const run of fills.ask(gap.start, gap.end, asker)) insertRun(this.#asked, run.start, run.end); + } + for (const refill of again) { + for (const run of fills.ask(refill.start, refill.end, asker)) insertRun(this.#refilled, run.start, run.end); + } } // Whether a held group waits on the local cap rising: one past it may still be read. A @@ -2458,6 +2707,8 @@ 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. + 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(); @@ -2497,8 +2748,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 max(start, subscriber.#cursor.peek().start); + if (start === "pending") return start; + const floor = start === undefined ? undefined : 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 : min(floor, filling); }; hooks.tryRecvGroup = (subscriber, dispositions) => subscriber.#tryRecvGroup(dispositions); hooks.parked = (subscriber) => { @@ -2533,11 +2789,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); @@ -2666,6 +2922,7 @@ export class Subscriber { return dispose; }; hooks.groupChanged = (subscriber, fn) => subscriber.#groupChanged(fn); + hooks.askFetch = (subscriber, sequence) => subscriber.#askFetch(sequence); hooks.fetchBudget = (subscriber, maxDelay) => { subscriber.#fetchBudget = maxDelay ?? Number.POSITIVE_INFINITY; }; @@ -2942,6 +3199,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" }); @@ -3000,6 +3258,8 @@ 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. + 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" }; @@ -3076,9 +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)]), @@ -3100,8 +3364,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(); }; @@ -3223,7 +3488,14 @@ 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. Its staleness deadline + // wakes the cursor too, so a fill that never answers cannot pin it. + if (this.#askFills(start, end, drift) === undefined) 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); this.#state.waitingOrdered = true; return true; @@ -3262,6 +3534,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); @@ -3282,6 +3555,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; @@ -3299,6 +3574,12 @@ 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. + 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" }; + } const end = this.#state.end.peek(); if (this.#exhausted()) return { kind: "done" }; if ( @@ -3414,8 +3695,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(); } } diff --git a/quest/m1/interop-coverage/js-ietf-fetch.md b/quest/m1/interop-coverage/js-ietf-fetch.md index 95c5c900d60..dcaf9307ffe 100644 --- a/quest/m1/interop-coverage/js-ietf-fetch.md +++ b/quest/m1/interop-coverage/js-ietf-fetch.md @@ -16,7 +16,7 @@ draft 18 or a fill on draft 22 fetch-stream decoder and head stitching are what a standalone FETCH reuses. Decided 2026-10-28 (maintainer): one [M] quest in m1, after -[JS ranges](/quest/m1/subscribe-ranges/js.md), which turns `fetchGroup` into +JS ranges ([moq-dev/moq#7696](https://github.com/moq-dev/moq/pull/7696)), which turns `fetchGroup` into a one-range subscription. Map a past range to a standalone FETCH, the way Rust's subscriber does. Then add the native JS runtimes as subscribers to the `run_fetch_round` cells in the tail suite. Our publishers answer only one @@ -25,7 +25,3 @@ past-range FETCH against them is refused. Test ranges against a third-party publisher, and one group against ours. Public API: none beyond JS ranges' surface. Wire: none. - -## Required - -- [JS ranges](/quest/m1/subscribe-ranges/js.md) - the one-range subscription this maps onto FETCH diff --git a/quest/m1/js-fetch-on-demand.md b/quest/m1/js-fetch-on-demand.md index cbf598357b9..ea8c6275435 100644 --- a/quest/m1/js-fetch-on-demand.md +++ b/quest/m1/js-fetch-on-demand.md @@ -5,7 +5,7 @@ A JavaScript publisher answers IETF FETCH from a native subscriber for groups that are no longer in its live cache, or never were, by dispatching onto the on-demand request surface `@moq/net` gains in -[JS ranges](/quest/m1/subscribe-ranges/js.md). +JS ranges ([moq-dev/moq#7696](https://github.com/moq-dev/moq/pull/7696)). ## Plan @@ -23,7 +23,3 @@ supported-draft matrix and `just test interop --all` through CI. Public API: none beyond JS ranges' surface. Wire: none beyond the cached half's FETCH support. - -## Required - -- [JS ranges](/quest/m1/subscribe-ranges/js.md) - the on-demand request surface this dispatches onto diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index dc7923ec187..c3900761b4f 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -82,7 +82,7 @@ The `Time(pts)` range end rides in the subscribe-ranges children already Require Decided 2026-10-27 (maintainer): of [Subscribe ranges](/quest/m1/subscribe-ranges/README.md), only the children that change the lite-07 wire gate the cut: [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md), -[JS ranges](/quest/m1/subscribe-ranges/js.md), and +JS ranges ([moq-dev/moq#7696](https://github.com/moq-dev/moq/pull/7696)), and [Lite-07 FETCH is single-group only](/quest/m1/subscribe-ranges/lite07-fetch.md). The fill path, fetch as a range, and the start bookkeeping change no wire. @@ -109,7 +109,6 @@ timestamp bound in [#6168](https://github.com/moq-dev/moq/pull/6168). - [Routes and announces](/quest/m1/cluster-routing/routes/README.md) - lite-07 carries the route layer: ROUTE per origin node and path-less ANNOUNCE, with the hop list gone - [Drop set](/quest/m1/drop-set.md) - lite-07's SUBSCRIBE_DROP carries `Max Age`, so a widening re-offers groups reported dropped - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - a relay fills a lite-07 upstream through the subscription -- [JS ranges](/quest/m1/subscribe-ranges/js.md) - JS speaks lite-07 ranges - [Lite-07 FETCH is single-group only](/quest/m1/subscribe-ranges/lite07-fetch.md) - lite-07 FETCH reads one group or a slice of one, and SUBSCRIBE ranges of whole groups - [Lite-07 by start](/quest/m1/time-addressing/lite07.md) - lite-07 carries group starts, previous-start links, GROUP_END, and time bounds instead of sequence numbers - [@moq/net by start](/quest/m1/time-addressing/js.md) - JS speaks the same lite-07 wire diff --git a/quest/m1/read-backfill.md b/quest/m1/read-backfill.md index 4611998630d..34489990830 100644 --- a/quest/m1/read-backfill.md +++ b/quest/m1/read-backfill.md @@ -59,7 +59,3 @@ SUBSCRIBE_OK, now landed, and JS ranges, not the whole Public API: no type change; the ordered read changes in Rust and JS (the floor comes from reported bounds, and JS drops backfill). Wire: none. - -## Required - -- [JS ranges](/quest/m1/subscribe-ranges/js.md) - the JS reader's requested ranges set its floor diff --git a/quest/m1/subscribe-ranges/README.md b/quest/m1/subscribe-ranges/README.md index 18c8813079b..787f43f74e3 100644 --- a/quest/m1/subscribe-ranges/README.md +++ b/quest/m1/subscribe-ranges/README.md @@ -99,7 +99,6 @@ every sequence delivered or dropped. ## Required - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - the lite-07 wire, Rust publisher and subscriber, and the draft -- [JS ranges](/quest/m1/subscribe-ranges/js.md) - `@moq/net`'s on-demand request surface and `fetchGroup` as a range - [Lite-07 FETCH is single-group only](/quest/m1/subscribe-ranges/lite07-fetch.md) - lite-07 FETCH reads one group or a slice of one, and SUBSCRIBE ranges of whole groups, in Rust, JS, and the draft - [Delete the old start bookkeeping](/quest/m1/subscribe-ranges/start-bookkeeping.md) - what each lite cursor is owed and dropped lives in the model, and `TrackRun` only translates it per version diff --git a/quest/m1/subscribe-ranges/js.md b/quest/m1/subscribe-ranges/js.md deleted file mode 100644 index abffd7eb703..00000000000 --- a/quest/m1/subscribe-ranges/js.md +++ /dev/null @@ -1,108 +0,0 @@ -# [M] JS ranges - -## Goal - -`@moq/net` matches Rust: `fetchGroup` becomes a one-range subscription or is -removed, and a JavaScript publisher serves requested ranges that are no longer -in its live cache. - -## Plan - -Landed in [moq-dev/moq#6949](https://github.com/moq-dev/moq/pull/6949): -`Subscription.ranges` of `absolute`, `relative`, and `time` anchors in place of -`groups`, a per-reader window (`js/net/src/window.ts`) with the Rust time-end -walk, the union aggregate, lite-07 SUBSCRIBE carrying the list with times in -the track's timescale (older wires the covering span, refusing other relative -and time anchors per reader), the lite-07 publisher resolving relative and -time anchors and naming each range's start in SUBSCRIBE_START, FINning a -covered bounded subscription without SUBSCRIBE_END, and the subscriber -keeping that copy and opening a fresh SUBSCRIBE on the same track once the -demand moves past what it covered. `delay: { max: null }` landed with -[moq-dev/moq#7597](https://github.com/moq-dev/moq/pull/7597). - -Reader completion, decided 2026-11-02 (maintainer, on -[moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545) and -[moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)), replacing the -2026-10-31 decision that a range-bounded reader parks: - -1. Park in both: keep the copy on a covered FIN, and leave a read that should - end to the request surface and `fetchGroup`. -2. ✅ Complete in both: a bounded read ends once every group in its ranges is - handed out, dropped, skipped as stale, or given up, and only wire - publishers park. -3. Leave it: JS copies keep releasing on a covered FIN. - -JavaScript matches Rust: a plain reader judges its own window, as the Rust -`Cursor::is_exhausted` does, and a reader following route copies judges it on -the serving copy, as the Rust `Reader::exhausted` does. Wire publishers and -route copies read through the package-internal `hooks.parked`, the Rust -`track::Subscriber::parked`. A lite-07 copy still outlives a covered FIN, so -the cache answers the same range and a widening update still delivers. - -Decided 2026-11-03 (maintainer): main moved the cursor paths under -[moq-dev/moq#6949](https://github.com/moq-dev/moq/pull/6949) -([moq-dev/moq#7486](https://github.com/moq-dev/moq/pull/7486), -[moq-dev/moq#7542](https://github.com/moq-dev/moq/pull/7542), -[moq-dev/moq#7597](https://github.com/moq-dev/moq/pull/7597), -[moq-dev/moq#7609](https://github.com/moq-dev/moq/pull/7609)), so the PR -re-ports its ranges onto them: - -1. ✅ Re-port in place, on the same PR. -2. A fresh branch, closing and deleting this one. -3. Park it. - -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. - -- **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. - -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 -violation, as `lite/subscriber.ts` `runGroup` does. Preserve the per-reader -group-bound rule for reliable reads, live-edge selection, subscription -and subscription updates. Datagrams move to their own track kind ([Datagram tracks](/quest/m1/datagram-tracks/README.md)). - -## 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/lite.md b/quest/m1/subscribe-ranges/lite.md index 63e8fc9bdb4..185f31ebc87 100644 --- a/quest/m1/subscribe-ranges/lite.md +++ b/quest/m1/subscribe-ranges/lite.md @@ -224,6 +224,17 @@ budget drops. Tests: a group still in flight on the existing subscription sends no second SUBSCRIBE, and a dropped group is recovered exactly once. +### JavaScript names the explicit end + +Moved here from JS ranges on 2026-11-03 (maintainer, on +[moq-dev/moq#7696](https://github.com/moq-dev/moq/pull/7696)), which finished +that quest: the SUBSCRIBE_FINISH JS work belongs with +[moq-dev/moq#7675](https://github.com/moq-dev/moq/pull/7675), which brought the +JS lite-07 publisher and subscriber to the explicit end. What it left: rename +SUBSCRIBE_END to SUBSCRIBE_FINISH in `js/net`, as Rust and the draft did, and +delete the JS subscriber's covered-FIN path (`#parkCovered`, `#demandCovered`, +the `short` reopen), which no lite-07 publisher triggers any more. + ### Draft and checks Update `drafts/draft-lcurley-moq-lite.md` with each wire change here, 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 diff --git a/quest/m1/time-addressing/js.md b/quest/m1/time-addressing/js.md index 29f62db8869..645cf6f6b14 100644 --- a/quest/m1/time-addressing/js.md +++ b/quest/m1/time-addressing/js.md @@ -16,8 +16,9 @@ previous-start links instead. Starts are `bigint`, as group IDs already are, so they are carried past 2^53 (decided 2026-11-03, maintainer). The spike found no sparse-ID breakage in direct `@moq/net` sessions over -lite-06 and lite-07; its relay fills follow Rust's once -[JS ranges](/quest/m1/subscribe-ranges/js.md) land. Decided 2026-10-27 +lite-06 and lite-07; its relay fills follow Rust's once JavaScript received +copies fill, which JS ranges ([moq-dev/moq#7696](https://github.com/moq-dev/moq/pull/7696)) +left as a follow-up. Decided 2026-10-27 (maintainer): this requires JS ranges, so the ranges it rekeys exist first. Public API: breaking, mirroring Rust's. Wire: as the lite-07 quest. @@ -25,4 +26,3 @@ Public API: breaking, mirroring Rust's. Wire: as the lite-07 quest. ## Required - [Lite-07 by start](/quest/m1/time-addressing/lite07.md) - the wire this speaks -- [JS ranges](/quest/m1/subscribe-ranges/js.md) - the JS range model and relay fills this moves onto starts diff --git a/quest/m2/readers-range-live.md b/quest/m2/readers-range-live.md index 93c0e0151f9..172fc8343b7 100644 --- a/quest/m2/readers-range-live.md +++ b/quest/m2/readers-range-live.md @@ -38,7 +38,3 @@ rather than a start. Each reader keeps its existing tests, plus one against a warm relay copy. Public API: none expected. Wire: none. - -## Required - -- [JS ranges](/quest/m1/subscribe-ranges/js.md) - `@moq/room` chat needs relative ranges in `@moq/net` 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 8b22484f8c1..5ff5fabae80 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,29 @@ 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 +74,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: BigInt(GROUPS), frame: 0 }); + const live = track.createGroup(BigInt(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(Number(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(Number(group.sequence)).entries()) { @@ -95,6 +121,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 +141,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 dcf80847019..ee23c7580a5 100755 --- a/test/interop/interop.sh +++ b/test/interop/interop.sh @@ -504,6 +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 + # 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" @@ -2054,12 +2056,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 @@ -2068,7 +2074,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" && @@ -2082,15 +2088,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" @@ -2436,7 +2442,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