From 9b44107f4d62244bdfb15c160f1335665e8f613c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 16:48:08 -0700 Subject: [PATCH 1/3] chore(quest): claim quest/m1/api-audit/resolve/js.md Quest-Claim: 93cf000540999544 From c41965f2558d6de8634b38c628c333a207867e35 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 16:59:23 -0700 Subject: [PATCH 2/3] refactor(js)!: follow(path) replaces request's announced option `@moq/net` names its two resolutions like Rust: `request(path, { epoch })` resolves one publisher instance and `follow(path, { epoch })` follows the path across instances. `RequestOptions.announced` is gone. Behavior is unchanged; callers across the repo move to `follow`, and the compat client detects which API the package under test has. Co-Authored-By: Claude Opus 5.5 --- bench/browser/page/transport.ts | 2 +- doc/lib/js/net.md | 4 +- doc/lib/rs/moq-net.md | 2 +- js/e2ee/src/transport.test.ts | 2 +- js/net/api/index.api.md | 4 +- js/net/bench/requests.ts | 2 +- js/net/examples/discovery.ts | 2 +- js/net/examples/wait.ts | 2 +- js/net/src/announced.test.ts | 4 +- js/net/src/connection/connect.ts | 2 +- js/net/src/connection/forward.test.ts | 20 ++-- js/net/src/connection/migrate.test.ts | 6 +- js/net/src/connection/reload.test.ts | 4 +- js/net/src/integration.test.ts | 24 ++--- js/net/src/origin-request.test.ts | 111 +++++++++++++------- js/net/src/origin.test.ts | 6 +- js/net/src/origin.ts | 74 +++++++------ js/publish/src/announce.test.ts | 4 +- js/publish/src/audio/encoder.test.ts | 2 +- js/publish/src/broadcast.test.ts | 4 +- js/publish/src/video/encoder.test.ts | 2 +- js/watch/src/broadcast.test.ts | 8 +- js/watch/src/broadcast.ts | 6 +- quest/m1/api-audit/resolve/README.md | 1 - quest/m1/api-audit/resolve/callers.md | 1 - quest/m1/api-audit/resolve/js.md | 25 ----- quest/m2/release/runner-client-bump.md | 2 +- test/drain/drain.ts | 2 +- test/interop/clients/js-native/finish.ts | 4 +- test/interop/clients/js-native/goaway.ts | 2 +- test/interop/clients/js-native/subscribe.ts | 2 +- test/interop/clients/js-native/tail.ts | 2 +- test/interop/compat/client.ts | 8 +- test/wasm/baseline/consumer.ts | 2 +- 34 files changed, 188 insertions(+), 160 deletions(-) delete mode 100644 quest/m1/api-audit/resolve/js.md diff --git a/bench/browser/page/transport.ts b/bench/browser/page/transport.ts index 4c56c1e28d8..0c408caf1e1 100644 --- a/bench/browser/page/transport.ts +++ b/bench/browser/page/transport.ts @@ -73,7 +73,7 @@ async function prepare(config: Transport): Promise { websocket: { enabled: false }, }); if (connection.transport !== "webtransport") throw new Error(`consumer negotiated ${connection.transport}`); - const request = origin.request(Moq.Path.from(config.path), { announced: true }); + const request = origin.follow(Moq.Path.from(config.path)); cleanup.push(() => { request.close(); connection.abort(); diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index f1e564df1fa..61e136ac3ff 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -42,8 +42,8 @@ publication.announce(); - **Answer claimed paths with `using`.** `requests(prefix)` claims a prefix and yields each requested path. Use `using prepared = request.prepare(epoch)`, fill its broadcast, then `prepared.publish()` to answer with a new publisher instance and keep the `Publication` it returns. Leaving the scope without publishing, including on a throw, refuses the request as unroutable. Explicit `prepared.close()` or closing its unpublished broadcast does the same; disposal after publishing leaves the returned publication and its fill broadcast live. Reject before preparing with `request.reject(err)`. A retained, unclosed prepared answer keeps the request pending; JavaScript garbage collection provides no prompt cleanup guarantee. - **End content by finishing tracks.** A broadcast has no finished state. When the input ends, `finish()` each track, then `close()` it; closing a track without finishing aborts it. The broadcast stays announced and keeps serving them until you `close()` it. How long to keep it up for late readers is yours to decide. - **Requests can pin an epoch.** `consumer.request(path, { epoch })` resolves only through a route announcing that [publisher epoch](/concept/moq-lite#publisher-epochs). The resolved broadcast's `epoch` names the route it came through, pinned or not. -- **Follow restarts.** `origin.request(path, { announced: true })` follows whichever publisher instance serves the path: its `active` changes to a fresh broadcast on a restart, clears on an end, and resolves again on the next start, so read it reactively and close the request when done. Instances are never stitched, so subscribe again to each new broadcast. Another route of the same epoch taking over (epochs travel only on `moq-lite-07-wip`) keeps `active` as is, and each track subscription resumes there from the first group it lacks. A refusal ends the request. Add `epoch` to pin one instance, which the request waits for again after an end. A plain `request(path)` keeps its accepted instance and ends once that instance stops serving; while pending, it fails `Unroutable` once discovery of its path has synced without a route for it. To list what is live, iterate `announced(scope)`. -- **Discovery follows what you watch.** A `consume` origin asks the relay for announcements only under the prefixes its readers watch with `announced(scope)` or `request(path)`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. Every request watches its path from creation until closed, so it outlives the listing that found it. A relay that refuses an announce request downgrades that session: plain requests subscribe blind through it, and announced requests keep waiting for a session that can discover. +- **Follow restarts.** `origin.follow(path)` follows whichever publisher instance serves the path: its `active` changes to a fresh broadcast on a restart, clears on an end, and resolves again on the next start, so read it reactively and close it when done. Instances are never stitched, so subscribe again to each new broadcast. Another route of the same epoch taking over (epochs travel only on `moq-lite-07-wip`) keeps `active` as is, and each track subscription resumes there from the first group it lacks. A refusal ends it. Pass `{ epoch }` to pin one instance, which it waits for again after an end. `request(path)` instead keeps its accepted instance and ends once that instance stops serving; while pending, it fails `Unroutable` once discovery of its path has synced without a route for it. To list what is live, iterate `announced(scope)`. +- **Discovery follows what you watch.** A `consume` origin asks the relay for announcements only under the prefixes its readers watch with `announced(scope)`, `request(path)`, or `follow(path)`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. Every request and follower watches its path from creation until closed, so it outlives the listing that found it. A relay that refuses an announce request downgrades that session: requests subscribe blind through it, and followers keep waiting for a session that can discover. - **Connections share by URL and versions.** `new Connection({ url })` pools and reconnects with backoff, which the elements use. An ordered `versions` list, spelled like `moq-lite-06` as in Rust, applies to both WebTransport and WebSocket; equivalent lists share, while a different order or an omitted list gets its own pool entry. Supplying your own transport options or origin selects a private loop. Receive estimates are on demand: observe `connection.probe` reactively or subscribe while you need them; `peek()` alone opens no PROBE stream. - **GOAWAY moves the session.** The connection dials the replacement at once while the old session keeps serving its groups, up to `goaway.handover` (default 10s, or the relay's deadline when that is sooner). New requests keep opening on the old session until the replacement's route outranks it, which is a restart without an epoch: an unpinned announced request follows the replacement, while a blind or epoch-pinned request stays on its accepted instance. With an epoch, which travels only when `moq-lite-07-wip` is offered, the replacement serves the same broadcast, so open subscriptions move across without missing a group. An empty GOAWAY redials the same URL. A redirect stays on the same host unless `goaway.redirect` is `"follow"`, which also presents the tokens on the connection's `auth` handle to the new host. - **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. diff --git a/doc/lib/rs/moq-net.md b/doc/lib/rs/moq-net.md index f7022eb7b4e..2a3ed97631f 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -18,7 +18,7 @@ What you use it for, beyond what the concept page already describes: - **An origin outlives the session.** Creating a broadcast returns an origin publication that controls its announcement and exposes the broadcast to fill. Standalone and Prepared fill producers cannot announce; only publishing the Prepared answer admits its publication. A reconnect announces existing publications again, and closing the session does not delete them. - **Requests can pin an epoch.** `consumer.request_broadcast(path, Some(epoch))` resolves only through a route announcing that [publisher epoch](/concept/moq-lite#publisher-epochs); `None` takes whichever route wins. The resolved consumer names its epoch in `info().epoch`, pinned or not. - **Rank several CDNs.** Dial each with its own subscribe handle, `origin.clone().with_preference(origin::Preference::new(rank))` (higher wins; 0 is neutral and a negative rank demotes), all on one origin. Requests use the preferred link that has a route and fail over to the next; see [multiple CDNs](/concept/moq-lite#multiple-cdns). -- **Follow restarts.** `consumer.announced_broadcast(path, None)` hands out each publisher instance serving a path from `available()`: the first once announced, then each one that takes over or returns after an end, like JS `request(path, { announced: true })`. A broadcast already resolved stays on the old instance until dropped or its route goes. `consumer.follow(path)` yields the underlying start, update, restart, and end of the route a request resolves. +- **Follow restarts.** `consumer.announced_broadcast(path, None)` hands out each publisher instance serving a path from `available()`: the first once announced, then each one that takes over or returns after an end, like JS `follow(path)`. A broadcast already resolved stays on the old instance until dropped or its route goes. `consumer.follow(path)` yields the underlying start, update, restart, and end of the route a request resolves. - **Discovery follows what you watch.** A client session asks the relay for announcements only under the prefixes its subscribe origin's readers watch, with `announced()`, `routed_broadcast`, or `announced_broadcast`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A broadcast resolved through a discovered route keeps its path watched until dropped. `request_broadcast` owns discovery of its path and reports absence only once discovery has synced; no separate watch is needed. A server session, or a client fed into an origin handle marked `with_link(origin::Link::Peer)` or `Link::Upstream`, asks for everything it may, so a relay discovers everything. An HTTP gateway (the moq-hls `Server`, the moq-rtc WHEP router) watches its whole scope while it lives, so the paths its callers name never open a request each. moq-lite-03/04 sessions, whose announcements mark no initial set, still ask for everything. - **One track per name.** Concurrent subscriptions share one request and producer. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a producer that replaces it starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups with `create_group` at an explicit sequence. Readers of an aborted track resume onto the replacement only when the broadcast announces an epoch; otherwise their subscription ends with the error. - **End content by finishing tracks.** A broadcast has no finished state. When the input ends, finish each track; the broadcast stays announced and keeps serving them until you close it or drop its last producer. How long to keep it up for late readers is yours to decide: `moq_mux::Linger` holds a hang broadcast for a fixed window. diff --git a/js/e2ee/src/transport.test.ts b/js/e2ee/src/transport.test.ts index 0dad9d490d0..6731284b1c0 100644 --- a/js/e2ee/src/transport.test.ts +++ b/js/e2ee/src/transport.test.ts @@ -39,7 +39,7 @@ async function session(protocol: string) { } async function active(origin: Origin.Producer, path: Path.Valid): Promise { - const request = origin.request(path, { announced: true }); + const request = origin.follow(path); for (;;) { const front = request.active.peek(); if (front) return front; diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index b6b296c3992..d4986d25a6f 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -362,6 +362,7 @@ 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; request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; } export type Cost = bigint; @@ -381,6 +382,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; request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; requests(prefix: Path.Valid): Origin.Requests; scope(root: Path.Valid, patterns: Path.Patterns): Origin.Producer; @@ -402,7 +404,6 @@ export namespace Origin { reject(err: Error): void; } export interface RequestOptions { - announced?: boolean; epoch?: Epoch.Valid; } export class Requesting { @@ -428,6 +429,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; request(path: Path.Valid, options?: Origin.RequestOptions): Origin.Requesting; requests(prefix: Path.Valid): Origin.Requests; } diff --git a/js/net/bench/requests.ts b/js/net/bench/requests.ts index 4f519d0deb5..937a747f7dd 100644 --- a/js/net/bench/requests.ts +++ b/js/net/bench/requests.ts @@ -34,7 +34,7 @@ for (const touched of ["watched", "unrelated"]) broadcastPublication.announce(); return broadcast; }); - const requests = Array.from({ length: followers }, () => origin.request(path, { announced: true })); + const requests = Array.from({ length: followers }, () => origin.follow(path)); await settle(); let current = broadcasts[0]; let unrelated: (typeof broadcasts)[number] | undefined; diff --git a/js/net/examples/discovery.ts b/js/net/examples/discovery.ts index da00d189ba8..3229f8e88e3 100644 --- a/js/net/examples/discovery.ts +++ b/js/net/examples/discovery.ts @@ -15,7 +15,7 @@ async function main() { console.log("New stream available:", announcement.prefix); // One request per path follows its publisher restarts until closed. - const request = origin.request(announcement.prefix, { announced: true }); + const request = origin.follow(announcement.prefix); request.active.subscribe((broadcast) => console.log(request.path, broadcast ? "live" : "offline")); requests.set(announcement.prefix, request); } diff --git a/js/net/examples/wait.ts b/js/net/examples/wait.ts index ca3eabcb207..977c21bed86 100644 --- a/js/net/examples/wait.ts +++ b/js/net/examples/wait.ts @@ -10,7 +10,7 @@ async function main() { // Wait for a broadcast that may not exist yet. a plain `request` would subscribe blind and get reset // if nobody is publishing the path; this waits for the announcement instead. - const broadcast = origin.request(Moq.Path.from("my-broadcast"), { announced: true }); + const broadcast = origin.follow(Moq.Path.from("my-broadcast")); const effect = new Effect(); effect.run((effect) => { diff --git a/js/net/src/announced.test.ts b/js/net/src/announced.test.ts index df01e31868e..d5c0cd7091c 100644 --- a/js/net/src/announced.test.ts +++ b/js/net/src/announced.test.ts @@ -111,7 +111,7 @@ test("an origin handle resolves a local publish with no session attached", async const origin = new OriginProducer(); const path = p("loopback"); - const watch = origin.request(path, { announced: true }); + const watch = origin.follow(path); await settle(); expect(watch.active.peek()).toBeUndefined(); @@ -149,7 +149,7 @@ test("the local route wins over a blind request on a no-discovery origin", async const detach = wireOf(origin).attach(false); const broadcast = publish(origin, path); - const watch = origin.request(path, { announced: true }); + const watch = origin.follow(path); await settle(); expect(watch.active.peek()).toBeDefined(); diff --git a/js/net/src/connection/connect.ts b/js/net/src/connection/connect.ts index 62dba052534..1ac53d96214 100644 --- a/js/net/src/connection/connect.ts +++ b/js/net/src/connection/connect.ts @@ -208,7 +208,7 @@ export interface ConnectProps { * nothing. * * What the peer announces under the prefixes the origin's readers watch - * (`announced(scope)` or `request(path, { announced: true })`) appears in its table for + * (`announced(scope)`, `request(path)`, or `follow(path)`) appears in its table for * the session's lifetime, consumable by path; nothing is asked until something watches, * and the entries retract when the session dies. Pass the producer behind * {@link ConnectProps.publish} to route both directions through one origin: a locally diff --git a/js/net/src/connection/forward.test.ts b/js/net/src/connection/forward.test.ts index 74f49a6c8be..58e39cdc479 100644 --- a/js/net/src/connection/forward.test.ts +++ b/js/net/src/connection/forward.test.ts @@ -124,7 +124,7 @@ function record(stream: Announce.Consumer): string[] { return events; } -test("a plain request discovers an unwatched path and waits for its initial set", async () => { +test("a request discovers an unwatched path and waits for its initial set", async () => { const origin = new OriginProducer(); const session = new FakeSession(); forwardAnnounced(session.session, origin); @@ -209,17 +209,17 @@ test("a watch change reports only its prefix and the watches it covers", () => { const unlisten = wireOf(origin).interests((prefix, wanted) => events.push(`${wanted ? "+" : "-"}${prefix}`)); const state = origin.consume(); - const ab = state.request(Path.from("a/b"), { announced: true }); - const ac = state.request(Path.from("a/c"), { announced: true }); - const x = state.request(Path.from("x"), { announced: true }); + const ab = state.follow(Path.from("a/b")); + const ac = state.follow(Path.from("a/c")); + const x = state.follow(Path.from("x")); expect(events.splice(0)).toEqual(["+a/b", "+a/c", "+x"]); // The broader watch opens first, then releases the ones it now covers; unrelated `x` is untouched. - const a = state.request(Path.from("a"), { announced: true }); + const a = state.follow(Path.from("a")); expect(events.splice(0)).toEqual(["+a", "-a/b", "-a/c"]); // A watch beneath a covered prefix changes nothing. - const abd = state.request(Path.from("a/b/d"), { announced: true }); + const abd = state.follow(Path.from("a/b/d")); abd.close(); expect(events.splice(0)).toEqual([]); @@ -237,12 +237,12 @@ test("a watch change reports only its prefix and the watches it covers", () => { origin.close(); }); -test("an announced request is a watch on its path", async () => { +test("a follower is a watch on its path", async () => { const origin = new OriginProducer(); const session = new FakeSession(); forwardAnnounced(session.session, origin); - const request = origin.request(Path.from("room/alice"), { announced: true }); + const request = origin.follow(Path.from("room/alice")); await settle(); expect(session.open()).toEqual(["room/alice/**"]); // Gated on the announcement, so nothing answers it blind meanwhile. @@ -461,7 +461,7 @@ test("a refused announce request downgrades the session once, and later watches const path = Path.from("room"); forwardAnnounced(session.session, origin); - const watched = origin.request(path, { announced: true }); + const watched = origin.follow(path); await settle(); expect(origin.discovery.peek()).toBe(true); expect(watched.active.peek()).toBeUndefined(); @@ -495,7 +495,7 @@ test("a discovery failure under a live session retracts what it fed and answers const path = Path.from("room"); forwardAnnounced(session.session, origin); - const watched = origin.request(path, { announced: true }); + const watched = origin.follow(path); await settle(); start(session.stream("room/**"), "room"); await settle(); diff --git a/js/net/src/connection/migrate.test.ts b/js/net/src/connection/migrate.test.ts index 9dcd75e1064..59162933992 100644 --- a/js/net/src/connection/migrate.test.ts +++ b/js/net/src/connection/migrate.test.ts @@ -76,7 +76,7 @@ const url = new URL("https://relay.example/room"); // Short enough to watch, long enough that a handover visibly overlaps the replacement. const handover = Milli(200); -test("an empty GOAWAY migrates the announced request to the replacement session", async () => { +test("an empty GOAWAY migrates the follower to the replacement session", async () => { const clock = new Manual(); const installed = clock.install(); const { dials, origin } = fleet(); @@ -93,7 +93,7 @@ test("an empty GOAWAY migrates the announced request to the replacement session" // A session younger than this counts as redirected immediately and backs off first. delay: { initial: Milli(1) }, }); - const watched = consume.request(Path.from("cam"), { announced: true }); + const watched = consume.follow(Path.from("cam")); try { await waitUntil(() => watched.active.peek() !== undefined); @@ -113,7 +113,7 @@ test("an empty GOAWAY migrates the announced request to the replacement session" expect(reload.status.peek()).toBe("connected"); // Without an epoch the replacement route is a new publisher instance. - // The announced request follows it while the old session finishes draining. + // The follower follows it while the old session finishes draining. await elapse(clock, () => watched.active.peek() !== undefined && watched.active.peek() !== served); expect(watched.closed.peek()).toBeUndefined(); await elapse(clock, () => drained.closed); diff --git a/js/net/src/connection/reload.test.ts b/js/net/src/connection/reload.test.ts index 6cca856ef05..e4a27ed3f9d 100644 --- a/js/net/src/connection/reload.test.ts +++ b/js/net/src/connection/reload.test.ts @@ -206,7 +206,7 @@ async function waitUntil(pred: () => boolean): Promise { throw new Error("timed out waiting for condition"); } -test("an announced request follows the reconnect on the same handle", async () => { +test("a follower follows the reconnect on the same handle", async () => { const original = globalThis.WebTransport; const url = new URL("https://example.com/"); @@ -233,7 +233,7 @@ test("an announced request follows the reconnect on the same handle", async () = delay: { initial: Milli(10), multiplier: 1, max: Milli(10) }, consume: clientOrigin, }); - const watched = clientOrigin.request(Path.from("late"), { announced: true }); + const watched = clientOrigin.follow(Path.from("late")); try { await waitUntil(() => watched.active.peek() !== undefined); diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 1217fd0d295..4dbdb494cd3 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -1692,7 +1692,7 @@ async function waitFor(signal: Getter, pred: (value: T) => boolean): Promi } } -test("integration: an announced request waits for a late publisher", async () => { +test("integration: a follower waits for a late publisher", async () => { const pair = createMockTransportPair(Lite.ALPN_06); const origin = new OriginProducer(); const clientOrigin = new OriginProducer(); @@ -1712,7 +1712,7 @@ test("integration: an announced request waits for a late publisher", async () => // Nobody publishes this path yet. A blind consume would be reset (see the // "subscribe to non-existent broadcast" test); the handle just stays offline. - const watched = clientOrigin.request(Path.from("late"), { announced: true }); + const watched = clientOrigin.follow(Path.from("late")); await sleep(50); expect(watched.active.peek()).toBeUndefined(); @@ -1751,7 +1751,7 @@ test("integration: an announced request waits for a late publisher", async () => clientOrigin.close(); }); -test("integration: only a plain request consumes blind without discovery", async () => { +test("integration: only a request consumes blind without discovery", async () => { withoutDiscovery(); const pair = createMockTransportPair(Lite.ALPN_06); const origin = new OriginProducer(); @@ -1770,7 +1770,7 @@ test("integration: only a plain request consumes blind without discovery", async } })(); - const followed = clientOrigin.request(Path.from("test"), { announced: true }); + const followed = clientOrigin.follow(Path.from("test")); await until(() => clientOrigin.discovery.peek() === false); expect(followed.active.peek()).toBeUndefined(); const watched = clientOrigin.request(Path.from("test")); @@ -1807,7 +1807,7 @@ test("integration: a republish is not served from the previous generation's cach const first = publish(origin, Path.from("shared")); const servingFirst = serve(first, "old"); - const watched = clientOrigin.request(Path.from("shared"), { announced: true }); + const watched = clientOrigin.follow(Path.from("shared")); const active = await waitFor(watched.active, (b) => b !== undefined); if (!active) throw new Error("expected an active broadcast"); expect(await active.track("video").subscribe().ordered().readString()).toBe("old"); @@ -1827,7 +1827,7 @@ test("integration: a republish is not served from the previous generation's cach const second = publish(origin, Path.from("shared")); const servingSecond = serve(second, "new"); - const again = clientOrigin.request(Path.from("shared"), { announced: true }); + const again = clientOrigin.follow(Path.from("shared")); const republished = await waitFor(again.active, (b) => b !== undefined); if (!republished) throw new Error("expected a republished broadcast"); expect(await republished.track("video").subscribe().ordered().readString()).toBe("new"); @@ -1862,7 +1862,7 @@ async function runRepublishCycle(protocol: string) { } }; - const watched = clientOrigin.request(Path.from("toggle"), { announced: true }); + const watched = clientOrigin.follow(Path.from("toggle")); let previous: BroadcastConsumer | undefined; for (let generation = 0; generation < 3; generation++) { const payload = `gen${generation}`; @@ -2174,7 +2174,7 @@ test("origin: one origin on both directions consumes locally and never echoes", serverSees.close(); }); -test("origin: a plain request discovers the peer cannot announce before resolving blind", async () => { +test("origin: a request discovers the peer cannot announce before resolving blind", async () => { const refused = withoutDiscovery(); const pair = createMockTransportPair(Lite.ALPN_05); const serverOrigin = new OriginProducer(); @@ -2278,8 +2278,8 @@ test.each([Lite.ALPN_05, Lite.ALPN_06, Lite.ALPN_07_WIP])( ); for (const alpn of [Lite.ALPN_06, Lite.ALPN_07_WIP]) { - for (const announced of [false, true]) { - test(`${alpn}: a request outlives the listing it resolved through (announced: ${announced})`, async () => { + for (const method of ["request", "follow"] as const) { + test(`${alpn}: a ${method} outlives the listing it resolved through`, async () => { const run = LitePublisher.prototype.runAnnounce; let started = 0; let ended = 0; @@ -2312,7 +2312,7 @@ for (const alpn of [Lite.ALPN_06, Lite.ALPN_07_WIP]) { const reader = clientOrigin.consume(); const listing = reader.announced(Path.Pattern.subtree(Path.from("room"))); expect((await listing.next())?.kind).toBe("start"); - const request = reader.request(Path.from("room/cam"), { announced }); + const request = reader[method](Path.from("room/cam")); await until(() => request.active.peek() !== undefined); const front = request.active.peek(); @@ -2437,7 +2437,7 @@ test("origin: a reactive handle follows announcements across a republish", async accept(pair.server, url, { publish: serverOrigin.consume() }), ]); - const watch = clientOrigin.request(Path.from("show"), { announced: true }); + const watch = clientOrigin.follow(Path.from("show")); // Nothing published yet: the handle waits instead of subscribing blind. for (let i = 0; i < 5; i++) await sleep(1); diff --git a/js/net/src/origin-request.test.ts b/js/net/src/origin-request.test.ts index a3cd00c2e19..48c05665c65 100644 --- a/js/net/src/origin-request.test.ts +++ b/js/net/src/origin-request.test.ts @@ -10,13 +10,13 @@ import { wireOf } from "./wire"; const settle = () => new Promise((resolve) => setImmediate(resolve)); -test("an announced request follows restart, end and a later start", async () => { +test("a follower moves through restart, end and a later start", async () => { const origin = new Producer(); const path = Path.from("room/audio"); const firstPublication = origin.createBroadcast(path); const first = firstPublication.broadcast; firstPublication.announce(); - const request = origin.request(path, { announced: true }); + const request = origin.follow(path); expect(request.active.peek()?.closed).toBe(first.closed); const secondPublication = origin.createBroadcast(path); const second = secondPublication.broadcast; @@ -38,14 +38,14 @@ test("an announced request follows restart, end and a later start", async () => origin.close(); }); -test("an epoch-pinned announced request refuses another instance", async () => { +test("an epoch-pinned follower refuses another instance", async () => { const origin = new Producer(); const path = Path.from("room/audio"); const epoch = Epoch.mint(); const firstPublication = origin.createBroadcast(path); const first = firstPublication.broadcast; firstPublication.announce({ epoch }); - const request = origin.request(path, { announced: true, epoch }); + const request = origin.follow(path, { epoch }); const secondPublication = origin.createBroadcast(path); const second = secondPublication.broadcast; secondPublication.announce({ epoch: Epoch.mint() }); @@ -57,14 +57,14 @@ test("an epoch-pinned announced request refuses another instance", async () => { origin.close(); }); -test("an announced request changes its handle on an in-place epoch restart", async () => { +test("a follower changes its handle on an in-place epoch restart", async () => { const origin = new Producer(); const path = Path.from("room/audio"); const broadcastPublication = origin.createBroadcast(path); const broadcast = broadcastPublication.broadcast; const before = Epoch.mint(); broadcastPublication.announce({ epoch: before }); - const request = origin.request(path, { announced: true }); + const request = origin.follow(path); const old = request.active.peek(); const after = Epoch.mint(); broadcastPublication.announce({ epoch: after }); @@ -76,10 +76,10 @@ test("an announced request changes its handle on an in-place epoch restart", asy origin.close(); }); -test("a closed announced request never acquires another publisher", async () => { +test("a closed follower never acquires another publisher", async () => { const origin = new Producer(); const path = Path.from("room/audio"); - const request = origin.request(path, { announced: true }); + const request = origin.follow(path); request.close(); const broadcastPublication = origin.createBroadcast(path); const broadcast = broadcastPublication.broadcast; @@ -91,21 +91,21 @@ test("a closed announced request never acquires another publisher", async () => origin.close(); }); -test.each([false, true])( - "requests refuse unwatchable paths and scope violations before registering (announced: %s)", - (announced) => { +test.each(["request", "follow"] as const)( + "%s refuses unwatchable paths and scope violations before registering", + (method) => { const origin = new Producer(); - expect(() => origin.request(Path.from("camera*main"), { announced })).toThrow(); + expect(() => origin[method](Path.from("camera*main"))).toThrow(); const scoped = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.subtree(Path.from("pool/job/cam"))])); - expect(() => scoped.request(Path.from("pool/job"), { announced })).toThrow(); + expect(() => scoped[method](Path.from("pool/job"))).toThrow(); expect(wireOf(origin).requests.peek()?.size).toBe(0); origin.close(); }, ); -test("unrelated routes never notify announced request followers", async () => { +test("unrelated routes never notify followers", async () => { const origin = new Producer(); - const requests = Array.from({ length: 32 }, (_, i) => origin.request(Path.from(`room/${i}`), { announced: true })); + const requests = Array.from({ length: 32 }, (_, i) => origin.follow(Path.from(`room/${i}`))); await settle(); let changes = 0; const stops = requests.map((request) => request.active.subscribe(() => changes++)); @@ -123,9 +123,9 @@ test("unrelated routes never notify announced request followers", async () => { origin.close(); }); -test("an origin closing settles pending announced requests", async () => { +test("an origin closing settles pending followers", async () => { const origin = new Producer(); - const request = origin.request(Path.from("absent"), { announced: true }); + const request = origin.follow(Path.from("absent")); origin.close(); await settle(); expect(request.closed.peek()).toBeNull(); @@ -133,12 +133,12 @@ test("an origin closing settles pending announced requests", async () => { request.close(); }); -test("only a plain request can use a session without discovery", async () => { +test("only a request can use a session without discovery", async () => { const origin = new Producer(); const wire = wireOf(origin); const detach = wire.attach(false); const path = Path.from("blind"); - const followed = origin.request(path, { announced: true }); + const followed = origin.follow(path); const slot = wire.requests.peek()?.get(path); if (!slot) throw new Error("request did not register"); expect(wire.blind(slot)).toBe(false); @@ -150,7 +150,7 @@ test("only a plain request can use a session without discovery", async () => { await settle(); expect(requested.active.peek()?.closed).toBe(source.closed); expect(followed.active.peek()).toBeUndefined(); - const joined = origin.request(path, { announced: true }); + const joined = origin.follow(path); await settle(); expect(joined.active.peek()).toBeUndefined(); joined.close(); @@ -164,7 +164,7 @@ test("only a plain request can use a session without discovery", async () => { origin.close(); }); -test("announced requests follow the serving prefix, ignoring descendants and re-prices", async () => { +test("followers track the serving prefix, ignoring descendants and re-prices", async () => { const origin = new Producer(); const source = new BroadcastProducer(); const keeper = source.consume(); @@ -172,7 +172,7 @@ test("announced requests follow the serving prefix, ignoring descendants and re- const serving = (async () => { for await (const request of prefix.requested()) hooks.acceptRequest(request, source.consume()); })(); - const request = origin.request(Path.from("pool/job"), { announced: true }); + const request = origin.follow(Path.from("pool/job")); await settle(); expect(request.active.peek()?.closed).toBe(source.closed); const belowPublication = origin.createBroadcast(Path.from("pool/job/thumb")); @@ -203,14 +203,14 @@ test("announced requests follow the serving prefix, ignoring descendants and re- await serving; }); -test("an announced request ignores a covering route whose scope excludes its path", async () => { +test("a follower ignores a covering route whose scope excludes its path", async () => { const origin = new Producer(); const scoped = origin.scope(Path.empty(), new Path.Patterns([Path.Pattern.parse("room/*/chat")])); const prefix = scoped.requestsRoute(Path.from("room/alice")); const exactPublication = origin.createBroadcast(Path.from("room/alice")); const exact = exactPublication.broadcast; exactPublication.announce({ cost: 5n }); - const request = origin.request(Path.from("room/alice"), { announced: true }); + const request = origin.follow(Path.from("room/alice")); expect(request.active.peek()?.closed).toBe(exact.closed); exact.close(); await settle(); @@ -220,7 +220,7 @@ test("an announced request ignores a covering route whose scope excludes its pat origin.close(); }); -test("an announced request follows an epochless route replaced by an identical one", async () => { +test("a follower tracks an epochless route replaced by an identical one", async () => { const origin = new Producer(); const path = Path.from("room"); const serve = (source: BroadcastProducer) => { @@ -232,7 +232,7 @@ test("an announced request follows an epochless route replaced by an identical o }; const firstSource = new BroadcastProducer(); const first = serve(firstSource); - const request = origin.request(path, { announced: true }); + const request = origin.follow(path); await settle(); expect(request.active.peek()?.closed).toBe(firstSource.closed); @@ -251,7 +251,7 @@ test("an announced request follows an epochless route replaced by an identical o origin.close(); }); -test("an origin closing settles an announced request a served route resolved", async () => { +test("an origin closing settles a follower a served route resolved", async () => { const origin = new Producer(); const path = Path.from("room"); const source = new BroadcastProducer(); @@ -259,7 +259,7 @@ test("an origin closing settles an announced request a served route resolved", a void (async () => { for await (const request of route.requested()) hooks.acceptRequest(request, source.consume()); })(); - const request = origin.request(path, { announced: true }); + const request = origin.follow(path); await settle(); expect(request.active.peek()).toBeDefined(); const abort = new Error("shutdown"); @@ -271,12 +271,12 @@ test("an origin closing settles an announced request a served route resolved", a source.close(); }); -test("an announced request keeps a refusal that lands with a re-price", async () => { +test("a follower keeps a refusal that lands with a re-price", async () => { const origin = new Producer(); const path = Path.from("room"); const route = origin.requestsRoute(path); const requested = route.requested(); - const request = origin.request(path, { announced: true }); + const request = origin.follow(path); const pending = (await requested.next()).value; if (!pending) throw new Error("expected a request"); @@ -299,7 +299,7 @@ test("an announced request keeps a refusal that lands with a re-price", async () }); for (const received of [false, true]) { - test(`a plain request owns discovery through both local and received routes (received: ${received})`, async () => { + test(`a request owns discovery through both local and received routes (received: ${received})`, async () => { const origin = new Producer(); const path = Path.from("room"); const events: string[] = []; @@ -415,7 +415,7 @@ test("an answer prepared for an abandoned claim is never announced", async () => const prepared = pending.prepare(Epoch.mint()); claim.close(); expect(() => prepared.publish()).toThrow("request is closed"); - const announced = origin.request(path, { announced: true }); + const announced = origin.follow(path); await settle(); expect(announced.active.peek()).toBeUndefined(); announced.close(); @@ -583,7 +583,7 @@ test("an epoch-pinned follower resumes when its instance returns after a gap", a return route; }; const first = serve(epoch, source); - const request = origin.request(path, { announced: true, epoch }); + const request = origin.follow(path, { epoch }); await settle(); expect(request.active.peek()?.epoch).toBe(epoch); first.close(); @@ -608,7 +608,7 @@ test("an epoch-pinned follower resumes when its instance returns after a gap", a origin.close(); }); -test("a plain request owns its scoped discovery until closed", async () => { +test("a request owns its scoped discovery until closed", async () => { const origin = new Producer(); const wire = wireOf(origin); const detach = wire.attach(true); @@ -630,7 +630,40 @@ test("a plain request owns its scoped discovery until closed", async () => { origin.close(); }); -test("a pending plain request fails Unroutable once its discovery syncs without a route", async () => { +test("a follower keeps its scoped discovery across instances until closed", async () => { + const origin = new Producer(); + const wire = wireOf(origin); + const detach = wire.attach(true); + const path = Path.from("room/audio"); + const interests: string[] = []; + let synced: (() => void) | undefined; + const stop = wire.interests((prefix, wanted) => { + interests.push(`${prefix} ${wanted}`); + if (wanted) synced = wire.snapshot(prefix); + }); + const follower = origin.follow(path); + expect(interests).toEqual(["room/audio true"]); + synced?.(); + await settle(); + expect(follower.closed.peek()).toBeUndefined(); + const publication = origin.createBroadcast(path); + publication.announce(); + await settle(); + expect(follower.active.peek()?.closed).toBe(publication.broadcast.closed); + publication.broadcast.close(); + await settle(); + // The instance ending keeps the follower and its discovery open for the next one. + expect(follower.active.peek()).toBeUndefined(); + expect(follower.closed.peek()).toBeUndefined(); + expect(interests).toEqual(["room/audio true"]); + follower.close(); + expect(interests).toEqual(["room/audio true", "room/audio false"]); + stop(); + detach(); + origin.close(); +}); + +test("a pending request fails Unroutable once its discovery syncs without a route", async () => { const origin = new Producer(); const wire = wireOf(origin); const detach = wire.attach(true); @@ -641,7 +674,7 @@ test("a pending plain request fails Unroutable once its discovery syncs without const missing = origin.request(Path.from("room/missing")); const found = origin.request(Path.from("room/found")); const pinned = origin.request(Path.from("room/pinned"), { epoch: Epoch.mint() }); - const follower = origin.request(Path.from("room/followed"), { announced: true }); + const follower = origin.follow(Path.from("room/followed")); // The initial set reports these before it lands, and nothing at all for the rest. const route = wire.receive(Path.from("room/found")); const other = wire.receive(Path.from("room/pinned"), { epoch: Epoch.mint() }); @@ -666,12 +699,12 @@ test("a pending plain request fails Unroutable once its discovery syncs without origin.close(); }); -test("an announced request retains a selected handler's explicit unroutable refusal", async () => { +test("a follower retains a selected handler's explicit unroutable refusal", async () => { const origin = new Producer(); const path = Path.from("room/audio"); const route = origin.requestsRoute(path); const pending = route.requested(); - const requested = origin.request(path, { announced: true }); + const requested = origin.follow(path); const request = (await pending.next()).value; if (!request) throw new Error("request did not reach its handler"); const refused = new StreamError(StreamCode.Unroutable); @@ -683,7 +716,7 @@ test("an announced request retains a selected handler's explicit unroutable refu origin.close(); }); -test("a pending plain request retries a route gap and never retargets after resolving", async () => { +test("a pending request retries a route gap and never retargets after resolving", async () => { const origin = new Producer(); const path = Path.from("room/audio"); const first = origin.requestsRoute(path); diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index d813749cc82..c9bdb656877 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -740,7 +740,7 @@ test("discovery reflects the attached sessions", async () => { origin.close(); }); -test("announced requests share no subscription and follow discovery", () => { +test("followers share no subscription and follow discovery", () => { const origin = new Producer(); const wire = wireOf(origin); @@ -756,7 +756,7 @@ test("announced requests share no subscription and follow discovery", () => { const requests = []; try { - for (let i = 0; i < 200; i++) requests.push(origin.request(Path.from(`user${i}`), { announced: true })); + for (let i = 0; i < 200; i++) requests.push(origin.follow(Path.from(`user${i}`))); } finally { spy.mockRestore(); } @@ -2018,7 +2018,7 @@ test("closing a derived handle withdraws the sessions and answers attached throu // The session stops asking its peer for announcements, now and for later watches. expect(interests.splice(0)).toEqual(["-"]); - consumer.request(Path.from("later"), { announced: true }).close(); + consumer.follow(Path.from("later")).close(); expect(interests).toEqual([]); // The answer, the attached session, and the initial set in flight went with the handle. diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index 3d1bff155f8..d7196ed82bc 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -585,7 +585,7 @@ class OriginState { // present, not known live, so it must not read as an availability claim. requests = new Signal | undefined>(new Map()); - // Path-local wakeups for announced requests, which survive the end of a resolved instance. + // Path-local wakeups for followers, which survive the end of a resolved instance. // A counter rather than the instance: the instance is a plain object, so two epochless // routes with identical metadata compare equal, and a coalesced write could hide a takeover // or the origin closing. Watchers read the table and `closed` themselves when woken. @@ -668,8 +668,8 @@ class OriginState { return true; } - // The literal heads readers are watching, counted, as a trie: announcement streams and - // announced requests. Sessions ask their peer for announcements under the broadest of + // The literal heads readers are watching, counted, as a trie: announcement streams, + // requests, and followers. Sessions ask their peer for announcements under the broadest of // these and nothing else, and hear each change to that covering set as it happens, so a // watch coming or going touches only its prefix and the watches directly above or below. #watches: WatchNode = { path: Path.empty(), children: new Map(), count: 0 }; @@ -1119,9 +1119,12 @@ export interface Table { /** Create an unannounced broadcast at `path`; see {@link Producer.createBroadcast}. */ createBroadcast(path: Path.Valid): Publication; - /** Resolve `path`, optionally waiting for an announcement; see {@link Consumer.request}. */ + /** Resolve one publisher instance at `path`; see {@link Consumer.request}. */ request(path: Path.Valid, options?: RequestOptions): Requesting; + /** Follow `path` across publisher instances; see {@link Consumer.follow}. */ + follow(path: Path.Valid, options?: RequestOptions): Requesting; + /** The available broadcasts under `scope`, as a live stream; see {@link Consumer.announced}. */ announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer; @@ -1135,13 +1138,8 @@ export interface Table { ): Requests; } -/** Options for resolving a broadcast path. */ +/** Options for resolving a broadcast path, by {@link Consumer.request} or {@link Consumer.follow}. */ export interface RequestOptions { - /** - * Follow announced instances, pinned to one epoch when provided. Requires discovery; - * never falls back to a blind request when discovery is unavailable. - */ - announced?: boolean; /** Refuse a different publisher instance, including an asynchronous answer or a retry. */ epoch?: Epoch.Valid; } @@ -1522,11 +1520,16 @@ export class Producer implements Table { return this.#reader.discovery; } - /** Resolve `path`, optionally waiting for an announcement; see {@link Consumer.request}. */ + /** Resolve one publisher instance at `path`; see {@link Consumer.request}. */ request(path: Path.Valid, options?: RequestOptions): Requesting { return this.#reader.request(path, options); } + /** Follow `path` across publisher instances; see {@link Consumer.follow}. */ + follow(path: Path.Valid, options?: RequestOptions): Requesting { + return this.#reader.follow(path, options); + } + /** The available broadcasts under `scope`, as a live stream; see {@link Consumer.announced}. */ announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer { return this.#reader.announced(scope, options); @@ -1614,7 +1617,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}. + * An owned request for a broadcast path; see {@link Consumer.request} and {@link Consumer.follow}. * * @public */ @@ -1624,8 +1627,8 @@ export class Requesting { /** * The current broadcast, or undefined while nothing provides the path. - * Announced requests follow publisher instances, pinned to one when requested. - * Plain requests retain their accepted instance. Another route of the same epoch taking over keeps + * 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 * this handle: its tracks resume on that route from the first group each reader lacks. * Closing this handle affects only this request. */ @@ -1633,9 +1636,9 @@ export class Requesting { /** * Settles on refusal, origin shutdown, or explicit close. - * A plain request also ends when its accepted instance stops serving, and fails + * A request also ends when its accepted instance stops serving, and fails * `Unroutable` while pending once discovery syncs without a route for it; - * an announced request waits for a later start, even when pinned. + * a followed path waits for a later start, even when pinned. */ readonly closed: GetPromise; @@ -1741,18 +1744,28 @@ export class Consumer { } /** - * Resolve one publisher instance, or follow announcements when `announced` is true. - * Every request owns discovery of its path until closed. A pending plain request fails - * `Unroutable` once every session's discovery has synced without a route for it, and can - * use a session without discovery instead. A follower requires discovery and waits for its - * pinned instance to return instead of closing on a gap. + * Resolve one publisher instance serving `path`, pinned to `epoch` when given. + * + * The request owns discovery of its path until closed and retries route churn while + * pending. It fails `Unroutable` once every session's discovery has synced without a + * route for it, and can use a session without discovery instead. Once resolved it keeps + * that instance, ending when the instance stops serving. Use {@link follow} to move on + * to the next one. */ request(path: Path.Valid, options: RequestOptions = {}): Requesting { - if (options.announced) return this.#following(path, options); - return this.#resolve(path, options); + return this.#resolve(path, options.epoch, false); } - #following(path: Path.Valid, options: RequestOptions): Requesting { + /** + * Follow `path` across publisher instances, pinned to `epoch` when given. + * + * `active` moves to each instance announced at the path, clears between them, and never + * closes on a gap: a pinned follower waits for its instance to return. Owns discovery of + * 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 { + const epoch = options.epoch; const absolute = this.#scope.path(path); Path.Pattern.literal(path); let watch = this.#state.watchers.get(absolute); @@ -1827,7 +1840,7 @@ export class Consumer { ended(next.closed.peek(), next); }; try { - replace(this.#resolve(path, options)); + replace(this.#resolve(path, epoch, true)); } catch (error) { finish(error instanceof Error ? error : new Error(String(error))); throw error; @@ -1846,8 +1859,9 @@ export class Consumer { const same = previous && next && sameInstance(previous, next); previous = next; if (!next) { - if (had) replace(this.#resolve(path, options)); - } else if (!same || !current || current.closed.peek() !== undefined) replace(this.#resolve(path, options)); + if (had) replace(this.#resolve(path, epoch, true)); + } else if (!same || !current || current.closed.peek() !== undefined) + replace(this.#resolve(path, epoch, true)); }; if (!disposed) { unwatch = watched.version.subscribe(changed); @@ -1857,9 +1871,10 @@ export class Consumer { return makeRequesting(path, active, closed, () => finish(null)); } - #resolve(path: Path.Valid, options: RequestOptions): Requesting { + // One resolution of `path`. A follower's (`announced`) takes only an announced front and + // never reports absence: {@link follow} retries it on the next instance instead. + #resolve(path: Path.Valid, epoch: Epoch.Valid | undefined, announced: boolean): Requesting { Path.Pattern.literal(path); - const epoch = options.epoch; const relative = path; path = this.#scope.path(path); const requests = this.#state.requests.peek(); @@ -1891,7 +1906,6 @@ export class Consumer { const closed = new Once(); slot.handles.add(closed); // Counted, not subscribed: serving sessions decide blindness from the live discovery state. - const announced = options.announced === true; if (!announced) slot.blind += 1; // Resolution owns discovery from the first ask, not just after a route arrives. const unwatch = this.#state.watch([path]); diff --git a/js/publish/src/announce.test.ts b/js/publish/src/announce.test.ts index 7a93cf4fcd4..69315565ba5 100644 --- a/js/publish/src/announce.test.ts +++ b/js/publish/src/announce.test.ts @@ -170,8 +170,8 @@ test("capture gaps keep the broadcast epoch and same-identity track sequences", await start(env); const net = env.broadcast.net.peek(); if (!net) throw new Error("expected a network producer"); - const request = env.broadcast.in.origin.peek()?.request(env.broadcast.in.name.peek(), { announced: true }); - if (!request) throw new Error("expected an announced request"); + const request = env.broadcast.in.origin.peek()?.follow(env.broadcast.in.name.peek()); + if (!request) throw new Error("expected a follower"); const epoch = request.active.peek()?.epoch; const active: boolean[] = []; const stop = request.active.subscribe((value) => active.push(value !== undefined)); diff --git a/js/publish/src/audio/encoder.test.ts b/js/publish/src/audio/encoder.test.ts index 3830e540388..8aae953203c 100644 --- a/js/publish/src/audio/encoder.test.ts +++ b/js/publish/src/audio/encoder.test.ts @@ -710,7 +710,7 @@ test("audio failure stays local through demand changes and capture format re-arm await settle(); const net = broadcast.net.peek(); if (!net) throw new Error("expected network broadcast"); - announced = broadcast.in.origin.peek()?.request(broadcast.in.name.peek(), { announced: true }); + announced = broadcast.in.origin.peek()?.follow(broadcast.in.name.peek()); const epoch = announced?.active.peek()?.epoch; const sibling = broadcast.video("video"); sibling.config.set({ codec: "avc1.640028", container: { kind: "legacy" } }); diff --git a/js/publish/src/broadcast.test.ts b/js/publish/src/broadcast.test.ts index 680f6a74830..82c58d1d0a9 100644 --- a/js/publish/src/broadcast.test.ts +++ b/js/publish/src/broadcast.test.ts @@ -245,7 +245,7 @@ test("a re-announce continues the catalog's group sequence", async () => { const net = broadcast.net.peek(); if (!net) throw new Error("expected a network producer once connected"); - const announced = broadcast.in.origin.peek()?.request(broadcast.in.name.peek(), { announced: true }); + const announced = broadcast.in.origin.peek()?.follow(broadcast.in.name.peek()); const first = net.track(Broadcast.CATALOG_TRACK).subscribe().ordered(); expect((await first.nextGroup())?.sequence).toBe(0); @@ -467,7 +467,7 @@ test("a served decoder identity change moves the rendition to a fresh track name const net = broadcast.net.peek(); if (!net) throw new Error("expected a network producer once connected"); - const announced = broadcast.in.origin.peek()?.request(broadcast.in.name.peek(), { announced: true }); + const announced = broadcast.in.origin.peek()?.follow(broadcast.in.name.peek()); const epoch = announced?.active.peek()?.epoch; const catalog = new Json.Snapshot.Consumer({ track: net.track(Broadcast.CATALOG_TRACK).subscribe(), diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index 67dbf8a023d..cd809ecd4f4 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -1090,7 +1090,7 @@ test("a failed video encoder disables only its rendition and recovers on a fresh await encoder.out.catalog.changed(); const net = broadcast.net.peek(); if (!net) throw new Error("expected network broadcast"); - announced = broadcast.in.origin.peek()?.request(broadcast.in.name.peek(), { announced: true }); + announced = broadcast.in.origin.peek()?.follow(broadcast.in.name.peek()); const epoch = announced?.active.peek()?.epoch; const sibling = broadcast.video("video/sd"); sibling.config.set({ codec: "avc1.640028", container: { kind: "legacy" } }); diff --git a/js/watch/src/broadcast.test.ts b/js/watch/src/broadcast.test.ts index 13e87d69114..17f8d134cff 100644 --- a/js/watch/src/broadcast.test.ts +++ b/js/watch/src/broadcast.test.ts @@ -531,7 +531,7 @@ it("a blind broadcast does not follow another publisher instance", async () => { }); describe("restart", () => { - it("follows a republish through its announced request", async () => { + it("follows a republish through its follower", async () => { const announced = true; const owner = new Origin.Producer(); const name = Path.from("live.hang"); @@ -576,9 +576,9 @@ describe("restart", () => { // Count every request the player opens and closes. let open = 0; - const request = owner.request.bind(owner); - owner.request = (path, options) => { - const opened = request(path, options); + const follow = owner.follow.bind(owner); + owner.follow = (path, options) => { + const opened = follow(path, options); open += 1; const close = opened.close.bind(opened); let closed = false; diff --git a/js/watch/src/broadcast.ts b/js/watch/src/broadcast.ts index d5da5c25c87..51615ed7fb9 100644 --- a/js/watch/src/broadcast.ts +++ b/js/watch/src/broadcast.ts @@ -252,7 +252,7 @@ export class Broadcast { let entry = this.#references.get(path); if (!entry || entry.origin !== origin || entry.announced !== announced) { entry?.request.close(); - entry = { origin, announced, request: origin.request(path, { announced }), users: 0 }; + entry = { origin, announced, request: announced ? origin.follow(path) : origin.request(path), users: 0 }; this.#references.set(path, entry); } @@ -283,7 +283,7 @@ export class Broadcast { let request: Moq.Origin.Requesting; try { - request = origin.request(name, { announced }); + request = announced ? origin.follow(name) : origin.request(name); } catch (err) { effect.set(this.#out.error, err instanceof Error ? err : new Error(String(err)), undefined); return; @@ -298,7 +298,7 @@ export class Broadcast { effect.run((nested) => { const closed = nested.get(request.closed); if (!closed) return; - // An announced request outlives its instances, so only a refusal ends it. A blind one + // A follower outlives its instances, so only a refusal ends it. A plain request // ends with its accepted instance, which reads as offline rather than an error. const offline = !announced && resolved && closed instanceof NetError.Stream && closed.code === StreamCode.Unroutable; diff --git a/quest/m1/api-audit/resolve/README.md b/quest/m1/api-audit/resolve/README.md index 215dd750002..06bbee60d73 100644 --- a/quest/m1/api-audit/resolve/README.md +++ b/quest/m1/api-audit/resolve/README.md @@ -51,7 +51,6 @@ Wire: none. ## Required - [Rust request and follow](/quest/m1/api-audit/resolve/rust.md) - Rust names the two resolutions `request` and `follow`, deletes `routed` and `routed_broadcast`, and makes the route-level `Follow` private -- [JS request and follow](/quest/m1/api-audit/resolve/js.md) - `@moq/net` exposes `request(path, {epoch})` and `follow(path, {epoch})` instead of the `announced` option - [Bindings request and follow](/quest/m1/api-audit/resolve/bindings.md) - moq-ffi, the C ABI, and every wrapper mirror `request` and `follow` with an optional epoch - [Callers resolve once](/quest/m1/api-audit/resolve/callers.md) - no caller hand-rolls synced resolution or decides table absence by wall clock diff --git a/quest/m1/api-audit/resolve/callers.md b/quest/m1/api-audit/resolve/callers.md index 40978216747..0326463498a 100644 --- a/quest/m1/api-audit/resolve/callers.md +++ b/quest/m1/api-audit/resolve/callers.md @@ -25,4 +25,3 @@ Public API: none beyond the callers' own surfaces. Wire: none. ## Required - [Rust request and follow](/quest/m1/api-audit/resolve/rust.md) - the Rust names the callers move to -- [JS request and follow](/quest/m1/api-audit/resolve/js.md) - the JS names the callers move to diff --git a/quest/m1/api-audit/resolve/js.md b/quest/m1/api-audit/resolve/js.md deleted file mode 100644 index 38890233630..00000000000 --- a/quest/m1/api-audit/resolve/js.md +++ /dev/null @@ -1,25 +0,0 @@ -# [M] JS request and follow - -## Goal - -`@moq/net` exposes `request(path, {epoch})` and `follow(path, {epoch})` -instead of the `announced` option, and its in-package callers use them. - -## Plan - -Split from [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md) -on 2026-10-28 (maintainer); its Plan holds the behavior already landed in -[moq-dev/moq#6445](https://github.com/moq-dev/moq/pull/6445). - -- Keep the landed synced-absence `Unroutable` for `request` while `follow` - stays open, and its pending retry through a route gap without retargeting a - resolved instance. -- Retain synchronous request peeks and path-local wakeups. -- `Producer` pass-throughs stay only where `Table` needs them. -- Mirror the Rust names from [Rust request and follow](/quest/m1/api-audit/resolve/rust.md). - -Tests: synced absence, no follower fallback on a blind peer, pinned follow -return, and discovery retention and release, on mocked time. - -Public API: breaking in `@moq/net` (the `announced` option goes), with an -Impact migration note and a regenerated API report. Wire: none. diff --git a/quest/m2/release/runner-client-bump.md b/quest/m2/release/runner-client-bump.md index 8cca6b58184..aa7deb9a32e 100644 --- a/quest/m2/release/runner-client-bump.md +++ b/quest/m2/release/runner-client-bump.md @@ -30,7 +30,7 @@ subscription under `data-subgroup-basic`'s dynamic claim then fails whether that has landed before calling it a client bug. The JS client's announcement check also moves from `"retracted"` to `"end"` when it takes the cut. Its `data-subgroup-basic` subscriber also stalls there: on `main`, -`request(path, { announced: true })` asks SUBSCRIBE_NAMESPACE for the +`follow(path)` asks SUBSCRIBE_NAMESPACE for the tuple's own namespace, and a moq-transport relay such as imquic answers only with namespaces beneath it, never the shorter routing prefix the publisher claimed. 0.4.x asked for the origin's scoped prefix. Untested options: hold diff --git a/test/drain/drain.ts b/test/drain/drain.ts index 2e5ce10382a..6556b2001cd 100644 --- a/test/drain/drain.ts +++ b/test/drain/drain.ts @@ -149,7 +149,7 @@ const viewer = new Moq.Connection({ // One request and one subscription, at the default zero budget, read for the whole run: the // route moving from A to B re-sources the track underneath. -const request = watched.request(path, { announced: true }); +const request = watched.follow(path); await until("the broadcast to resolve", () => request.active.peek() !== undefined); const active = request.active.peek() as Moq.Broadcast.Consumer; log("watching"); diff --git a/test/interop/clients/js-native/finish.ts b/test/interop/clients/js-native/finish.ts index 9410e834946..6a02a7f167a 100644 --- a/test/interop/clients/js-native/finish.ts +++ b/test/interop/clients/js-native/finish.ts @@ -13,8 +13,8 @@ export async function readFinish( ): Promise { const source = origin.consume(); const routes = source.announced(); - const request = origin.request(Moq.Path.from(path), { announced: true }); - const healthRequest = origin.request(Moq.Path.from(`${path}.health`), { announced: true }); + const request = origin.follow(Moq.Path.from(path)); + const healthRequest = origin.follow(Moq.Path.from(`${path}.health`)); try { let broadcast = request.active.peek(); while (!broadcast) { diff --git a/test/interop/clients/js-native/goaway.ts b/test/interop/clients/js-native/goaway.ts index 16e36a0eac4..6ed95ee2e90 100644 --- a/test/interop/clients/js-native/goaway.ts +++ b/test/interop/clients/js-native/goaway.ts @@ -18,7 +18,7 @@ const connection = new Reload({ goaway: { redirect: "follow" }, }); let replacementProbe: Moq.Track.Subscriber | undefined; -const requests = [origin.request(Moq.Path.from("handover"), { announced: true })]; +const requests = [origin.follow(Moq.Path.from("handover"))]; async function active(request: (typeof requests)[number]) { let broadcast = request.active.peek(); while (!broadcast) { diff --git a/test/interop/clients/js-native/subscribe.ts b/test/interop/clients/js-native/subscribe.ts index e578b11789b..d1454f96785 100644 --- a/test/interop/clients/js-native/subscribe.ts +++ b/test/interop/clients/js-native/subscribe.ts @@ -256,7 +256,7 @@ async function run(): Promise { return; } const path = Moq.Path.from(broadcast as string); - requested = origin.request(path, { announced: true }); + requested = origin.follow(path); let bc = requested.active.peek(); while (!bc) { await requested.active.changed(); diff --git a/test/interop/clients/js-native/tail.ts b/test/interop/clients/js-native/tail.ts index 9fcc225e1eb..5ea73db8fd6 100644 --- a/test/interop/clients/js-native/tail.ts +++ b/test/interop/clients/js-native/tail.ts @@ -136,7 +136,7 @@ try { broadcast.close(); console.error("tail acknowledged"); } else { - const request = origin.request(Moq.Path.from(path), { announced: true }); + const request = origin.follow(Moq.Path.from(path)); try { let broadcast = request.active.peek(); while (!broadcast) { diff --git a/test/interop/compat/client.ts b/test/interop/compat/client.ts index 0d8924d81c4..ae0f598ff93 100644 --- a/test/interop/compat/client.ts +++ b/test/interop/compat/client.ts @@ -202,6 +202,9 @@ async function audio( /** What a subscriber reads: a video frame and decoded audio, or the group live demand fills on a track. */ type Read = { kind: "media"; out: string; ms: number } | { kind: "group"; file: string; track?: string }; +/** The released origin, which follows a path through `request`. */ +type Released = { request(path: Moq.Path.Valid, options: { announced: true }): Moq.Origin.Requesting }; + /** Print `received N bytes` once both media have arrived, or record the observed group. */ async function subscribe(url: URL, broadcast: string, read: Read) { install(); @@ -210,7 +213,10 @@ async function subscribe(url: URL, broadcast: string, read: Read) { if (read.kind === "media" && !(await Libav.polyfill())) throw new Error("no AudioDecoder"); const origin = new Moq.Origin.Producer(); const connection = await connect({ url, consume: origin, websocket: { enabled: false } }); - const requested = origin.request(Moq.Path.from(broadcast), { announced: true }); + // Released packages follow with `request(path, { announced: true })`; current ones with `follow(path)`. + const path = Moq.Path.from(broadcast); + const requested = + "follow" in origin ? origin.follow(path) : (origin as unknown as Released).request(path, { announced: true }); try { let bc = requested.active.peek(); while (!bc) { diff --git a/test/wasm/baseline/consumer.ts b/test/wasm/baseline/consumer.ts index 1b30a668051..4fc044df6aa 100644 --- a/test/wasm/baseline/consumer.ts +++ b/test/wasm/baseline/consumer.ts @@ -71,7 +71,7 @@ async function run(config: Sample) { }); await Promise.all( Array.from({ length: config.publishers }, async (_, publisher) => { - const request = origin.request(net.Path.from(`${config.id}/${publisher}`), { announced: true }); + const request = origin.follow(net.Path.from(`${config.id}/${publisher}`)); disposers.push(() => request.close()); let broadcast = request.active.peek(); while (!broadcast) { From 61d9c7dfce01c47c0c11d9ca4a1f61213f1dc252 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 17:03:00 -0700 Subject: [PATCH 3/3] test(smoke): follow on either side of the follow(path) rename The smoke client runs the npm `latest` @moq/net, which keeps the `announced` option until the next release. Co-Authored-By: Claude Opus 5.5 --- test/smoke/clients/js-native/subscribe.ts | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/test/smoke/clients/js-native/subscribe.ts b/test/smoke/clients/js-native/subscribe.ts index d95b6b970fa..66d5bb39e70 100644 --- a/test/smoke/clients/js-native/subscribe.ts +++ b/test/smoke/clients/js-native/subscribe.ts @@ -15,6 +15,12 @@ import * as Catalog from "@moq/hang/catalog"; import * as Moq from "@moq/net"; import { install } from "@moq/web-transport"; +// An origin from either side of the `follow(path)` rename, since `latest` may predate it. +type Resolver = { + follow?(path: Moq.Path.Valid): Moq.Origin.Requesting; + request(path: Moq.Path.Valid, options: { announced: true }): Moq.Origin.Requesting; +}; + // globalThis.WebTransport = the polyfill (no-op if a native one already exists). // @moq/net's connect() reads globalThis.WebTransport at call time, so this just // has to run before run() below. @@ -65,9 +71,12 @@ async function run(): Promise { // Wait for the broadcast to be announced before subscribing. Subscribing to a // track on a broadcast the publisher hasn't announced yet races the relay, - // which resets the catalog stream (RESET_STREAM). `announced: true` folds that - // wait into the request; the outer timeout below bounds it. - const request = origin.request(Moq.Path.from(broadcast as string), { announced: true }); + // which resets the catalog stream (RESET_STREAM). Following folds that wait + // into the request; the outer timeout below bounds it. Packages before + // `follow(path)` follow with `request(path, { announced: true })`. + const path = Moq.Path.from(broadcast as string); + const resolver = origin as unknown as Resolver; + const request = resolver.follow ? resolver.follow(path) : resolver.request(path, { announced: true }); try { let bc = request.active.peek(); while (!bc) bc = await request.active.changed();