From 6ba9dc6a1a4a2c7675ddda078e216dff6a423c80 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 22:27:37 -0700 Subject: [PATCH 1/3] chore(quest): claim quest/m1/api-audit/resolve/js-following.md Quest-Claim: b3f23fa14d5762a1 From c281f1a8f1e763a9a0b3b039d8a0a1a73608dc84 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 22:33:30 -0700 Subject: [PATCH 2/3] refactor(net)!: return Following from origin follow Co-Authored-By: GPT-6.1 Sol --- js/net/api/index.api.md | 12 ++- js/net/examples/discovery.ts | 2 +- js/net/src/connection/forward.ts | 6 +- js/net/src/origin-request.test.ts | 6 +- js/net/src/origin.ts | 80 ++++++++++++++++---- js/publish/src/audio/encoder.test.ts | 2 +- js/publish/src/video/encoder.test.ts | 2 +- js/watch/src/broadcast.ts | 9 ++- quest/m1/api-audit/resolve/README.md | 1 - quest/m1/api-audit/resolve/follow-options.md | 6 +- quest/m1/api-audit/resolve/js-following.md | 23 ------ test/interop/clients/js-native/subscribe.ts | 2 +- 12 files changed, 94 insertions(+), 57 deletions(-) delete mode 100644 quest/m1/api-audit/resolve/js-following.md diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index 841422bf7bc..0c921a88991 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -363,10 +363,16 @@ export namespace Origin { announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer; get closed(): Signals.GetPromise; get discovery(): Signals.Getter; - follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; + follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Following; request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; } export type Cost = bigint; + export class Following { + readonly active: Signals.Getter; + close(): void; + readonly closed: Signals.GetPromise; + readonly path: Path.Valid; + } export type Hop = infer; export const HopSchema: $ZodBranded, "Hop", "out">; export class Prepared { @@ -383,7 +389,7 @@ export namespace Origin { consume(): Origin.Consumer; createBroadcast(path: Path.Valid): Origin.Publication; get discovery(): Signals.Getter; - follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; + follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Following; request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; requests(prefix: Path.Valid): Origin.Requests; scope(root: Path.Valid, patterns: Path.Patterns): Origin.Producer; @@ -430,7 +436,7 @@ export namespace Origin { readonly closed: Signals.GetPromise; createBroadcast(path: Path.Valid): Origin.Publication; readonly discovery: Signals.Getter; - follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; + follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Following; request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; requests(prefix: Path.Valid): Origin.Requests; } diff --git a/js/net/examples/discovery.ts b/js/net/examples/discovery.ts index 3229f8e88e3..b361e02e7ab 100644 --- a/js/net/examples/discovery.ts +++ b/js/net/examples/discovery.ts @@ -7,7 +7,7 @@ async function main() { // Own and close the origin announcement watch. const announced = origin.announced(); - const requests = new Map(); + const requests = new Map(); // Discover broadcasts announced by the server for await (const announcement of announced) { diff --git a/js/net/src/connection/forward.ts b/js/net/src/connection/forward.ts index 0ca6982e222..5812a7b765c 100644 --- a/js/net/src/connection/forward.ts +++ b/js/net/src/connection/forward.ts @@ -109,7 +109,7 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi existing.reporters.set(interest, route); // Another request covering the prefix only holds it; the first reporter drives it. if (joined && existing.reporters.keys().next().value === interest) { - follow(existing, prefix, route, event.kind === "restart"); + updateReported(existing, prefix, route, event.kind === "restart"); } }; @@ -118,7 +118,7 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi * instance, so nothing resolved through the old one is joined again, and an in-place * update otherwise. */ - const follow = (existing: Reported, prefix: Path.Valid, route: Route, restart: boolean) => { + const updateReported = (existing: Reported, prefix: Path.Valid, route: Route, restart: boolean) => { if (restart || route.epoch !== existing.handle.route.epoch) { // Inserted before the old one leaves, so local readers see one restart rather than // an end and a start. @@ -146,7 +146,7 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi // The next request takes over driving. Without an epoch nothing proves it reports the // instance the handle serves, and the session consumes each request's announcements as // an instance of their own, so the route restarts rather than stitch two together. - follow(existing, prefix, next.value, next.value.epoch === undefined); + updateReported(existing, prefix, next.value, next.value.epoch === undefined); } }; diff --git a/js/net/src/origin-request.test.ts b/js/net/src/origin-request.test.ts index 48c05665c65..615a48c6af4 100644 --- a/js/net/src/origin-request.test.ts +++ b/js/net/src/origin-request.test.ts @@ -4,7 +4,7 @@ import * as Epoch from "./epoch"; import { StreamCode, StreamError } from "./error"; import { Route } from "./hop"; import { hooks } from "./internal.ts"; -import { Producer, type Publication, type Request } from "./origin"; +import { type Following, Producer, type Publication, type Request, type Requesting } from "./origin"; import * as Path from "./path"; import { wireOf } from "./wire"; @@ -16,7 +16,7 @@ test("a follower moves through restart, end and a later start", async () => { const firstPublication = origin.createBroadcast(path); const first = firstPublication.broadcast; firstPublication.announce(); - const request = origin.follow(path); + const request: Following = origin.follow(path); expect(request.active.peek()?.closed).toBe(first.closed); const secondPublication = origin.createBroadcast(path); const second = secondPublication.broadcast; @@ -142,7 +142,7 @@ test("only a request can use a session without discovery", async () => { const slot = wire.requests.peek()?.get(path); if (!slot) throw new Error("request did not register"); expect(wire.blind(slot)).toBe(false); - const requested = origin.request(path); + const requested: Requesting = origin.request(path); expect(wire.blind(slot)).toBe(true); // The blind answer lands in the shared slot, but only the plain handle takes it. const source = new BroadcastProducer(); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index 772b34f40a4..a52abe69ad8 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -1123,7 +1123,7 @@ export interface Table { request(path: Path.Valid, options?: RequestOptions): Requesting; /** Follow `path` across publisher instances; see {@link Consumer.follow}. */ - follow(path: Path.Valid, options?: RequestOptions): Requesting; + follow(path: Path.Valid, options?: RequestOptions): Following; /** The available broadcasts under `scope`, as a live stream; see {@link Consumer.announced}. */ announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer; @@ -1526,7 +1526,7 @@ export class Producer implements Table { } /** Follow `path` across publisher instances; see {@link Consumer.follow}. */ - follow(path: Path.Valid, options?: RequestOptions): Requesting { + follow(path: Path.Valid, options?: RequestOptions): Following { return this.#reader.follow(path, options); } @@ -1591,7 +1591,7 @@ export class Producer implements Table { // that would leak the unexported OriginState. Assigned in the class's static block. let makeConsumer: (state: OriginState, scope: Scope) => Consumer; -// Same for Requesting: a public constructor would let a caller forge a handle that no origin +// Same for Requesting and Following: a public constructor would let a caller forge a handle that no origin // ever registered, whose lifecycle guarantees are then false. `@internal` alone would not // stop it, since the declaration emit keeps the constructor. let makeRequesting: ( @@ -1601,6 +1601,13 @@ let makeRequesting: ( dispose: Dispose, ) => Requesting; +let makeFollowing: ( + path: Path.Valid, + active: Getter, + closed: Once, + dispose: Dispose, +) => Following; + let makeDynamic: ( prefix: Path.Valid, entry: RouteEntry, @@ -1617,7 +1624,7 @@ let publishPrepared: (request: Request, publication: Publication, epoch: Epoch.V let rejectPrepared: (request: Request, err: Error) => void; /** - * An owned request for a broadcast path; see {@link Consumer.request} and {@link Consumer.follow}. + * An owned request for one publisher instance at a broadcast path; see {@link Consumer.request}. * * @public */ @@ -1626,19 +1633,16 @@ export class Requesting { readonly path: Path.Valid; /** - * The current broadcast, or undefined while nothing provides the path. - * A followed path moves to each publisher instance, pinned to one when requested. - * A request retains its accepted instance. Another route of the same epoch taking over keeps + * The accepted broadcast, or undefined while the request is pending. + * Another route of the same epoch taking over keeps * this handle: its tracks resume on that route from the first group each reader lacks. * Closing this handle affects only this request. */ readonly active: Getter; /** - * Settles on refusal, origin shutdown, or explicit close. - * A request also ends when its accepted instance stops serving, and fails - * `Unroutable` while pending once discovery syncs without a route for it; - * a followed path waits for a later start, even when pinned. + * Settles on refusal, origin shutdown, explicit close, or the accepted instance ending. + * Fails `Unroutable` while pending once discovery syncs without a route for it. */ readonly closed: GetPromise; @@ -1669,6 +1673,56 @@ export class Requesting { } } +/** + * An owned follower of the publisher instances announced at a broadcast path; see {@link Consumer.follow}. + * + * @public + */ +export class Following { + /** The followed path. */ + readonly path: Path.Valid; + + /** + * The current announced broadcast, or undefined between publisher instances. + * Moves to each new instance, or waits for the pinned epoch when one was requested. + * Another route of the same epoch keeps this handle and resumes its tracks. + * Closing this handle affects only this follower. + */ + readonly active: Getter; + + /** + * Settles on refusal, origin shutdown, or explicit close. + * Waits through gaps in announcements for a later start, even when pinned to an epoch. + */ + readonly closed: GetPromise; + + #dispose: Dispose; + #disposed = false; + + private constructor( + path: Path.Valid, + active: Getter, + closed: GetPromise, + dispose: Dispose, + ) { + this.path = path; + this.active = active; + this.closed = closed; + this.#dispose = dispose; + } + + static { + makeFollowing = (path, active, closed, dispose) => new Following(path, active, closed, dispose); + } + + /** Withdraw the follower. The path stays routed for any other open request. Idempotent. */ + close(): void { + if (this.#disposed) return; + this.#disposed = true; + this.#dispose(); + } +} + /** * The read side of an origin: resolve broadcasts by path and watch what is available. * @@ -1764,7 +1818,7 @@ export class Consumer { * its path until closed. Requires discovery: a session without it never serves a follower. * A selected handler's refusal or the origin closing ends it. */ - follow(path: Path.Valid, options: RequestOptions = {}): Requesting { + follow(path: Path.Valid, options: RequestOptions = {}): Following { const epoch = options.epoch; const absolute = this.#scope.path(path); Path.Pattern.literal(path); @@ -1868,7 +1922,7 @@ export class Consumer { changed(); } - return makeRequesting(path, active, closed, () => finish(null)); + return makeFollowing(path, active, closed, () => finish(null)); } // One resolution of `path`. A follower's (`announced`) takes only an announced front and diff --git a/js/publish/src/audio/encoder.test.ts b/js/publish/src/audio/encoder.test.ts index 30b5ab7a039..d6ae8036049 100644 --- a/js/publish/src/audio/encoder.test.ts +++ b/js/publish/src/audio/encoder.test.ts @@ -792,7 +792,7 @@ test("audio failure stays local through demand changes and capture format re-arm } await feed.drain(); }; - let announced: Moq.Origin.Requesting | undefined; + let announced: Moq.Origin.Following | undefined; try { await configuring; await settle(); diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index 0ea3499c4c9..71f77cc7ef6 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -1243,7 +1243,7 @@ test("a failed video encoder disables only its rendition and recovers on a fresh let siblingSubscriber: Moq.Track.Subscriber | undefined; let catalogSubscriber: Moq.Track.Subscriber | undefined; let recovered: Moq.Track.Subscriber | undefined; - let announced: Moq.Origin.Requesting | undefined; + let announced: Moq.Origin.Following | undefined; try { await encoder.out.catalog.changed(); const net = broadcast.net.peek(); diff --git a/js/watch/src/broadcast.ts b/js/watch/src/broadcast.ts index 5f630169488..a5b982d35e8 100644 --- a/js/watch/src/broadcast.ts +++ b/js/watch/src/broadcast.ts @@ -169,7 +169,12 @@ export class Broadcast { // Requests are shared by callers; each owns its restart watch in the origin. readonly #references = new Map< Moq.Path.Valid, - { origin: Moq.Origin.Table; follow: boolean; request: Moq.Origin.Requesting; users: number } + { + origin: Moq.Origin.Table; + follow: boolean; + request: Moq.Origin.Requesting | Moq.Origin.Following; + users: number; + } >(); // The catalog as published, before renditions this consumer cannot use are dropped. Kept @@ -282,7 +287,7 @@ export class Broadcast { const name = effect.get(this.in.name); const follow = effect.get(this.in.follow); - let request: Moq.Origin.Requesting; + let request: Moq.Origin.Requesting | Moq.Origin.Following; try { request = follow ? origin.follow(name) : origin.request(name); } catch (err) { diff --git a/quest/m1/api-audit/resolve/README.md b/quest/m1/api-audit/resolve/README.md index 87d53d5d5e1..7f363780744 100644 --- a/quest/m1/api-audit/resolve/README.md +++ b/quest/m1/api-audit/resolve/README.md @@ -57,7 +57,6 @@ Wire: none. ## Required - [The player takes any read-side origin](/quest/m1/api-audit/resolve/watch-origin.md) - `@moq/watch`'s `Player` and `Broadcast` accept a read-only `Origin.Consumer` as well as a `Table` -- [JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md) - `follow` and `request` get their own JS types, matching Rust and the bindings - [JS follow takes FollowOptions](/quest/m1/api-audit/resolve/follow-options.md) - `follow` and `request` get their own JS options types ## Related diff --git a/quest/m1/api-audit/resolve/follow-options.md b/quest/m1/api-audit/resolve/follow-options.md index 6ef60260c0d..783f4ab0aa3 100644 --- a/quest/m1/api-audit/resolve/follow-options.md +++ b/quest/m1/api-audit/resolve/follow-options.md @@ -11,7 +11,7 @@ regenerated. ## Plan Planned 2026-10-31 (`/quest-plan`, maintainer), a follow-up from -[JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md), +[JS follow returns a Following](https://github.com/moq-dev/moq/pull/7476), which split the return types but kept one `RequestOptions` for both methods. Keep the shared fields' names. Drop a field from `FollowOptions` only if `follow` ignores it today, and say which in the PR. If the two @@ -20,7 +20,3 @@ point is that each method's docs describe one behavior. Public API: breaking for TypeScript type annotations that name `RequestOptions` for a `follow` call. Wire: none. - -## Required - -- [JS follow returns a Following](/quest/m1/api-audit/resolve/js-following.md) - the `Following` return type this finishes diff --git a/quest/m1/api-audit/resolve/js-following.md b/quest/m1/api-audit/resolve/js-following.md deleted file mode 100644 index 4b02b3cefbc..00000000000 --- a/quest/m1/api-audit/resolve/js-following.md +++ /dev/null @@ -1,23 +0,0 @@ -# [S] JS follow returns a Following - -## Goal - -In `@moq/net`, `Origin.Consumer.follow(path, ...)` returns its own -`Following` type, matching Rust and every binding, and `request` keeps -`Requesting`. Each type documents one meaning. js/watch's annotation -(`js/watch/src/broadcast.ts:284`) and the other callers compile against it. js/watch's cache -entry (`js/watch/src/broadcast.ts:172`) and the local at `:285` hold either -result, so they take a shared read-side type (the common `active`/`closed` -shape) or `Requesting | Following`. - -## Plan - -Found by the 2026-10-30 origin API audit -([route epic](/quest/m1/api-audit/route/README.md)). Today both methods -return `Requesting`, whose docs (`js/net/src/origin.ts:1624-1650`) describe -both behaviors. Keep the `active`/`closed` shape, and rename only where a -member means something different for `follow`. A local helper in -`js/net/src/connection/forward.ts:121` is also named `follow` but -re-receives a route; rename it so it stops reading as `Consumer.follow`. - -Public API: breaking for TypeScript type annotations only. Wire: none. diff --git a/test/interop/clients/js-native/subscribe.ts b/test/interop/clients/js-native/subscribe.ts index 2247ce38c04..39fcc73c513 100644 --- a/test/interop/clients/js-native/subscribe.ts +++ b/test/interop/clients/js-native/subscribe.ts @@ -242,7 +242,7 @@ async function run(): Promise { }; printGrant(connection.auth.grant.peek()); const unwatch = connection.auth.grant.subscribe(printGrant); - let requested: Moq.Origin.Requesting | undefined; + let requested: Moq.Origin.Following | undefined; try { if (values.finish) { console.error("finish reader ready"); From 32a8da4216d3a386665fce11c6ab9d13560ccef9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 21:37:55 -0800 Subject: [PATCH 3/3] chore(net): regenerate the API report for Reader.follow Co-Authored-By: Claude Opus 5.5 --- js/net/api/index.api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index a8f82155a6a..e009f823516 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -435,7 +435,7 @@ export namespace Origin { announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer; readonly closed: Signals.GetPromise; readonly discovery: Signals.Getter; - follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; + follow(path: Path.Valid, options?: Origin.RequestOptions): Origin.Following; request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; } export class Request {