From 87605788a928b3f0f81c00df4a5d92dfc3865ef7 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:35:05 -0700 Subject: [PATCH 1/5] chore: claim resumed subscriber fork quest From caca147e0436ab9810d712e456f0b7701fb7e26f Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:38:43 -0700 Subject: [PATCH 2/5] fix(net): keep resumed subscriber forks on the logical route Co-Authored-By: GPT-6.1-Sol --- js/net/bench/resume.ts | 27 +++++++--- js/net/src/resume.test.ts | 100 ++++++++++++++++++++++++++++++++++++++ js/net/src/resume.ts | 5 +- js/net/src/track.ts | 5 +- quest/m1/README.md | 1 - quest/m1/resume-fork.md | 33 ------------- 6 files changed, 122 insertions(+), 49 deletions(-) delete mode 100644 quest/m1/resume-fork.md diff --git a/js/net/bench/resume.ts b/js/net/bench/resume.ts index e5f8da67b4c..e9a251ddd2e 100644 --- a/js/net/bench/resume.ts +++ b/js/net/bench/resume.ts @@ -1,6 +1,6 @@ /** - * Sweep readers and route swaps for groups read through a logical front, against the same - * groups read straight from the track. + * Sweep readers and route swaps for direct and forked readers through a logical front, + * against the same groups read straight from the track. * * A front reads its serving route's copy directly, so with one route it should cost about what a * direct read does, and each swap should leave nothing behind once its groups are read. @@ -38,7 +38,7 @@ function read(subscribers: Subscriber[]) { } /** Microseconds per group per reader, reading through a front after `swaps` route swaps, or directly. */ -async function measure(readers: number, swaps: number | undefined): Promise { +async function measure(readers: number, swaps: number | undefined, fork = false): Promise { let sequence = 0; const sources: { broadcast: BroadcastProducer; write: () => void }[] = []; const source = () => { @@ -68,7 +68,14 @@ async function measure(readers: number, swaps: number | undefined): Promise consumer.track("seq").subscribe()); + const track = consumer.track("seq"); + if (fork) { + const parent = track.subscribe(); + subscribers = Array.from({ length: readers }, () => parent.fork()); + parent.close(); + } else { + subscribers = Array.from({ length: readers }, () => track.subscribe()); + } for (let swap = 0; swap < swaps; swap++) { publish(); read(subscribers); @@ -96,28 +103,32 @@ async function measure(readers: number, swaps: number | undefined): Promise baseline * maxSlope) { + if (Math.max(frontUs, forkUs) > baseline * maxSlope) { throw new Error( - `${readers} readers after ${swaps} swaps cost ${frontUs.toFixed(2)} us/group, over ${maxSlope}x ${baseline.toFixed(2)}`, + `${readers} readers after ${swaps} swaps cost ${Math.max(frontUs, forkUs).toFixed(2)} us/group, over ${maxSlope}x ${baseline.toFixed(2)}`, ); } } diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 7a02492714e..de650e0eaf0 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -1,4 +1,5 @@ import { expect, test } from "bun:test"; +import { Milli } from "@moq/clock"; import { Producer as BroadcastProducer } from "./broadcast.ts"; import * as Epoch from "./epoch.ts"; import { NotFound, StreamCode, StreamError } from "./error.ts"; @@ -88,6 +89,105 @@ async function setup() { }; } +test("a fork continues its open group across a route failure after its parent closes", async () => { + const a = new BroadcastProducer(); + const b = new BroadcastProducer(); + const ta = copy(a); + const tb = copy(b); + const front = new Front(); + front.serve(a.consume()); + const parent = front.consumer.track("seq").subscribe(); + const fork = parent.fork(); + try { + const stalled = ta.write(0, 1, false); + const group = await fork.recvGroup(); + if (!group) throw new Error("expected group 0"); + expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); + parent.close(); + + const next = group.readFrame(); + tb.write(0, 3); + front.serve(b.consume()); + stalled.close(new StreamError(StreamCode.SessionClosed)); + expect(dec.decode((await next)?.payload)).toBe("0.1"); + expect(dec.decode((await group.readFrame())?.payload)).toBe("0.2"); + expect(await group.readFrame()).toBeUndefined(); + } finally { + parent.close(); + fork.close(); + front.consumer.close(); + a.close(); + b.close(); + } +}); + +test("a resumed fork has its own preferences and replay cursor", async () => { + const a = new BroadcastProducer(); + const b = new BroadcastProducer(); + const ta = copy(a); + const tb = copy(b); + const front = new Front(); + front.serve(a.consume()); + const parent = front.consumer.track("seq").subscribe({ + priority: 2, + groups: { start: { included: 1 } }, + }); + ta.write(0); + ta.write(1); + expect(drain(parent)).toEqual([1]); + const fork = parent.fork({ priority: 7, maxDelay: Milli(10_000) }); + try { + expect(drain(fork)).toEqual([0, 1]); + fork.update({ priority: 9 }); + expect(parent.subscription.peek()?.priority).toBe(2); + expect(fork.subscription.peek()?.priority).toBe(9); + const subscribed = tb.producer.subscription.changed(); + front.serve(b.consume()); + expect((await subscribed)?.priority).toBe(9); + const narrowed = tb.producer.subscription.changed(); + fork.close(); + expect((await narrowed)?.priority).toBe(2); + tb.write(2); + expect(drain(parent)).toEqual([2]); + const unused = tb.producer.demand().unused(); + parent.close(); + await unused; + } finally { + parent.close(); + fork.close(); + front.consumer.close(); + a.close(); + b.close(); + } +}); + +test("a resumed fork shares an on-demand track request", async () => { + const a = new BroadcastProducer(); + const requested = wireOf(a).requested(); + const front = new Front(); + front.serve(a.consume()); + const parent = front.consumer.track("seq").subscribe(); + const request = await requested; + if (!request) throw new Error("expected on-demand track request"); + const producer = request.accept(); + const extra = wireOf(a).requested(); + const fork = parent.fork(); + try { + producer.writeFrame({ payload: enc.encode("shared") }); + for (const subscriber of [parent, fork]) { + const group = await subscriber.recvGroup(); + expect(dec.decode((await group?.readFrame())?.payload)).toBe("shared"); + group?.close(); + } + } finally { + parent.close(); + fork.close(); + front.consumer.close(); + a.close(); + } + expect(await extra).toBeUndefined(); +}); + test("a subscription reads on across a same-epoch route swap, each group once", async () => { const { a, b, active, request, swap, close } = await setup(); const ta = copy(a); diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index 2fc0b0fc443..123561331b5 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -673,10 +673,7 @@ class Reader implements ResumeSource { } fork(options?: track.Subscription): track.Subscriber { - this.sync(); - const serving = this.#serving(); - if (!serving) throw new Error("track has no serving route to fork from"); - return serving.sub.fork(options); + return hooks.resumeSubscriber(this.route.name, options, (shell) => new Reader(this.route, shell, this.#record)); } close(): void { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 46245ad877f..8106ea1e536 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -1925,9 +1925,8 @@ export class Subscriber { * the retained window. * * Reads here do not consume anything this one would deliver, which is what lets a - * publisher read the cache alongside the cursor it is serving from. Resolving the track - * again through the broadcast would not do: a dynamic serve is one request per peer - * subscription, so that mints a second producer the application has to answer separately. + * publisher read the cache alongside the cursor it is serving from. A routed track's + * fork follows the same logical track across route swaps. * * @internal Wire layers only. */ diff --git a/quest/m1/README.md b/quest/m1/README.md index d49835a8183..84e8eb43dd8 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -107,7 +107,6 @@ lands before the cut. - [Rust resumed reads](/quest/m1/resume-ordered.md) - a Rust reader takes the lowest group across route copies in both orders, as JS does - [Resumed close](/quest/m1/resume-closed.md) - a resumed JS track keeps its declared end across copies, and its `closed` and `largest()` settle on a clean end - [Resumed in-flight groups](/quest/m1/resume-in-flight.md) - a replaced route copy stays while a group below its bound is in flight or it backs a handed-out group late, and no longer than the reader's budget -- [Resumed forks](/quest/m1/resume-fork.md) - a fork of a resumed JS subscriber follows route swaps like its parent - [Recovered group readiness](/quest/m1/resume-readable.md) - a recovered JS group's `readable()` ignores frames its replacement replays - [Resumed datagrams](/quest/m1/resume-datagrams.md) - a resumed track skips only datagrams it already delivered, not every lower sequence - [Received timestamps are media time](/quest/m1/lite-time-provenance.md) - a received timed track's timestamps are media time, so the rewind check can run across hops diff --git a/quest/m1/resume-fork.md b/quest/m1/resume-fork.md deleted file mode 100644 index 4b7c9fefb24..00000000000 --- a/quest/m1/resume-fork.md +++ /dev/null @@ -1,33 +0,0 @@ -# [S] A forked resumed subscriber follows route swaps - -## Goal - -A fork of a resumed JS track subscriber (`Track.Subscriber.fork()` on a -subscriber reading a front's route copies) is itself a logical reader. It -follows the same-epoch route swaps its parent does, so a read it has open -continues on the new route instead of ending with the old one. - -## Plan - -Found by a hosted Codex review of #5836. `ResumeSource.fork` in -`js/net/src/resume.ts` returns `serving.sub.fork(options)`, a subscriber tied -to the copy serving at fork time. The IETF draft-20 FILL path in -`js/net/src/ietf/publisher.ts` forks the track to drain cached and arriving -content. If the old route fails while the fill reads an incomplete group or -waits for an announced one, the parent recovers through the new route and the -fill ends on the old one. - -- Make a resumed `fork` open another logical reader on the same `Route`, as - `hooks.resumeSubscriber` does for the parent, with the fork's own - subscription, instead of delegating to the serving copy. -- Rust has no subscriber fork today, so nothing to mirror. Check that the IETF - FILL path in `rs/moq-net` reads through the logical track. -- Regression test: fork a resumed subscriber, swap routes while the fork reads - an open group, fail the old route, and the fork reads the rest of the group - from the new one. - -Public API: behavior only. Wire: none. - -## Related - -- [Resumed in-flight groups](/quest/m1/resume-in-flight.md) - another resume follow-up from #5836 From 540a9da0dc3de6a1e8313666336bc5ee2c6e75f9 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:52:18 -0700 Subject: [PATCH 3/5] chore(quest): retain resumed fork lifecycle follow-up Restore the original quest while finite group-only closure remains unresolved. The implementation and prior source validation remain at caca147e0. Co-Authored-By: GPT-6.1-Sol --- quest/m1/README.md | 1 + quest/m1/resume-fork.md | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) create mode 100644 quest/m1/resume-fork.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 84e8eb43dd8..d49835a8183 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -107,6 +107,7 @@ lands before the cut. - [Rust resumed reads](/quest/m1/resume-ordered.md) - a Rust reader takes the lowest group across route copies in both orders, as JS does - [Resumed close](/quest/m1/resume-closed.md) - a resumed JS track keeps its declared end across copies, and its `closed` and `largest()` settle on a clean end - [Resumed in-flight groups](/quest/m1/resume-in-flight.md) - a replaced route copy stays while a group below its bound is in flight or it backs a handed-out group late, and no longer than the reader's budget +- [Resumed forks](/quest/m1/resume-fork.md) - a fork of a resumed JS subscriber follows route swaps like its parent - [Recovered group readiness](/quest/m1/resume-readable.md) - a recovered JS group's `readable()` ignores frames its replacement replays - [Resumed datagrams](/quest/m1/resume-datagrams.md) - a resumed track skips only datagrams it already delivered, not every lower sequence - [Received timestamps are media time](/quest/m1/lite-time-provenance.md) - a received timed track's timestamps are media time, so the rewind check can run across hops diff --git a/quest/m1/resume-fork.md b/quest/m1/resume-fork.md new file mode 100644 index 00000000000..4b7c9fefb24 --- /dev/null +++ b/quest/m1/resume-fork.md @@ -0,0 +1,33 @@ +# [S] A forked resumed subscriber follows route swaps + +## Goal + +A fork of a resumed JS track subscriber (`Track.Subscriber.fork()` on a +subscriber reading a front's route copies) is itself a logical reader. It +follows the same-epoch route swaps its parent does, so a read it has open +continues on the new route instead of ending with the old one. + +## Plan + +Found by a hosted Codex review of #5836. `ResumeSource.fork` in +`js/net/src/resume.ts` returns `serving.sub.fork(options)`, a subscriber tied +to the copy serving at fork time. The IETF draft-20 FILL path in +`js/net/src/ietf/publisher.ts` forks the track to drain cached and arriving +content. If the old route fails while the fill reads an incomplete group or +waits for an announced one, the parent recovers through the new route and the +fill ends on the old one. + +- Make a resumed `fork` open another logical reader on the same `Route`, as + `hooks.resumeSubscriber` does for the parent, with the fork's own + subscription, instead of delegating to the serving copy. +- Rust has no subscriber fork today, so nothing to mirror. Check that the IETF + FILL path in `rs/moq-net` reads through the logical track. +- Regression test: fork a resumed subscriber, swap routes while the fork reads + an open group, fail the old route, and the fork reads the rest of the group + from the new one. + +Public API: behavior only. Wire: none. + +## Related + +- [Resumed in-flight groups](/quest/m1/resume-in-flight.md) - another resume follow-up from #5836 From e57cc99762f38d6a5151c2400dcf169e4ba1abf7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 22:31:16 -0700 Subject: [PATCH 4/5] fix(net): adapt the fork test to track demand and retire the fork quest The merged main replaced `Demand.unused()` with `wanted`; wait through `unwanted` instead. Restore the fork comment's reason for not resolving through the broadcast again. The fork quest is complete: the group-only closure gap it inherits is the existing `resume-closed` quest's, shared by every resumed reader. Co-Authored-By: Claude Opus 5.5 --- js/net/src/resume.test.ts | 4 ++-- js/net/src/track.ts | 6 ++++-- quest/m1/README.md | 1 - quest/m1/resume-fork.md | 33 --------------------------------- 4 files changed, 6 insertions(+), 38 deletions(-) delete mode 100644 quest/m1/resume-fork.md diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index d939a16deec..8eef82ddc4f 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -10,6 +10,7 @@ import { Producer } from "./origin.ts"; import * as Path from "./path.ts"; import { Front } from "./resume.ts"; import type * as track from "./track.ts"; +import { unwanted } from "./util/demand.ts"; import { overrideBroadcastWire, wireOf } from "./wire.ts"; const EPOCH = Epoch.parse("01900000-0000-7000-8000-000000000001"); @@ -160,9 +161,8 @@ test("a resumed fork has its own preferences and replay cursor", async () => { expect((await narrowed)?.priority).toBe(2); tb.write(2); expect(drain(parent)).toEqual([2]); - const unused = tb.producer.demand().unused(); parent.close(); - await unused; + await unwanted(tb.producer.demand()); } finally { parent.close(); fork.close(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index c0ffcea75d9..47b3eef98bc 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -2012,8 +2012,10 @@ export class Subscriber { * the retained window. * * Reads here do not consume anything this one would deliver, which is what lets a - * publisher read the cache alongside the cursor it is serving from. A routed track's - * fork follows the same logical track across route swaps. + * publisher read the cache alongside the cursor it is serving from. Resolving the track + * again through the broadcast would not do: a dynamic serve is one request per peer + * subscription, so that mints a second producer the application has to answer separately. + * A routed track's fork follows the same logical track across route swaps. * * @internal Wire layers only. */ diff --git a/quest/m1/README.md b/quest/m1/README.md index 66954fab446..0b21073e7f3 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -107,7 +107,6 @@ lands before the cut. - [Rust resumed reads](/quest/m1/resume-ordered.md) - a Rust reader takes the lowest group across route copies in both orders, as JS does - [Resumed close](/quest/m1/resume-closed.md) - a resumed JS track keeps its declared end across copies, and its `closed` and `largest()` settle on a clean end - [Resumed in-flight groups](/quest/m1/resume-in-flight.md) - a replaced route copy stays while a group below its bound is in flight or it backs a handed-out group late, and no longer than the reader's budget -- [Resumed forks](/quest/m1/resume-fork.md) - a fork of a resumed JS subscriber follows route swaps like its parent - [Recovered group readiness](/quest/m1/resume-readable.md) - a recovered JS group's `readable()` ignores frames its replacement replays - [Resumed datagrams](/quest/m1/resume-datagrams.md) - a resumed track skips only datagrams it already delivered, not every lower sequence - [Received timestamps are media time](/quest/m1/lite-time-provenance.md) - a received timed track's timestamps are media time, so the rewind check can run across hops diff --git a/quest/m1/resume-fork.md b/quest/m1/resume-fork.md deleted file mode 100644 index 4b7c9fefb24..00000000000 --- a/quest/m1/resume-fork.md +++ /dev/null @@ -1,33 +0,0 @@ -# [S] A forked resumed subscriber follows route swaps - -## Goal - -A fork of a resumed JS track subscriber (`Track.Subscriber.fork()` on a -subscriber reading a front's route copies) is itself a logical reader. It -follows the same-epoch route swaps its parent does, so a read it has open -continues on the new route instead of ending with the old one. - -## Plan - -Found by a hosted Codex review of #5836. `ResumeSource.fork` in -`js/net/src/resume.ts` returns `serving.sub.fork(options)`, a subscriber tied -to the copy serving at fork time. The IETF draft-20 FILL path in -`js/net/src/ietf/publisher.ts` forks the track to drain cached and arriving -content. If the old route fails while the fill reads an incomplete group or -waits for an announced one, the parent recovers through the new route and the -fill ends on the old one. - -- Make a resumed `fork` open another logical reader on the same `Route`, as - `hooks.resumeSubscriber` does for the parent, with the fork's own - subscription, instead of delegating to the serving copy. -- Rust has no subscriber fork today, so nothing to mirror. Check that the IETF - FILL path in `rs/moq-net` reads through the logical track. -- Regression test: fork a resumed subscriber, swap routes while the fork reads - an open group, fail the old route, and the fork reads the rest of the group - from the new one. - -Public API: behavior only. Wire: none. - -## Related - -- [Resumed in-flight groups](/quest/m1/resume-in-flight.md) - another resume follow-up from #5836 From 86efdf9ca534ba4ebe1a4bdb3d3a9227a745d01f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 22:40:37 -0700 Subject: [PATCH 5/5] fix(net): start a resumed fork on its parent's newest copy A fork made between routes or after its front concluded found no route source and ended with a dropped route, though its parent still held the copy and its retained groups. Seed the fork with a fork of the parent's newest copy at that copy's generation, then follow the route as before. Co-Authored-By: Claude Opus 5.5 --- js/net/src/resume.test.ts | 21 +++++++++++++++++++++ js/net/src/resume.ts | 33 +++++++++++++++++++++++++++++---- 2 files changed, 50 insertions(+), 4 deletions(-) diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 8eef82ddc4f..0693e5bbbe9 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -133,6 +133,27 @@ test("a fork continues its open group across a route failure after its parent cl } }); +test.each(["conclude", "park"] as const)("a fork made after the front's %s replays its parent's copy", async (end) => { + const a = new BroadcastProducer(); + const ta = copy(a); + const front = new Front(); + front.serve(a.consume()); + const parent = front.consumer.track("seq").subscribe(); + ta.write(0); + ta.write(1); + expect(drain(parent)).toEqual([1]); + front[end](); + const fork = parent.fork({ maxDelay: Milli(10_000) }); + try { + expect(drain(fork)).toEqual([0, 1]); + } finally { + parent.close(); + fork.close(); + front.consumer.close(); + a.close(); + } +}); + test("a resumed fork has its own preferences and replay cursor", async () => { const a = new BroadcastProducer(); const b = new BroadcastProducer(); diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index 9acd8ab40fb..f108886ba1b 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -265,7 +265,8 @@ class Reader implements ResumeSource { /** Records the properties a copy committed, and which source it came from. */ #record: (info: track.Info, source: Source) => void; - constructor(route: Route, shell: ResumeShell, record: (info: track.Info, source: Source) => void) { + /** `parent` is the newest copy of the reader this one forks, if any. */ + constructor(route: Route, shell: ResumeShell, record: (info: track.Info, source: Source) => void, parent?: Copy) { this.route = route; this.#shell = shell; this.#record = record; @@ -278,6 +279,19 @@ class Reader implements ResumeSource { for (const copy of this.#copies) this.#bound(copy); }), ); + // A fork starts on its parent's newest copy, at that copy's generation: the copy keeps its + // retained groups even where no route serves the track, between routes or once the front + // concluded. + if (parent) { + this.#generation = parent.generation; + this.#add({ + generation: parent.generation, + source: parent.source, + sub: parent.sub.fork(this.#wire({})), + replaced: false, + lease: 0, + }); + } // Subscribed to the serving copy at once, so groups it has now are the reader's even if // the route changes before the first read, and to each copy after. this.sync(); @@ -295,7 +309,7 @@ class Reader implements ResumeSource { // group they get meanwhile may be one the new route never has. See #observe. for (const copy of this.#copies) copy.replaced = true; const floor = this.#newest; - const copy: Copy = { + this.#add({ generation: route.generation, source, // The wire request carries the floor from the first message: some sessions read the @@ -305,7 +319,12 @@ class Reader implements ResumeSource { datagramsSeen: this.#datagram, replaced: false, lease: 0, - }; + }); + } + + /** Read `copy` as the newest one, recording the properties it commits. */ + #add(copy: Copy): void { + const { source } = copy; source.retain(); this.#bound(copy); this.#copies.push(copy); @@ -676,7 +695,13 @@ class Reader implements ResumeSource { } fork(options?: track.Subscription): track.Subscriber { - return hooks.resumeSubscriber(this.route.name, options, (shell) => new Reader(this.route, shell, this.#record)); + this.sync(); + const newest = this.#copies.at(-1); + return hooks.resumeSubscriber( + this.route.name, + options, + (shell) => new Reader(this.route, shell, this.#record, newest), + ); } close(): void {