diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 7bc2bf2a57d..4991605ed12 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -21353,11 +21353,11 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqoriginconsumer_announced_broadcast() != - 56171) { + 40619) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqoriginconsumer_request_broadcast() != - 54627) { + 36974) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqoriginproducer_consume() != 52357) { diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 6d05c601615..3e0aa334b20 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; a plain `request(path)` keeps its accepted instance, can resolve blindly, and ends once that instance stops serving. 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, { announced: true })`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A plain `request(path)` asks nothing and subscribes blind, but once it resolves through a discovered route it watches its path until closed, so it outlives the listing that found it. A relay that refuses an announce request turns that session's announced requests blind too. +- **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. - **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 b3afcc93296..aefe8b84227 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -19,7 +19,7 @@ What you use it for, beyond what the concept page already describes: - **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. -- **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` watches nothing, so a path nobody watches is unroutable. 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. +- **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. - **Publish only while someone is watching.** `demand()` on a track, group, or broadcast says whether a subscriber is attached, which is how capture and transcode skip work nobody asked for. Holding a broadcast or track consumer is not demand: a track consumer requests nothing until it queries, subscribes, or fetches, and those count until dropped. A shared fetch stays up until its last reader leaves. diff --git a/js/net/bench/requests.ts b/js/net/bench/requests.ts index 57de2aeff2b..4f519d0deb5 100644 --- a/js/net/bench/requests.ts +++ b/js/net/bench/requests.ts @@ -1,4 +1,4 @@ -/** Sweep request restart and cancellation over independent origin and waiter dimensions. */ +/** Sweep request restart, cancellation, and discovery settlement over independent origin and waiter dimensions. */ import { Producer as Broadcast } from "../src/broadcast"; import * as Epoch from "../src/epoch"; import { Publisher as IetfPublisher } from "../src/ietf/publisher"; @@ -94,6 +94,40 @@ for (const unrelated of [8, 128, 2048]) origin.close(); } +// An initial set landing settles only the pending requests beneath its prefix, never every +// request in the table, however many land in one task. +console.log("pending,landed,settle_us"); +for (const pending of [128, 1024, 8192]) + for (const landed of [1, 16, 128]) { + const samples: number[] = []; + for (let round = 0; round < 5; round++) { + const origin = new Producer(); + const wire = wireOf(origin); + const detach = wire.attach(true); + const initialSets = new Map void>(); + const stop = wire.interests((prefix, wanted) => { + if (wanted) initialSets.set(prefix, wire.snapshot(prefix)); + }); + const held = Array.from({ length: pending }, (_, i) => origin.request(Path.from(`held/${i}`))); + const touched = Array.from({ length: landed }, (_, i) => origin.request(Path.from(`touched/${i}`))); + await settle(); + const start = performance.now(); + for (let i = 0; i < landed; i++) initialSets.get(Path.from(`touched/${i}`))?.(); + // The settlement is one microtask queued by the first landing, ahead of this one. + await Promise.resolve(); + if (round > 0) samples.push((performance.now() - start) * 1000); + if (touched.some((request) => request.closed.peek() === undefined)) throw new Error("absence unsettled"); + if (held.some((request) => request.closed.peek() !== undefined)) throw new Error("unsynced path settled"); + for (const request of [...held, ...touched]) request.close(); + for (const release of initialSets.values()) release(); + stop(); + detach(); + origin.close(); + } + samples.sort((a, b) => a - b); + console.log(`${pending},${landed},${samples[2].toFixed(2)}`); + } + // Keep old instances on distinct same-epoch failovers, then cancel new demand. // This exercises ownership checks inside one cleanup, independently of wire sharing. console.log("failovers,extra_routes,cancel_us"); diff --git a/js/net/src/connection/forward.test.ts b/js/net/src/connection/forward.test.ts index 7bec151809d..74f49a6c8be 100644 --- a/js/net/src/connection/forward.test.ts +++ b/js/net/src/connection/forward.test.ts @@ -124,17 +124,21 @@ function record(stream: Announce.Consumer): string[] { return events; } -test("no watcher opens no announce request, and a plain request answers blind", async () => { +test("a plain request discovers an unwatched path and waits for its initial set", async () => { const origin = new OriginProducer(); const session = new FakeSession(); forwardAnnounced(session.session, origin); - + expect(session.requests).toEqual([]); const request = origin.request(Path.from("room")); await settle(); - expect(session.requests).toEqual([]); + expect(session.open()).toEqual(["room/**"]); + expect(request.active.peek()).toBeUndefined(); + expect(session.consumes(Path.from("room"))).toBe(0); + start(session.stream("room/**"), "room"); + session.stream("room/**").synced(); + await settle(); expect(request.active.peek()).toBeDefined(); expect(session.consumes(Path.from("room"))).toBe(1); - request.close(); session.die(); origin.close(); @@ -466,8 +470,12 @@ test("a refused announce request downgrades the session once, and later watches session.stream("room/**").close(new Error("namespace rejected")); await settle(); expect(origin.discovery.peek()).toBe(false); - // The gated request falls back to a blind answer on the live session. - expect(watched.active.peek()).toBeDefined(); + // Following cannot use a peer that no longer announces; a plain request can. + expect(watched.active.peek()).toBeUndefined(); + expect(session.consumes(path)).toBe(0); + const plain = origin.request(path); + await settle(); + expect(plain.active.peek()).toBeDefined(); expect(session.consumes(path)).toBe(1); const later = origin.announced(Path.Pattern.subtree(Path.from("other"))); @@ -475,6 +483,7 @@ test("a refused announce request downgrades the session once, and later watches expect(session.requests.length).toBe(1); later.close(); + plain.close(); watched.close(); session.die(); origin.close(); @@ -503,13 +512,17 @@ test("a discovery failure under a live session retracts what it fed and answers expect(wireOf(origin).routes(path)).toBe(false); expect(origin.discovery.peek()).toBe(false); - // The same request falls back to a blind answer on the live session. + // The follower stays offline; a separate plain request can use the blind peer. expect(watched.closed.peek()).toBeUndefined(); - expect(watched.active.peek()).toBeDefined(); + expect(watched.active.peek()).toBeUndefined(); + const plain = origin.request(path); + await settle(); + expect(plain.active.peek()).toBeDefined(); // The announcement's own consume, plus the blind answer standing in for it now. expect(session.consumes(path)).toBe(2); watched.close(); + plain.close(); session.die(); origin.close(); }); @@ -544,6 +557,11 @@ test("a request replaced across one coalesced wakeup still gets answered", async const path = Path.from("wanted"); forwardAnnounced(session.session, origin); + // Refusing discovery downgrades the session, so plain requests take its blind answers. + const listing = origin.announced(Path.Pattern.subtree(path)); + await settle(); + session.stream("wanted/**").close(new Error("namespace rejected")); + await settle(); const first = origin.request(path); await settle(); @@ -563,6 +581,7 @@ test("a request replaced across one coalesced wakeup still gets answered", async expect(session.consumes(path)).toBe(2); second.close(); + listing.close(); session.die(); origin.close(); }); @@ -606,7 +625,7 @@ test("a scoped origin narrows a root watch to its disjoint literal heads", async origin.close(); }); -test("a scoped session filters announcements and blind requests under its root", async () => { +test("a scoped session filters discovered routes and requests under its root", async () => { const origin = new OriginProducer(); const scoped = origin.scope(Path.from("tenant"), new Path.Patterns([Path.Pattern.parse("room/*/chat")])); const session = new FakeSession(); @@ -617,12 +636,13 @@ test("a scoped session filters announcements and blind requests under its root", await settle(); // Session-relative: the scope's root is the session's. expect(session.open()).toEqual(["room/**"]); - for (const prefix of ["room/alice/video", "room/alice/chat"]) start(session.stream("room/**"), prefix); + for (const prefix of ["room/alice/video", "room/alice/chat", "room/bob/chat"]) + start(session.stream("room/**"), prefix); const allowed = origin.request(Path.from("tenant/room/bob/chat")); const denied = origin.request(Path.from("tenant/room/bob/video")); await settle(); - expect(events).toEqual(["start tenant/room/alice/chat"]); + expect(events).toEqual(["start tenant/room/alice/chat", "start tenant/room/bob/chat"]); expect(session.consumes(Path.from("room/bob/chat"))).toBe(1); expect(session.consumes(Path.from("room/bob/video"))).toBe(0); @@ -728,3 +748,23 @@ test("a request synced as it opens releases the watcher", async () => { session.die(); origin.close(); }); + +test("a scoped session refuses blind requests outside its allowed paths", async () => { + const origin = new OriginProducer(); + const scoped = origin.scope(Path.from("tenant"), new Path.Patterns([Path.Pattern.parse("room/*/chat")])); + const session = new FakeSession(); + forwardAnnounced(session.session, scoped); + const allowed = origin.request(Path.from("tenant/room/bob/chat")); + const denied = origin.request(Path.from("tenant/room/bob/video")); + await settle(); + for (const request of session.requests) request.stream.close(new Error("no discovery")); + await settle(); + expect(allowed.active.peek()).toBeDefined(); + expect(session.consumes(Path.from("room/bob/chat"))).toBe(1); + expect(denied.active.peek()).toBeUndefined(); + expect(session.consumes(Path.from("room/bob/video"))).toBe(0); + allowed.close(); + denied.close(); + session.die(); + origin.close(); +}); diff --git a/js/net/src/connection/forward.ts b/js/net/src/connection/forward.ts index 664ec4f8a02..9bbab37870d 100644 --- a/js/net/src/connection/forward.ts +++ b/js/net/src/connection/forward.ts @@ -50,7 +50,7 @@ interface Reported { * requests with blind subscriptions. * * Discovery is lazy. One announce request opens per prefix in the origin's covering set of - * watches (`announced(scope)` and `request(path, { announced: true })`) that no open request + * watches (`announced(scope)` and every `request(path)`) that no open request * already covers, and closes {@link LINGER} after nothing at or beneath its prefix is watched. * A narrower watch rides an open broader request, and a narrower request already open stays * open until the broader one covering it goes, so neither takes the other's routes over @@ -70,8 +70,8 @@ interface Reported { * session to the same origin and re-opens whatever is still watched. * * A peer that refuses or resets an announce request downgrades the whole session to blind - * answers: gated requests stop waiting for an announcement, and later watches open nothing - * on it. + * answers: plain requests subscribe through it without waiting for an announcement, and + * later watches open nothing on it. * * @internal */ @@ -153,8 +153,8 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi const downgrade = (failure: unknown) => { if (blind) return; blind = true; - // Announcement-gated consumers would wait forever on a table this session cannot fill, - // so they fall back to blind answers, which this session still provides. + // Plain requests can still use this session's blind answers. Announcement followers + // keep waiting for a source that can discover their path. console.warn("broadcast discovery failed; broadcasts resolve on request only.", failure); detach(); detach = originWire.attach(false); @@ -183,10 +183,11 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi // The origin's readers under the prefix wait on this request's initial set. Released // once the session stream has synced, which it reports only after the last of those - // events is reported here. + // events is reported here. A closing stream also reads as synced, but a failure is not + // an answer: the loop below releases it with the downgrade, in one step. const snapshot = originWire.snapshot(prefix); const synced = interest.announced.synced.subscribe((synced) => { - if (synced) snapshot(); + if (synced && interest.announced.closed.peek() === undefined) snapshot(); }); // A request with no initial set to wait for is synced before the listener exists. if (interest.announced.synced.peek()) snapshot(); diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 7d65dcf01e0..1217fd0d295 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -1751,7 +1751,7 @@ test("integration: an announced request waits for a late publisher", async () => clientOrigin.close(); }); -test("integration: an announced request consumes blind without discovery", async () => { +test("integration: only a plain request consumes blind without discovery", async () => { withoutDiscovery(); const pair = createMockTransportPair(Lite.ALPN_06); const origin = new OriginProducer(); @@ -1770,13 +1770,16 @@ test("integration: an announced request consumes blind without discovery", async } })(); - // No announcement ever arrives, so waiting for one would hang. Subscribe anyway. - const watched = clientOrigin.request(Path.from("test"), { announced: true }); + const followed = clientOrigin.request(Path.from("test"), { announced: true }); + await until(() => clientOrigin.discovery.peek() === false); + expect(followed.active.peek()).toBeUndefined(); + const watched = clientOrigin.request(Path.from("test")); 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("blind"); watched.close(); + followed.close(); broadcast.close(); await serving; client.abort(); @@ -1923,7 +1926,7 @@ test("integration: a blind handle picks up a publisher that arrives late", async ]); // Without discovery there is no announcement to wait for, so the handle consumes blind. - const watched = clientOrigin.request(Path.from("later"), { announced: true }); + const watched = clientOrigin.request(Path.from("later")); const blind = await waitFor(watched.active, (b) => b !== undefined); if (!blind) throw new Error("expected a blind consumer"); @@ -1962,7 +1965,7 @@ test("integration: a blind handle goes offline when the session dies", async () accept(pair.server, url, { publish: origin.consume() }), ]); - const watched = clientOrigin.request(Path.from("whatever"), { announced: true }); + const watched = clientOrigin.request(Path.from("whatever")); await waitFor(watched.active, (b) => b !== undefined); // The gated path goes offline when the announcement stream ends with the session. There is @@ -1987,7 +1990,7 @@ test("integration: ietf blind handle picks up a publisher that arrives late", as accept(pair.server, url, { publish: origin.consume() }), ]); - const watched = clientOrigin.request(Path.from("later"), { announced: true }); + const watched = clientOrigin.request(Path.from("later")); const blind = await waitFor(watched.active, (b) => b !== undefined); if (!blind) throw new Error("expected a blind consumer"); @@ -2171,7 +2174,7 @@ test("origin: one origin on both directions consumes locally and never echoes", serverSees.close(); }); -test("origin: a plain request resolves blind without opening discovery", async () => { +test("origin: a plain request discovers the peer cannot announce before resolving blind", async () => { const refused = withoutDiscovery(); const pair = createMockTransportPair(Lite.ALPN_05); const serverOrigin = new OriginProducer(); @@ -2192,8 +2195,7 @@ test("origin: a plain request resolves blind without opening discovery", async ( })(); const reader = clientOrigin.consume(); - // Nothing watches, so the session never asks about announcements and never learns the - // relay would refuse: the table stays empty and a plain request answers blind. + // A request owns discovery, so it learns that this peer needs a blind request. expect(wireOf(reader).routes(Path.from("blind"))).toBe(false); const request = reader.request(Path.from("blind")); @@ -2203,8 +2205,8 @@ test("origin: a plain request resolves blind without opening discovery", async ( const track = front?.track("chat").subscribe().ordered(); if (!track) throw new Error("expected a track"); expect(await track.readString()).toBe("found you"); - expect(refused()).toBe(0); - expect(reader.discovery.peek()).toBe(true); + expect(refused()).toBe(1); + expect(reader.discovery.peek()).toBe(false); track.close(); request.close(); @@ -2375,6 +2377,7 @@ test.each([Ietf.ALPN.DRAFT_18])( ); test("origin: a blind request ends with its session, and the next session answers a fresh one", async () => { + withoutDiscovery(); const original = globalThis.WebTransport; const reconnectUrl = new URL("https://example.com/re-request"); diff --git a/js/net/src/origin-request.test.ts b/js/net/src/origin-request.test.ts index 019e3e68530..a3cd00c2e19 100644 --- a/js/net/src/origin-request.test.ts +++ b/js/net/src/origin-request.test.ts @@ -91,13 +91,17 @@ test("a closed announced request never acquires another publisher", async () => origin.close(); }); -test("announced requests refuse paths that cannot be watched or are outside scope", () => { - const origin = new Producer(); - expect(() => origin.request(Path.from("camera*main"), { announced: true })).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: true })).toThrow(); - origin.close(); -}); +test.each([false, true])( + "requests refuse unwatchable paths and scope violations before registering (announced: %s)", + (announced) => { + const origin = new Producer(); + expect(() => origin.request(Path.from("camera*main"), { announced })).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(wireOf(origin).requests.peek()?.size).toBe(0); + origin.close(); + }, +); test("unrelated routes never notify announced request followers", async () => { const origin = new Producer(); @@ -129,20 +133,34 @@ test("an origin closing settles pending announced requests", async () => { request.close(); }); -test("an announced request keeps its fallback blind answer", async () => { +test("only a plain 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 request = origin.request(path, { announced: true }); - const broadcast = new BroadcastProducer(); - const withdraw = wire.answer(path, broadcast.consume()); + const followed = origin.request(path, { announced: true }); + 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); + 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(); + const withdraw = wire.answer(path, source.consume()); await settle(); - expect(request.active.peek()?.closed).toBe(broadcast.closed); - request.close(); + expect(requested.active.peek()?.closed).toBe(source.closed); + expect(followed.active.peek()).toBeUndefined(); + const joined = origin.request(path, { announced: true }); + await settle(); + expect(joined.active.peek()).toBeUndefined(); + joined.close(); + requested.close(); + await settle(); + expect(wire.blind(slot)).toBe(false); + followed.close(); withdraw?.(); + source.close(); detach(); - broadcast.close(); origin.close(); }); @@ -281,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 watches its path only through a received route (received: ${received})`, async () => { + test(`a plain request owns discovery through both local and received routes (received: ${received})`, async () => { const origin = new Producer(); const path = Path.from("room"); const events: string[] = []; @@ -295,12 +313,12 @@ for (const received of [false, true]) { const request = origin.request(path); await settle(); expect(request.active.peek()).toBeDefined(); - // A local route needs no discovery; one a session received stays discovered while held. - expect(events).toEqual(received ? ["room true"] : []); + // Every request owns discovery, independent of the route that currently serves it. + expect(events).toEqual(["room true"]); request.close(); await settle(); - expect(events).toEqual(received ? ["room true", "room false"] : []); + expect(events).toEqual(["room true", "room false"]); stop(); route.close(); source.close(); @@ -550,3 +568,168 @@ test("a forwarded request cannot be prepared by setting a publisher property", a route.close(); origin.close(); }); + +test("an epoch-pinned follower resumes when its instance returns after a gap", async () => { + const origin = new Producer(); + const path = Path.from("room/audio"); + const epoch = Epoch.mint(); + const source = new BroadcastProducer(); + const keeper = source.consume(); + const serve = (instance: Epoch.Valid, broadcast: BroadcastProducer) => { + const route = origin.requestsRoute(path, { epoch: instance }); + void (async () => { + for await (const request of route.requested()) hooks.acceptRequest(request, broadcast.consume()); + })(); + return route; + }; + const first = serve(epoch, source); + const request = origin.request(path, { announced: true, epoch }); + await settle(); + expect(request.active.peek()?.epoch).toBe(epoch); + first.close(); + await settle(); + expect(request.active.peek()).toBeUndefined(); + expect(request.closed.peek()).toBeUndefined(); + const otherSource = new BroadcastProducer(); + const other = serve(Epoch.mint(), otherSource); + await settle(); + expect(request.active.peek()).toBeUndefined(); + other.close(); + await settle(); + expect(request.closed.peek()).toBeUndefined(); + const back = serve(epoch, source); + await settle(); + expect(request.active.peek()?.epoch).toBe(epoch); + request.close(); + back.close(); + keeper.close(); + source.close(); + otherSource.close(); + origin.close(); +}); + +test("a plain request owns its scoped discovery 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 request = origin.request(path); + expect(interests).toEqual(["room/audio true"]); + synced?.(); + expect(request.closed.peek()).toBeUndefined(); + request.close(); + expect(interests).toEqual(["room/audio true", "room/audio false"]); + stop(); + detach(); + origin.close(); +}); + +test("a pending plain request fails Unroutable once its discovery syncs without a route", async () => { + const origin = new Producer(); + const wire = wireOf(origin); + const detach = wire.attach(true); + const initialSets: (() => void)[] = []; + const stop = wire.interests((prefix, wanted) => { + if (wanted) initialSets.push(wire.snapshot(prefix)); + }); + 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 }); + // 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() }); + await settle(); + for (const request of [missing, found, pinned, follower]) expect(request.closed.peek()).toBeUndefined(); + + for (const synced of initialSets) synced(); + await settle(); + for (const request of [missing, pinned]) { + const err = request.closed.peek(); + expect(err).toBeInstanceOf(StreamError); + expect((err as StreamError).code).toBe(StreamCode.Unroutable); + } + expect(found.closed.peek()).toBeUndefined(); + expect(follower.closed.peek()).toBeUndefined(); + + for (const request of [missing, found, pinned, follower]) request.close(); + route.close(); + other.close(); + stop(); + detach(); + origin.close(); +}); + +test("an announced request 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 request = (await pending.next()).value; + if (!request) throw new Error("request did not reach its handler"); + const refused = new StreamError(StreamCode.Unroutable); + request.reject(refused); + await settle(); + expect(requested.closed.peek()).toBe(refused); + requested.close(); + route.close(); + origin.close(); +}); + +test("a pending plain 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); + const requested = origin.request(path); + const before = await first.requested().next(); + expect(before.value).toBeDefined(); + first.close(); + await settle(); + expect(requested.closed.peek()).toBeUndefined(); + const second = origin.requestsRoute(path); + const pending = (await second.requested().next()).value; + if (!pending) throw new Error("replacement route was not requested"); + const source = new BroadcastProducer(); + const keeper = source.consume(); + hooks.acceptRequest(pending, source.consume()); + await settle(); + expect(requested.active.peek()?.closed).toBe(source.closed); + const replacement = origin.createBroadcast(path); + replacement.announce(); + await settle(); + expect(requested.active.peek()?.closed).toBe(source.closed); + second.close(); + await settle(); + expect(requested.closed.peek()).toBeInstanceOf(StreamError); + expect(requested.active.peek()).toBeUndefined(); + requested.close(); + replacement.broadcast.close(); + keeper.close(); + source.close(); + origin.close(); +}); + +test("a plain epoch pin never takes an answer without that epoch", () => { + const origin = new Producer(); + const wire = wireOf(origin); + const detach = wire.attach(false); + const path = Path.from("room/audio"); + const requested = origin.request(path, { epoch: Epoch.mint() }); + expect(requested.closed.peek()).toBeUndefined(); + const source = new BroadcastProducer(); + const withdraw = wire.answer(path, source.consume()); + expect(requested.active.peek()).toBeUndefined(); + expect(requested.closed.peek()).toBeUndefined(); + requested.close(); + withdraw?.(); + source.close(); + detach(); + origin.close(); +}); diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index 33c4e7d0179..d813749cc82 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -767,12 +767,12 @@ test("announced requests share no subscription and follow discovery", () => { const slots = [...(wire.requests.peek()?.values() ?? [])]; expect(slots.length).toBe(200); - // Gated with no session attached and with full discovery; blind once one session cannot announce. + // Following remains gated even when a session cannot announce. expect(slots.some((slot) => wire.blind(slot))).toBe(false); const seeing = wire.attach(true); expect(slots.some((slot) => wire.blind(slot))).toBe(false); const silent = wire.attach(false); - expect(slots.every((slot) => wire.blind(slot))).toBe(true); + expect(slots.some((slot) => wire.blind(slot))).toBe(false); silent(); expect(slots.some((slot) => wire.blind(slot))).toBe(false); @@ -2010,7 +2010,8 @@ test("closing a derived handle withdraws the sessions and answers attached throu expect(request.active.peek()).toBeDefined(); expect(consumer.discovery.peek()).toBe(false); expect(announced.synced.peek()).toBe(false); - expect(interests.splice(0)).toEqual(["+"]); + // The request owns its path's discovery until the root watch covers it. + expect(interests.splice(0)).toEqual(["+blind", "+", "-blind"]); scoped.close(); await settle(); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index f011df8ceb2..3d1bff155f8 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -243,12 +243,12 @@ class CoveringRoot { * @internal */ export interface RequestSlot { - /** Open handles that always take a blind answer. */ + /** Open plain handles that can use a peer without discovery. */ blind: number; - /** Open announcement-gated handles, which take a blind answer only while discovery is incomplete. */ - announced: number; answer?: broadcast.Consumer; readonly handles: Set>; + /** Pending plain handles, each ending itself once synced discovery leaves it no route. */ + readonly absent: Set<() => void>; readonly route: Signal; /** The front a detached slot took from the table, closed with its last handle. */ retired?: broadcast.Consumer; @@ -335,6 +335,9 @@ function unroutable(): StreamError { return new StreamError(StreamCode.Unroutable, { message: "unroutable" }); } +// A selected handler refused these requests; a coalesced route gap can have the same error. +const refusedRequests = new WeakSet>(); + /** A served route from {@link Producer.requests}: the queue a handler drains. */ class ServeState { readonly root: Path.Valid; @@ -619,9 +622,52 @@ class OriginState { if (count > 0) counts.set(prefix, count); else counts.delete(prefix); }); + this.settle(prefix); }; } + // The prefixes whose pending plain requests may have lost their last reason to wait. + #unsettled = new Set(); + + /** + * Recheck the pending plain requests under the absolute `prefix` once the current task + * settles, so a session releasing its initial set and downgrading reads as one step. + */ + settle(prefix: Path.Valid): void { + if (this.#unsettled.size === 0) queueMicrotask(() => this.#settled()); + this.#unsettled.add(prefix); + } + + #settled(): void { + const requests = this.requests.peek(); + const visited = new Set(); + for (const prefix of this.#unsettled) { + // Every request watches its own path, so the watches beneath the prefix name exactly + // the requests it can settle, without scanning the rest of the table. + let node: WatchNode | undefined = this.#watches; + for (const part of prefix === Path.empty() ? [] : prefix.split("/")) node = node?.children.get(part); + const stack = node ? [node] : []; + for (let next = stack.pop(); next; next = stack.pop()) { + if (visited.has(next)) continue; + visited.add(next); + // Children first: settling a request may prune its node. + stack.push(...next.children.values()); + const slot = requests?.get(next.path); + if (slot) for (const absent of [...slot.absent]) absent(); + } + } + this.#unsettled.clear(); + } + + /** Whether every attached session discovers and none owes an initial set covering `path`. */ + synced(path: Path.Valid): boolean { + const { total, discovery } = this.sessions.peek(); + if (total === 0 || discovery < total) return false; + const snapshots = this.snapshots.peek(); + for (const prefix of coveringPrefixes(path)) if (snapshots.has(prefix)) return false; + 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 // these and nothing else, and hear each change to that covering set as it happens, so a @@ -877,14 +923,9 @@ class OriginState { } } - /** - * Whether sessions should answer `slot` with a blind subscription. An announcement-gated - * handle falls back to one only while at least one attached session cannot announce, and - * stays gated with no session attached. - */ + /** Whether a plain request needs the non-discovery session's blind answer. */ blind(slot: RequestSlot): boolean { - if (slot.blind > 0) return true; - if (slot.announced === 0) return false; + if (slot.blind === 0) return false; const { total, discovery } = this.sessions.peek(); return discovery < total; } @@ -897,13 +938,17 @@ class OriginState { refuse(path: Path.Valid, entry: RouteEntry, err: Error): void { // A detached slot failing over to this route ends with its answer. for (const other of [...(this.detached.get(path) ?? [])]) { - if (other.failover === entry) this.drop(path, other, err); + if (other.failover === entry) { + for (const closed of other.handles) refusedRequests.add(closed); + this.drop(path, other, err); + } } const slot = this.requests.peek()?.get(path); if (!slot) return; // Only the route the request is waiting on speaks for it; one superseded by another // route or a local broadcast has a moot answer. if (this.bestEntry(path) !== entry || this.localWins(path, entry)) return; + for (const closed of slot.handles) refusedRequests.add(closed); this.drop(path, slot, err); } @@ -1093,8 +1138,8 @@ export interface Table { /** Options for resolving a broadcast path. */ export interface RequestOptions { /** - * Follow announced instances unless an epoch is pinned; resolve blindly when discovery is - * unavailable. Watches the path, so a `consume` session asks its peer about it. + * 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. */ @@ -1394,6 +1439,8 @@ export class Producer implements Table { total: total + delta, discovery: d + (discovery ? delta : 0), })); + // Losing a session without discovery can leave every pending request synced. + this.#state.settle(Path.empty()); } // Run `release` once, at the first of its own call or this derived handle's close, so a @@ -1577,8 +1624,8 @@ export class Requesting { /** * The current broadcast, or undefined while nothing provides the path. - * Announced requests without an epoch follow publisher restarts. Blind and epoch-pinned - * requests retain their accepted instance. Another route of the same epoch taking over keeps + * 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 * this handle: its tracks resume on that route from the first group each reader lacks. * Closing this handle affects only this request. */ @@ -1586,8 +1633,9 @@ export class Requesting { /** * Settles on refusal, origin shutdown, or explicit close. - * A pinned or blind request also ends when its accepted instance stops serving; - * an unpinned announced request waits for a later start instead. + * A plain 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. */ readonly closed: GetPromise; @@ -1693,16 +1741,14 @@ export class Consumer { } /** - * Resolve a path, following publisher restarts when `announced` is true and no epoch is pinned. - * Announced requests clear `active` on an end and resolve again on the next start. A refusal - * is terminal. An epoch-pinned request never changes instance; a plain request keeps its - * accepted instance and may resolve blindly when discovery has no answer. Either one, - * once resolved through a discovered route, watches its path until closed. - * Announcement gating falls back to blind resolution when discovery is unavailable. - * Close the request to release its handle and announcement watch. + * 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. */ request(path: Path.Valid, options: RequestOptions = {}): Requesting { - if (options.announced && options.epoch === undefined) return this.#following(path, options); + if (options.announced) return this.#following(path, options); return this.#resolve(path, options); } @@ -1721,8 +1767,6 @@ export class Consumer { const active = new Signal(undefined); const closed = new Once(); let current: Requesting | undefined; - // Whether `current` ever resolved, so losing it reads as an end rather than a refusal. - let resolved = false; let subscriptions: Dispose[] = []; let disposed = false; const release = () => { @@ -1740,10 +1784,15 @@ export class Consumer { active.set(undefined); closed.set(error); }; - const ended = (error: Error | null | undefined) => { + const ended = (error: Error | null | undefined, request: Requesting | undefined = current) => { if (!error) return; - // Losing an accepted instance waits for its next announcement; a refusal is final. - if (resolved && error instanceof StreamError && error.code === StreamCode.Unroutable) { + // Provenance survives a coalesced end/start, even when both routes serve one epoch. + if ( + error instanceof StreamError && + error.code === StreamCode.Unroutable && + request && + !refusedRequests.has(request.closed) + ) { active.set(undefined); return; } @@ -1769,15 +1818,13 @@ export class Consumer { current = next; active.set(value); if (!next) return; - resolved = value !== undefined; subscriptions.push( next.active.subscribe((value) => { - if (value) resolved = true; active.set(value); }), ); - subscriptions.push(next.closed.subscribe(ended)); - ended(next.closed.peek()); + subscriptions.push(next.closed.subscribe((error) => ended(error, next))); + ended(next.closed.peek(), next); }; try { replace(this.#resolve(path, options)); @@ -1811,6 +1858,7 @@ export class Consumer { } #resolve(path: Path.Valid, options: RequestOptions): Requesting { + Path.Pattern.literal(path); const epoch = options.epoch; const relative = path; path = this.#scope.path(path); @@ -1831,8 +1879,8 @@ export class Consumer { // notify nobody. const created: RequestSlot = { blind: 0, - announced: 0, handles: new Set(), + absent: new Set(), route: new Signal(this.#state.route(path, {})), }; slot = created; @@ -1844,10 +1892,9 @@ export class Consumer { slot.handles.add(closed); // Counted, not subscribed: serving sessions decide blindness from the live discovery state. const announced = options.announced === true; - if (announced) slot.announced += 1; - else slot.blind += 1; - // An announced request is a watch: sessions ask their peer about this path while it lives. - let unwatch = announced ? this.#state.watch([path]) : undefined; + if (!announced) slot.blind += 1; + // Resolution owns discovery from the first ask, not just after a route arrives. + const unwatch = this.#state.watch([path]); this.#state.requests.mutate(() => {}); // Hand out a handle of the request's own rather than the table's. Closing a consumer @@ -1867,7 +1914,9 @@ export class Consumer { let logical: Front | undefined; const own = (resolution: Resolution | undefined): broadcast.Consumer | undefined => { if (released) return undefined; - const front = epoch === undefined || resolution?.epoch === epoch ? resolution?.front : undefined; + // A follower takes only a front something announced; a blind answer is for plain handles. + const offered = announced && !resolution?.source ? undefined : resolution?.front; + const front = epoch === undefined || resolution?.epoch === epoch ? offered : undefined; if (logical && source?.epoch !== undefined && resolution?.epoch === source.epoch) { // Between routes of the instance, readers wait for the next one to answer. if (front) logical.serve(front); @@ -1898,36 +1947,45 @@ export class Consumer { // holder that only ever peeked would then pin a route that has already been retracted // until it happened to read again. Following the route as well retires it promptly, // and the memo makes the two paths agree: whichever runs first does the swap. - // Any other request watches its path once it resolves through a discovered route, so that - // route stays discovered after whatever watch found it, such as a listing, is gone. - const discovered = (resolution: Resolution | undefined) => { - if (unwatch || !resolution?.front) return; - // Only a route a session received; a local broadcast or dynamic route needs no discovery. - const entry = this.#state.materialized.get(path)?.entry; - if (!entry || entry.identity !== resolution.source || !received(entry)) return; - unwatch = this.#state.watch([path]); + // A pending plain request reports absence, as Rust's request does, once discovery of + // its path has synced without a route for its instance. Sessions hold that sync from + // when the watch opens, so a fresh request waits for its peer's answer. A follower + // keeps waiting for a start, and a resolved request ends only with its instance. + const absent = () => { + if (released || closed.peek() !== undefined) return; + if (source) { + taken.absent.delete(absent); + return; + } + const resolution = route.peek(); + if (resolution && (epoch === undefined || resolution.epoch === epoch)) return; + if (!this.#state.synced(path)) return; + closed.set(unroutable()); + release(); }; - discovered(route.peek()); + if (!announced) taken.absent.add(absent); + const unsubscribe = route.subscribe((resolution) => { own(resolution); - discovered(resolution); + if (!announced) absent(); }); - return makeRequesting(relative, active, closed, () => { + const release = () => { // Releases this request's handle; the route itself belongs to the table. + if (released) return; released = true; unsubscribe(); + taken.absent.delete(absent); logical?.conclude(); logical = undefined; handle?.close(); handle = undefined; source = undefined; - unwatch?.(); + unwatch(); taken.handles.delete(closed); if (closed.peek() === undefined) closed.set(null); - if (announced) taken.announced -= 1; - else taken.blind -= 1; + if (!announced) taken.blind -= 1; this.#state.requests.mutate(() => {}); if (taken.handles.size > 0) return; @@ -1952,7 +2010,10 @@ export class Consumer { this.#state.releaseMaterialized(path); this.#state.forget(path); }); - }); + }; + + if (!announced) absent(); + return makeRequesting(relative, active, closed, release); } /** diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index c213af84b51..0e1d07a5e75 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -261,7 +261,7 @@ Every handle whose cleanup is `cancel()` is an async context manager, so exiting - **`OriginConsumer`**. Discover broadcasts. - `.announced(prefix, filter=None) → AnnounceConsumer` (async iterator of `AnnounceEvent`: `AnnounceEventStart`, `AnnounceEventUpdate`, `AnnounceEventEnd`, or `AnnounceEventRestart`, each carrying an `Announce` whose `.route.epoch` names the publisher run; on a restart, request the path again); `filter` is a pattern relative to the literal prefix, while each `Announce.prefix` stays origin-relative and `.captures` reports wildcard matches - `.announced_broadcast(path) → AnnouncedBroadcast` (awaitable, waits until something serves the path) - - `.request_broadcast(path) → BroadcastConsumer` (awaitable; announced now or a dynamic fallback, else raises) + - `.request_broadcast(path) → BroadcastConsumer` (awaitable; owns discovery and resolves one instance, or raises once synced without a route) ### Types diff --git a/quest/m1/api-audit/resolve.md b/quest/m1/api-audit/resolve.md index 7cce21a65ce..d0a7ea317fc 100644 --- a/quest/m1/api-audit/resolve.md +++ b/quest/m1/api-audit/resolve.md @@ -20,54 +20,57 @@ No caller can assemble a racy two-step resolve, and no crate hand-rolls Decided 2026-10-22 (API audit, maintainer approved the recommendation). -Rust `origin::Consumer` today has five overlapping operations -(`rs/moq-net/src/model/origin.rs`): `routed(path) -> Option` (swallows -errors), `follow(path) -> Follow` (route level), `routed_broadcast(path)` (no -epoch), `announced_broadcast(path, epoch)`, and `request_broadcast(path, -epoch)`. Per `rs/moq-net/MIGRATE.md`, `request_broadcast` on a client fails -`Unroutable` for a path no reader watches, even when the peer announces it, -and the bindings promote it as a top-level convenience. +The behavioral checkpoint makes `request_broadcast` own scoped discovery and +retry route churn. It reports table absence only after sync; a selected handler's +explicit refusal stays terminal, including a dropped Prepared answer. The front +records that refusal privately at its existing standing-route decision, rather +than guessing from unrelated mutations of the table. The old immediate lookup +is private to sessions. `Requesting::is_queued` and the public `Routing` task are +gone; `Requesting` is the owned task. The stats reader uses it instead of its +own retry on `is_queued`; the mux binding keeps its pinned `routed_broadcast` +wait. Rust and JS have same-epoch follow-return coverage, and every JS request +owns its discovery watch from creation. A pending plain JS request fails +`Unroutable` once that discovery syncs with no route for it, matching Rust. JS +announcement-following no longer silently uses a blind peer. The existing +`routed_broadcast` helper retains its route-change retry policy for the CLI, +gateway, mux binding, and relay HTTP consumers. Its removal belongs to the remaining rollout. -- Rust: `request(path, epoch) -> Pending` takes - `routed_broadcast`'s semantics plus the epoch pin and the synced - `Unroutable` answer, with no wall clock (relays never block on peers). - `follow(path, epoch)` is today's `announced_broadcast`. Delete `routed`, - `routed_broadcast`, and `Requesting::is_queued`. The immediate table lookup - (today's `request_broadcast`) and the route-level `Follow` become - `pub(crate)` for the sessions; route inspection stays where a consumer - needs it (the `routed()` callers in moq-cli reporting move to whatever - route observation remains public, or drop the report). -- JS (`js/net/src/origin.ts` `Consumer.request(path, {announced, epoch})`): - two methods, `request(path, {epoch})` and `follow(path, {epoch})`. Fix the - mismatch where `{announced: true, epoch}` closes when the instance ends - while Rust's pinned follow hands back the same instance if it returns. Drop - the silent fallback that turns `announced: true` into a blind request when - discovery is unavailable. `Producer.request`/`announced` pass-throughs stay - only if `Table` needs them. moq.pro's five `{announced: true}` sites move - to `follow`. -- Bindings: `request_broadcast(path, epoch)` and `announced_broadcast(path, - epoch)` map onto the two operations under the same names as Rust, and the - Kotlin, Dart, Go, and Python top-level shortcuts follow. -- Callers to fix: `rs/moq-wasm/src/lib.rs` (`routed()` then - `request_broadcast()`, error hidden by `.ok()`), `rs/moq-srt/src/ts.rs` - `Subscriber::new` (production), `rs/moq-cli/src/subscribe.rs` and - `report.rs`, `rs/moq-transcode/examples/transcode.rs`, - `rs/moq-bench/src/connection.rs`, the hand-rolled resolvers in - `rs/moq-mux/src/source.rs` (with `moq_mux::follow` on `announced_broadcast`), `rs/moq-hls/src/server/mod.rs` (wall-clock - `RESOLVE_TIMEOUT`) and `rs/moq-stats/src/aggregate.rs`, the - `rs/moq-relay/src/web.rs` fetch deadline, the `rs/moq-e2ee/MIGRATE.md` - advice to read the epoch via `routed()` (supersede it in the Impact bullet), and - `demo/carla/sim/moq_carla_sim/publish.py`, which reads the epoch from an - announce and then requests unpinned. +The approved public method names have not rolled out. What remains: -The prior audit's race claim is narrower than stated: discovery lingers 2 s -after `routed()` drops its follower, so the window is a route retraction or -failover between the two calls. +- Rust: name the owned operation `request(path, epoch)` and today's + `announced_broadcast` operation `follow(path, epoch)`. Keep the immediate + table lookup private. Delete `routed` and `routed_broadcast` and fix their + callers. Preserve terminal selected-handler refusals, private deferred + validity checks, and instance identity across route churn. +- Move the remaining route-level `Follow` consumers before making it private: + the moq-hls server's resolve and the tests that read its events. `moq play` + and `moqsrc` already follow through `moq_mux::Source::follow`. Do not add a + new public route API or compatibility shim to make the privatization pass. +- JS: expose `request(path, {epoch})` and `follow(path, {epoch})` instead of the + `announced` option and migrate actual callers. Keep the checkpoint's + 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. +- Bindings: mirror `request` and `follow`, including the optional epoch, in + the FFI and every actual wrapper/consumer. Regenerate from source, update + package migrations, and run all-language interop. Existing binding names + currently inherit the owned-discovery behavior, not the final naming. +- Callers: remove the racy two-step lookup and hidden error in moq-wasm, + route waits in moq-cli subscribe/report, and the HLS hand-rolled discovery + and `RESOLVE_TIMEOUT`. Review SRT, transcode, benchmark connections, relay + HTTP fetch deadlines, the e2ee epoch advice, and the demo's announce-derived + epoch pin. No caller should hand-roll synced resolution or rely on a wall + clock to decide table absence. -Tests: a lite client resolves an announced but unwatched path; a pinned -`follow` hands back the same instance when its route returns, in Rust and JS. +Tests cover an announced but unwatched path over lite-05/06/07-wip, Rust and JS +synced absence, discovery retention and release, pinned follow return, no follower +fallback on a blind peer, and unchanged explicit refusal. Finish the API and +caller rollout with the same lifecycle and churn checks, then the required +Nix gate and all-language interop. -Public API: breaking in moq-net, `@moq/net`, moq-ffi, and every wrapper. +Public API: breaking task shape in moq-net; behavior changes in `@moq/net` and +the bindings. Final method/epoch naming remains breaking across every wrapper. Wire: none. ## Related diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 603979dfcef..62b4b36445b 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -2138,12 +2138,10 @@ pub extern "C" fn moq_origin_announced_broadcast_cancel(task: u32) -> i32 { /// Request a broadcast from an origin by path, resolving as soon as it can be served. /// -/// Resolves against what is announced *now*, where [moq_origin_announced_broadcast] waits -/// indefinitely: it returns an announced broadcast at once, and fails when none is reachable, -/// including a broadcast created but not announced. It does NOT wait for a later -/// announcement. Serve on-demand paths with [moq_origin_requests]. A client session only -/// asks its peer about paths something watches, through [moq_origin_announced] or -/// [moq_origin_announced_broadcast], so a path nothing watches is unreachable on it. +/// Owns discovery of the path and retries route churn while resolving one publisher instance. +/// It fails as unroutable once discovery has synced without a covering route, including a +/// broadcast created but not announced. No separate announcement stream is needed. +/// Serve on-demand paths with [moq_origin_requests]. /// /// `on_broadcast` is invoked with a positive broadcast handle once served, then exactly once more /// with a terminal code: `0` (finished, including after [moq_origin_request_cancel]) or a negative diff --git a/rs/moq-ffi/src/origin.rs b/rs/moq-ffi/src/origin.rs index 8afc000e7c0..77944683067 100644 --- a/rs/moq-ffi/src/origin.rs +++ b/rs/moq-ffi/src/origin.rs @@ -464,10 +464,8 @@ impl MoqOriginConsumer { /// Follow the broadcast at `path`, resolving each publisher instance that serves it. /// - /// This is how you resolve a path right after connecting: announcements arrive over the - /// session after it opens, so `request_broadcast` on its own races them. A - /// broadcast created on this origin resolves once it is announced, like a - /// remote one. + /// Unlike `request_broadcast`, this waits for future announcements and keeps following + /// publisher instances. A local broadcast resolves once announced, like a remote one. pub fn announced_broadcast(&self, path: String) -> Result, MoqError> { let _guard = crate::ffi::enter(); self.driver.check()?; @@ -489,14 +487,9 @@ impl MoqOriginConsumer { /// Resolves through the best announced route covering the path: an announced broadcast /// on this origin, a route a session announced (served on demand by that session), or a /// dynamic handler on the origin. The most specific prefix wins, then the cheapest. An - /// unannounced broadcast is unroutable. Unlike `announced_broadcast`, this answers for what is - /// reachable *now* and errors if nothing can serve the path. Drop the returned future to - /// cancel. - /// - /// Calling this straight after connecting therefore races the session's announcements - /// and can report a live broadcast as unroutable. Await `announced_broadcast` first. A - /// client only asks the relay about paths something watches, through `announced` or - /// `announced_broadcast`, so a path nothing watches stays unroutable. + /// unannounced broadcast is unroutable once discovery has synced without a covering route. + /// The request owns discovery of its path and retries route churn until then; no separate + /// announcement stream is needed. Drop the returned future to cancel. pub async fn request_broadcast(&self, path: String) -> Result, MoqError> { let broadcast = self .driver diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 2234b94424f..747c01781c9 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -220,9 +220,8 @@ fn video_init(format: MoqVideoFormat, data: Vec) -> MoqVideoInit { /// Wait for `path` to be announced on `origin` and return its consumer. /// -/// A created broadcast becomes routable asynchronously, and resolving a reference goes through -/// `request_broadcast`, which reports a not-yet-announced path as unroutable rather than waiting. -/// So every broadcast a test resolves has to be awaited, not just the one it starts from. +/// A local reference published asynchronously may appear after discovery has synced empty. +/// These tests wait for that future announcement before resolving the reference. async fn await_announced(consumer: &MoqOriginConsumer, path: &str) -> Arc { let announced = consumer.announced_broadcast(path.into()).unwrap(); tokio::time::timeout(TIMEOUT, announced.available()) @@ -4711,7 +4710,7 @@ async fn cancel_retracts_the_route_synchronously() { let dynamic = serve(&origin, ""); let inner = origin.inner().consume(); - let queued = inner.request_broadcast("x", None).into_inner(); + let mut queued = inner.request_broadcast("x", None).into_inner(); assert!( queued.poll_ok(&kio::Waiter::noop()).is_pending(), "the route must serve while the handler lives" @@ -4719,7 +4718,7 @@ async fn cancel_retracts_the_route_synchronously() { drop(queued); dynamic.cancel(); - let verdict = inner.request_broadcast("y", None).into_inner(); + let mut verdict = inner.request_broadcast("y", None).into_inner(); match verdict.poll_ok(&kio::Waiter::noop()) { std::task::Poll::Ready(Err(moq_net::Error::Unroutable)) => {} std::task::Poll::Ready(Err(err)) => panic!("unexpected error: {err}"), diff --git a/rs/moq-mux/src/source.rs b/rs/moq-mux/src/source.rs index 385b2506e76..4931b2bf422 100644 --- a/rs/moq-mux/src/source.rs +++ b/rs/moq-mux/src/source.rs @@ -362,7 +362,7 @@ enum Bound { Ready(moq_net::broadcast::Consumer), /// A request issued when the binding was made, resolved once something announces the path. Requested { - routing: Box>, + routing: Box>, /// Where the answer is pinned, the first for its path winning. pins: Pins, path: moq_net::Path, diff --git a/rs/moq-net/benches/origin.rs b/rs/moq-net/benches/origin.rs index ccc8bf0157a..e9a3de89237 100644 --- a/rs/moq-net/benches/origin.rs +++ b/rs/moq-net/benches/origin.rs @@ -650,34 +650,40 @@ fn bench_subscribe(c: &mut Criterion) { /// depend on `publishers`. fn bench_request(c: &mut Criterion) { let mut group = c.benchmark_group("origin/request"); - // A request costs nothing per subscriber, so this sweeps the publisher counts - // in `SHAPES` rather than its shapes, whose last two share one. for publishers in [100, 1_000] { - let mut fleet = fanout(publishers, 0); - // A broadcast above the misses covers them without serving them. - let _covering = fleet.producer.publish("room", origin::Route::default()).unwrap(); - let waiter = kio::Waiter::noop(); - group.bench_function(BenchmarkId::new("local", publishers), |b| { - b.iter(|| { - let pending = fleet.consumer.request_broadcast("room/0", None); - // The front's driver resolves the first request; later ones join it. - fleet.driver.poll(moq_net::time::Instant::now(), &waiter).unwrap(); - pending - .now_or_never() - .expect("resolves once driven") - .expect("local broadcast"); + for requesters in [1, 8, 32] { + let mut fleet = fanout(publishers, 0); + let _covering = fleet.producer.publish("room", origin::Route::default()).unwrap(); + let waiter = kio::Waiter::noop(); + let shape = format!("{publishers}p_{requesters}r"); + group.throughput(Throughput::Elements(requesters)); + group.bench_function(BenchmarkId::new("local", &shape), |b| { + b.iter(|| { + let pending: Vec<_> = (0..requesters) + .map(|_| fleet.consumer.request_broadcast("room/0", None)) + .collect(); + fleet.driver.poll(moq_net::time::Instant::now(), &waiter).unwrap(); + for pending in pending { + pending + .now_or_never() + .expect("resolves once driven") + .expect("local broadcast"); + } + }); }); - }); - group.bench_function(BenchmarkId::new("unroutable", publishers), |b| { - b.iter(|| { - let result = fleet - .consumer - .request_broadcast("room/missing", None) - .now_or_never() - .expect("fails synchronously"); - assert!(matches!(result, Err(moq_net::Error::Unroutable))); + group.bench_function(BenchmarkId::new("unroutable", &shape), |b| { + b.iter(|| { + for _ in 0..requesters { + let result = fleet + .consumer + .request_broadcast("room/missing", None) + .now_or_never() + .expect("fails synchronously"); + assert!(matches!(result, Err(moq_net::Error::Unroutable))); + } + }); }); - }); + } } group.finish(); } diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index bef40fac89c..1a423f775e1 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -990,7 +990,8 @@ impl Publisher { else { return Ok(None); }; - let requesting = origin.request_broadcast(path, epoch); + // The immediate lookup: answering a peer never starts discovery of its own. + let requesting = origin.request(path.clone(), epoch.as_ref()); self.until_withdrawn(stream, |waiter| requesting.poll_ok(waiter)) .await .transpose() @@ -1407,7 +1408,7 @@ impl Publisher { )) }; // We just received a subscribe for this exact namespace, so the peer must have - // already seen the announcement. `request_broadcast` resolves it immediately, or + // already seen the announcement. The immediate lookup resolves it at once, or // falls back to the route covering it (an `origin::Requests`), if any. Pinned to // the instance it names, if any: another is refused, never served. let broadcast = match self.resolve(&mut stream, &msg.track_namespace, msg.epoch.clone()).await { diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index df8415c642f..c4d32173d53 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1564,7 +1564,7 @@ enum RequestState { /// broadcast (may wait on a dynamic handler). Resolve { msg: M, - requesting: Option, + requesting: Option, }, Serve(R), /// FIN the reply, and keep the request until the requester closes its side. @@ -1677,7 +1677,7 @@ impl RequestServe { RequestState::Resolve { msg, requesting } => { if requesting.is_none() { // The peer requested this exact path, so it has already seen an - // announcement for it. `request_broadcast` resolves it immediately, is + // announcement for it. The immediate lookup resolves it at once, is // served on demand by the route covering it (an `origin::Requests`), or // errors when there is none. let origin = ready!(self.shared.poll_serving_origin(waiter)); diff --git a/rs/moq-net/src/model/follow.rs b/rs/moq-net/src/model/follow.rs index 43763970379..c5ea1ee376a 100644 --- a/rs/moq-net/src/model/follow.rs +++ b/rs/moq-net/src/model/follow.rs @@ -1,7 +1,7 @@ use std::task::{Poll, ready}; use super::WeakEntry; -use super::origin_impl::{Announce, AnnounceConsumer, AnnounceEvent, Consumer, Routing}; +use super::origin_impl::{Announce, AnnounceConsumer, AnnounceEvent, Consumer, Requesting}; use crate::{Epoch, Error, Path, broadcast}; /// The announcements covering one path, as one broadcast coming online, being replaced, and @@ -202,7 +202,7 @@ pub struct AnnouncedBroadcast { /// An instance serves the path that was not handed out yet. unseen: bool, /// The resolution in flight, kept across a dropped wait so a retry picks it up. - resolving: Option, + resolving: Option, /// The broadcast handed out last, until the path goes offline. Weak, so it never keeps an /// instance the caller let go of from retiring. last: Option, @@ -589,6 +589,37 @@ mod tests { assert_ne!(current.info().epoch.as_ref(), Some(&epoch)); } + #[moq_clock::test] + async fn announced_pinned_hands_out_its_instance_after_a_gap() { + let origin = Hop::new(1).unwrap().produce(); + let epoch = Epoch::mint(); + let first = origin.publish("live", route(&epoch)).unwrap(); + let mut announced = origin.consume().announced_broadcast("live", epoch.clone()).unwrap(); + assert_eq!(available(&mut announced).await.info().epoch.as_ref(), Some(&epoch)); + first.unannounce(); + none(&mut announced).await; + first.announce(route(&epoch)).unwrap(); + assert_eq!(available(&mut announced).await.info().epoch.as_ref(), Some(&epoch)); + } + + #[moq_clock::test] + async fn announced_reports_a_dropped_prepared_answer() { + let origin = Hop::new(1).unwrap().produce(); + let claim = origin.requests("live").unwrap(); + let mut announced = origin.consume().announced_broadcast("live", None).unwrap(); + let (result, ()) = futures::join!( + moq_clock::timeout(Duration::from_secs(1), announced.available()), + async { + let prepared = requested(&claim).await.prepare(Epoch::mint()).unwrap(); + drop(prepared); + } + ); + assert!(matches!( + result.expect("the selected refusal must answer"), + Err(Error::Unroutable) + )); + } + /// A path no pattern can spell is refused rather than followed through the whole scope, /// where a route that never serves it could win its prefix. #[test] diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index 53e8f8a2143..caf9fc7d0d6 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -49,9 +49,12 @@ pub use timed::Timed; /// Publishing broadcasts, announcing routes, and consuming both through an origin. pub mod origin { pub use super::follow::AnnouncedBroadcast; + #[cfg(feature = "async")] + // private: capability gap + pub(crate) use super::origin_impl::Lookup; pub use super::origin_impl::{ Config, Consumer, Cost, Driver, HopLimit, Link, Preference, Prepared, Producer, Publication, Request, - Requesting, Requests, Route, Routing, Source, + Requesting, Requests, Route, Source, }; } diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 8ae96cf62a8..74084355d9c 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -3436,6 +3436,13 @@ async fn serve_front(task: FrontTask) -> Vec { loop { while let Some(event) = events.pop_front() { + let refused = matches!( + &event, + Event::Resolved { + result: Err(Refusal { standing: true, .. }), + .. + } + ); let answered = match &event { Event::TrackInfo { track, source, .. } => Some((track.clone(), *source)), _ => None, @@ -3700,6 +3707,7 @@ async fn serve_front(task: FrontTask) -> Vec { .fronts .remove_if(&(path.clone(), horizon), |front| front.request.same_channel(&request)); if let Ok(mut pending) = request.write() { + pending.refused = refused; pending.resolved.get_or_insert(Err(err.clone())); } // Ending the broadcast only retracts it: no new requesters or @@ -5412,6 +5420,8 @@ struct PendingFront { /// was minted for, then each one it selects. Written under the table's lock, so a /// request never joins a front that picked an instance the request saw beaten. selected: Instance, + /// The selected serving handler refused, rather than the route disappearing. + refused: bool, } /// What a front resolved: the instance its first source serves, and the route that @@ -5822,13 +5832,9 @@ impl Drop for Request { } } -/// The pollable result of [`Consumer::request_broadcast`]. -/// -/// Awaited via the [`kio::Pending`] wrapper; resolves to the [`broadcast::Consumer`] -/// immediately when the broadcast was already announced, or once a [`Requests`] -/// handler serves the request. Resolves to an error if the request is rejected or every -/// handler drops before serving it. -pub struct Requesting { +/// The immediate table lookup serving a peer without initiating application discovery. +// private: capability gap +pub(crate) struct Lookup { inner: RequestState, // The path the requester asked for, relative to its cursor's root. Stamped on the // resolved broadcast (see [`broadcast::Info::path`]) because a handler is free to @@ -5854,7 +5860,7 @@ enum RequestState { }, } -impl Requesting { +impl Lookup { fn failed(error: Error) -> Self { Self::new(RequestState::Failed(error)) } @@ -5863,18 +5869,6 @@ impl Requesting { Self::new(RequestState::Pending { front, broadcast }) } - /// Whether the request was handed to a serving route, rather than decided on - /// the spot. - /// - /// Fixed at request time, so it distinguishes the two ways - /// [`Error::Unroutable`] arises: a queued request that fails was killed by - /// its serving route retracting, and the table may already hold a - /// replacement worth retrying against (`Consumer::routed_broadcast` does), - /// while an unqueued failure means nothing could serve the path at all. - pub fn is_queued(&self) -> bool { - matches!(self.inner, RequestState::Pending { .. }) - } - fn new(inner: RequestState) -> Self { Self { inner, @@ -5933,7 +5927,7 @@ impl Requesting { } } -impl kio::Task for Requesting { +impl kio::Task for Lookup { type Output = Result; fn poll(&mut self, waiter: &kio::Waiter) -> Poll { @@ -5941,8 +5935,8 @@ impl kio::Task for Requesting { } } -/// The pollable result of [`Consumer::routed_broadcast`]. -pub struct Routing { +/// An owned broadcast resolution, driven by polling or awaiting it. +pub struct Requesting { consumer: Consumer, path: Path, // Asks sessions to discover the path for as long as this waits on it. @@ -5950,20 +5944,61 @@ pub struct Routing { // The covering routes, watched since the generation the last ask saw. watch: Option<(Watch, u64)>, // The ask in flight, dropped once it fails `Unroutable` until the routes move. - request: Option, + request: Option, // The publisher instance every ask is pinned to, if any. epoch: Option, + // A finite request owns discovery and can conclude absence once its initial set lands. + discovery: Option, + routed: bool, + // Legacy route-wait callers retry refusals only after the covering routes move. + terminal_refusal: bool, } -impl kio::Task for Routing { - type Output = Result; - - fn poll(&mut self, waiter: &kio::Waiter) -> Poll { +impl Requesting { + /// Poll for the requested instance, retrying only after its covering routes change. + pub fn poll_ok(&mut self, waiter: &kio::Waiter) -> Poll> { loop { + if let Some(discovery) = &mut self.discovery { + loop { + match discovery.poll_next(waiter) { + Poll::Ready(Some(AnnounceEvent::End(_))) => self.routed = false, + Poll::Ready(Some( + AnnounceEvent::Start(announce) + | AnnounceEvent::Restart(announce) + | AnnounceEvent::Update(announce), + )) => { + self.routed = self.epoch.is_none() || announce.route.epoch == self.epoch; + } + Poll::Ready(None) => return Poll::Ready(Err(Error::Closed)), + Poll::Pending => break, + } + } + // Sync is an event, not a deadline: sessions hold it from the moment the + // interest is created until the initial announcement set is delivered. + let synced = discovery.poll_synced(waiter).is_ready(); + if self.request.is_none() + && synced && (!self.routed || self.watch.as_ref().is_some_and(|(watch, seen)| watch.seen() == *seen)) + { + return Poll::Ready(Err(Error::Unroutable)); + } + } + match (&self.watch, &self.request) { (_, Some(request)) => match ready!(request.poll_ok(waiter)) { Ok(broadcast) => return Poll::Ready(Ok(broadcast)), - Err(Error::Unroutable) => self.request = None, + Err(Error::Unroutable) => { + // The front already distinguishes a selected handler's refusal + // from route churn; retain that verdict rather than infer it from + // unrelated changes a prepared answer makes to the table. + let refused = match &request.inner { + RequestState::Pending { front, .. } => front.read().refused, + RequestState::Failed(_) => false, + }; + if self.terminal_refusal && refused { + return Poll::Ready(Err(Error::Unroutable)); + } + self.request = None; + } Err(err) => return Poll::Ready(Err(err)), }, (Some((watch, seen)), None) => { @@ -5992,7 +6027,7 @@ impl kio::Task for Routing { }; let watch = table.watch(&self.consumer.shared, &resolved); let seen = watch.seen(); - if self.interest.is_none() && self.consumer.interested { + if self.interest.is_none() && self.discovery.is_none() && self.consumer.interested { let resolved = resolved.clone(); self.interest = Some(Interest::new(&mut table, &self.consumer.shared, resolved)); } @@ -6009,6 +6044,14 @@ impl kio::Task for Routing { } } +impl kio::Task for Requesting { + type Output = Result; + + fn poll(&mut self, waiter: &kio::Waiter) -> Poll { + self.poll_ok(waiter) + } +} + /// Derive a read view from a handle. /// /// Lets APIs accept either a producer or a consumer (e.g. @@ -6461,37 +6504,41 @@ impl Consumer { /// [`Error::Unauthorized`] for a path outside this consumer's scope, /// [`Error::Closed`] once the origin closes, and any other resolution /// failure as-is. Await it, or poll it through [`kio::Task`]. - pub fn routed_broadcast(&self, path: impl TryInto>) -> kio::Pending { - let routing = match path::convert(path) { + pub fn routed_broadcast(&self, path: impl TryInto>) -> kio::Pending { + let mut request = match path::convert(path) { Ok(path) => self.routing(path, None), - Err(err) => Routing { - consumer: self.clone(), - path: Path::empty(), - interest: None, - watch: None, - request: Some(Requesting::failed(err)), - epoch: None, - }, + Err(err) => self.failed(err), }; - kio::Pending::new(routing) + request.terminal_refusal = false; + kio::Pending::new(request) } - /// [`Self::routed_broadcast`], refusing any instance but `epoch` when one is pinned. - pub(super) fn routing(&self, path: Path, epoch: Option) -> Routing { + /// A resolution that already failed with `err`. + fn failed(&self, err: Error) -> Requesting { + let mut request = self.routing(Path::empty(), None); + request.request = Some(Lookup::failed(err)); + request + } + + /// Resolve a routed instance, returning a selected handler's refusal directly. + pub(super) fn routing(&self, path: Path, epoch: Option) -> Requesting { // The scope keeps narrower permissions intact: if the whole path is not // reachable, no route can ever cover it, so bail rather than loop forever. let request = match self.root.join(&path) { Ok(named) if self.scope.permits(&named) => None, - Ok(_) => Some(Requesting::failed(Error::Unauthorized)), - Err(err) => Some(Requesting::failed(err.into())), + Ok(_) => Some(Lookup::failed(Error::Unauthorized)), + Err(err) => Some(Lookup::failed(err.into())), }; - Routing { + Requesting { consumer: self.clone(), path, interest: None, watch: None, request, epoch, + discovery: None, + routed: false, + terminal_refusal: true, } } @@ -6499,7 +6546,7 @@ impl Consumer { /// /// The Rust form of JS `request(path, { announced: true })`. The first /// [`available`](AnnouncedBroadcast::poll_available) resolves the instance serving the path - /// once one is announced, riding out churn as [`Self::routed_broadcast`] does. Each + /// once one is announced, retrying route churn but returning a selected handler's refusal. Each /// later call waits for another instance to take over (an /// [`AnnounceEvent::Restart`]), or for the path to be served again after an /// [`AnnounceEvent::End`], even by the same instance. Drop what was read from the @@ -6567,13 +6614,11 @@ impl Consumer { /// when requesting and when an asynchronous answer resolves. `None` leaves lookup /// unpinned. A pinned request never resumes on a route whose epoch disappeared. /// - /// The returned future fails with [`Error::Unroutable`] at once when no - /// announced route covers the path, including a broadcast created on this - /// origin but not announced. A client session only discovers what this - /// origin's readers watch, so a path no [`Self::announced`], - /// [`Self::routed_broadcast`], or [`Self::announced_broadcast`] watches is - /// unroutable on it. A broadcast resolved through a discovered route keeps its - /// path watched until dropped. + /// The request owns discovery for its path and retries when its covering routes change. + /// It reports [`Error::Unroutable`] once discovery has synced without a covering route + /// for the requested instance. A selected handler's explicit refusal is returned as-is. + /// A broadcast resolved through a discovered route keeps + /// its path watched until dropped; no separate announcement watcher is needed. /// A route claims capability, not inventory: resolving a covered path /// succeeds optimistically, and a path that names nothing surfaces as /// [`Error::NotFound`] on its tracks instead. @@ -6582,23 +6627,39 @@ impl Consumer { path: impl TryInto>, epoch: impl Into>, ) -> kio::Pending { - let epoch = epoch.into(); - match path::convert(path) { - Ok(path) => self.request(path, epoch.as_ref()), - Err(err) => kio::Pending::new(Requesting::failed(err)), + let path = match path::convert(path) { + Ok(path) => path, + Err(err) => return kio::Pending::new(self.failed(err)), + }; + let mut routing = self.routing(path.clone(), epoch.into()); + match self.follow(&path) { + Ok(discovery) => { + routing.discovery = Some(discovery); + if let Some(resolved) = self.root.join(&path).ok().and_then(|named| self.scope.resolve(&named)) { + let mut table = self.shared.lock(); + let watch = table.watch(&self.shared, &resolved); + let seen = watch.seen(); + drop(table); + routing.watch = Some((watch, seen)); + } + // A requests handler hears an already-routed request at creation time. + routing.request = Some(self.request(path, routing.epoch.as_ref()).into_inner()); + } + Err(err) => routing.request = Some(Lookup::failed(err)), } + kio::Pending::new(routing) } /// [`Self::request_broadcast`], refused with [`Error::Unroutable`] unless the /// winning route serves `epoch`: a peer asking for one publisher instance must /// not be handed another. - pub(crate) fn request(&self, path: Path, epoch: Option<&crate::Epoch>) -> kio::Pending { + pub(crate) fn request(&self, path: Path, epoch: Option<&crate::Epoch>) -> kio::Pending { // The path as this handle names it, absolute: what its scope authorizes and // what its egress is counted under, so a read through a mount bills where // the reader asked. let named = match self.root.join(&path) { Ok(named) => named, - Err(err) => return kio::Pending::new(Requesting::failed(err.into())), + Err(err) => return kio::Pending::new(Lookup::failed(err.into())), }; let scope = self.stats.egress(&named); // The resolved handle is named by what *this* cursor asked for, not by the absolute @@ -6608,20 +6669,20 @@ impl Consumer { // Routes only cover paths within this consumer's scope. if !self.scope.permits(&named) { - return kio::Pending::new(Requesting::failed(Error::Unauthorized)); + return kio::Pending::new(Lookup::failed(Error::Unauthorized)); } // Key requests by the absolute path on the origin, past any mount, so scoped, // rooted, and mounted consumers and handlers agree on the same entry and front. let Some(absolute) = self.scope.resolve(&named) else { - return kio::Pending::new(Requesting::failed(BoundsExceeded.into())); + return kio::Pending::new(Lookup::failed(BoundsExceeded.into())); }; let mut state = self.shared.lock(); // The origin's driver dropped: nothing will ever serve this. if state.closed { - return kio::Pending::new(Requesting::failed(Error::Closed)); + return kio::Pending::new(Lookup::failed(Error::Closed)); } let horizon = self.horizon.effective(&state.routes, &absolute); @@ -6631,7 +6692,7 @@ impl Consumer { // route retracted takes no newcomers. let best = match state.best_route(&absolute, horizon, &HashSet::new(), |_| true) { Some(best) if epoch.is_none_or(|epoch| best.epoch.as_ref() == Some(epoch)) => best.instance(), - _ => return kio::Pending::new(Requesting::failed(Error::Unroutable)), + _ => return kio::Pending::new(Lookup::failed(Error::Unroutable)), }; // Join the live front for this path and horizon, if any: its watcher @@ -6660,7 +6721,7 @@ impl Consumer { if let Some(held) = held { state.next_route += 1; front.joined.store(state.next_route, Ordering::Release); - let pending = Requesting::queued(front.request.consume(), held) + let pending = Lookup::queued(front.request.consume(), held) .with_path(requested) .with_stats(scope) .with_epoch(epoch.cloned()); @@ -6684,6 +6745,7 @@ impl Consumer { let request = kio::Producer::new(PendingFront { resolved: None, selected: best, + refused: false, }); let consumer = request.consume(); // The front starts held by this request; see [`Front::new`]. @@ -6716,7 +6778,7 @@ impl Consumer { self.tasks.clone(), )); kio::Pending::new( - Requesting::queued(consumer, held) + Lookup::queued(consumer, held) .with_path(requested) .with_stats(scope) .with_epoch(epoch.cloned()), @@ -9562,6 +9624,7 @@ mod tests { request: kio::Producer::new(PendingFront { resolved: None, selected: Instance::Route(0), + refused: false, }), joined: Arc::default(), timers: consumer.timers.clone(), diff --git a/rs/moq-net/tests/integration/lazy_discovery.rs b/rs/moq-net/tests/integration/lazy_discovery.rs index e93c48af9c8..d7b6bba54d9 100644 --- a/rs/moq-net/tests/integration/lazy_discovery.rs +++ b/rs/moq-net/tests/integration/lazy_discovery.rs @@ -85,13 +85,18 @@ impl Lazy { .announced() } - /// Whether the client's origin routes `path` right now. + /// Inspect the current table without running discovery for the observation itself. async fn routes(&self, path: &str) -> bool { - match self.subscriber.consume().request_broadcast(path, None).await { - Ok(_) => true, - Err(Error::Unroutable) => false, - Err(err) => panic!("{path}: {err}"), - } + let consumer = self + .subscriber + .consume() + .scope("", &Patterns::from(Pattern::literal(path).unwrap())) + .unwrap(); + let mut announced = consumer.announced(); + matches!( + announced.poll_next(&kio::Waiter::noop()), + std::task::Poll::Ready(Some(announce::Event::Start(_))) + ) } } @@ -352,10 +357,57 @@ async fn serving_the_peer_asks_nothing() { .filter(|kind| *kind == ANNOUNCE) .count(); assert_eq!(requests, 0, "{version}"); - assert!(matches!( - local.consume().request_broadcast("a/x", None).await, - Err(Error::Unroutable) - )); + // An application request is a reader, unlike the peer's serving view. + let _read = local.consume().request_broadcast("a/x", None).await.unwrap(); + let requests = pair + .client_transport + .bidi_types() + .into_iter() + .filter(|kind| *kind == ANNOUNCE) + .count(); + assert_eq!(requests, 1, "{version}: only the application request starts discovery"); + } +} + +/// Resolving a path owns the discovery that makes the peer's announcement visible. +#[moq_clock::test] +async fn requesting_an_unwatched_path_discovers_its_instance() { + for version in VERSIONS { + let lazy = Lazy::new(version).await; + assert_eq!(lazy.requests(), 0, "{version}"); + let broadcast = lazy + .subscriber + .consume() + .request_broadcast("a/x", None) + .await + .expect("request discovers the announced instance without a separate watcher"); + assert_eq!(broadcast.info().path.as_str(), "a/x"); + assert_eq!(lazy.requests(), 1, "{version}"); + } +} + +/// Absence is answered by the peer's sync boundary, without a timer in resolution. +#[moq_clock::test] +async fn an_unwatched_missing_path_is_unroutable_after_sync() { + for version in VERSIONS { + let lazy = Lazy::new(version).await; + let result = moq_clock::timeout(SETTLE, lazy.subscriber.consume().request_broadcast("missing", None)) + .await + .expect("the peer synced"); + assert!(matches!(result, Err(Error::Unroutable)), "{version}"); + assert_eq!(lazy.requests(), 1, "{version}"); + let broadcast = lazy.subscriber.consume().request_broadcast("a/x", None).await.unwrap(); + moq_clock::sleep(LINGERED).await; + assert!( + lazy.routes("a/x").await, + "{version}: request ownership keeps discovery alive" + ); + drop(broadcast); + moq_clock::sleep(LINGERED).await; + assert!( + !lazy.routes("a/x").await, + "{version}: dropping the last reader releases discovery" + ); } } diff --git a/rs/moq-net/tests/integration/model.rs b/rs/moq-net/tests/integration/model.rs index 5dbcf90053c..f3e656685ed 100644 --- a/rs/moq-net/tests/integration/model.rs +++ b/rs/moq-net/tests/integration/model.rs @@ -29,7 +29,7 @@ fn origin_front_serves_media_with_only_explicit_polls() { broadcast.announce(origin::Route::default()).unwrap(); // Resolving and subscribing pass through the origin's core front tasks. - let requesting = origin.consume().request_broadcast("room/live", None); + let mut requesting = origin.consume().request_broadcast("room/live", None); assert!(requesting.poll_ok(&waiter).is_pending()); driver.poll(now, &waiter).unwrap(); let receiving: broadcast::Consumer = ready(requesting.poll_ok(&waiter)).unwrap(); diff --git a/rs/moq-stats/src/aggregate.rs b/rs/moq-stats/src/aggregate.rs index ae48146fefc..ff2bec1d472 100644 --- a/rs/moq-stats/src/aggregate.rs +++ b/rs/moq-stats/src/aggregate.rs @@ -709,15 +709,8 @@ impl Shape for Grouped { /// One node's subscription to the merged track. enum Reader { - /// Resolving the announced path into a broadcast. `queued` records whether - /// the request was handed to a serving route (fixed at request time): a - /// queued request that fails `Unroutable` was killed by its serving route - /// retracting (the table has already changed), while an unqueued - /// `Unroutable` means nothing serves the path at all. - Resolving { - pending: Pending, - queued: bool, - }, + /// Resolving the instance while owning discovery and retrying route churn. + Resolving(Box>), /// Waiting for the node's listing to offer the track. Waiting, /// Awaiting the subscription handshake. @@ -1033,7 +1026,7 @@ fn advance( } match &mut node.reader { - Reader::Resolving { pending, queued } => match pending.poll_ok(waiter) { + Reader::Resolving(pending) => match pending.poll_ok(waiter) { // An unpinned retry on a known lineage can reach a replacement publisher // before its announcement drains here. Its counters belong to its own entry, // which that announcement creates, so this lineage keeps its last frame. @@ -1067,15 +1060,6 @@ fn advance( return changed | node.depart(); } }, - // A queued request killed by its route retracting: an identical - // standby swaps in without any announce update, so re-resolve - // through the already-updated table. Each retry consumed a real - // retraction, so this cannot spin; an instant Unroutable instead - // means nothing serves the path (the retraction that empties the - // table also unannounces this node). - Poll::Ready(Err(moq_net::Error::Unroutable)) if *queued => { - node.reader = resolve(origin, &node.path, node.epoch.clone()); - } Poll::Ready(Err(err)) => { tracing::debug!(?err, name, "stats: node broadcast unresolvable"); return changed | node.depart(); @@ -1166,8 +1150,7 @@ fn advance( /// Start resolving `path` (relative to the announce cursor) into a broadcast. fn resolve(origin: &origin::Consumer, path: &Path, epoch: Option) -> Reader { let pending = origin.request_broadcast(path, epoch); - let queued = pending.is_queued(); - Reader::Resolving { pending, queued } + Reader::Resolving(Box::new(pending)) } #[cfg(test)] @@ -1746,7 +1729,7 @@ mod tests { .announce(origin::Route::default().with_epoch(epoch_b.clone())) .unwrap(); new.publish("acme/room", 30); - let pending = origin.consume().request_broadcast(".stats/node/a", None); + let mut pending = origin.consume().request_broadcast(".stats/node/a", None); let front = futures::executor::block_on(kio::wait(|waiter| { driver.poll(now, waiter).unwrap(); pending.poll_ok(waiter)