diff --git a/demo/web/src/index.ts b/demo/web/src/index.ts index ba610880327..7c52e99a516 100644 --- a/demo/web/src/index.ts +++ b/demo/web/src/index.ts @@ -190,7 +190,7 @@ discovery.run((effect) => { for (;;) { const entry = await Promise.race([effect.cancel, announced.next()]); if (!entry) break; - const path = Net.Path.join(prefix, entry.path); + const path = Net.Path.join(prefix, entry.prefix); // Only `.hang` broadcasts are watchable streams; this skips the relay's // `.stats` broadcast (see the stats dashboard demo for that one). if (!path.endsWith(".hang")) continue; diff --git a/demo/web/src/stats.ts b/demo/web/src/stats.ts index 11aa846a2a5..e5c9aefee86 100644 --- a/demo/web/src/stats.ts +++ b/demo/web/src/stats.ts @@ -109,9 +109,9 @@ discovery.run((effect) => { for (;;) { const entry = await Promise.race([effect.cancel, announced.next()]); if (!entry) break; - const node = entry.path as string; + const node = entry.prefix as string; if (!node) continue; - const path = Net.Path.join(prefix, entry.path); + const path = Net.Path.join(prefix, entry.prefix); if (entry.active) { if (subs.has(node)) continue; diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 4cdcc26c7d2..483b37a32b0 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -374,36 +374,33 @@ Rules worth knowing: ### Redundant Publishers (1+1) -Relays key a broadcast's content identity on the publisher's Hop ID (the -first hop of its announcements). Two publishers of the same broadcast that -share an id are treated as interchangeable sources: relays hold both routes -and fail over between them at a group boundary, so killing one leaves viewers -running off the other. - -Sharing an id is a promise: the publishers MUST produce the same broadcast, -meaning the same track names carrying the same content, with group sequences -aligned on the same boundaries. Relays may switch between same-id sources -whenever routing prefers another (not only on failure), splicing at the next -group boundary, so encoders that drift (for example segment-numbered tracks -from processes started at different times) tear down subscribers on the -switch. Independent publishers with different tracks or timelines MUST use -different Hop IDs; the newcomer then takes the broadcast over instead of -joining. Run the same command from two aligned encoders, pinning the same id -on both: +An announcement's route names the publisher's Hop ID as its first hop. +Two publishers of the same broadcast that share an id (and cost) advertise +identical routes, which relays deduplicate: the mesh sees one route while +either publisher is alive, so killing one retracts nothing and the survivor +keeps serving. + +A relay never splices a live subscription from one publisher to another. +When the publisher serving a subscription goes away, that subscription ends +and the viewer re-subscribes, landing on the best remaining route; players do +this automatically when the path is (still) announced. So 1+1 buys a fast +resubscribe instead of a dead stream, not a seamless mid-group handover, and +the two encoders should still produce equivalent broadcasts (same track +names, comparable timelines) so a viewer that fails over keeps decoding. Run +the same command from two encoders, pinning the same id on both: ```bash moq --hop 42 --connect https://relay-a.example.com/anon --broadcast event.hang import ts moq --hop 42 --connect https://relay-b.example.com/anon --broadcast event.hang import ts ``` -Leave `--hop` unset everywhere else. The default fresh id per run is what -makes a restarted encoder look like new content (ending subscriptions and -invalidating caches) instead of silently splicing mid-stream. A publisher with -a *different* id takes the broadcast over the moment it announces, ending the -incumbent rather than waiting behind it, so a reconnect is live again without -waiting for the relay's transport to time out the connection it replaced. The -last publisher to announce a path owns it, so use authorization to decide who -may publish where. +Leave `--hop` unset everywhere else. The Hop ID also feeds loop +detection: a relay drops announcements whose route already contains its own +id, so reusing one id across unrelated publishers can make their routes +invisible to each other. New subscriptions always resolve through the best +current route, newest first on a tie, so a restarted publisher serves new +viewers the moment it announces; use authorization to decide who may publish +where. ### Capture a Webcam diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index cd3c9344d24..5c5715b6af7 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -7,7 +7,7 @@ description: Run multiple moq-relay instances across multiple hosts/regions Relays can be joined together to proxy announcements and subscriptions between each other. A viewer talks to whichever relay is closest; if their broadcast lives somewhere else in the cluster, the local relay fetches it from a neighbor and caches it. -A broadcast carries a small hop list as it travels. Each relay it passes through adds itself to the list, which is how loops are caught and how the network picks the shortest path when there's more than one. When two paths are the same length, every relay breaks the tie the same way (a hash of the broadcast name and hop list), so the whole cluster converges on one route instead of flapping between equals. +An announcement carries a small hop list as it travels. Each relay it passes through adds itself to the list, which is how loops are caught and how the network picks the shortest path when there's more than one. When two paths are the same length, every relay breaks the tie the same way (a hash of the announced prefix and hop list), so the whole cluster converges on one route instead of flapping between equals. Both wire protocols carry this. `moq-lite` has the hop list and route cost in its announcements natively; `moq-transport` gets them from the [MoQ Cluster extension](/draft/moq-cluster), negotiated per session on `moqt-17` and later. A peer that doesn't speak the extension still works, it just contributes no path or price of its own. @@ -53,22 +53,13 @@ connect = [ Price is per direction. Pulling from a metered origin can cost far more than pushing to it, so each end declares its own and the two need not match; a relay that receives a price it disagrees with keeps its own `?cost=` for its own routing. An unpriced direction costs 1, which reproduces plain hop counting. -The cost a relay advertises is the *marginal* cost of pulling the broadcast through it. A relay actively carrying a broadcast (a subscriber is pulling it) re-announces it at cost 0: its upstream fetch is already paid for, so a sibling should pull the warm copy over a free intra-DC link instead of opening a second metered fetch. When the last subscriber leaves, the cost decays back after a short grace period. Standby publishers (e.g. a transcoder pool) can seed a large cost so they are only selected when nothing cheaper exists, and the winner's cost drops to 0 once it starts working. +The cost a relay advertises for a route is the accumulated price of the links it crossed: each relay adds the `?cost=` of the link an announcement arrived on before forwarding it. Routing prefers the most specific announced prefix, then the lowest cost, then the shortest hop list; a remaining tie breaks toward the newest announcement, so a reconnecting publisher is not outranked by the stale session it replaced. -That discount is what makes the cluster share one copy, but it also erases something. Once several relays are all carrying the broadcast they *all* advertise 0, so asking "what does this cost you?" gets the same answer everywhere and can no longer say which of them ought to be the one doing the pulling. +`moq-lite-06` announcements actually carry two prices, *warm* and *cold*: what one more subscription would cost the mesh right now, versus what the same path would cost if nothing along it were cached. The protocol lets a relay that is already carrying content discount its warm price to 0, so a cluster can consolidate onto one warm copy while the cold price still ranks the carriers (see the [moq-lite draft](/draft/moq-lite)). moq-relay does not implement that discount yet: it forwards both prices accumulated, so today they rank identically and routing runs on configured link costs alone. -So `moq-lite-06` announcements carry two prices instead of one: +Prices are not static. A publisher can re-price a live announcement, for example a standby transcoder pool that seeds a large cost so it is only selected when nothing cheaper exists and lowers it once it starts working. A relay that receives a GOAWAY from a peer re-prices every route learned from it to the maximum cost, steering new subscriptions elsewhere while existing ones finish. -- **warm**: what pulling costs right now, given which relays already have it. Zero at any relay that is carrying. This is the number routing minimizes, and it is what consolidates the fleet onto one copy. -- **cold**: what the same route would cost if no relay had it. It ignores the discounts entirely, so it does not collapse, and it keeps saying how far each relay sits from the publisher. - -The first picks where a relay fetches from. The second picks which relay does the fetching: a carrying relay hands its subscribers over to another carrying relay only when that one's cold price is lower, so the relay nearest the publisher becomes the aggregation point and the rest consolidate onto it. Relays equally far from the publisher tie there and fall back to a hash of the broadcast path, which spreads ownership across the fleet instead of funneling every broadcast onto one of them. - -Both matter. Without the warm price every relay opens its own fetch and the backbone carries N copies. Without the cold price the relays that are already carrying cannot be told apart, so the aggregation point lands wherever a coin flip puts it, which can leave a relay one cheap link from the publisher pulling through a relay several expensive links away. - -A relay waits about half a second before moving onto another relay, and re-checks when the wait is up. Prices are reported, not observed, so a report still crossing the mesh can be cheaper than what its sender would say now, and while prices are rising a ring of relays could otherwise each defer to a stale neighbour and all let go at once, leaving nobody pulling. The wait outlasts that propagation, so the re-check runs on current prices, and it carries a small per-relay spread so a whole PoP does not reconsider on the same instant. Some moves never wait: reconnecting to the peer you were already pulling from (recognized by its declared identity, so a relay that withheld one waits like anything else), and repairs, meaning replacing a route that has vanished or stopped announcing, which would otherwise keep the relay on a dead source while a live one sits in the table. Leaving a *draining* route does wait, because a relay that received a GOAWAY keeps serving until its handover window closes, and a fleet draining together is exactly when relays re-parent off prices that have not landed. If the drain turns into a disconnection the route vanishes, and that case is immediate, so the wait is never longer than the session it is waiting on. Only trading a working upstream for a better one waits, and that includes a relay with no viewers, whose choice is simply the one it will pull down when a viewer arrives. - -`moq-transport` has nowhere to carry the cold price, so those routes keep the older coin-flip behavior. +`moq-transport` has nowhere to carry the cold price, so a route learned from it ranks with an unknown (worst-case) cold cost. ## Auto-discovery diff --git a/doc/concept/layer/moq-lite.md b/doc/concept/layer/moq-lite.md index 0fbca72e536..0f923f1b46d 100644 --- a/doc/concept/layer/moq-lite.md +++ b/doc/concept/layer/moq-lite.md @@ -58,21 +58,26 @@ Transports that don't carry a request URI (native QUIC, or qmux over TCP/TLS) al ### Announcements -`moq-lite` optionally supports live discovery of broadcasts. +`moq-lite` optionally supports live discovery via announcements. -Depending on the language, there's an `announced(prefix: Path)` method on the session. -This asks the peer to notify us of any existing broadcasts that match the prefix and any future updates. +An announcement is a **route**: a claim that broadcasts under a path prefix can be served. +Depending on the language, there's an `announce(prefix)` method on the publishing side and an `announced(prefix)` method on the session. +The latter asks the peer for every route that intersects the prefix, plus any future updates. + +By convention a publisher announces each broadcast's exact path, so subscribers can enumerate broadcasts by iterating routes. +But a route can also cover a whole subtree: a dashboard server announces one short prefix and serves whatever broadcast is requested beneath it, with no per-broadcast announcement. +It's up to the application to decide that an announced path is a broadcast and request it. This is extremely useful for conference rooms, as you can live discover when participants join and leave. It's also useful for individual broadcasts as you can get notifications it comes online or goes offline (no spamming F5). The [moq-relay clustering](/bin/relay/cluster) feature actually uses this to discover other nodes in the cluster AND what broadcasts are available on each node. -The peer first replies with the set of broadcasts that are currently live, then streams updates as they change. +The peer first replies with the set of routes that are currently advertised, then streams updates as they change. This initial set is a discrete batch: the latest draft reports how many entries to expect up front, so a freshly connected session can wait until that snapshot has fully arrived before listing what's available, rather than racing the gossip. -Each announcement also describes the route it took: the chain of relay identities it passed through (which is how forwarding loops are caught) and what pulling the broadcast via that route would cost. +Each route also describes the path it took: the chain of relay identities it passed through (which is how forwarding loops are caught) and what pulling content via that route would cost. The cost comes in two magnitudes, compared in order. -The *warm* cost is what one more subscription would cost the mesh right now, so it collapses to zero at any relay already carrying the broadcast; that is what lets a cluster deduplicate onto a warm copy instead of opening a second ingest. +The *warm* cost is what one more subscription would cost the mesh right now, so it collapses to zero at any relay already carrying the content; that is what lets a cluster deduplicate onto a warm copy instead of opening a second ingest. The *cold* cost prices the same path as if nothing were cached, so when two warm relays tie at zero it still says which of them sits closer to the publisher. Subscribers route to the lowest warm cost and break ties on cold; [moq-relay clustering](/bin/relay/cluster) covers how relays use this to pick an aggregation point. diff --git a/doc/lib/go/moq.md b/doc/lib/go/moq.md index 8e319209cc5..d4cfe17190d 100644 --- a/doc/lib/go/moq.md +++ b/doc/lib/go/moq.md @@ -49,9 +49,14 @@ for ann, err := range announced.All(ctx) { } log.Fatal(err) } - fmt.Println("got broadcast", ann.Path()) + // An announcement is a route; its path is relative to the prefix. + fmt.Println("got route", ann.Path()) - catalog, err := ann.Broadcast().Catalog(ctx) + broadcast, err := client.RequestBroadcast("demos/" + ann.Path()) + if err != nil { + log.Fatal(err) + } + catalog, err := broadcast.Catalog(ctx) if err != nil { log.Fatal(err) } diff --git a/doc/lib/js/@moq/net.md b/doc/lib/js/@moq/net.md index 85128acc232..2a306111c3a 100644 --- a/doc/lib/js/@moq/net.md +++ b/doc/lib/js/@moq/net.md @@ -75,6 +75,8 @@ request.close(); // when done Use `origin.announced(prefix)` to discover what is available rather than asking for a path you already know. +`origin.announce(prefix, provider)` is the other half: advertise that paths under a prefix can be served, handing back a broadcast from `provider.consume(path)` for whatever is requested beneath it. Publishing a broadcast announces its exact path already, so reach for this when one service covers a whole subtree. The returned dispose retracts the route. + ### Broadcasts A collection of related tracks. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 51ef3dae6c5..8af21f13bc2 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -41,9 +41,11 @@ import kotlinx.coroutines.flow.collect Moq.connect("https://relay.example.com").use { moq -> moq.announcements("demos/").collect { announcement -> - println("got broadcast ${announcement.path()}") + // The announced path is relative to the prefix. + println("got route ${announcement.path()}") - announcement.broadcast().subscribeCatalog().updates().collect { catalog -> + val broadcast = moq.requestBroadcast("demos/" + announcement.path()) + broadcast.subscribeCatalog().updates().collect { catalog -> println("catalog: $catalog") } } diff --git a/doc/lib/kt/moq.md b/doc/lib/kt/moq.md index 0df92144647..d46e46d7cda 100644 --- a/doc/lib/kt/moq.md +++ b/doc/lib/kt/moq.md @@ -95,8 +95,11 @@ import kotlinx.coroutines.flow.collect Moq.connect("https://relay.example.com").use { moq -> moq.announcements("demos/").collect { announcement -> + // An announcement is a route; resolve its path into a broadcast. + val broadcast = moq.requestBroadcast("demos/" + announcement.path()) + // Convenience: subscribe and grab the current catalog. - val catalog = announcement.broadcast().catalog() + val catalog = broadcast.catalog() println("catalog: $catalog") } } @@ -105,7 +108,7 @@ Moq.connect("https://relay.example.com").use { moq -> Raw track subscribers can query the publisher's track properties and change their own delivery preferences without resubscribing: ```kotlin -val track = announcement.broadcast().subscribeTrack( +val track = broadcast.subscribeTrack( "events", Subscription(priority = 10u.toUByte()), ) @@ -116,7 +119,7 @@ track.update(Subscription(priority = 20u.toUByte())) A catalog rendition may name a *different* broadcast: `MoqVideo.broadcast` / `MoqAudio.broadcast` is a path relative to the broadcast the catalog came from, so a transcode output at `live/hd` can describe a track that actually lives in `live/source`. `decodeAudio` and `decodeVideo` follow it for you. `subscribeMedia`, `subscribeTrack`, `fetchGroup`, and `fetchMediaGroup` take a track name rather than a rendition, so resolve first: ```kotlin -val source = announcement.broadcast().resolve(rendition.broadcast) +val source = broadcast.resolve(rendition.broadcast) val consumer = source.subscribeMedia(name, rendition.container) ``` diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 8347085de66..3b89d5948b3 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -54,10 +54,11 @@ import moq async def main(): async with moq.Client("https://cdn.moq.dev/anon") as client: async for announcement in client.announced(): - catalog = await announcement.broadcast.catalog() + broadcast = await client.request_broadcast(announcement.path) + catalog = await broadcast.catalog() for name in catalog.audio: - async for frame in announcement.broadcast.subscribe_media(name): + async for frame in broadcast.subscribe_media(name): print(f"frame: {len(frame.payload)} bytes, ts={frame.timestamp_us}") asyncio.run(main()) diff --git a/doc/lib/py/moq-rs.md b/doc/lib/py/moq-rs.md index c6b37b5e800..a62903b8d42 100644 --- a/doc/lib/py/moq-rs.md +++ b/doc/lib/py/moq-rs.md @@ -175,9 +175,10 @@ broadcast.set_video_properties( ```python async for announcement in client.announced("prefix/"): - catalog = await announcement.broadcast.catalog() + broadcast = await client.request_broadcast("prefix/" + announcement.path) + catalog = await broadcast.catalog() track_name, track = next(iter(catalog.audio.items())) - consumer = await announcement.broadcast.subscribe_media(track_name, track) + consumer = await broadcast.subscribe_media(track_name, track) async for frame in consumer: ... @@ -192,10 +193,10 @@ actually lives in `live/source`. `decode_audio` and `decode_video` follow it for so resolve first: ```python -catalog = await announcement.broadcast.catalog() +catalog = await broadcast.catalog() track_name, track = next(iter(catalog.video.items())) -source = await announcement.broadcast.resolve(track.broadcast) +source = await broadcast.resolve(track.broadcast) consumer = await source.subscribe_media(track_name, track) ``` @@ -217,7 +218,8 @@ broadcast = client.create_broadcast("my-stream") broadcast.set_catalog_section("transcript", {"track": "transcript.json"}) # Subscribe: read it back. Sections are unknown to the base catalog, so decode the JSON yourself. -catalog = await announcement.broadcast.catalog() +consumer = await client.request_broadcast("my-stream") +catalog = await consumer.catalog() if "transcript" in catalog.sections: info = json.loads(catalog.sections["transcript"]) ``` @@ -372,21 +374,23 @@ The served broadcast is not announced. It only resolves consumers that call `req ```python async for announcement in client.announced("live/"): - print(announcement.path) - print(announcement.broadcast.route.hops) # relay origin ids, oldest first + print(announcement.path) # the route's prefix, relative to "live/" + print(announcement.route.hops) # relay origin ids, oldest first ... -# Or wait for a specific path to be announced: +# Or wait for a route covering a specific path: broadcast = await client.announced_broadcast("live/cam1") -# Or request a path: resolves an existing exact-path broadcast, announced or not, -# then falls back to a dynamic handler. Does not wait for a future announcement. +# Or request a path: resolves a local broadcast, a covering route, or a dynamic +# handler. Does not wait for a future announcement. broadcast = await client.request_broadcast("live/cam1") ``` -Announcements arrive over the session after it connects, so `request_broadcast` on its own races them: right after connecting it can raise for a broadcast that is live but not reachable locally yet. Await `announced_broadcast(path)` first when you know the path you want; use `request_broadcast` for a path already reachable locally, whether announced or not, or one a dynamic handler serves. +Announcements arrive over the session after it connects, so `request_broadcast` on its own races them: right after connecting it can raise for a broadcast that is live but not routed locally yet. Await `announced_broadcast(path)` first when you know the path you want; use `request_broadcast` for a path already served locally or covered by a route. + +An announcement is a route, not a broadcast: a claim that paths under `announcement.path` can be served. By convention a publisher announces each broadcast's exact path, so iterating announcements still enumerates broadcasts; it is up to you to resolve one with `request_broadcast`. Each route carries `route.hops`, the chain of relay origin ids (as `list[int]`) the announcement passed through to reach you, oldest first, and `route.cost`, the advertised preference (lower wins). A repeated announcement for the same path is a metadata update; `announcement.active` is `False` when the route was retracted. -Each broadcast carries a `Route`: `route.hops` is the chain of relay origin ids (as `list[int]`) the broadcast passed through to reach you, oldest first, and `route.cost` is the publisher's advertised preference (lower wins). The route is dynamic; `await broadcast.route_changed()` returns the current route first, then blocks for each change (e.g. an upstream failover), and returns `None` once the broadcast ends. A publisher advertises its own route with `producer.set_route(moq.Route(hops=[], cost=10))`, for example a standby transcoder that lowers its cost to 0 once it is warm. +A publisher can also announce a route directly, covering a whole prefix without creating a broadcast per path: `producer.announce("live/")` returns a handle that keeps the route advertised until cancelled, with `update()` to re-price its hops and cost (pass a `moq.Route` as the second argument to set them up front). Pair it with `producer.dynamic()` to serve whatever paths are requested beneath the prefix. ## Examples diff --git a/doc/lib/rs/env/native.md b/doc/lib/rs/env/native.md index 8c5a9cba897..ed4cccc569d 100644 --- a/doc/lib/rs/env/native.md +++ b/doc/lib/rs/env/native.md @@ -90,9 +90,12 @@ Wire an [`origin::Producer`](https://docs.rs/moq-net/latest/moq_net/origin/struc let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); let _connection = client.with_publisher(origin.consume()).connect(url); -let route = moq_net::broadcast::Route::new().with_announce(true); -let mut broadcast = origin.create_broadcast("", route)?; +let mut broadcast = origin.create_broadcast("")?; // ... add catalog and tracks to the broadcast ... +// Then announce the exact path as a route, so the advertisement lands with the +// tracks in place. Dropping the announcement retracts the route while the +// broadcast itself stays reachable by path. +let _announcement = origin.announce("", Default::default())?; ``` See the full [video.rs](https://github.com/moq-dev/moq/blob/main/rs/hang/examples/video.rs) example for catalog setup, track creation, and frame encoding. @@ -107,15 +110,18 @@ Subscribing works the same way round: wire an origin in before connecting and re // Consume into an origin wired before connecting, so announcements keep flowing // across a reconnect. Hold the connection to keep redialing. let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); -let mut announced = origin.consume().announced(); +let consumer = origin.consume(); +let mut announced = consumer.announced(); let _connection = client.with_subscriber(origin).connect(url); -// Wait for broadcasts to be announced. +// Wait for routes to be announced. By convention a publisher announces each +// broadcast's exact path, so resolve the announced path into a broadcast. while let Some(update) = announced.next().await { - let Some(broadcast) = update.broadcast else { - tracing::info!(path = %update.path, "broadcast ended"); + if !update.active { + tracing::info!(prefix = %update.route.prefix, "route ended"); continue; - }; + } + let broadcast = consumer.request_broadcast(&update.route.prefix).await?; // Subscribe to tracks on this broadcast... } ``` diff --git a/doc/lib/rs/index.md b/doc/lib/rs/index.md index 7d0e1233c5a..499aec350d2 100644 --- a/doc/lib/rs/index.md +++ b/doc/lib/rs/index.md @@ -293,12 +293,14 @@ broadcast's hop chain: ```rust // Subscribe: wait for broadcasts to be announced. let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); -let mut announced = origin.consume().announced(); +let consumer = origin.consume(); +let mut announced = consumer.announced(); let _connection = client.with_subscriber(origin).connect(url); while let Some(update) = announced.next().await { - // `update.broadcast` is None when the path went away. - // ... subscribe to tracks on each broadcast ... + // `update.active` is false when the route went away. By convention each + // broadcast's exact path is announced, so resolve it to subscribe: + // `consumer.request_broadcast(&update.route.prefix).await?` } ``` diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 54079be8676..7120807f79b 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -69,9 +69,11 @@ let session = try await client.connect(to: "https://relay.example.com") // origin between both sides. let announced = try session.consumer.announced(prefix: "demos/") for try await announcement in announced { - print("got broadcast \(announcement.path)") + // An announcement is a route; its path is relative to the prefix. + print("got route \(announcement.path)") - let catalog = try announcement.broadcast.subscribeCatalog() + let broadcast = try await session.consumer.requestBroadcast(path: "demos/" + announcement.path) + let catalog = try broadcast.subscribeCatalog() for try await update in catalog { print("catalog: \(update)") } diff --git a/doc/lib/swift/moq.md b/doc/lib/swift/moq.md index dc584688521..24d29ac25a6 100644 --- a/doc/lib/swift/moq.md +++ b/doc/lib/swift/moq.md @@ -109,7 +109,9 @@ Every consumer is an `AsyncSequence`, so iterate directly: let announced = try session.consumer.announced(prefix: "demos/") for try await announcement in announced { - let catalog = try announcement.broadcast.subscribeCatalog() + // An announcement is a route; resolve its path into a broadcast. + let broadcast = try await session.consumer.requestBroadcast(path: "demos/" + announcement.path) + let catalog = try broadcast.subscribeCatalog() for try await update in catalog { print("catalog: \(update)") } @@ -119,7 +121,7 @@ for try await announcement in announced { Raw track subscribers can query the publisher's track properties and change their own delivery preferences without resubscribing: ```swift -let track = try await announcement.broadcast.subscribeTrack( +let track = try await broadcast.subscribeTrack( name: "events", subscription: Subscription(priority: 10)) let info = try track.info() @@ -133,7 +135,7 @@ track that actually lives in `live/source`. `decodeAudio` and `decodeVideo` foll a rendition, so resolve first: ```swift -let source = try await announcement.broadcast.resolve(rendition.broadcast) +let source = try await broadcast.resolve(rendition.broadcast) let consumer = try await source.subscribeMedia(name: name, container: rendition.container) ``` diff --git a/drafts/draft-lcurley-moq-broadcast.md b/drafts/draft-lcurley-moq-broadcast.md deleted file mode 100644 index f2a3d52ba5a..00000000000 --- a/drafts/draft-lcurley-moq-broadcast.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: "MoQ Broadcast Extension" -abbrev: "moq-broadcast" -category: info - -docname: draft-lcurley-moq-broadcast-latest -submissiontype: IETF # also: "independent", "editorial", "IAB", or "IRTF" -number: -date: -v: 3 -area: wit -workgroup: moq - -author: - - - fullname: Luke Curley - email: kixelated@gmail.com - -normative: - moqt: I-D.ietf-moq-transport - cluster: - title: "MoQ Cluster Extension" - target: https://datatracker.ietf.org/doc/draft-lcurley-moq-cluster/ - author: - - - ins: L. Curley - name: Luke Curley - date: false - -informative: - ---- abstract - -This document defines a Broadcast extension for MoQ Transport {{moqt}}. -Each namespace advertisement carries an Epoch identifying the generation of content published under the namespace. -Receivers resolve competing advertisements by Epoch rather than arrival order, and a subscriber can pin a subscription or fetch to a specific generation. - ---- middle - -# Conventions and Definitions -{::boilerplate bcp14-tagged} - -A **broadcast** is one generation of the content published under a namespace: when a publisher restarts with new content, or a different publisher takes over the name, a new broadcast occupies the same namespace. - - -# Introduction -{{moqt}} identifies content by namespace, but a namespace is reused across time: a restarted or replacement publisher advertises the same name for entirely new content. -A receiver cannot tell that apart from the same content arriving over another path, so implementations fall back to preferring the most recently received advertisement, which is a race: a stale advertisement on a fresh session looks newer than the generation it predates. -The origin identity of {{cluster}} does not close the gap either: the same publisher producing new content after a restart is indistinguishable from a route change. - -This extension adds an **Epoch** to each namespace advertisement. -The original publisher assigns it, relays forward it unchanged, and a larger value identifies a newer generation, so replacement is decided by value rather than arrival order. -A subscriber can also echo the Epoch in a subscription or fetch, turning "give me the content I saw advertised" into a check the publisher enforces. - - -# Setup Negotiation -The Broadcast extension is negotiated during the SETUP exchange as defined in {{moqt}} Section 10.3. -An endpoint indicates support by including the following Setup Option; it carries no value. - -~~~ -BROADCAST Setup Option { - Option Key (vi64) = 0x40B59 - Option Value Length (vi64) = 0 -} -~~~ - -The extension is negotiated independently per session. -Negotiating it also enables the extended NAMESPACE message format of {{cluster}}, which appends a Parameters field to NAMESPACE; the appended field carries whichever parameters the negotiated extensions define. - -Message parameters in {{moqt}} have no generic skip rule, so an endpoint MUST NOT send EPOCH on a session that did not negotiate this extension. -A relay forwarding into such a session strips EPOCH, and downstream receivers treat the advertisement as unspecified (see [Unspecified Epochs](#unspecified-epochs)). - - -# EPOCH Parameter -The EPOCH parameter carries the generation of the broadcast. -It is a parameter (see {{moqt}} Section 2.5) carried in a namespace advertisement (PUBLISH_NAMESPACE, {{moqt}} Section 10.15, or an extended NAMESPACE, {{cluster}}), and in SUBSCRIBE, FETCH, and PUBLISH to pin the request (see [Pinning Subscriptions, Fetches, and Publishes](#pinning-subscriptions-fetches-and-publishes)). - -~~~ -EPOCH Parameter { - Type (vi64) = 0x40B5B - Length (vi64) - Epoch (vi64) -} -~~~ - -**Epoch**: -The generation of content at this namespace, chosen by the original publisher and forwarded unchanged by relays. -Each new generation MUST use a non-zero Epoch greater than every Epoch still observable at the namespace (the incumbent advertisement and any generation the publisher retains), and MUST NOT equal another publisher's Epoch except by deliberate agreement: equal Epochs declare interchangeable content. -RECOMMENDED construction: wall-clock milliseconds shifted left 16 bits with the low 16 bits random, clamped to at least one more than the highest observable Epoch; the timestamp preserves ordering across restarts without persisted state, the random bits make accidental collisions improbable, and the clamp covers same-millisecond generations, clock rollback, and skew. -A violation is not fatal: receivers keep no high-water mark, so an erroneously high Epoch suppresses newer generations only while its advertisement remains available. -A value of 0 is equivalent to omitting the parameter. - -## Selection by Epoch -A receiver holding advertisements for the same namespace MUST prefer the highest Epoch (a specified Epoch outranks an unspecified one): a lower Epoch is a stale generation, never an alternate path, regardless of arrival order or path length. -A relay SHOULD end its advertisement of a lower generation once it holds a higher one, rather than wait for it to end on its own, which would hold the namespace for however long the transport takes to notice a publisher is gone. - -Advertisements with the same non-zero Epoch carry interchangeable content: a receiver MAY hold them as redundant paths and switch between them, including failing an active subscription over when the serving path ends. -Cooperating redundant publishers opt in by minting the same Epoch, e.g. derived from the event rather than from each process. -Any other pair is two generations: cached immutable track properties MUST be discarded on replacement, and existing subscriptions do not carry over. - -When combined with {{cluster}}, Epoch comparison happens first; its path-length tie-break and origin-identity rules apply only among advertisements with the same Epoch. - -## Unspecified Epochs -An advertisement without EPOCH carries no generation: the publisher predates this extension, or the parameter was stripped crossing a non-supporting session. -Unspecified advertisements are never interchangeable with specified ones; among themselves, the identity rules otherwise in effect apply ({{cluster}} origin identity, or plain {{moqt}} semantics). - -## Pinning Subscriptions, Fetches, and Publishes -On a session that negotiated this extension, a subscriber MAY include EPOCH in SUBSCRIBE or FETCH; the request then targets exactly that generation, and the publisher MUST reject it rather than serve a different one. -A publisher that retains an older generation (e.g. a recording) MAY serve a FETCH pinned to it even after a newer generation replaced the namespace. -A request without EPOCH targets whatever generation the publisher currently serves, matching {{moqt}}'s default behavior. -Echoing the Epoch of the advertisement acted on closes the race where a request crosses a replacement in flight. - -The same race exists in the push direction: a publisher SHOULD include EPOCH in PUBLISH, and a receiver MUST reject a PUBLISH whose Epoch differs from the generation it currently holds for the namespace, so a stale push cannot attach its tracks to a replacement. - - -# Security Considerations -A wall-clock-derived Epoch reveals approximately when a broadcast started; a publisher that considers this sensitive can use any other increasing scheme. - -A misbehaving publisher or relay can advertise an arbitrarily high Epoch and suppress legitimate content at that namespace, but only while its advertisement remains available, since receivers keep no high-water mark. -This is the same trust already placed in namespace advertisements themselves; receivers MUST NOT treat an Epoch as proof of freshness or authenticity. - - -# IANA Considerations - -This document requests the following registrations. -High, distinctive values are requested to avoid the low ranges reserved by {{moqt}} and to minimize collisions with provisional registrations by other extensions. - -## MOQT Setup Options - -This document requests a registration in the "MOQT Setup Options" registry ({{moqt}} Section 15.4), whose policy is Specification Required. - -| Value | Name | Reference | -|:--------|:----------|:--------------| -| 0x40B59 | BROADCAST | This Document | - -## MOQT Message Parameters - -This document requests a registration in the "MOQT Message Parameters" registry ({{moqt}} Section 15.7). - -| Value | Name | Carried In | Reference | -|:--------|:------|:-------------------------------------------------------|:--------------| -| 0x40B5B | EPOCH | PUBLISH_NAMESPACE, NAMESPACE, SUBSCRIBE, FETCH, PUBLISH | This Document | - - ---- back - -# Acknowledgments -{:numbered="false"} - -This document was drafted with the assistance of Claude, an AI assistant by Anthropic. diff --git a/drafts/draft-lcurley-moq-cluster.md b/drafts/draft-lcurley-moq-cluster.md index a62114763d7..9b275ede5dc 100644 --- a/drafts/draft-lcurley-moq-cluster.md +++ b/drafts/draft-lcurley-moq-cluster.md @@ -95,7 +95,6 @@ Hop IDs SHOULD be unique among the endpoints an advertisement can traverse. An endpoint MAY generate one randomly, since collisions across a 64-bit space are unlikely, or use a stable configured identifier that survives restarts. Loop detection and origin identification compare Hop IDs for equality, so two endpoints sharing a Hop ID are indistinguishable. -Redundant publishers producing interchangeable content MAY share one deliberately, so a receiver treats their paths as failover options for the same content ({{selection}}). ## The Reserved Hop ID 0 {#zero} **0 means "no identity"** and is reserved. @@ -104,7 +103,7 @@ It is used for an endpoint that did not negotiate this extension, and an endpoin Because any number of endpoints can be 0, it identifies nothing, which constrains all three uses: - **Loop detection**: 0 in a HOP_PATH is never a loop. A receiver whose own Hop ID is 0 cannot detect loops through itself, and MUST NOT discard an advertisement merely because the path contains 0. -- **Origin identity**: an advertisement whose first entry is 0 has an unknown origin. A receiver MUST NOT treat two such advertisements as interchangeable ({{selection}}). Updating one advertisement is not two ({{updating}}). +- **Origin identity**: an advertisement whose first entry is 0 has an unknown origin. Updating one advertisement is not two ({{updating}}). - **Filtering**: a peer that declared 0 declared no identity, so there is nothing on the wire to filter that session on. A receiver MAY assign one ({{assigned}}), which covers what it attributes to that session itself but not an advertisement that arrived carrying its own HOP_PATH. Duplicate *non-zero* Hop IDs in one HOP_PATH are a loop; duplicate zeros are not. @@ -119,10 +118,10 @@ An advertisement that arrives carrying its own HOP_PATH names the sender there, So an assigned ID governs the advertisements a receiver attributed itself, and a peer that both declares 0 and sends its own HOP_PATH keeps the consequences in {{zero}}. An assigned ID MUST NOT be shared between peers not known to be the same endpoint. -Sharing one makes their content interchangeable ({{selection}}) and suppresses each one's advertisements to the other, so two unrelated publishers would be spliced into one and starve each other of routes. +Sharing one suppresses each one's advertisements to the other, so two unrelated publishers would starve each other of routes. How an endpoint scopes the ID follows from what it can establish about the peer. -One it authenticated, or one it dialed and therefore chose, SHOULD get a single stable ID, which additionally lets reconnects and redundant sessions be recognized as the same content ({{selection}}); assigning per connection there would make one peer look like several. +One it authenticated, or one it dialed and therefore chose, SHOULD get a single stable ID; assigning per connection there would make one peer look like several. An endpoint accepting an anonymous session can establish nothing and cannot correlate it with any other, so it SHOULD assign a distinct ID per session: less than an identity, but enough to keep routes it attributed to that session from being advertised back to it, which is the loop 0 cannot prevent. An assigned ID is indistinguishable on the wire from a declared one, so it identifies the peer to everyone the receiver forwards to; a peer that declared 0 for anonymity did not ask for that. @@ -208,11 +207,7 @@ A receiver MUST NOT treat the repeat as a duplicate or a protocol violation. In {{moqt}} an advertisement lives for the lifetime of its stream, so an update on a *new* stream would leave two streams claiming one namespace and let the superseded one retract its replacement. An endpoint MUST NOT open a second stream for a namespace it already advertises on this session. -Replacement is atomic, so a receiver MUST NOT tear down subscriptions or drop cached state merely because an update arrived. -What it means for existing subscriptions follows the first HOP_PATH entry ({{selection}}): unchanged, the content is continuous and subscriptions MAY resume on the new route at a group boundary; changed, a different publisher has taken over and they do not carry over. - -This is the one comparison 0 ({{zero}}) does not decide: it identifies nothing, but there is one advertisement here and the stream carrying it is the continuity. -An endpoint whose publisher did change MUST withdraw the advertisement (NAMESPACE_DONE or PUBLISH_NAMESPACE_DONE) and advertise again rather than update in place. +An update is metadata only: it re-prices or re-routes the advertisement and carries no content claim, so a receiver MUST NOT tear down subscriptions or drop cached state merely because one arrived. The expected case is a ROUTE_COST-only change, which is how a relay signals that it started or stopped carrying the namespace. @@ -221,8 +216,8 @@ The expected case is a ROUTE_COST-only change, which is how a relay signals that A receiver holding advertisements for the same namespace over several sessions SHOULD prefer the lowest ROUTE_COST, breaking ties toward the shorter HOP_PATH and then toward the most recently received. This is advisory: a receiver MAY apply local policy such as measured RTT instead. -Two advertisements whose HOP_PATH begins with the same non-zero Hop ID share a publisher and carry interchangeable content, so a receiver MAY hold them as redundant paths and fail an active subscription over to the survivor. -If the first entries differ, or either is 0, they are distinct publishers reusing a namespace: a receiver MUST NOT treat them as interchangeable and SHOULD treat the later as replacing the earlier. +An advertisement carries no content identity: nothing promises that two paths to one namespace serve interchangeable bytes. +A receiver MUST NOT splice an active subscription across sessions; when the serving session's advertisement goes away, subscriptions through it end, and the receiver re-subscribes through the best remaining path. A publisher MUST NOT advertise a path whose HOP_PATH contains the Hop ID that peer declared. The receiver can only discard it, and acting on it would form a loop, so sending one is never useful. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 5ca90695bf0..6585b8d4435 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -111,9 +111,10 @@ Any broadcasts and subscriptions are transparently proxied by the CDN behind the A Broadcast is a collection of Tracks from a single publisher. This corresponds to a MoqTransport's "track namespace". -A publisher may produce multiple broadcasts, each of which is advertised via an ANNOUNCE_START message. -The subscriber uses the ANNOUNCE_REQUEST message to discover available broadcasts. -These announcements are live and can change over time, allowing for dynamic origin discovery. +A publisher advertises what it can serve via ANNOUNCE_START messages, each carrying a path prefix: a route covering every broadcast path beneath it. +The subscriber uses the ANNOUNCE_REQUEST message to discover these routes, then subscribes to specific paths under them; which paths name broadcasts is an application convention. +The common convention is that a publisher announces each broadcast's exact path as its own route, so subscribers can enumerate broadcasts, while a service announces one short prefix and serves whatever is requested beneath it. +Announcements are live and can change over time, allowing for dynamic origin discovery. A broadcast consists of any number of Tracks. The contents, relationships, and encoding of tracks are determined by the application. @@ -325,32 +326,34 @@ There's a 1-byte STREAM_TYPE at the beginning of each stream. | ------- | ------------- | ----------- | ### Announce -A subscriber can open an Announce Stream to discover broadcasts matching a prefix. +A subscriber can open an Announce Stream to discover routes matching a prefix. +A route is an advertisement that paths under its prefix can be served; it claims capability, not inventory, so it never asserts that any specific broadcast exists. The subscriber creates the stream with an ANNOUNCE_REQUEST message. -The publisher replies with a single ANNOUNCE_OK message followed by announcements for any matching broadcasts and any future changes: +The publisher replies with a single ANNOUNCE_OK message followed by announcements for any matching routes and any future changes: -- ANNOUNCE_START: a matching broadcast is available. -- ANNOUNCE_END: a previously started broadcast is no longer advertised. -- ANNOUNCE_UPDATE: a previously started advertisement was atomically replaced. +- ANNOUNCE_START: a matching route is available. +- ANNOUNCE_END: a previously started route is no longer advertised. +- ANNOUNCE_UPDATE: a previously started advertisement was atomically updated (new hops or cost). ANNOUNCE_OK carries metadata that applies to every announcement on the stream: the publisher's own `Hop ID` (the implicit trailing entry of every announcement's path) and the number of initial announcements, which lets the subscriber deliver the initial set as a batch (see [ANNOUNCE_OK](#announce-ok)). Each ANNOUNCE_START implicitly assigns the next Announce ID on the stream: a counter starting at 0 that increments by 1 per ANNOUNCE_START. The id never appears on the wire; both endpoints derive it from the message order on the (reliable, ordered) stream. -ANNOUNCE_END and ANNOUNCE_UPDATE reference the Announce ID instead of repeating the broadcast path. +ANNOUNCE_END and ANNOUNCE_UPDATE reference the Announce ID instead of repeating the route's prefix. -Each broadcast has at most one current advertisement per stream. -A second ANNOUNCE_START for an already-available path is a protocol violation; an ANNOUNCE_UPDATE atomically replaces the current advertisement (equivalent to ANNOUNCE_END+ANNOUNCE_START) while keeping its id live. +Each route prefix has at most one current advertisement per stream. +A second ANNOUNCE_START for an already-advertised prefix is a protocol violation; an ANNOUNCE_UPDATE atomically updates the current advertisement's metadata while keeping its id live. -The subscriber MUST close the session with a PROTOCOL_VIOLATION if it receives an ANNOUNCE_END or ANNOUNCE_UPDATE referencing an Announce ID that was never assigned or already retired, an ANNOUNCE_START for a path that is already available, or any announcement before ANNOUNCE_OK. -When the stream is closed, the subscriber MUST assume that all broadcasts are now unavailable. +The subscriber MUST close the session with a PROTOCOL_VIOLATION if it receives an ANNOUNCE_END or ANNOUNCE_UPDATE referencing an Announce ID that was never assigned or already retired, an ANNOUNCE_START for a prefix that is already advertised, or any announcement before ANNOUNCE_OK. +When the stream is closed, the subscriber MUST assume that all routes are now unavailable. -Path prefix matching and equality is done on a byte-by-byte basis. +A route covers a path when its prefix is a leading run of the path's segments; matching is per path segment, so a prefix never matches half a segment, and equality is byte-by-byte within each segment. +A publisher answering a request stream presents each of its routes clamped to the intersection with the requested prefix: a route above the request's prefix appears as the request prefix itself (an empty suffix), which is exactly the covered set the subscriber may see. There MAY be multiple Announce Streams, potentially containing overlapping prefixes, that get their own ANNOUNCE_OK + announcements. #### Routing {#routing} -Each advertisement carries an `Epoch` identifying the generation of content at the path, the path of Hop IDs it traversed, and an accumulated Warm and Cold Route Cost (see [ANNOUNCE_START](#announce-start)), which relays use to build a loop-free mesh. +Each advertisement carries the path of Hop IDs it traversed and an accumulated Warm and Cold Route Cost (see [ANNOUNCE_START](#announce-start)), which relays use to build a loop-free mesh. A receiver MUST discard an announcement whose reconstructed path contains its own Hop ID: it has looped back, so forwarding it would extend the loop and subscribing through it would route the receiver back to itself. This is the only loop defense moq-lite requires, and it catches loops of any length. @@ -366,15 +369,11 @@ The per-subscriber winner changing travels as an ANNOUNCE_UPDATE; the last quali When serving a subscription, a publisher MUST select the source by that same exclusion; if only excluded sources remain, the subscription is unroutable. Applying one rule to both advertisement and dispatch keeps advertised paths truthful, which is what prevents subscription cycles of any length. -A subscriber that sees the same broadcast advertised across multiple streams MUST prefer the highest `Epoch` (any non-zero value outranks 0): a lower Epoch never displaces a higher one, regardless of cost or arrival order. -Among interchangeable advertisements, the subscriber SHOULD route subscriptions to the lowest Warm Route Cost after adding each arriving link's cost (see [Cost Parameter](#cost-parameter)), breaking ties toward the lowest Cold Route Cost, then toward the shortest path, and then toward the most recently received, so a reconnecting publisher is not outranked by the stale session it replaced. -The Cold tie-break matters exactly where the Warm one runs out: two relays that both carry the broadcast both advertise a Warm cost of 0, and only their Cold costs say which of them sits closer to the publisher. +When resolving a path covered by several routes (across any number of streams), the subscriber SHOULD prefer the most specific covering prefix, then the lowest Warm Route Cost after adding each arriving link's cost (see [Cost Parameter](#cost-parameter)), breaking ties toward the lowest Cold Route Cost, then toward the shortest path, and then toward the most recently received, so a reconnecting publisher is not outranked by the stale session it replaced. +The Cold tie-break matters exactly where the Warm one runs out: two relays that both carry the content both advertise a Warm cost of 0, and only their Cold costs say which of them sits closer to the publisher. -Advertisements with the same non-zero `Epoch` carry interchangeable content: a relay MAY hold them as redundant routes for one broadcast and splice a live subscription across them at a [Position](#positions). -If a route ends partway through a Group, the replacement continues from the next frame instead of abandoning the rest of the Group. -Cooperating redundant publishers opt in by minting the same Epoch, e.g. derived from the event rather than from each process. -Any other pair is two generations colliding on one path: a relay MUST NOT splice between them and MUST end the lower-Epoch advertisement rather than wait for it to end on its own, which would hold the path for however long the transport takes to notice a publisher is gone. -Only when both Epochs are 0 does identity fall back to the first entry of the reconstructed path: a shared non-zero first entry is spliceable, while differing or zero first entries (0 proves nothing shared) are a replacement decided toward the most recently received. +A route carries no content identity: nothing on the wire promises that two routes covering one path serve interchangeable bytes. +A relay MUST NOT splice a live subscription across sources reached through different routes; when a serving session ends, in-flight subscriptions end with it (a reset), and the subscriber re-requests through the best remaining route. ### Subscribe A subscriber opens Subscribe Streams to request a Track. @@ -382,7 +381,8 @@ A subscriber opens Subscribe Streams to request a Track. The subscriber MUST start a Subscribe Stream with a SUBSCRIBE message followed by any number of SUBSCRIBE_UPDATE messages. The publisher replies with a SUBSCRIBE_OK message once the start group is resolved, followed by any number of SUBSCRIBE_END and SUBSCRIBE_DROP messages. For a live track the publisher MAY withhold SUBSCRIBE_OK until the first matching group resolves the start; if the track has already ended with no matching groups, it sends SUBSCRIBE_END with no preceding SUBSCRIBE_OK. -A rejection is a stream reset: a publisher that cannot serve the subscription (no such track, an ended broadcast, an `Epoch` that is not the one being served, or any other refusal) MUST promptly reset the stream rather than leave it pending, so a subscriber distinguishes "pending" from "refused" by the reset, not by a timeout. +A rejection is a stream reset: a publisher that cannot serve the subscription (no such track, an ended broadcast, or any other refusal) MUST promptly reset the stream rather than leave it pending, so a subscriber distinguishes "pending" from "refused" by the reset, not by a timeout. +A route claims capability rather than inventory, so a subscription for a covered path that names nothing is refused this way too. The track's immutable publisher properties are not carried here; they are fetched once via a [Track Stream](#track-stream). The subscriber needs the track's TRACK_INFO (notably its timescale) to interpret FRAME messages, and MAY open the Track and Subscribe streams concurrently, buffering frames until it arrives. @@ -395,8 +395,8 @@ Unbounded subscriptions stay open until SUBSCRIBE_END, and either endpoint MAY r ### Fetch A subscriber opens a Fetch Stream (0x3) to request a single Group from a Track. -The subscriber sends a FETCH message containing the broadcast path, track name, epoch, priority, group sequence, and the frame range within that group. -Unlike SUBSCRIBE, FETCH works on both live and ended broadcasts; it is the only way to read an ended one, and a non-zero epoch pins the fetch to a specific content generation (see [FETCH](#fetch)). +The subscriber sends a FETCH message containing the broadcast path, track name, priority, group sequence, and the frame range within that group. +Unlike SUBSCRIBE, FETCH works on both live and ended broadcasts; it is the only way to read an ended one. The publisher responds with FRAME messages directly on the same bidirectional stream — there is no response header. The Subscribe ID, Group Sequence, and index of the first returned frame are implicit, taken from the original FETCH request. Because there is no response header, a publisher that cannot serve the requested frame range in full MUST reset the stream rather than return a shorter run; the subscriber has no way to learn where a truncated response actually started. @@ -408,12 +408,9 @@ Fetch behaves like HTTP: a single request/response per stream. ### Track {#track-stream} A subscriber opens a Track Stream (0x6) to learn a Track's immutable publisher properties without subscribing or fetching. -The subscriber sends a TRACK message containing the broadcast path, track name, and epoch (0 for the current generation). -The publisher replies with a single TRACK_INFO message carrying the resolved epoch and then FINs the stream, or resets the stream on error (e.g. the track does not exist, or a non-zero epoch does not match). -The returned properties are fixed for the lifetime of that generation, so the subscriber SHOULD cache TRACK_INFO keyed by broadcast path, track name, and epoch, and reuse it across every SUBSCRIBE and FETCH of the same generation. -An announcement that changes the broadcast's Epoch replaces the content (see [ANNOUNCE_UPDATE](#announce-update)); cached TRACK_INFO from another generation MUST NOT be used to parse its frames, since the timescale may differ. -A subscriber without announcements (a path known out of band) gets the same protection by waiting for TRACK_INFO and echoing its non-zero resolved epoch in SUBSCRIBE and FETCH, so a concurrent replacement is a reset rather than misparsed frames; opening those streams concurrently with Epoch 0 forfeits this. -A resolved epoch of 0 pins nothing and cannot key the cache: a subscriber following announcements MUST discard such a cache when the advertisement is replaced, and one without announcements SHOULD NOT keep it beyond the connection. +The subscriber sends a TRACK message containing the broadcast path and track name. +The publisher replies with a single TRACK_INFO message and then FINs the stream, or resets the stream on error (e.g. the track does not exist). +The returned properties are fixed for the lifetime of the track, so the subscriber SHOULD cache TRACK_INFO keyed by broadcast path and track name, and reuse it across every SUBSCRIBE and FETCH of the same track over the session that served it. If FRAME messages cannot be decoded against the cached TRACK_INFO, the subscriber MUST reset the affected stream with a protocol violation and re-request it. Because a subscriber cannot parse buffered group frames until TRACK_INFO arrives, the publisher SHOULD prioritize TRACK_INFO ahead of group data on the connection. @@ -769,7 +766,7 @@ ANNOUNCE_OK Message { The publisher's own Hop ID. This is treated as the implicit trailing entry of every ANNOUNCE_START and ANNOUNCE_UPDATE Hop ID list on this stream; those messages MUST NOT repeat this value as the last entry of their `Hop ID` list. The value 0 is reserved to mean "unknown": either no Hop ID was assigned (e.g. when bridging from an older protocol version) or the endpoint deliberately withholds it to obscure the underlying routing. -A publisher that assigns a Hop ID MUST choose a non-zero value, and SHOULD assign itself one (a fresh random value per session suffices): the first entry of the path is the fallback content identity when `Epoch` is 0, and 0 proves nothing shared (see [Routing](#routing)). +A publisher that assigns a Hop ID MUST choose a non-zero value, and SHOULD assign itself one (a fresh random value per session suffices), so downstream receivers can detect loops through it. Receivers reconstruct the full path as `Hop IDs ++ [ANNOUNCE_OK.Hop ID]`. **Active Count**: @@ -780,17 +777,16 @@ A value of `0` is valid and means the publisher is offering no initial available ## ANNOUNCE_START {#announce-start} -A publisher sends an ANNOUNCE_START message to advertise that a broadcast is available. +A publisher sends an ANNOUNCE_START message to advertise a route: a claim that paths under a prefix can be served. Each ANNOUNCE_START implicitly assigns the next Announce ID on the stream, later referenced by ANNOUNCE_END and ANNOUNCE_UPDATE (see [Announce](#announce)). -Only the suffix is encoded on the wire, as the full path can be constructed by prepending the requested prefix. +Only the suffix is encoded on the wire, as the full route prefix can be constructed by prepending the requested prefix. ~~~ ANNOUNCE_START Message { Type (i) = 0x0 Message Length (i) - Broadcast Path Suffix (s), - Epoch (i), + Route Prefix Suffix (s), Hop Count (i), Hop ID (i) ..., Warm Route Cost (i), @@ -801,15 +797,9 @@ ANNOUNCE_START Message { **Type**: Set to 0x0 to indicate an ANNOUNCE_START message. -**Broadcast Path Suffix**: -This is combined with the broadcast path prefix to form the full broadcast path. - -**Epoch**: -The generation of content at this path, chosen by the original publisher and forwarded unchanged by relays. -Each new generation MUST use a non-zero Epoch greater than every Epoch still observable at the path (the incumbent advertisement and any generation the publisher retains), and MUST NOT equal another publisher's Epoch except by deliberate agreement: equal Epochs declare interchangeable content. -RECOMMENDED construction: wall-clock milliseconds shifted left 16 bits with the low 16 bits random, clamped to at least one more than the highest observable Epoch; the timestamp preserves ordering across restarts without persisted state, the random bits make accidental collisions improbable, and the clamp covers same-millisecond generations, clock rollback, and skew. -A violation is not fatal: receivers keep no high-water mark, so an erroneously high Epoch suppresses newer generations only while its advertisement remains available. -A value of 0 means unspecified: identity falls back to the first entry of the path (see [Routing](#routing)), e.g. when bridging from an endpoint that does not assign Epochs. +**Route Prefix Suffix**: +This is combined with the requested prefix to form the route's full prefix. +An empty suffix advertises the requested prefix itself, which is how a route covering more than the request presents (see [Announce](#announce)). **Hop Count**: The number of Hop ID entries that follow, NOT including the publisher's own `Hop ID` from ANNOUNCE_OK. @@ -820,24 +810,23 @@ A receiver MUST close the stream with a PROTOCOL_VIOLATION if the Hop Count does A unique identifier for each relay in the path from the origin publisher, ordered from origin to the upstream of the responding publisher. The responding publisher's own Hop ID is NOT included in this list; it is carried once in ANNOUNCE_OK, so the total path length is `Hop Count + 1`. When forwarding an announcement received from an upstream peer, a relay MUST append the upstream peer's ANNOUNCE_OK `Hop ID` to this list, since that ID is no longer implicit downstream. -The first entry of the reconstructed path identifies the original publisher of the broadcast; it is the fallback content identity when `Epoch` is 0 (see [Routing](#routing)). +The first entry of the reconstructed path identifies the endpoint that originated the route. A Hop ID value of 0 means the hop is unknown: either it was never assigned or a relay deliberately withholds it (see [Routing](#routing)). A receiver MUST close the session with a PROTOCOL_VIOLATION if a non-zero Hop ID appears twice in this list. Duplicate values of 0 are not a violation, since 0 identifies nothing and any number of hops may be unknown. **Warm Route Cost** and **Cold Route Cost**: -What subscribing to the broadcast via this advertisement costs, in units chosen by the deployment, priced against two different cache states. +What subscribing to content under this route costs, in units chosen by the deployment, priced against two different cache states. The Warm cost is what one more subscription would cost the mesh as it stands, and is what routing minimizes. The Cold cost prices the identical path as if no relay along it were carrying anything, and exists to rank two relays that both discounted their Warm cost to 0. The original publisher seeds both with its production cost: 0 for content it is already producing, larger for content it would have to start producing on demand (e.g. a standby transcoder that advertises every broadcast it could serve, at a cost reflecting the work of actually serving it). When forwarding an announcement received from an upstream peer, a relay adds the cost that peer declared (see [Cost Parameter](#cost-parameter)) to both, saturating rather than wrapping so an absurd upstream value ranks last instead of overflowing to best. Saturation MUST cap each sum at the largest value a variable-length integer can carry, since the sums are re-encoded when forwarded: a peer may legally advertise that largest value, and a wider ceiling would leave the relay unable to encode what it just computed. -A relay that is actively carrying the broadcast (a live subscription exists for at least one of its tracks) SHOULD advertise a Warm cost of 0 instead of the accumulated value: its ingress is already paid for, which is what lets a cluster deduplicate onto a warm copy. +A relay that is actively carrying content under the route (a live subscription exists through it) MAY advertise a Warm cost of 0 instead of the accumulated value: its ingress is already paid for, which is what lets a cluster deduplicate onto a warm copy. The discount applies to the Warm cost only; the Cold cost is forwarded accumulated, since it prices the path the relay would have to open if it were not already carrying it. -The discount applies only to the path the relay actually serves from; a standby path keeps its accumulated Warm value, since serving from it means opening a fresh ingest. -When the relay stops carrying the broadcast it SHOULD restore the accumulated value via ANNOUNCE_UPDATE, optionally after a grace period so brief churn does not flap routing. +When the relay stops carrying content under the route it SHOULD restore the accumulated value via ANNOUNCE_UPDATE, optionally after a grace period so brief churn does not flap routing. A relay whose wire cannot express a Cold cost (an endpoint bridging from another protocol, or a peer that predates this field) advertises nothing, and a receiver SHOULD treat the missing value as the saturation ceiling rather than as 0: an unknown path ranks last instead of impersonating the publisher's own. @@ -846,19 +835,19 @@ Draining is the ceiling's primary producer: a session that received a GOAWAY (se The rule is deliberately keyed on the value rather than on why it was reached: a cost that saturated through accumulated charges marks a path of last resort all the same, and value-keyed behavior is what independent implementations can agree on, since the reason does not travel on the wire. Forgoing the discount is also what carries a drain across a mesh: each carrying relay along the path repeats it, so the ceiling survives hops that would otherwise re-mask it as 0. -Two relays that independently begin carrying the same broadcast would each see the other's 0 as cheaper than its own source, and both switching at once would leave the broadcast with no source. -Before re-parenting onto a 0-cost advertisement from another actively-carrying relay (one whose path has two or more entries), a relay SHOULD require that relay's rank to be strictly lower than its own, where a relay's rank is the Cold Route Cost of the path it serves from, followed by a hash of the broadcast path and its Hop ID. +Two relays that independently begin carrying the same content would each see the other's 0 as cheaper than its own source, and both switching at once would leave the content with no source. +Before re-parenting onto a 0-cost advertisement from another actively-carrying relay (one whose path has two or more entries), a relay SHOULD require that relay's rank to be strictly lower than its own, where a relay's rank is the Cold Route Cost of the path it serves from, followed by a hash of the route prefix and its Hop ID. Adopting a parent adds that link's cost to the adopting relay's own Cold cost, so once the move lands it ranks above the relay it adopted, and the two cannot adopt each other. Ranking on Cold cost first also puts the aggregation point at the relay with the cheapest path to the publisher, instead of wherever a hash happens to fall; the hash only separates relays that are equally far from it. Equal ranks (including two relays that both declared Hop ID 0) cannot be ordered, and neither side SHOULD move. -Cheaper advertisements from anything else carry no such hazard and SHOULD be adopted immediately. +Cheaper advertisements from anything else carry no such hazard and MAY be adopted immediately. This ordering is only shared between two relays while the costs behind it are. A relay reports its own Cold Route Cost, and a report still crossing the mesh can be lower than the value its sender would report now, so while costs are rising three or more relays can each rank a stale neighbour below themselves and all re-parent at once, leaving the broadcast with no source until the real advertisements arrive. A relay SHOULD therefore delay re-parenting onto a route learned from a peer, re-evaluating when the delay expires rather than acting on the decision that started it, so the advertisements the decision rests on are refreshed before it takes effect. The delay MUST exceed the time an advertisement takes to cross the mesh, and SHOULD carry a spread that is stable per relay and broadcast, so that a group of relays reconsidering the same broadcast does not do so on a single instant. Having no subscribers does not exempt a relay: the choice it records is the one it will pull down when a subscriber does arrive, so an unserved relay is a ring that starts later rather than one that cannot form. -Neither does a short path, since a peer that does not carry Hop IDs is indistinguishable from the original publisher however deep the chain behind it is. +Neither does a short path, since a peer that does not carry Hop IDs is indistinguishable from the route's origin however deep the chain behind it is. Two cases are exempt: a fresh session from the peer already being pulled from, which is the same dependency rather than a new one, and a route that has disappeared, since waiting strands the relay with nothing to serve from at all. The second exemption is a deliberate residual rather than a proof. @@ -871,11 +860,11 @@ The exemptions also compose: should the drain become a disconnection, the route ## ANNOUNCE_END {#announce-end} -A publisher sends an ANNOUNCE_END message to retract a previously started broadcast, referencing its Announce ID. +A publisher sends an ANNOUNCE_END message to retract a previously started route, referencing its Announce ID. The id is retired and MUST NOT be referenced again. -Retraction claims nothing about the content: a broadcast that ends but remains readable retracts too, and serves its stored groups over FETCH. +Retraction claims nothing about the content: a broadcast whose publisher stops advertising may remain readable by exact path, serving its stored groups over FETCH. Retraction does not disturb subscriptions already in flight, which conclude normally with SUBSCRIBE_END. -How a subscriber learns the path and epoch of stored content is out of band, e.g. an application catalog. +How a subscriber learns the path of stored content is out of band, e.g. an application catalog. ~~~ ANNOUNCE_END Message { @@ -891,30 +880,19 @@ Set to 0x1 to indicate an ANNOUNCE_END message. **Announce ID**: The ordinal implicitly assigned by a prior ANNOUNCE_START on this stream. Referencing an id that was never assigned, or one already retired, is a protocol violation. -Announce IDs are never reused within a stream; a broadcast that is announced again after an ANNOUNCE_END gets a fresh id from its next ANNOUNCE_START. +Announce IDs are never reused within a stream; a prefix that is announced again after an ANNOUNCE_END gets a fresh id from its next ANNOUNCE_START. ## ANNOUNCE_UPDATE {#announce-update} -A publisher sends an ANNOUNCE_UPDATE message to atomically replace a previously started advertisement, referencing its Announce ID. -The advertisement is replaced in place (equivalent to ANNOUNCE_END+ANNOUNCE_START) and the id stays live. -The Hop ID list MAY differ from the original (e.g. after a relay failover or upstream restart). - -The `Epoch` determines what the update means (see [ANNOUNCE_START](#announce-start)): - -- Unchanged (non-zero): the same content over a different route, or a changed Route Cost. - Cached TRACK_INFO stays valid (see [Track](#track-stream)) and the subscriber MAY resume in-flight subscriptions at a group boundary. -- Changed: a different generation occupies the path. - Cached TRACK_INFO MUST be discarded and existing subscriptions do not carry over. - A publisher SHOULD only move to a lower Epoch when the higher generation is gone entirely, e.g. the newer publisher vanished and an older redundant one remains. -- Both 0: the first entry of the reconstructed path decides instead, a preserved non-zero entry meaning a route change and a changed or zero entry a replacement (0 proves nothing shared). - The first entry only identifies the publisher, so a restart with new content is indistinguishable from a route change; assigning Epochs is what makes it detectable. +A publisher sends an ANNOUNCE_UPDATE message to atomically update a previously started advertisement's metadata, referencing its Announce ID. +The route's prefix is unchanged and the id stays live; the Hop ID list MAY differ from the original (e.g. after a relay failover or upstream restart). +An update carries no content claim: in-flight subscriptions under the route are undisturbed. ~~~ ANNOUNCE_UPDATE Message { Type (i) = 0x2 Message Length (i) Announce ID (i), - Epoch (i), Hop Count (i), Hop ID (i) ..., Warm Route Cost (i), @@ -929,9 +907,9 @@ Set to 0x2 to indicate an ANNOUNCE_UPDATE message. The ordinal implicitly assigned by a prior ANNOUNCE_START on this stream. Referencing an id that was never assigned, or one already retired by an ANNOUNCE_END, is a protocol violation. -**Epoch**, **Hop Count**, **Hop ID**, **Warm Route Cost**, and **Cold Route Cost**: +**Hop Count**, **Hop ID**, **Warm Route Cost**, and **Cold Route Cost**: As defined for [ANNOUNCE_START](#announce-start). -An update whose only change is a Route Cost is valid: it is how a relay advertises that it started or stopped actively carrying the broadcast. +An update whose only change is a Route Cost is valid: it is how a relay advertises that it started or stopped actively carrying content under the route. ## SUBSCRIBE @@ -943,7 +921,6 @@ SUBSCRIBE Message { Subscribe ID (i) Broadcast Path (s) Track Name (s) - Epoch (i) Subscriber Priority (8) Subscriber Max Age (i) Group Start (i) @@ -957,10 +934,6 @@ SUBSCRIBE Message { A unique identifier chosen by the subscriber. A Subscribe ID MUST NOT be reused within the same session, even if the prior subscription has been closed. -**Epoch**: -The generation to subscribe to (see [ANNOUNCE_START](#announce-start)): 0 for the current one, or a non-zero value that MUST match the generation being served (the publisher resets the stream otherwise). -Echoing the Epoch of the advertisement acted on closes the race where a SUBSCRIBE crosses a replacement in flight. - **Subscriber Priority**: The priority of the subscription within the session, represented as a u8. The publisher SHOULD transmit *higher* values first during congestion. @@ -1033,7 +1006,6 @@ TRACK Message { Message Length (i) Broadcast Path (s) Track Name (s) - Epoch (i) } ~~~ @@ -1043,9 +1015,6 @@ The broadcast path of the track. **Track Name**: The name of the track. -**Epoch**: -The generation to resolve (see [ANNOUNCE_START](#announce-start)): 0 for the current one, or a non-zero value that MUST match a generation the publisher can serve (it resets the stream otherwise). - ## TRACK_INFO {#track-info} TRACK_INFO is sent by the publisher in response to a TRACK message. It is the sole message on the Track Stream; the publisher FINs immediately afterward, or resets the stream on error (e.g. the track does not exist). @@ -1053,21 +1022,16 @@ It is the sole message on the Track Stream; the publisher FINs immediately after ~~~ TRACK_INFO Message { Message Length (i) - Epoch (i) Publisher Priority (8) Publisher Max Age (i) Timescale (i) } ~~~ -Every field is **fixed for the lifetime of the Track** and MUST NOT change; a change requires a new Track (a re-announcement of the broadcast). +Every field is **fixed for the lifetime of the Track** and MUST NOT change; a change requires a new Track. This is what lets the properties live on their own stream, fetched once and cached, instead of being echoed on every SUBSCRIBE and FETCH response. Publisher properties fan *out* at a relay (one upstream subscription serving many downstreams), so a change would have to propagate everywhere; subscriber properties fan *in*, which the relay already merges, so they MAY change freely via SUBSCRIBE_UPDATE. -**Epoch**: -The generation these properties belong to (see [ANNOUNCE_START](#announce-start)), or 0 when the publisher assigns none. -Subscribers key their TRACK_INFO cache by it, and a SUBSCRIBE or FETCH that will parse frames against a cached non-zero Epoch MUST send that Epoch: no data response identifies the generation actually served, so an unpinned request can silently cross a replacement. - **Publisher Priority**: The publisher's priority for this Track, represented as a u8, used only to resolve ties between subscriptions of equal subscriber priority. See the [Prioritization](#prioritization) section for more information. @@ -1176,7 +1140,6 @@ FETCH Message { Message Length (i) Broadcast Path (s) Track Name (s) - Epoch (i) Subscriber Priority (8) Group Sequence (i) Frame Start (i) @@ -1190,10 +1153,6 @@ The broadcast path of the track to fetch from. **Track Name**: The name of the track to fetch from. -**Epoch**: -The generation to fetch from (see [ANNOUNCE_START](#announce-start)): 0 for the current one. -A publisher that retains a non-current generation (e.g. a recording) MAY serve it, but MUST reset the stream rather than serve a group from a different generation than requested. - **Subscriber Priority**: The priority of the fetch within the session, represented as a u8. See the [Prioritization](#prioritization) section for more information. @@ -1334,18 +1293,17 @@ The `Message Length` describes the payload size on the wire. - Split ANNOUNCE_BROADCAST into three typed messages: ANNOUNCE_START (0x0), ANNOUNCE_END (0x1), and ANNOUNCE_UPDATE (0x2), each prefixed with a Type discriminator like the subscribe stream's responses. - Added implicit Announce IDs: each ANNOUNCE_START assigns the next per-stream ordinal. - ANNOUNCE_END and ANNOUNCE_UPDATE reference the Announce ID instead of repeating the broadcast path. -- Replaced the duplicate-`active` restart idiom with ANNOUNCE_UPDATE; a second ANNOUNCE_START for an already-available path is now a protocol violation. -- Made the Announce Stream violations close the session rather than reset the stream: an unknown or retired Announce ID, an ANNOUNCE_START for an already-available path, and any announcement before ANNOUNCE_OK. -- Added an `Epoch` to ANNOUNCE_START and ANNOUNCE_UPDATE: a per-path content generation minted by the original publisher and forwarded unchanged, 0 meaning unspecified. The highest Epoch wins (non-zero outranks 0) and replacement is decided by value rather than arrival order; equal non-zero Epochs splice, and the first entry of the path remains the identity only when both are 0. That fallback identity requires a non-zero first entry: 0 identifies nothing, so it never proves continuity, and publishers SHOULD assign themselves a Hop ID (a random per-session value suffices). -- Stated the ended-broadcast lifecycle without a flag: a broadcast that ends but remains readable is retracted with ANNOUNCE_END, which never disturbs in-flight subscriptions, and its stored groups are read over FETCH, discovered out of band. -- Added an `Epoch` to SUBSCRIBE, FETCH, and TRACK (0 = current, mismatch = reset) and the resolved `Epoch` to TRACK_INFO, so metadata and groups always come from the same generation and requests cannot race a replacement. +- Replaced the duplicate-`active` restart idiom with ANNOUNCE_UPDATE; a second ANNOUNCE_START for an already-advertised prefix is now a protocol violation. +- Made the Announce Stream violations close the session rather than reset the stream: an unknown or retired Announce ID, an ANNOUNCE_START for an already-advertised prefix, and any announcement before ANNOUNCE_OK. +- Redefined an announcement as a route: the advertised path is a prefix claiming that paths beneath it can be served, matching moq-transport's namespace semantics, rather than the exact path of one available broadcast. A route claims capability, not inventory; which covered paths name broadcasts is an application convention (announcing each broadcast's exact path keeps enumeration working). ANNOUNCE_UPDATE updates a route's metadata in place and carries no content claim. Because routes carry no content identity, a relay never splices a live subscription across sources reached through different routes: a serving session ending resets its subscriptions and the subscriber re-requests through the best remaining route. +- Stated the ended-broadcast lifecycle without a flag: a broadcast whose route is retracted with ANNOUNCE_END may remain readable by exact path, its stored groups read over FETCH, discovered out of band; retraction never disturbs in-flight subscriptions. +- Specified route matching as per path segment (a prefix never matches half a segment) and specified how a route broader than the requested prefix presents: clamped to the request, as an empty suffix. - Added `Warm Route Cost` and `Cold Route Cost` fields to ANNOUNCE_START and ANNOUNCE_UPDATE: the same path priced against two cache states. Warm is the accumulated cost of the transfers a subscription via this advertisement would newly cause, and is what route selection minimizes; Cold prices the path as if nothing along it were carrying, and breaks a Warm tie before path length, with the most recently received advertisement below that. Only Warm takes the actively-carrying discount, so Cold still ranks two relays that both advertise 0, and a relay adopts another carrying relay only when that relay's `(Cold cost, hash)` rank is strictly lower. A wire that cannot express Cold is read as the saturation ceiling, not as 0. - Added a SETUP `Cost` parameter (0x4) declaring what subscribing from the sender costs, added by the receiver to every announcement that sender forwards. Both endpoints send their own, so the two directions are priced independently, and a receiver MAY charge a locally configured value instead. Unpriced directions default to 1, degrading to shortest-path routing. - Removed `Exclude Hop` from ANNOUNCE_REQUEST. The receiver's hop-based loop check already discards a looped announcement, so the field only saved the wasted send. - Stated the receiver's loop check normatively in ANNOUNCE_START: an announcement whose reconstructed path contains the receiver's own Hop ID is neither forwarded nor selected as a route. - Added a SETUP `Hop` parameter (0x5): each endpoint declares its Hop ID at session setup, carrying session-wide the identity `Exclude Hop` carried per announce stream, and filtering subscriptions as well as announcements (including sessions that never open an Announce Stream). - Made advertisement selection per subscriber: a publisher MUST NOT advertise a path containing the subscriber's declared Hop ID and otherwise advertises the best remaining one (a subscriber the serving path flows through receives the best standby instead of nothing), MUST serve subscriptions by the same exclusion, and the actively-carrying cost discount applies only to the serving path. This is how redundant publishers fail over across a mesh. -- Defined same-path advertisements with the same non-zero Epoch as interchangeable content a relay may splice across at a Position. When both Epochs are 0, identity falls back to a shared non-zero first Hop ID; differing or unknown identities never splice. - Added `Frame Start` and `Frame End` to SUBSCRIBE and SUBSCRIBE_UPDATE, qualifying the start and end group with a frame index so a subscription can begin or end partway through a group. `Frame Start` is a plain index qualifying the `Group Start` group; `Frame End` is the index + 1, matching `Group End`, and MUST be 0 when `Group End` is absent. - Added `Frame Start` and `Frame End` to FETCH, bounding the returned frames within the group. A publisher that cannot serve the full range resets the stream. - Added `Frame Start` to GROUP, giving the index of the first FRAME on the stream so a partial group is self-describing. diff --git a/go/wrapper/client.go b/go/wrapper/client.go index 7b21c0521df..b361bc4b723 100644 --- a/go/wrapper/client.go +++ b/go/wrapper/client.go @@ -252,18 +252,19 @@ func (c *Client) CreateBroadcast(path string) (*BroadcastProducer, error) { return c.publisher.CreateBroadcast(path) } -// Announced streams broadcasts announced by the remote under prefix. +// Announced streams routes announced by the remote under prefix. func (c *Client) Announced(prefix string) (*Announced, error) { return c.consumer.Announced(prefix) } -// AnnouncedBroadcast resolves a single announced broadcast at path. +// AnnouncedBroadcast waits for a route covering path, then resolves the +// broadcast there. func (c *Client) AnnouncedBroadcast(path string) (*AnnouncedBroadcast, error) { return c.consumer.AnnouncedBroadcast(path) } // RequestBroadcast resolves a broadcast at path as soon as it can be served: an -// existing exact-path broadcast whether announced or not, otherwise a dynamic +// existing exact-path broadcast, a covering announced route, or a dynamic // fallback on the origin, or an error. Unlike AnnouncedBroadcast, it does not wait // for a future announcement. func (c *Client) RequestBroadcast(path string) (*BroadcastConsumer, error) { diff --git a/go/wrapper/example_test.go b/go/wrapper/example_test.go index 3e51bc3ea47..b769352ef72 100644 --- a/go/wrapper/example_test.go +++ b/go/wrapper/example_test.go @@ -32,6 +32,9 @@ func ExampleClient_Announced() { } log.Fatal(err) } + if !ann.Active() { + continue + } fmt.Println("broadcast:", ann.Path()) } } diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index 1b3fa6f33dd..9ffb27eb01e 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -267,11 +267,19 @@ func TestLocalPublishConsumeAudio(t *testing.T) { if ann.Path() != "live" { t.Fatalf("path = %q, want %q", ann.Path(), "live") } - if route := ann.Broadcast().Route(); len(route.Hops) != 0 { + if !ann.Active() { + t.Fatal("expected an active announcement") + } + if route := ann.Route(); len(route.Hops) != 0 { t.Fatalf("route hops = %v, want empty for local origin", route.Hops) } - catalog, err := ann.Broadcast().Catalog(ctx) + bc, err := consumer.RequestBroadcast(ann.Path()) + if err != nil { + t.Fatal(err) + } + + catalog, err := bc.Catalog(ctx) if err != nil { t.Fatal(err) } @@ -288,7 +296,7 @@ func TestLocalPublishConsumeAudio(t *testing.T) { t.Fatalf("audio = %+v, want opus/48000/2", audio) } - mediaConsumer, err := ann.Broadcast().SubscribeMedia(trackName, audio.Container, nil) + mediaConsumer, err := bc.SubscribeMedia(trackName, audio.Container, nil) if err != nil { t.Fatal(err) } diff --git a/go/wrapper/origin.go b/go/wrapper/origin.go index 804b8cd2bf4..baff72adeed 100644 --- a/go/wrapper/origin.go +++ b/go/wrapper/origin.go @@ -38,11 +38,11 @@ func (o *OriginProducer) Dynamic() *OriginDynamic { // CreateBroadcast creates a broadcast at the given path, returning the producer // that feeds it. // -// The broadcast starts live: the origin announces the path so subscribers can -// discover it, becoming visible shortly after this returns. Toggle -// discoverability with [BroadcastProducer.SetAnnounce]; Finish unpublishes -// immediately, while dropping the producer without finishing also unpublishes -// but reads to subscribers as a failure rather than a deliberate end. +// The broadcast starts announced: the origin advertises the exact path as a +// route so subscribers can discover it, becoming visible shortly after this +// returns. Toggle discoverability with [BroadcastProducer.SetAnnounce]; Finish +// unpublishes immediately, while dropping the producer without finishing also +// unpublishes but reads to subscribers as a failure rather than a deliberate end. func (o *OriginProducer) CreateBroadcast(path string) (*BroadcastProducer, error) { inner, err := o.inner.CreateBroadcast(path) if err != nil { @@ -51,6 +51,34 @@ func (o *OriginProducer) CreateBroadcast(path string) (*BroadcastProducer, error return &BroadcastProducer{inner: inner}, nil } +// Announce advertises a route: a claim that paths under route.Prefix can be +// served. Hold the returned Announce for as long as the route should stay +// advertised. Announcing is independent of CreateBroadcast: announce one short +// prefix and serve requests beneath it with Dynamic. +func (o *OriginProducer) Announce(prefix string, route Route) (*Announce, error) { + inner, err := o.inner.Announce(prefix, route) + if err != nil { + return nil, err + } + return &Announce{inner: inner}, nil +} + +// Announce is a live route advertisement. The route stays advertised until +// Cancel (or garbage collection releases the handle). +type Announce struct { + inner *ffi.MoqAnnounce +} + +// Update re-prices the route in place: replaces its hops and cost. +func (a *Announce) Update(route Route) error { + return a.inner.Update(route) +} + +// Cancel retracts the route. +func (a *Announce) Cancel() { + a.inner.Cancel() +} + // OriginDynamic streams requests for paths with no existing exact-path broadcast. type OriginDynamic struct { inner *ffi.MoqOriginDynamic @@ -105,7 +133,7 @@ type OriginConsumer struct { inner *ffi.MoqOriginConsumer } -// Announced streams broadcasts whose path starts with prefix. +// Announced streams route announcements whose prefix starts with prefix. func (o *OriginConsumer) Announced(prefix string) (*Announced, error) { inner, err := o.inner.Announced(prefix) if err != nil { @@ -114,7 +142,8 @@ func (o *OriginConsumer) Announced(prefix string) (*Announced, error) { return &Announced{inner: inner}, nil } -// AnnouncedBroadcast resolves a single broadcast at an exact path. +// AnnouncedBroadcast waits for a route covering an exact path, then resolves +// the broadcast there. func (o *OriginConsumer) AnnouncedBroadcast(path string) (*AnnouncedBroadcast, error) { inner, err := o.inner.AnnouncedBroadcast(path) if err != nil { @@ -123,11 +152,11 @@ func (o *OriginConsumer) AnnouncedBroadcast(path string) (*AnnouncedBroadcast, e return &AnnouncedBroadcast{inner: inner}, nil } -// RequestBroadcast resolves a broadcast at path as soon as it can be served: an -// existing exact-path broadcast whether announced or not, otherwise a dynamic -// fallback on the origin, or an error if neither can serve it. Unlike -// AnnouncedBroadcast, it does not wait for a future announcement. Blocks until -// resolved. +// RequestBroadcast resolves a broadcast at path as soon as it can be served: a +// local broadcast at the exact path, the best announced route covering it +// (served on demand by the session that announced it), or a dynamic fallback on +// the origin; errors if nothing can serve it. Unlike AnnouncedBroadcast, it +// does not wait for a future announcement. Blocks until resolved. func (o *OriginConsumer) RequestBroadcast(path string) (*BroadcastConsumer, error) { inner, err := o.inner.RequestBroadcast(path) if err != nil { @@ -136,22 +165,31 @@ func (o *OriginConsumer) RequestBroadcast(path string) (*BroadcastConsumer, erro return &BroadcastConsumer{inner: inner}, nil } -// Announcement is a discovered broadcast. +// Announcement is a route announcement or retraction. A route claims that +// paths under Path can be served; it carries no broadcast. Resolve a specific +// path with [OriginConsumer.RequestBroadcast]. By convention a publisher +// announces each broadcast's exact path. type Announcement struct { inner *ffi.MoqAnnouncement } -// Path is the broadcast's announced path. +// Path is the announced route's prefix, relative to the Announced prefix. func (a *Announcement) Path() string { return a.inner.Path() } -// Broadcast returns a consumer for the announced broadcast's tracks. -func (a *Announcement) Broadcast() *BroadcastConsumer { - return &BroadcastConsumer{inner: a.inner.Broadcast()} +// Active reports whether the route is active (true) or was retracted (false). +// A repeated active announcement for the same path is a metadata update. +func (a *Announcement) Active() bool { + return a.inner.Active() +} + +// Route is the route serving the prefix: its relay hops and cost. +func (a *Announcement) Route() Route { + return a.inner.Route() } -// Announced is a stream of broadcast announcements. +// Announced is a stream of route announcements and retractions. type Announced struct { inner *ffi.MoqAnnounced } diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index dfc3526bc9f..2bcb9e0db95 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -80,16 +80,9 @@ func (b *BroadcastProducer) Dynamic() (*BroadcastDynamic, error) { return &BroadcastDynamic{inner: inner}, nil } -// SetRoute sets the broadcast's route: the hop chain, cost, and liveness it -// advertises. Use it as conditions shift (e.g. a standby transcoder lowering -// its cost once warm); consumers observe the change via RouteUpdates. -func (b *BroadcastProducer) SetRoute(route Route) error { - return b.inner.SetRoute(route) -} - -// SetAnnounce sets whether the broadcast is announced, keeping the rest of its route. +// SetAnnounce sets whether the broadcast's exact path is announced as a route. // -// The origin announces the path only while the broadcast is announced; a unannounced +// The origin announces the path only while the broadcast is announced; an unannounced // broadcast stays reachable by exact path for subscribes and fetches. This is // how a publisher goes on and off the air without tearing down the broadcast. func (b *BroadcastProducer) SetAnnounce(live bool) error { diff --git a/go/wrapper/subscribe.go b/go/wrapper/subscribe.go index e5a2cd90e6a..110665b014e 100644 --- a/go/wrapper/subscribe.go +++ b/go/wrapper/subscribe.go @@ -12,34 +12,6 @@ type BroadcastConsumer struct { inner *ffi.MoqBroadcastConsumer } -// Route returns the route the broadcast currently takes to reach this origin: -// relay hop ids (oldest first) plus the publisher's advertised cost (lower wins). -func (b *BroadcastConsumer) Route() Route { - return b.inner.Route() -} - -// RouteUpdates watches the broadcast's route. Next yields the current route -// first, then every change (e.g. an upstream failover). -func (b *BroadcastConsumer) RouteUpdates() *RouteWatch { - return &RouteWatch{inner: b.inner.RouteUpdates()} -} - -// RouteWatch is a stream of route updates for one broadcast. -type RouteWatch struct { - inner *ffi.MoqRouteWatch -} - -// Next returns the next route: the current one on the first call, then each -// change, or (nil, nil) when the broadcast ends. -func (r *RouteWatch) Next(ctx context.Context) (*Route, error) { - return runCancellable(ctx, r.inner.Cancel, r.inner.Next) -} - -// Cancel stops the watch, unblocking any in-flight Next. -func (r *RouteWatch) Cancel() { - r.inner.Cancel() -} - // SubscribeCatalog subscribes to the broadcast's catalog track. func (b *BroadcastConsumer) SubscribeCatalog() (*CatalogConsumer, error) { inner, err := b.inner.SubscribeCatalog() diff --git a/js/moq-boy/src/element.tsx b/js/moq-boy/src/element.tsx index 65942871570..9e690df439b 100644 --- a/js/moq-boy/src/element.tsx +++ b/js/moq-boy/src/element.tsx @@ -138,7 +138,7 @@ export default class MoqBoy extends HTMLElement { if (!entry) break; // Skip nested paths (e.g. "viewer/..." sub-broadcasts). - const suffix = entry.path; + const suffix = entry.prefix; if (!suffix || suffix.includes("/")) continue; const id = suffix; diff --git a/js/net/examples/discovery.ts b/js/net/examples/discovery.ts index 06d97d6430e..e426b2e3d2f 100644 --- a/js/net/examples/discovery.ts +++ b/js/net/examples/discovery.ts @@ -12,10 +12,10 @@ async function main() { const announcement = await announced.next(); if (!announcement) break; - console.log("New stream available:", announcement.path); + console.log("New stream available:", announcement.prefix); // Subscribe to new streams - const _broadcast = connection.consume(announcement.path); + const _broadcast = connection.consume(announcement.prefix); // Do something with the broadcast } diff --git a/js/net/src/announced.test.ts b/js/net/src/announced.test.ts index 9e254bfc574..b31161dc750 100644 --- a/js/net/src/announced.test.ts +++ b/js/net/src/announced.test.ts @@ -9,11 +9,11 @@ test("next streams every appended event in order", async () => { const producer = new Announce.Producer(); const consumer = producer.consume(); - producer.append({ path: p("a"), active: true }); - producer.append({ path: p("a"), active: false }); + producer.append({ prefix: p("a"), active: true }); + producer.append({ prefix: p("a"), active: false }); - expect(await consumer.next()).toEqual({ path: p("a"), active: true }); - expect(await consumer.next()).toEqual({ path: p("a"), active: false }); + expect(await consumer.next()).toEqual({ prefix: p("a"), active: true }); + expect(await consumer.next()).toEqual({ prefix: p("a"), active: false }); }); test("a same-name re-announce is a distinct update", async () => { @@ -23,11 +23,11 @@ test("a same-name re-announce is a distinct update", async () => { // The stream is a log, not a set: it carries a redundant active:true as its own update rather // than collapsing it. Deciding what a repeat means belongs to the session layer, which resolves // a restart into either nothing (a route change) or an end + start (a new publisher). - producer.append({ path: p("a"), active: true }); - producer.append({ path: p("a"), active: true }); + producer.append({ prefix: p("a"), active: true }); + producer.append({ prefix: p("a"), active: true }); - expect(await consumer.next()).toEqual({ path: p("a"), active: true }); - expect(await consumer.next()).toEqual({ path: p("a"), active: true }); + expect(await consumer.next()).toEqual({ prefix: p("a"), active: true }); + expect(await consumer.next()).toEqual({ prefix: p("a"), active: true }); }); test("closing resolves next with undefined", async () => { diff --git a/js/net/src/announced.ts b/js/net/src/announced.ts index d235db33520..7cadae22e22 100644 --- a/js/net/src/announced.ts +++ b/js/net/src/announced.ts @@ -10,14 +10,19 @@ import type { Request as OriginRequest, Table as OriginTable } from "./origin.js import * as Path from "./path.js"; /** - * The availability of a broadcast. + * A route announcement or retraction. + * + * A route claims that paths under {@link prefix} can be served; it carries no + * broadcast. By convention a publisher announces each broadcast's exact path, + * so enumerating routes enumerates broadcasts; resolve one with the origin's + * `request(path)`. * * @public */ export interface Event { - /** Broadcast path relative to the prefix passed to `announced()`. */ - path: Path.Valid; - /** True when the broadcast is available, false when it was removed. */ + /** What the route covers, relative to the prefix passed to `announced()`. */ + prefix: Path.Valid; + /** True while the route is advertised, false when it was retracted. */ active: boolean; } @@ -287,7 +292,7 @@ export class Broadcast { if (!event) break; // Scoped to `path`, so the exact broadcast arrives with an empty suffix; ignore children. - if (event.path !== Path.empty()) continue; + if (event.prefix !== Path.empty()) continue; if (event.active) { // A live subscription survives a redundant (re-)announce; only replace a dead one. @@ -356,7 +361,7 @@ export class Broadcast { if (!event) break; // Scoped to `path`, so the exact broadcast arrives with an empty suffix; ignore children. - if (event.path !== Path.empty()) continue; + if (event.prefix !== Path.empty()) continue; if (event.active) { current?.close(); diff --git a/js/net/src/connection/forward.test.ts b/js/net/src/connection/forward.test.ts index d6bc0252fe8..4c92de31b0f 100644 --- a/js/net/src/connection/forward.test.ts +++ b/js/net/src/connection/forward.test.ts @@ -72,7 +72,7 @@ test("a discovery failure under a live session downgrades the origin", async () forwardAnnounced(session.session, origin); // The relay announces a broadcast, which lands in the table. - session.announces.append({ path, active: true }); + session.announces.append({ prefix: path, active: true }); await settle(); expect(origin.discovery.peek()).toBe(true); expect(origin.routes(path)).toBe(true); @@ -112,7 +112,7 @@ test("a request outlives the discovery failure that fed it", async () => { forwardAnnounced(session.session, origin); // Announced, so the table routes it and no blind answer is needed. - session.announces.append({ path, active: true }); + session.announces.append({ prefix: path, active: true }); await settle(); const request = origin.request(path); diff --git a/js/net/src/connection/forward.ts b/js/net/src/connection/forward.ts index 8d53cc355b2..a6aa1be09bf 100644 --- a/js/net/src/connection/forward.ts +++ b/js/net/src/connection/forward.ts @@ -1,5 +1,5 @@ /** - * Feeds a session's announced broadcasts into an origin; the `subscribe` connect option. + * Feeds a session's announced routes into an origin; the `subscribe` connect option. * * @module */ @@ -10,13 +10,14 @@ import type { Established } from "./established.ts"; /** * Wire a session into `origin` for the session's lifetime: forward the peer's announced - * broadcasts into the table, and answer the origin's open requests with blind + * routes into the table, and answer the origin's open requests with blind * subscriptions. * - * Each active announcement inserts a lazily-subscribing front, so nothing touches the wire - * until somebody consumes the path. A retraction removes the entry, and so does the session - * dying (the announce stream ends with it), which is what scopes remote entries to the - * session that discovered them. A reconnect wires a fresh session to the same origin and + * Each active announcement inserts a route covering the announced prefix, served + * lazily through this connection, so nothing touches the wire until somebody requests + * a path under it. A retraction removes the entry, and so does the session dying (the + * announce stream ends with it), which is what scopes remote routes to the session + * that announced them. A reconnect wires a fresh session to the same origin and * re-populates it. * * Without discovery there are no announcements to forward, so the table stays empty and @@ -58,12 +59,12 @@ export function forwardAnnounced(conn: Established, origin: OriginProducer): voi if (!event) break; if (event.active) { - // A same-path re-announce supersedes: retract the old front first. - inserted.get(event.path)?.(); - inserted.set(event.path, origin.insertRemote(event.path, conn.consume(event.path))); + // A same-prefix re-announce supersedes: retract the old route first. + inserted.get(event.prefix)?.(); + inserted.set(event.prefix, origin.announce(event.prefix, conn)); } else { - const dispose = inserted.get(event.path); - inserted.delete(event.path); + const dispose = inserted.get(event.prefix); + inserted.delete(event.prefix); dispose?.(); } } diff --git a/js/net/src/connection/pool.ts b/js/net/src/connection/pool.ts index 90a82865e0e..4f8d1df0b6f 100644 --- a/js/net/src/connection/pool.ts +++ b/js/net/src/connection/pool.ts @@ -164,14 +164,14 @@ export class Shared { for (;;) { const entry = await Promise.race([effect.cancel, upstream.next()]); if (!entry) break; - if (entry.active) active.add(entry.path); - else active.delete(entry.path); + if (entry.active) active.add(entry.prefix); + else active.delete(entry.prefix); producer.append(entry); } } finally { if (!closed) { for (const path of active) { - producer.append({ path, active: false }); + producer.append({ prefix: path, active: false }); } } } diff --git a/js/net/src/connection/reload.ts b/js/net/src/connection/reload.ts index b112cba862b..a30bd3f006b 100644 --- a/js/net/src/connection/reload.ts +++ b/js/net/src/connection/reload.ts @@ -375,8 +375,8 @@ export class Reload { for (;;) { const entry = await Promise.race([effect.cancel, upstream.next()]); if (!entry) break; - if (entry.active) active.add(entry.path); - else active.delete(entry.path); + if (entry.active) active.add(entry.prefix); + else active.delete(entry.prefix); producer.append(entry); } } catch { @@ -385,8 +385,8 @@ export class Reload { // Retract everything from the connection that just went away, so a per-broadcast // watcher tears down instead of clinging to the dead route. if (!closed) { - for (const path of active) { - producer.append({ path, active: false }); + for (const prefix of active) { + producer.append({ prefix, active: false }); } } } diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index b1577b69885..1512bb55d55 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -82,7 +82,7 @@ test("an unsolicited announcement lands", async () => { ); const next = await announced.next(); - expect(next?.path).toBe(Path.from("surprise")); + expect(next?.prefix).toBe(Path.from("surprise")); expect(next?.active).toBe(true); // The handler holds the request open until the peer drops it, and withdraws the @@ -91,7 +91,7 @@ test("an unsolicited announcement lands", async () => { if (!peer) throw new Error("no PUBLISH_NAMESPACE stream to close"); peer.close(); await handler; - expect(await announced.next()).toMatchObject({ path: Path.from("surprise"), active: false }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("surprise"), active: false }); }); /** @@ -124,7 +124,7 @@ async function inlineNamespace(stream: Stream, path: Path.Valid, cluster?: Clust */ async function syncInline(stream: Stream, announced: announce.Consumer, cluster?: Cluster.Advert): Promise { await inlineNamespace(stream, Path.from("sentinel"), cluster); - expect(await announced.next()).toMatchObject({ path: Path.from("sentinel"), active: true }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("sentinel"), active: true }); } /** @@ -149,7 +149,7 @@ test("an announcement survives the first of its two sources ending", async () => new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("both") }), request, ); - expect(await announced.next()).toMatchObject({ path: Path.from("both"), active: true }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("both"), active: true }); await inlineNamespace(subscription, Path.from("both")); await syncInline(subscription, announced); @@ -185,7 +185,7 @@ test("an announcement ends once its last source does", async () => { new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("both") }), request, ); - expect(await announced.next()).toMatchObject({ path: Path.from("both"), active: true }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("both"), active: true }); await inlineNamespace(subscription, Path.from("both")); await syncInline(subscription, announced); @@ -199,7 +199,7 @@ test("an announcement ends once its last source does", async () => { await subscription.writer.u53(SubscribeNamespaceEntryDone.id); await new SubscribeNamespaceEntryDone({ suffix: Path.from("both") }).encode(subscription.writer, VERSION); - expect(await announced.next()).toMatchObject({ path: Path.from("both"), active: false }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("both"), active: false }); }); /** @@ -220,13 +220,13 @@ test("a subscription that dies releases what it advertised", async () => { await acceptSubscribeNamespace(pair.client); await inlineNamespace(streamA, Path.from("orphan")); - expect(await doomed.next()).toMatchObject({ path: Path.from("orphan"), active: true }); - expect(await survivor.next()).toMatchObject({ path: Path.from("orphan"), active: true }); + expect(await doomed.next()).toMatchObject({ prefix: Path.from("orphan"), active: true }); + expect(await survivor.next()).toMatchObject({ prefix: Path.from("orphan"), active: true }); // The stream that advertised it goes away without a NAMESPACE_DONE. streamA.writer.close(); - expect(await survivor.next()).toMatchObject({ path: Path.from("orphan"), active: false }); + expect(await survivor.next()).toMatchObject({ prefix: Path.from("orphan"), active: false }); }); /** @@ -248,7 +248,7 @@ test("a duplicate legacy publish_namespace is still refused", async () => { new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("twice") }), first, ); - expect(await announced.next()).toMatchObject({ path: Path.from("twice"), active: true }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("twice"), active: true }); // The same namespace again, on its own request. const second = await Stream.open(pair.server, { version: Version.DRAFT_15 }); @@ -263,7 +263,7 @@ test("a duplicate legacy publish_namespace is still refused", async () => { peer.close(); await handler; - expect(await announced.next()).toMatchObject({ path: Path.from("twice"), active: false }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("twice"), active: false }); }); /** @@ -322,7 +322,7 @@ test("concurrent legacy publish_namespace requests take one reference", async () second, ); - expect(await announced.next()).toMatchObject({ path: Path.from("raced"), active: true }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("raced"), active: true }); await two; // Only one reference was taken, so the surviving request ending retracts the path. @@ -331,7 +331,7 @@ test("concurrent legacy publish_namespace requests take one reference", async () peer.close(); await one; - expect(await announced.next()).toMatchObject({ path: Path.from("raced"), active: false }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("raced"), active: false }); }); /** The Hop IDs a cluster-negotiated session declared, ours first. */ @@ -370,10 +370,10 @@ test("an inline NAMESPACE that starts looping back is retracted", async () => { const subscription = await acceptSubscribeNamespace(pair.client); await inlineNamespace(subscription, Path.from("theirs"), { hops: [PEER], cost: 0n }); - expect(await announced.next()).toMatchObject({ path: Path.from("theirs"), active: true }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("theirs"), active: true }); await inlineNamespace(subscription, Path.from("theirs"), { hops: [SELF, PEER], cost: 0n }); - expect(await announced.next()).toMatchObject({ path: Path.from("theirs"), active: false }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("theirs"), active: false }); }); /** The same rule on the other kind of advertisement, which is a request we can refuse. */ @@ -450,7 +450,7 @@ test("a PUBLISH_NAMESPACE update that starts looping back is detached", async () const request = await Stream.open(pair.server, { version: VERSION }); const handler = subscriber.runPublishNamespace(advert([PEER]), request); - expect(await announced.next()).toMatchObject({ path: Path.from("theirs"), active: true }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("theirs"), active: true }); // The peer re-parents the namespace onto a route that runs back through us. const peer = await nextStream(pair.client); @@ -458,7 +458,7 @@ test("a PUBLISH_NAMESPACE update that starts looping back is detached", async () await peer.writer.u53(PublishNamespace.id); await advert([SELF, PEER]).encode(peer.writer, VERSION); - expect(await announced.next()).toMatchObject({ path: Path.from("theirs"), active: false }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("theirs"), active: false }); peer.close(); await handler; diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index b01385115a5..5b180994da6 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -148,7 +148,7 @@ export class Subscriber { for (const active of this.#announced.keys()) { const suffix = Path.stripPrefix(prefix, active); if (suffix === null) continue; - announced.append({ path: suffix, active: true }); + announced.append({ prefix: suffix, active: true }); } this.#announcedConsumers.add(announced); @@ -173,7 +173,7 @@ export class Subscriber { for (const consumer of this.#announcedConsumers) { const suffix = Path.stripPrefix(consumer.prefix, path); if (suffix === null) continue; - consumer.append({ path: suffix, active: true }); + consumer.append({ prefix: suffix, active: true }); } } @@ -199,7 +199,7 @@ export class Subscriber { const suffix = Path.stripPrefix(consumer.prefix, path); if (suffix === null) continue; try { - consumer.append({ path: suffix, active: false }); + consumer.append({ prefix: suffix, active: false }); } catch { // Consumer already closed, will be cleaned up } diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index ff59d6caf2d..e90f4a1a828 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -65,14 +65,14 @@ async function runPublishSubscribeFlow(protocol: string, version?: number) { const announced = client.announced(); const entry = await announced.next(); if (!entry) throw new Error("expected entry"); - expect(entry.path).toBe("test" as Path.Valid); + expect(entry.prefix).toBe("test" as Path.Valid); expect(entry.active).toBe(true); // Prefix-scoped discovery returns paths relative to the requested prefix. const prefixed = client.announced(Path.from("root")); const prefixedEntry = await prefixed.next(); if (!prefixedEntry) throw new Error("expected prefixed entry"); - expect(prefixedEntry.path).toBe("child" as Path.Valid); + expect(prefixedEntry.prefix).toBe("child" as Path.Valid); expect(prefixedEntry.active).toBe(true); // Client consumes the broadcast and subscribes to a track @@ -245,28 +245,28 @@ test("integration: lite draft-06 announce lifecycle", async () => { const announced = client.announced(); let entry = await announced.next(); if (!entry) throw new Error("expected announce"); - expect(entry.path).toBe("first" as Path.Valid); + expect(entry.prefix).toBe("first" as Path.Valid); expect(entry.active).toBe(true); // A live announce. const second = origin.publish(Path.from("second")); entry = await announced.next(); if (!entry) throw new Error("expected announce"); - expect(entry.path).toBe("second" as Path.Valid); + expect(entry.prefix).toBe("second" as Path.Valid); expect(entry.active).toBe(true); // Unannounce: retracted by announce id on the wire. second.close(); entry = await announced.next(); if (!entry) throw new Error("expected unannounce"); - expect(entry.path).toBe("second" as Path.Valid); + expect(entry.prefix).toBe("second" as Path.Valid); expect(entry.active).toBe(false); // Re-announce the same path: a fresh announce assigning a fresh id. const secondAgain = origin.publish(Path.from("second")); entry = await announced.next(); if (!entry) throw new Error("expected re-announce"); - expect(entry.path).toBe("second" as Path.Valid); + expect(entry.prefix).toBe("second" as Path.Valid); expect(entry.active).toBe(true); // Cleanup @@ -1340,7 +1340,7 @@ async function runOriginFlow(protocol: string, version?: number) { // The announcement lands in the client's origin. const reader = clientOrigin.consume(); const announced = reader.announced(); - expect(await announced.next()).toEqual({ path: Path.from("test"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("test"), active: true }); // Consuming through the origin reaches the wire. const remote = routed(reader, Path.from("test")); @@ -1350,7 +1350,7 @@ async function runOriginFlow(protocol: string, version?: number) { // Unpublishing retracts the entry over the wire and out of the origin. broadcast.close(); - expect(await announced.next()).toEqual({ path: Path.from("test"), active: false }); + expect(await announced.next()).toEqual({ prefix: Path.from("test"), active: false }); await until(() => !reader.routes(Path.from("test"))); await serving; diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index edd2f1e02e3..b35b2c06002 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -141,7 +141,7 @@ test("a restart from the same publisher is a route change, not a republish", asy Version.DRAFT_06, ), ); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); // Same publisher over a new route. In-flight subscriptions resume across it, so the // subscriber must not surface anything that would make a consumer re-subscribe. @@ -150,19 +150,19 @@ test("a restart from the same publisher is a route change, not a republish", asy // A different publisher took the path: nothing carries over, so this one does surface, // as an end before the start. Reaching it proves the reroute above emitted nothing. await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_B] }, Version.DRAFT_06)); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: false }); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: false }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); // A third publisher takes over. The replacement above has to leave its own publisher on // record, or this one reads as a first announcement and skips the end. await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_C] }, Version.DRAFT_06)); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: false }); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: false }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); // And the new owner's own reroute is still transparent. await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_C] }, Version.DRAFT_06)); await send((w) => encodeAnnounceBroadcast(w, { status: "endedId", id: 0n }, Version.DRAFT_06)); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: false }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: false }); announced.close(); subscriber.close(); @@ -178,13 +178,13 @@ test("a lite-05 duplicate announce follows the same restart rule", async () => { encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room"), hops }, Version.DRAFT_05); await send(active([PUBLISHER_A])); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); // On lite-05 a restart travels as a duplicate ANNOUNCE rather than its own message. await send(active([PUBLISHER_A])); await send(active([PUBLISHER_B])); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: false }); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: false }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); announced.close(); subscriber.close(); @@ -204,12 +204,12 @@ test("a restart from an unidentified publisher replaces rather than reroutes", a await send((w) => encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room"), hops: [] }, Version.DRAFT_06), ); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); // Nobody is named on either side, so this is not provably the same content. await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [] }, Version.DRAFT_06)); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: false }); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: false }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); announced.close(); subscriber.close(); @@ -370,11 +370,11 @@ test("a restart replaces an announce that was skipped as a reflected loop", asyn // The id stays live, so the peer may restart it into a route that is usable here. await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_A] }, Version.DRAFT_06)); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); // Retiring the id ends what the restart attached, and nothing else. await send((w) => encodeAnnounceBroadcast(w, { status: "endedId", id: 0n }, Version.DRAFT_06)); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: false }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: false }); announced.close(); subscriber.close(); @@ -404,13 +404,13 @@ test("retiring an id whose announce was skipped ends nothing", async () => { Version.DRAFT_06, ), ); - expect(await announced.next()).toEqual({ path: Path.from("lobby"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("lobby"), active: true }); // Retire the skipped one, then the live one. The first must surface nothing, so the // only end a consumer sees is "lobby". await send((w) => encodeAnnounceBroadcast(w, { status: "endedId", id: 0n }, Version.DRAFT_06)); await send((w) => encodeAnnounceBroadcast(w, { status: "endedId", id: 1n }, Version.DRAFT_06)); - expect(await announced.next()).toEqual({ path: Path.from("lobby"), active: false }); + expect(await announced.next()).toEqual({ prefix: Path.from("lobby"), active: false }); announced.close(); subscriber.close(); @@ -424,10 +424,10 @@ test("a draft-02 initial announcement can still be retracted", async () => { // ANNOUNCE_INIT carries the initial set. These are advertisements like any other, so // the peer may retract one later and the consumer has to hear about it. await send((w) => new AnnounceInit([Path.from("room")]).encode(w, Version.DRAFT_02)); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); await send((w) => encodeAnnounceBroadcast(w, { status: "ended", suffix: Path.from("room") }, Version.DRAFT_02)); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: false }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: false }); announced.close(); subscriber.close(); @@ -449,7 +449,7 @@ test("a duplicate start is reported even when its own route reflects", async () Version.DRAFT_06, ), ); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); // A second start for that path, carrying a route that loops back through us. Skipping // it must not pre-empt the violation: the peer sent two starts with no end between @@ -505,7 +505,7 @@ test("a violation on a very long path still ends the session", async () => { const long = Path.from("x".repeat(2000)); const active: AnnounceBroadcast = { status: "active", suffix: long, hops: [PUBLISHER_A] }; await send((w) => encodeAnnounceBroadcast(w, active, Version.DRAFT_06)); - expect(await announced.next()).toEqual({ path: long, active: true }); + expect(await announced.next()).toEqual({ prefix: long, active: true }); await send((w) => encodeAnnounceBroadcast(w, active, Version.DRAFT_06)); await expect(announced.next()).rejects.toThrow("duplicate announce"); @@ -526,7 +526,7 @@ test("a draft-04 duplicate start is a violation, not a restart", async () => { const active: AnnounceBroadcast = { status: "active", suffix: Path.from("room"), hops: [PUBLISHER_A] }; await send((w) => encodeAnnounceBroadcast(w, active, Version.DRAFT_04)); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); await send((w) => encodeAnnounceBroadcast(w, active, Version.DRAFT_04)); @@ -545,7 +545,7 @@ test("a draft-05 duplicate start is still a restart", async () => { const active: AnnounceBroadcast = { status: "active", suffix: Path.from("room"), hops: [PUBLISHER_A] }; await send((w) => encodeAnnounceBroadcast(w, active, Version.DRAFT_05)); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); // Same publisher over a new route: transparent, and emphatically not an error. await send((w) => encodeAnnounceBroadcast(w, active, Version.DRAFT_05)); @@ -553,8 +553,8 @@ test("a draft-05 duplicate start is still a restart", async () => { // A different publisher does surface, which is what proves the reroute above passed. const replaced: AnnounceBroadcast = { status: "active", suffix: Path.from("room"), hops: [PUBLISHER_B] }; await send((w) => encodeAnnounceBroadcast(w, replaced, Version.DRAFT_05)); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: false }); - expect(await announced.next()).toEqual({ path: Path.from("room"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: false }); + expect(await announced.next()).toEqual({ prefix: Path.from("room"), active: true }); announced.close(); subscriber.close(); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index e69ac3ef3f6..f0596434a3c 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -257,7 +257,7 @@ export class Subscriber { } advertised.set(suffix, { publisher: undefined, live: true }); console.debug(`announced: broadcast=${path} active=true`); - announced.append({ path: suffix, active: true }); + announced.append({ prefix: suffix, active: true }); } break; } @@ -348,7 +348,7 @@ export class Subscriber { if (!previous?.live) return; this.#consumes.evict(path); console.debug(`announced: broadcast=${path} active=false`); - announced.append({ path: suffix, active: false }); + announced.append({ prefix: suffix, active: false }); }; // In Lite05+ the sender's origin arrives via AnnounceOk, not in each hop @@ -404,7 +404,7 @@ export class Subscriber { } console.debug(`announced: broadcast=${path} active=true`); - announced.append({ path: suffix, active: true }); + announced.append({ prefix: suffix, active: true }); } announced.close(); diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index 3cf241507ac..631e2f274c0 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -24,6 +24,11 @@ function routed(consumer: Consumer, path: Path.Valid): BroadcastConsumer | undef return front; } +/** A stand-in for a session announcing a route: serves any path from `producer`. */ +function provider(producer: BroadcastProducer) { + return { consume: () => producer.consume() }; +} + test("a published broadcast resolves by path", async () => { const origin = new Producer(); const consumer = origin.consume(); @@ -168,16 +173,16 @@ test("announced streams the table with prefix-relative paths", async () => { const announced = consumer.announced(Path.from("room")); // The initial state arrives first. - expect(await announced.next()).toEqual({ path: Path.from("a"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("a"), active: true }); // Additions under the prefix stream in; paths outside it are invisible. const b = origin.publish(Path.from("room/b")); origin.publish(Path.from("lobby/c")); - expect(await announced.next()).toEqual({ path: Path.from("b"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("b"), active: true }); // Removals retract. b.close(); - expect(await announced.next()).toEqual({ path: Path.from("b"), active: false }); + expect(await announced.next()).toEqual({ prefix: Path.from("b"), active: false }); // The stream ends when the origin closes. origin.close(); @@ -193,7 +198,7 @@ test("a remote entry resolves by path and retracts on dispose", async () => { // Stand in for a session's discovered broadcast. const upstream = new BroadcastProducer(); - const dispose = origin.insertRemote(path, upstream.consume()); + const dispose = origin.announce(path, provider(upstream)); const handle = routed(consumer, path); expect(handle).toBeDefined(); @@ -201,10 +206,10 @@ test("a remote entry resolves by path and retracts on dispose", async () => { // Announced streams include remote entries. const announced = consumer.announced(); - expect(await announced.next()).toEqual({ path, active: true }); + expect(await announced.next()).toEqual({ prefix: path, active: true }); dispose(); - expect(await announced.next()).toEqual({ path, active: false }); + expect(await announced.next()).toEqual({ prefix: path, active: false }); expect(consumer.routes(path)).toBe(false); announced.close(); @@ -212,6 +217,26 @@ test("a remote entry resolves by path and retracts on dispose", async () => { origin.close(); }); +test("announced reports a broader covering route at the root", async () => { + const origin = new Producer(); + const consumer = origin.consume(); + + const upstream = new BroadcastProducer(); + const dispose = origin.announce(Path.from("room"), provider(upstream)); + + // A route above the requested prefix covers everything under it, so it + // presents at the root, matching what request() resolves there. + const announced = consumer.announced(Path.from("room/alice")); + expect(await announced.next()).toEqual({ prefix: Path.empty(), active: true }); + + dispose(); + expect(await announced.next()).toEqual({ prefix: Path.empty(), active: false }); + + announced.close(); + upstream.close(); + origin.close(); +}); + test("a local publish shadows a remote entry", async () => { const origin = new Producer(); const consumer = origin.consume(); @@ -219,7 +244,7 @@ test("a local publish shadows a remote entry", async () => { const upstream = new BroadcastProducer(); upstream.createTrack("remote-track"); - const dispose = origin.insertRemote(path, upstream.consume()); + const dispose = origin.announce(path, provider(upstream)); const local = origin.publish(path); local.createTrack("local-track"); @@ -233,7 +258,7 @@ test("a local publish shadows a remote entry", async () => { // One path, one announcement, even though both tables route it. const announced = consumer.announced(); - expect(await announced.next()).toEqual({ path, active: true }); + expect(await announced.next()).toEqual({ prefix: path, active: true }); // Dropping the local publish falls back to the remote entry without a retraction. local.close(); @@ -253,7 +278,7 @@ test("the publisher-facing table excludes remote entries", async () => { origin.publish(Path.from("mine")); const upstream = new BroadcastProducer(); - origin.insertRemote(Path.from("theirs"), upstream.consume()); + origin.announce(Path.from("theirs"), provider(upstream)); // What a session announces to a peer: local only, so a shared origin cannot echo. const table = consumer.broadcasts.peek(); @@ -264,18 +289,18 @@ test("the publisher-facing table excludes remote entries", async () => { origin.close(); }); -test("inserting into a closed origin releases the front", async () => { +test("inserting into a closed origin routes nothing", async () => { const origin = new Producer(); origin.close(); const upstream = new BroadcastProducer(); - const front = upstream.consume(); - const dispose = origin.insertRemote(Path.from("late"), front); + const dispose = origin.announce(Path.from("late"), provider(upstream)); dispose(); - // The origin dropped the only handle, closing the broadcast. + // Nothing was materialized, so the provider's broadcast is untouched. await settle(); - expect(upstream.closed.peek()).not.toBeUndefined(); + expect(upstream.closed.peek()).toBeUndefined(); + upstream.close(); }); test("a request resolves once a front answers, and survives its withdrawal", async () => { @@ -349,18 +374,18 @@ test("disposing the newest remote route promotes the fallback", async () => { // one goes away, so the route must fail over rather than black-hole. const older = new BroadcastProducer(); older.createTrack("chat"); - const disposeOlder = origin.insertRemote(path, older.consume()); + const disposeOlder = origin.announce(path, provider(older)); const newer = new BroadcastProducer(); - const disposeNewer = origin.insertRemote(path, newer.consume()); + const disposeNewer = origin.announce(path, provider(newer)); const announced = consumer.announced(); - expect(await announced.next()).toEqual({ path, active: true }); + expect(await announced.next()).toEqual({ prefix: path, active: true }); // The newer session dies: consumers see a retract then the promoted fallback. disposeNewer(); - expect(await announced.next()).toEqual({ path, active: false }); - expect(await announced.next()).toEqual({ path, active: true }); + expect(await announced.next()).toEqual({ prefix: path, active: false }); + expect(await announced.next()).toEqual({ prefix: path, active: true }); const handle = routed(consumer, path); const track = handle?.subscribe("chat"); @@ -426,7 +451,7 @@ test("requests never appear in announced or the table", async () => { const announced = consumer.announced(); origin.publish(Path.from("real")); - expect(await announced.next()).toEqual({ path: Path.from("real"), active: true }); + expect(await announced.next()).toEqual({ prefix: Path.from("real"), active: true }); announced.close(); request.close(); @@ -440,12 +465,12 @@ test("a republish retracts then re-announces the path", async () => { origin.publish(path); const announced = consumer.announced(); - expect(await announced.next()).toEqual({ path, active: true }); + expect(await announced.next()).toEqual({ prefix: path, active: true }); // A new broadcast takes the path: consumers must let go of the superseded one. origin.publish(path); - expect(await announced.next()).toEqual({ path, active: false }); - expect(await announced.next()).toEqual({ path, active: true }); + expect(await announced.next()).toEqual({ prefix: path, active: false }); + expect(await announced.next()).toEqual({ prefix: path, active: true }); announced.close(); origin.close(); @@ -472,7 +497,7 @@ test("a routed path needs no blind answer", async () => { // What a serving session scans: a request on a path the table routes resolves to that // route, so answering it blind would park a handle nothing reads. const upstream = new BroadcastProducer(); - const dispose = origin.insertRemote(path, upstream.consume()); + const dispose = origin.announce(path, provider(upstream)); const request = consumer.request(path); expect(origin.routes(path)).toBe(true); @@ -589,21 +614,31 @@ test("a retracted route is retired even for a request nobody reads again", async const older = new BroadcastProducer(); const newer = new BroadcastProducer(); - const disposeOlder = origin.insertRemote(path, older.consume()); - const disposeNewer = origin.insertRemote(path, newer.consume()); + // Model a session provider faithfully: the session holds its own handle on the + // broadcast for its lifetime and lends out clones, so releasing a materialized + // front never closes the producer. + const keepOlder = older.consume(); + const keepNewer = newer.consume(); + const disposeOlder = origin.announce(path, { consume: () => keepOlder.clone() }); + const disposeNewer = origin.announce(path, { consume: () => keepNewer.clone() }); const request = consumer.request(path); // One read, then the holder goes quiet: a peek-only holder must not pin the route. expect(request.active.peek()).toBeDefined(); - // The newest route retracts and the older one is promoted. Nothing reads `active`. + // The newest route retracts and the older one is promoted. Nothing reads + // `active`, but the retracted route's materialized subscription is released + // all the same (the producer itself belongs to the session, so it stays open). disposeNewer(); await settle(); - expect(newer.closed.peek()).not.toBeUndefined(); + expect(newer.closed.peek()).toBeUndefined(); request.close(); disposeOlder(); + keepNewer.close(); + keepOlder.close(); + newer.close(); older.close(); origin.close(); }); @@ -735,7 +770,7 @@ test("a seeded route still notifies when it retracts", async () => { // its first value. A silent seed leaves the pre-seed value as the baseline the next // change is compared against, which makes this retraction look like no change at all. const upstream = new BroadcastProducer(); - const dispose = origin.insertRemote(path, upstream.consume()); + const dispose = origin.announce(path, provider(upstream)); const request = origin.consume().request(path); expect(request.active.peek()).toBeDefined(); diff --git a/js/net/src/origin.ts b/js/net/src/origin.ts index a561425a478..97cfd922924 100644 --- a/js/net/src/origin.ts +++ b/js/net/src/origin.ts @@ -3,8 +3,10 @@ * * Publish broadcasts into an origin and hand the origin to one or more connections to * serve them; the broadcasts outlive any single session. Hand the same (or another) - * origin to a connection's `subscribe` option and the peer's announced broadcasts appear - * in the table too, consumable by path. Mirrors the `origin` module in `rs/moq-net`. + * origin to a connection's `subscribe` option and the peer's announced routes appear + * in the table too: each route covers a path prefix, and a request for a path under + * it resolves through the session that announced it. Mirrors the `origin` module in + * `rs/moq-net`. * * @module */ @@ -33,23 +35,40 @@ export interface RequestSlot { readonly route: Signal; } +/** + * What serves the paths a remote route covers: the connection that announced it. + * + * `consume` opens (or reuses) that session's subscription to the exact path; the + * origin materializes lazily, only when a request actually lands under the route. + * + * @internal + */ +export interface RouteProvider { + consume(path: Path.Valid): broadcast.Consumer; +} + /** Reactive backing state shared by origin producers and consumers. */ class OriginState { - // Both tables hold consumer fronts, so the application producing into the origin and - // the connections serving or feeding it stay decoupled. Undefined once the origin - // closes, so late writes fail loudly. + // Both tables decouple the application producing into the origin from the + // connections serving or feeding it. Undefined once the origin closes, so late + // writes fail loudly. // - // Local is what this endpoint publishes; sessions announce and serve it. Remote is - // what sessions feeding the origin discovered; an entry dies with the session that - // inserted it. They are separate maps so a session can never announce a remote entry - // back to a peer, which is what makes an origin shared by both directions echo-free. + // Local is what this endpoint publishes, keyed by exact path; sessions announce and + // serve it. Remote is the route table: the path prefixes sessions announced, each + // covering every path beneath it; an entry dies with the session that inserted it. + // They are separate so a session can never announce a remote entry back to a peer, + // which is what makes an origin shared by both directions echo-free. // - // Remote keeps every session's front per path, newest first: [0] is the route consumers - // resolve, and removing it promotes the next, so a session dying does not black-hole a - // path another live session still carries (which would stay dark forever, since that - // session already announced it and will not again). + // Remote keeps every session's provider per prefix, newest first: [0] is the one + // requests resolve through, and removing it promotes the next, so a session dying + // does not black-hole a prefix another live session still covers. local = new Signal | undefined>(new Map()); - remote = new Signal | undefined>(new Map()); + remote = new Signal | undefined>(new Map()); + + // Broadcasts materialized from remote routes, keyed by exact path. Shared by every + // request for the path so repeats reuse one session subscription; dropped (and + // closed) when the providing route goes away or the last request releases it. + materialized = new Map(); // Paths consumers asked for without waiting for an announcement; attached sessions // answer them with blind subscriptions. Never announced: an answered request is assumed @@ -81,9 +100,76 @@ class OriginState { slot.route.set(this.route(path, slot.answer)); } - /** What `path` resolves to: the table's route when it has one, else the blind answer. */ + /** + * Recompute every open request covered by `prefix`, after a route was inserted or + * removed there: a route covers many paths, so a single-path refresh is not enough. + * Materialized broadcasts whose provider changed are released here too, so a + * retracted route's session subscription closes even when nothing reads it again. + */ + refreshPrefix(prefix: Path.Valid): void { + for (const [path, cached] of [...this.materialized]) { + if (!Path.hasPrefix(prefix, path)) continue; + if (cached.provider !== this.provider(path)) { + this.materialized.delete(path); + cached.front.close(); + } + } + for (const [path, slot] of this.requests.peek() ?? []) { + if (Path.hasPrefix(prefix, path)) slot.route.set(this.route(path, slot.answer)); + } + } + + /** + * Release the materialized broadcast for `path`, once its last request is gone: the + * cache exists to share one session subscription between requests, not to outlive + * them. + */ + releaseMaterialized(path: Path.Valid): void { + const cached = this.materialized.get(path); + if (!cached) return; + this.materialized.delete(path); + cached.front.close(); + } + + /** The newest provider on the most specific route covering `path`, if any. */ + provider(path: Path.Valid): RouteProvider | undefined { + let bestPrefix: Path.Valid | undefined; + let best: RouteProvider | undefined; + for (const [prefix, providers] of this.remote.peek() ?? []) { + if (!providers[0]) continue; + if (!Path.hasPrefix(prefix, path)) continue; + if (bestPrefix === undefined || prefix.length > bestPrefix.length) { + bestPrefix = prefix; + best = providers[0]; + } + } + return best; + } + + /** + * What `path` resolves to: a local publish, a broadcast materialized from the best + * covering route, or the blind answer. + * + * Materialization is lazy and cached per path: the first request under a route opens + * the providing session's subscription, repeats share it, and a provider change (the + * route retracting, a better session taking over) swaps it out. + */ route(path: Path.Valid, answer?: broadcast.Consumer): broadcast.Consumer | undefined { - return this.local.peek()?.get(path) ?? this.remote.peek()?.get(path)?.[0] ?? answer; + const local = this.local.peek()?.get(path); + if (local) return local; + + const provider = this.provider(path); + const cached = this.materialized.get(path); + if (cached && cached.provider === provider) return cached.front; + if (cached) { + this.materialized.delete(path); + cached.front.close(); + } + if (!provider) return answer; + + const front = provider.consume(path); + this.materialized.set(path, { provider, front }); + return front; } } @@ -172,45 +258,48 @@ export class Producer implements Table { } /** - * Insert a broadcast discovered by a session, taking ownership of `front`. + * Advertise a route: a claim that paths under `prefix` can be served through + * `provider`. * - * The newest insertion becomes the route consumers resolve; earlier ones are kept as - * fallbacks and promoted when it goes away, so overlapping sessions carrying the same - * path fail over instead of black-holing it. The returned dispose retracts this front - * (whichever position it holds) and releases it; call it when the announcement ends or - * the session dies. Inserting into a closed origin releases the front immediately and - * retracts nothing. + * This is how sessions land the routes a peer announces, and how an application + * serves a whole subtree without publishing each path: announce one short prefix + * and hand back a broadcast from `provider.consume(path)` for whatever is + * requested beneath it. Announcing each broadcast's exact path is the convention + * that lets subscribers enumerate broadcasts ({@link publish} does that half). * - * @internal + * The newest announcement becomes the provider requests resolve through; earlier + * ones are kept as fallbacks and promoted when it goes away, so overlapping + * sessions covering the same prefix fail over instead of black-holing it. The + * returned dispose retracts this route (whichever position it holds); call it + * when the advertisement ends or the session dies. Announcing into a closed + * origin retracts nothing. + * + * @public */ - insertRemote(path: Path.Valid, front: broadcast.Consumer): Dispose { + announce(prefix: Path.Valid, provider: RouteProvider): Dispose { let closed = false; - this.#state.remote.mutate((broadcasts) => { - if (!broadcasts) { + this.#state.remote.mutate((routes) => { + if (!routes) { closed = true; return; } - const fronts = broadcasts.get(path); - if (fronts) fronts.unshift(front); - else broadcasts.set(path, [front]); + const providers = routes.get(prefix); + if (providers) providers.unshift(provider); + else routes.set(prefix, [provider]); }); - if (closed) { - front.close(); - return () => {}; - } - this.#state.refresh(path); + if (closed) return () => {}; + this.#state.refreshPrefix(prefix); return () => { - this.#state.remote.mutate((broadcasts) => { - const fronts = broadcasts?.get(path); - if (!fronts) return; - const index = fronts.indexOf(front); + this.#state.remote.mutate((routes) => { + const providers = routes?.get(prefix); + if (!providers) return; + const index = providers.indexOf(provider); if (index < 0) return; - fronts.splice(index, 1); - if (fronts.length === 0) broadcasts?.delete(path); + providers.splice(index, 1); + if (providers.length === 0) routes?.delete(prefix); }); - this.#state.refresh(path); - front.close(); + this.#state.refreshPrefix(prefix); }; } @@ -350,13 +439,12 @@ export class Producer implements Table { } return undefined; }); - this.#state.remote.update((broadcasts) => { - // Remote broadcasts are somebody else's; only release our handles on them. - for (const fronts of broadcasts?.values() ?? []) { - for (const front of fronts) front.close(); - } - return undefined; - }); + this.#state.remote.update(() => undefined); + // Materialized broadcasts are handles we opened; release them. + for (const cached of this.#state.materialized.values()) { + cached.front.close(); + } + this.#state.materialized.clear(); // Nothing will answer a request on a closed origin, whatever is still attached, so // existing requests report unroutable rather than waiting on a corpse. this.#state.answerers.set(0); @@ -497,7 +585,8 @@ export class Consumer { readonly #discovery: Getter; /** - * Whether the table routes `path` itself, by a local publish or a session's announcement. + * Whether the table routes `path`, by a local publish or an announced route + * covering it. * * Availability, not a handle: {@link request} is the only way to consume by path. A * request on a routed path resolves to that route and never to a blind answer, which is @@ -507,7 +596,7 @@ export class Consumer { */ routes(path: Path.Valid): boolean { if (this.#state.local.peek()?.has(path)) return true; - return (this.#state.remote.peek()?.get(path)?.length ?? 0) > 0; + return this.#state.provider(path) !== undefined; } /** @@ -609,15 +698,17 @@ export class Consumer { taken.answer?.close(); taken.answer = undefined; taken.route.set(undefined); + this.#state.releaseMaterialized(path); }); }); } /** - * The available broadcasts under `prefix`, as a live stream: everything currently - * routed arrives first as `active`, then additions and removals as they happen. Paths - * are relative to `prefix`. The stream ends when the origin closes or the consumer is - * closed. + * The announced routes under `prefix`, as a live stream: every currently announced + * prefix arrives first as `active`, then additions and retractions as they happen. A + * local publish announces its exact path; a session's route announces the prefix it + * covers. Paths are relative to `prefix`. The stream ends when the origin closes or + * the consumer is closed. */ announced(prefix: Path.Valid = Path.empty()): announce.Consumer { const producer = new announce.Producer(prefix); @@ -626,11 +717,12 @@ export class Consumer { } async #runAnnounced(producer: announce.Producer, prefix: Path.Valid): Promise { - // Keyed by suffix, valued by the routing front. Diffing identity rather than mere - // presence means a republish (a new broadcast taking the path) emits a retraction - // then a fresh announcement, so a consumer re-consumes instead of clinging to the - // superseded broadcast. - let active = new Map(); + // Keyed by suffix, valued by the routing identity (a local front or a route's + // newest provider). Diffing identity rather than mere presence means a republish + // (a new broadcast taking the path) emits a retraction then a fresh + // announcement, so a consumer re-consumes instead of clinging to the superseded + // broadcast; an identical route from a replacement session is invisible. + let active = new Map(); try { for (;;) { @@ -638,12 +730,24 @@ export class Consumer { const remote = this.#state.remote.peek(); if (local === undefined && remote === undefined) break; - const next = new Map(); + const next = new Map(); // Remote first, so a local publish at the same path overwrites it: the - // announcement points at whatever consume() would resolve. - for (const [path, fronts] of remote ?? []) { + // announcement points at whatever request() would resolve. + // The most specific route covering `prefix` itself wins the root slot, + // matching request() resolution. + let rootLen = -1; + for (const [path, providers] of remote ?? []) { + if (!providers[0]) continue; + if (Path.hasPrefix(path, prefix)) { + // A route at or above `prefix` covers everything under it and + // presents at the root, mirroring Rust's prefix intersection. + if (path.length < rootLen) continue; + rootLen = path.length; + next.set(Path.empty(), providers[0]); + continue; + } const suffix = Path.stripPrefix(prefix, path); - if (suffix !== null && fronts[0]) next.set(suffix, fronts[0]); + if (suffix !== null) next.set(suffix, providers[0]); } for (const [path, front] of local ?? []) { const suffix = Path.stripPrefix(prefix, path); @@ -651,10 +755,10 @@ export class Consumer { } for (const [path, front] of active) { - if (next.get(path) !== front) producer.append({ path, active: false }); + if (next.get(path) !== front) producer.append({ prefix: path, active: false }); } for (const [path, front] of next) { - if (active.get(path) !== front) producer.append({ path, active: true }); + if (active.get(path) !== front) producer.append({ prefix: path, active: true }); } active = next; diff --git a/js/watch/src/broadcast.ts b/js/watch/src/broadcast.ts index 9f80c49d69c..6410baaa9d0 100644 --- a/js/watch/src/broadcast.ts +++ b/js/watch/src/broadcast.ts @@ -192,8 +192,8 @@ export class Broadcast { if (!entry) break; this.#announced.mutate((active) => { if (!active) return; - if (entry.active) active.add(entry.path); - else active.delete(entry.path); + if (entry.active) active.add(entry.prefix); + else active.delete(entry.prefix); }); } }); @@ -209,15 +209,20 @@ export class Broadcast { effect.set(this.#out.catalog, raw ? filterCatalog(raw, usable) : undefined); } - // Whether `path` is currently announced, for `relativeBroadcast`'s cross-broadcast refs. - // Opens the announcement stream on first use. The blind cases (reload off, no discovery) - // never reach here; see `#relativeTarget`. + // Whether `path` is covered by an announced route, for `relativeBroadcast`'s + // cross-broadcast refs. Announcements are prefix routes, so a route at "room/" covers + // "room/alice/cam.hang" without naming it. Opens the announcement stream on first use. + // The blind cases (reload off, no discovery) never reach here; see `#relativeTarget`. #isPathAnnounced(effect: Effect, path: Moq.Path.Valid): boolean { this.#wantAnnounced.set(true); const active = effect.get(this.#announced); if (!active) return false; // stream not open yet: wait rather than subscribe to a maybe-absent path - return active.has(path); + if (active.has(path)) return true; + for (const prefix of active) { + if (Path.hasPrefix(prefix, path)) return true; + } + return false; } // Resolve `path` without waiting for an announcement. The request is table-first, so a diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index e0d7b2babb2..0a71fbec8fa 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -27,20 +27,20 @@ typealias OriginConsumer = uniffi.moq.MoqOriginConsumer typealias OriginDynamic = uniffi.moq.MoqOriginDynamic /** A requested broadcast not yet accepted: fulfill it with a producer or abort it. */ typealias BroadcastRequest = uniffi.moq.MoqBroadcastRequest -/** A stream of broadcast announcements under a prefix. */ +/** A stream of route announcements and retractions under a prefix. */ typealias Announced = uniffi.moq.MoqAnnounced -/** A pending wait for a specific broadcast path to be announced. */ +/** A pending wait for a route to cover a specific path. */ typealias AnnouncedBroadcast = uniffi.moq.MoqAnnouncedBroadcast -/** A single broadcast announcement: its path plus a consumer. */ +/** A single route announcement or retraction: its path, route metadata, and active flag. */ typealias Announcement = uniffi.moq.MoqAnnouncement +/** A live route advertisement: hold it while the route should stay announced. */ +typealias Announce = uniffi.moq.MoqAnnounce // Broadcast / track / group producers and consumers. /** The write side of a broadcast: publish tracks into it. */ typealias BroadcastProducer = uniffi.moq.MoqBroadcastProducer /** The read side of a broadcast: subscribe to its catalog and tracks. */ typealias BroadcastConsumer = uniffi.moq.MoqBroadcastConsumer -/** Watches a broadcast's route: yields the current route first, then every change. */ -typealias RouteWatch = uniffi.moq.MoqRouteWatch /** Receives tracks requested from a dynamically served broadcast. */ typealias BroadcastDynamic = uniffi.moq.MoqBroadcastDynamic /** The write side of a raw track: append groups of frames. */ @@ -121,7 +121,7 @@ typealias ContainerInit = uniffi.moq.MoqContainerInit typealias Audio = uniffi.moq.MoqAudio /** A width and height pair, in pixels. */ typealias Dimensions = uniffi.moq.MoqDimensions -/** The route a broadcast takes to reach this origin: relay hop ids (oldest first), advertised cost (lower wins), and whether it's announced. */ +/** A path-prefix route: the prefix it covers, relay hop ids (oldest first), and advertised cost (lower wins). */ typealias Route = uniffi.moq.MoqRoute /** Tunes how a track subscription is delivered: priority, group ordering, and range. */ typealias Subscription = uniffi.moq.MoqSubscription diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt index b17ac90d9c0..1eb57562c73 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt @@ -199,7 +199,7 @@ fun MoqGroupConsumer.frames(): Flow = flow { } /** - * Stream of broadcast announcements under a prefix. + * Stream of route announcements and retractions under a prefix. * * Acquires the subscription on first collection and cancels it when collection * ends, so callers never touch the underlying handle. Use the raw @@ -220,24 +220,3 @@ fun MoqOriginConsumer.announcements(prefix: String): Flow { } } -/** - * Stream of route updates for a broadcast: the current route first, then every - * change (e.g. an upstream failover). Terminates when the broadcast ends. - * - * Acquires the watch on first collection and cancels it when collection ends. - * Use the raw `routeUpdates()` if you need to hold and cancel the handle yourself. - */ -fun MoqBroadcastConsumer.routes(): Flow { - val consumer = this - return flow { - val watch = consumer.routeUpdates() - try { - while (true) { - currentCoroutineContext().ensureActive() - emit(watch.next() ?: break) - } - } finally { - watch.cancel() - } - } -} diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt index 7ae820fb5a8..eba312458e4 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt @@ -35,7 +35,7 @@ class Moq internal constructor( fun createBroadcast(path: String): BroadcastProducer = session.publisher().createBroadcast(path) /** - * Discover broadcasts whose path starts with [prefix] as a [Flow]. The + * Discover routes whose prefix starts with [prefix] as a [Flow]. The * subscription is acquired on collection and cancelled when collection * ends. Use [announced] for the raw handle. */ @@ -45,7 +45,7 @@ class Moq internal constructor( fun announced(prefix: String = ""): MoqAnnounced = session.consumer().announced(prefix) /** - * Await the broadcast announced at exactly [path]. + * Await a route covering exactly [path], then resolve the broadcast there. * * Unlike [requestBroadcast] this waits indefinitely for a future * announcement. Cancel the returned handle to stop waiting. @@ -53,9 +53,9 @@ class Moq internal constructor( fun announcedBroadcast(path: String): MoqAnnouncedBroadcast = session.consumer().announcedBroadcast(path) /** - * Resolve the broadcast at [path] as soon as it can be served: an existing - * exact-path broadcast whether announced or not, otherwise a dynamic fallback - * on the origin. + * Resolve the broadcast at [path] as soon as it can be served: a local + * broadcast at the exact path, the best announced route covering it, or a + * dynamic fallback on the origin. * * Unlike [announcedBroadcast] this does not wait for a future announcement; * it throws when neither can serve the path. diff --git a/py/moq-rs/examples/announced.py b/py/moq-rs/examples/announced.py index c6b28c0f73b..4e25eebd7d1 100644 --- a/py/moq-rs/examples/announced.py +++ b/py/moq-rs/examples/announced.py @@ -1,4 +1,4 @@ -"""List broadcasts announced on a relay under a given prefix. +"""List routes announced on a relay under a given prefix. python py/moq-rs/examples/announced.py --url https://relay.example.com python py/moq-rs/examples/announced.py --url https://relay.example.com --prefix live/ @@ -12,9 +12,10 @@ async def run(url: str, prefix: str, tls_verify: bool) -> None: async with moq.Client(url, tls_verify=tls_verify) as client: - print(f"watching announcements under {prefix!r} at {url}") + print(f"watching route announcements under {prefix!r} at {url}") async for announcement in client.announced(prefix): - print(f" + {announcement.path}") + sign = "+" if announcement.active else "-" + print(f" {sign} {announcement.path}") def main() -> None: diff --git a/py/moq-rs/moq/__init__.py b/py/moq-rs/moq/__init__.py index ac4aa2f0cfe..2cab424b1cd 100644 --- a/py/moq-rs/moq/__init__.py +++ b/py/moq-rs/moq/__init__.py @@ -9,6 +9,7 @@ from .errors import is_auth, is_shutdown from .log import log_level from .origin import ( + Announce, Announced, AnnouncedBroadcast, Announcement, @@ -86,6 +87,7 @@ ) __all__ = [ + "Announce", "Announced", "AnnouncedBroadcast", "Announcement", diff --git a/py/moq-rs/moq/origin.py b/py/moq-rs/moq/origin.py index 5ef85c042b2..daefbded9b1 100644 --- a/py/moq-rs/moq/origin.py +++ b/py/moq-rs/moq/origin.py @@ -3,6 +3,7 @@ from __future__ import annotations from moq_ffi import ( + MoqAnnounce, MoqAnnounced, MoqAnnouncedBroadcast, MoqAnnouncement, @@ -12,43 +13,78 @@ MoqOriginOptions, MoqOriginProducer, ) +from moq_ffi import ( + MoqRoute as Route, +) from .publish import BroadcastProducer from .subscribe import BroadcastConsumer class Announcement: - """A single broadcast discovered via :meth:`OriginConsumer.announced`. + """A route announcement (or retraction) from :meth:`OriginConsumer.announced`. - Read its :attr:`path` and get a :attr:`broadcast` consumer to subscribe to it. + A route claims that paths under :attr:`path` can be served; it carries no + broadcast. Resolve a specific path with :meth:`OriginConsumer.request_broadcast`. + By convention a publisher announces each broadcast's exact path, so + subscribers can enumerate broadcasts from routes. """ def __init__(self, inner: MoqAnnouncement) -> None: self._inner = inner - self._broadcast: BroadcastConsumer | None = None @property def path(self) -> str: - """The path this broadcast is announced at.""" + """The announced route's prefix, relative to the ``announced`` prefix.""" return self._inner.path() @property - def broadcast(self) -> BroadcastConsumer: - """The broadcast's consumer, one shared instance per announcement. + def active(self) -> bool: + """Whether the route is active (``True``) or was retracted (``False``). - Cached so stateful accessors (like the ``route_changed`` cursor) - survive repeated property access. + A repeated active announcement for the same path is a metadata update. """ - if self._broadcast is None: - self._broadcast = BroadcastConsumer(self._inner.broadcast()) - return self._broadcast + return self._inner.active() + + @property + def route(self) -> Route: + """The route serving the prefix: its relay hops and cost.""" + return self._inner.route() + + +class Announce: + """A live route advertisement, from :meth:`OriginProducer.announce`. + + The route stays advertised until :meth:`cancel` (or garbage collection). + Usable as a context manager, retracting on exit. + """ + + def __init__(self, inner: MoqAnnounce) -> None: + self._inner = inner + + def __enter__(self): + return self + + def __exit__(self, *exc) -> None: + self.cancel() + + def update(self, route: Route) -> None: + """Re-price the route in place: replace its hops and cost. + + The prefix is fixed at announce time; announce again to move it. + """ + self._inner.update(route) + + def cancel(self) -> None: + """Retract the route.""" + self._inner.cancel() class Announced: - """Async-iterable stream of :class:`Announcement` broadcasts as they appear. + """Async-iterable stream of :class:`Announcement` route updates as they arrive. Usable as an async context manager; iterate with ``async for`` and it keeps - yielding new broadcasts until cancelled. + yielding announcements and retractions until cancelled. """ def __init__(self, inner: MoqAnnounced) -> None: @@ -75,7 +111,7 @@ def cancel(self) -> None: class AnnouncedBroadcast: - """Awaitable that resolves when the broadcast at a specific path is announced. + """Awaitable that resolves once a route covers a specific path. ``await`` it (or call :meth:`available`) to get the :class:`BroadcastConsumer` once the broadcast becomes available. Usable as an async context manager. @@ -91,7 +127,7 @@ async def __aexit__(self, *exc) -> None: self.cancel() async def available(self) -> BroadcastConsumer: - """Await the broadcast becoming available and return its consumer.""" + """Await a covering route and return the resolved broadcast consumer.""" return BroadcastConsumer(await self._inner.available()) def __await__(self): @@ -155,20 +191,21 @@ def __init__(self, inner: MoqOriginConsumer) -> None: self._inner = inner def announced(self, prefix: str = "") -> Announced: - """Async-iterate broadcasts announced under ``prefix`` (empty matches all).""" + """Async-iterate route announcements under ``prefix`` (empty matches all).""" return Announced(self._inner.announced(prefix)) def announced_broadcast(self, path: str) -> AnnouncedBroadcast: - """Await announcement of the broadcast at exactly ``path``.""" + """Await a route covering ``path``, then resolve the broadcast there.""" return AnnouncedBroadcast(self._inner.announced_broadcast(path)) async def request_broadcast(self, path: str) -> BroadcastConsumer: """Request a broadcast by path, resolving as soon as it can be served. - Returns an existing exact-path broadcast immediately, whether announced or - not, otherwise falls back to a dynamic handler on the origin (if any), or - raises if neither can serve it. Unlike `announced_broadcast`, this does not - wait indefinitely for a future announcement. + Resolution order: a local broadcast at the exact path, then the best + announced route covering the path (served on demand by the session that + announced it), then a dynamic handler on the origin (if any); raises if + nothing can serve it. Unlike `announced_broadcast`, this does not wait + for a future announcement. """ return BroadcastConsumer(await self._inner.request_broadcast(path)) @@ -201,11 +238,21 @@ def dynamic(self) -> OriginDynamic: def create_broadcast(self, path: str) -> BroadcastProducer: """Create a broadcast at ``path``, returning the producer that feeds it. - The broadcast starts live: the origin announces the path so subscribers can - discover it, becoming visible shortly after this returns. Toggle - discoverability with :meth:`BroadcastProducer.set_announce`; ``finish()`` - unpublishes immediately, while dropping the producer without finishing - also unpublishes but reads to subscribers as a failure rather than a - deliberate end. + The broadcast starts announced: the origin advertises the exact path as a + route so subscribers can discover it, becoming visible shortly after this + returns. Toggle discoverability with :meth:`BroadcastProducer.set_announce`; + ``finish()`` unpublishes immediately, while dropping the producer without + finishing also unpublishes but reads to subscribers as a failure rather + than a deliberate end. """ return BroadcastProducer._from_inner(self._inner.create_broadcast(path)) + + def announce(self, prefix: str, route: Route | None = None) -> Announce: + """Advertise a route: a claim that paths under ``prefix`` can be served. + + Hold the returned :class:`Announce` for as long as the route should stay + advertised; ``route`` carries the optional metadata (relay hops and cost). + Announcing is independent of :meth:`create_broadcast`: announce one short + prefix and serve requests beneath it with :meth:`dynamic`. + """ + return Announce(self._inner.announce(prefix, route if route is not None else Route())) diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index 5d34c0576b6..86d8b7e8de9 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -36,7 +36,6 @@ AudioEncoderOutput, AudioFrame, Frame, - Route, Subscription, TrackInfo, VideoEncoderInput, @@ -536,17 +535,8 @@ def dynamic(self) -> BroadcastDynamic: """Accept subscriptions to tracks that are not published yet.""" return BroadcastDynamic(self._inner.dynamic()) - def set_route(self, route: Route) -> None: - """Update the broadcast's route: the hop chain, cost, and liveness it advertises. - - Use this as conditions shift (e.g. a standby transcoder lowering its - ``cost`` once warm); consumers observe the change via - :meth:`BroadcastConsumer.route_changed`. - """ - self._inner.set_route(route) - def set_announce(self, announce: bool) -> None: - """Set whether the broadcast is announced, keeping the rest of its route. + """Set whether the broadcast's exact path is announced as a route. The origin advertises the path only while announced; an unannounced broadcast stays reachable by exact path for subscribes and fetches. This is diff --git a/py/moq-rs/moq/subscribe.py b/py/moq-rs/moq/subscribe.py index 7f4e579bd16..08001146142 100644 --- a/py/moq-rs/moq/subscribe.py +++ b/py/moq-rs/moq/subscribe.py @@ -31,7 +31,6 @@ FetchGroupOptions, Frame, MediaFrame, - Route, Subscription, TrackInfo, Video, @@ -376,33 +375,12 @@ def cancel(self) -> None: class BroadcastConsumer: """The consume side of one broadcast: subscribe to its tracks, catalog, and media. - Built by resolving an announcement or request. Read its :attr:`route`, then use - the ``subscribe_*`` / :meth:`fetch_group` methods to pull tracks and media. + Built by resolving a request. Use the ``subscribe_*`` / :meth:`fetch_group` + methods to pull tracks and media. """ def __init__(self, inner: MoqBroadcastConsumer) -> None: self._inner = inner - self._route_watch = None - - @property - def route(self) -> Route: - """The route the broadcast currently takes to reach this origin. - - ``route.hops`` is the chain of relay origin ids (oldest first) and - ``route.cost`` the publisher's advertised preference (lower wins). - """ - return self._inner.route() - - async def route_changed(self) -> Route | None: - """Wait for the broadcast's route to change. - - The first call returns the current route immediately; each later call - blocks until it changes again (e.g. an upstream failover). Returns - ``None`` once the broadcast ends. - """ - if self._route_watch is None: - self._route_watch = self._inner.route_updates() - return await self._route_watch.next() async def subscribe_catalog(self) -> CatalogConsumer: """Subscribe to the broadcast's catalog, async-iterating snapshots as it changes.""" diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index f134bbcaf1b..b64adcbaca3 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -132,7 +132,8 @@ async def test_local_publish_consume_audio(): async for announcement in consumer.announced(): assert announcement.path == "live" - catalog = await announcement.broadcast.catalog() + broadcast_consumer = await consumer.request_broadcast(announcement.path) + catalog = await broadcast_consumer.catalog() assert len(catalog.audio) == 1 assert len(catalog.video) == 0 @@ -143,7 +144,7 @@ async def test_local_publish_consume_audio(): assert audio.sample_rate == 48000 assert audio.channel_count == 2 - media_consumer = await announcement.broadcast.subscribe_media(track_name, audio) + media_consumer = await broadcast_consumer.subscribe_media(track_name, audio) payload = b"opus audio payload data" media.write_frame(payload, 1_000_000) @@ -164,7 +165,8 @@ async def test_video_publish_consume(): consumer = origin.consume() async for announcement in consumer.announced(): - catalog = await announcement.broadcast.catalog() + broadcast_consumer = await consumer.request_broadcast(announcement.path) + catalog = await broadcast_consumer.catalog() assert len(catalog.video) == 1 assert len(catalog.audio) == 0 @@ -176,7 +178,7 @@ async def test_video_publish_consume(): assert video.coded.width == 1280 assert video.coded.height == 720 - media_consumer = await announcement.broadcast.subscribe_media(track_name, video) + media_consumer = await broadcast_consumer.subscribe_media(track_name, video) keyframe = bytes([0x00, 0x00, 0x00, 0x01, 0x65, 0xAA, 0xBB, 0xCC]) media.write_frame(keyframe, 0) @@ -197,10 +199,11 @@ async def test_multiple_frames_ordering(): consumer = origin.consume() async for announcement in consumer.announced(): - catalog = await announcement.broadcast.catalog() + broadcast_consumer = await consumer.request_broadcast(announcement.path) + catalog = await broadcast_consumer.catalog() track_name = list(catalog.audio.keys())[0] audio = catalog.audio[track_name] - media_consumer = await announcement.broadcast.subscribe_media(track_name, audio) + media_consumer = await broadcast_consumer.subscribe_media(track_name, audio) timestamps = [0, 20_000, 40_000, 60_000, 80_000] for i, ts in enumerate(timestamps): @@ -223,7 +226,8 @@ async def test_catalog_update_on_new_track(): consumer = origin.consume() async for announcement in consumer.announced(): - cat_consumer = await announcement.broadcast.subscribe_catalog() + broadcast_consumer = await consumer.request_broadcast(announcement.path) + cat_consumer = await broadcast_consumer.subscribe_catalog() # First catalog: 1 audio track. catalog1 = await anext(cat_consumer) @@ -255,7 +259,8 @@ async def test_announced_broadcast(): async for announcement in consumer.announced(): assert announcement.path == "test/broadcast" - _catalog = await announcement.broadcast.subscribe_catalog() + broadcast_consumer = await consumer.request_broadcast(announcement.path) + _catalog = await broadcast_consumer.subscribe_catalog() break @@ -576,14 +581,15 @@ async def test_subscribe_media_default_latency_and_context_manager(): consumer = origin.consume() async for announcement in consumer.announced(): - catalog = await announcement.broadcast.catalog() + broadcast_consumer = await consumer.request_broadcast(announcement.path) + catalog = await broadcast_consumer.catalog() track_name, audio = next(iter(catalog.audio.items())) # No container argument, no explicit latency. payload = b"opus audio payload data" media.write_frame(payload, 1_000_000) - async with await announcement.broadcast.subscribe_media(track_name, audio) as media_consumer: + async with await broadcast_consumer.subscribe_media(track_name, audio) as media_consumer: async for frame in media_consumer: assert frame.payload == payload break @@ -601,7 +607,8 @@ async def test_raw_publish_consume(): async for announcement in consumer.announced(): assert announcement.path == "robot/arm" - raw_consumer = await announcement.broadcast.subscribe_track("events") + broadcast_consumer = await consumer.request_broadcast(announcement.path) + raw_consumer = await broadcast_consumer.subscribe_track("events") payload = b'{"cmd": "button_changed", "arm": "left", "button": "THUMB", "state": "PRESSED"}' raw.write_frame(payload, 0) @@ -623,7 +630,8 @@ async def test_raw_multiple_frames(): consumer = origin.consume() async for announcement in consumer.announced(): - raw_consumer = await announcement.broadcast.subscribe_track("commands", moq.Subscription(max_age_ms=1_000)) + broadcast_consumer = await consumer.request_broadcast(announcement.path) + raw_consumer = await broadcast_consumer.subscribe_track("commands", moq.Subscription(max_age_ms=1_000)) messages = [ b'{"cmd": "led", "arm": "left", "led": "THUMB", "state": 1}', @@ -704,7 +712,8 @@ async def test_raw_group_sequence(): consumer = origin.consume() async for announcement in consumer.announced(): - raw_consumer = await announcement.broadcast.subscribe_track("seq", moq.Subscription(max_age_ms=1_000)) + broadcast_consumer = await consumer.request_broadcast(announcement.path) + raw_consumer = await broadcast_consumer.subscribe_track("seq", moq.Subscription(max_age_ms=1_000)) sent_sequences = [] for i in range(3): @@ -770,7 +779,8 @@ async def test_raw_multi_frame_group(): consumer = origin.consume() async for announcement in consumer.announced(): - raw_consumer = await announcement.broadcast.subscribe_track("chunks") + broadcast_consumer = await consumer.request_broadcast(announcement.path) + raw_consumer = await broadcast_consumer.subscribe_track("chunks") group_producer = raw.append_group() chunks = [b"chunk-0", b"chunk-1", b"chunk-2"] diff --git a/py/moq-rs/tests/test_server.py b/py/moq-rs/tests/test_server.py index 52863b55f55..8275bcbba2b 100644 --- a/py/moq-rs/tests/test_server.py +++ b/py/moq-rs/tests/test_server.py @@ -47,11 +47,12 @@ async def accept_loop() -> None: async for announcement in client.announced(): assert announcement.path == "hello" - catalog = await announcement.broadcast.catalog() + broadcast_consumer = await client.request_broadcast(announcement.path) + catalog = await broadcast_consumer.catalog() track_name, audio = next(iter(catalog.audio.items())) assert audio.codec == "opus" - media_consumer = await announcement.broadcast.subscribe_media(track_name, audio) + media_consumer = await broadcast_consumer.subscribe_media(track_name, audio) payload = b"hello over the wire" media.write_frame(payload, 1_000_000) @@ -234,7 +235,7 @@ async def test_serve_helper_accepts_clients(): async def test_broadcast_route_over_wire(): - """A broadcast received over the wire exposes its route: hop chain and cost.""" + """A route received over the wire exposes its hop chain and cost.""" async with moq.Server("127.0.0.1:0", tls_generate=["localhost"]) as server: broadcast = server.create_broadcast("with-route") @@ -247,15 +248,11 @@ async def test_broadcast_route_over_wire(): ) as client: async for announcement in client.announced(): assert announcement.path == "with-route" - # route_changed yields the current route first. - route = await announcement.broadcast.route_changed() - assert route is not None - assert route == announcement.broadcast.route + assert announcement.active + route = announcement.route assert all(isinstance(h, int) for h in route.hops) - # A broadcast crossing at least one session carries a non-empty hop chain. + # A route crossing at least one session carries a non-empty hop chain. assert len(route.hops) >= 1 - # Cost doesn't ride the wire yet, so a received route has the default. - assert route.cost == 0 break finally: serve_task.cancel() @@ -266,20 +263,15 @@ async def test_broadcast_route_over_wire(): broadcast.finish() -async def test_route_changed_observes_update(): - """Repeated announcement.broadcast access shares one route cursor. +async def test_route_update_observes_restart(): + """A route metadata update arrives as another active announcement. - Regression test: the broadcast property used to mint a fresh consumer per - access, so each route_changed() call restarted at the current route and a - watch loop busy-looped instead of blocking for the next change. + The publisher re-prices its announced route; the subscriber observes the new + hop chain in place (no retraction), and cancelling retracts it. """ - async with moq.Server("127.0.0.1:0", tls_generate=["localhost"]) as server: - broadcast = server.create_broadcast("routed") - # The first hop identifies the original publisher; keeping it stable - # across the update below makes the restart an in-place route change - # rather than a broadcast replacement. announce=True keeps the broadcast - # announced across the route update. - broadcast.set_route(moq.Route(hops=[42], cost=0, announce=True)) + origin = moq.OriginProducer() + async with moq.Server("127.0.0.1:0", tls_generate=["localhost"], publish=origin) as server: + announce = origin.announce("routed", moq.Route(hops=[42])) serve_task = asyncio.create_task(server.serve()) try: @@ -288,32 +280,25 @@ async def test_route_changed_observes_update(): tls_verify=False, bind="127.0.0.1:0", ) as client: - async for announcement in client.announced(): - assert announcement.path == "routed" - - # The property returns the same consumer every time. - assert announcement.broadcast is announcement.broadcast - - # First call yields the current route (via a fresh access each time). - first = await asyncio.wait_for(announcement.broadcast.route_changed(), timeout=5.0) - assert first is not None - assert 42 in first.hops - assert 77 not in first.hops - - # The publisher advertises a longer chain behind the same first - # hop; the shared cursor observes the update rather than - # replaying the old route. - broadcast.set_route(moq.Route(hops=[42, 77], cost=0, announce=True)) - updated = await asyncio.wait_for(announcement.broadcast.route_changed(), timeout=5.0) - assert updated is not None - assert 77 in updated.hops - - # Finishing the broadcast unpublishes it immediately; the - # watch ends cleanly with None. - broadcast.finish() - ended = await asyncio.wait_for(announcement.broadcast.route_changed(), timeout=5.0) - assert ended is None - break + announced = client.announced() + first = await asyncio.wait_for(announced.__anext__(), timeout=5.0) + assert first.path == "routed" + assert first.active + assert 42 in first.route.hops + assert 77 not in first.route.hops + + # The publisher advertises a longer chain: an in-place update. + announce.update(moq.Route(hops=[42, 77])) + updated = await asyncio.wait_for(announced.__anext__(), timeout=5.0) + assert updated.path == "routed" + assert updated.active + assert 77 in updated.route.hops + + # Cancelling retracts the route. + announce.cancel() + ended = await asyncio.wait_for(announced.__anext__(), timeout=5.0) + assert ended.path == "routed" + assert not ended.active finally: serve_task.cancel() try: diff --git a/rs/hang/examples/subscribe.rs b/rs/hang/examples/subscribe.rs index 5ea3b83c5fe..330989b6627 100644 --- a/rs/hang/examples/subscribe.rs +++ b/rs/hang/examples/subscribe.rs @@ -41,12 +41,14 @@ async fn run_session(origin: moq_net::origin::Producer) -> anyhow::Result<()> { // Subscribe to a broadcast and read media frames. async fn run_subscribe(consumer: moq_net::origin::Consumer) -> anyhow::Result<()> { - // Wait for a broadcast to be announced. - let moq_net::announce::Update { path, broadcast } = consumer.announced().next().await.context("origin closed")?; - - let broadcast = broadcast.with_context(|| format!("broadcast unannounced: {path}"))?; + // Wait for a route to be announced, then resolve the broadcast at its path. + // The convention is that a publisher announces each broadcast's exact path. + let update = consumer.announced().next().await.context("origin closed")?; + anyhow::ensure!(update.active, "route retracted: {}", update.prefix); + let path = update.prefix.as_path().to_owned(); tracing::info!(%path, "broadcast announced"); + let broadcast = consumer.request_broadcast(&path).await?; // Read the catalog to discover available tracks. let catalog_track = broadcast diff --git a/rs/hang/examples/video.rs b/rs/hang/examples/video.rs index ba305eef629..cc1b0890a73 100644 --- a/rs/hang/examples/video.rs +++ b/rs/hang/examples/video.rs @@ -82,9 +82,10 @@ fn create_track(broadcast: &mut moq_net::broadcast::Producer) -> anyhow::Result< async fn run_broadcast(origin: moq_net::origin::Producer) -> anyhow::Result<()> { // Create a broadcast on the origin; the live route announces it. // NOTE: The path is empty because we're using the URL to scope the broadcast. - let mut broadcast = origin - .create_broadcast("", moq_net::broadcast::Route::new().with_announce(true)) - .context("failed to create broadcast")?; + let mut broadcast = origin.create_broadcast("").context("failed to create broadcast")?; + let _announcement = origin + .announce("", Default::default()) + .context("failed to announce broadcast")?; let track = create_track(&mut broadcast)?; // Wrap in a Producer for keyframe-based group management. diff --git a/rs/libmoq/src/api.rs b/rs/libmoq/src/api.rs index c3f03bafb0f..d1e07130334 100644 --- a/rs/libmoq/src/api.rs +++ b/rs/libmoq/src/api.rs @@ -1117,8 +1117,8 @@ pub unsafe extern "C" fn moq_origin_publish(origin: u32, path: *const c_char, pa let path = unsafe { ffi::parse_str(path, path_len)? }; let mut state = State::lock(); - let broadcast = state.origin.publish(origin, path)?; - state.publish.create(broadcast) + let (broadcast, origin, path, announcement) = state.origin.publish(origin, path)?; + state.publish.create(broadcast, origin, path, announcement) }) } diff --git a/rs/libmoq/src/origin.rs b/rs/libmoq/src/origin.rs index d72c9c304c0..4440c96230d 100644 --- a/rs/libmoq/src/origin.rs +++ b/rs/libmoq/src/origin.rs @@ -78,7 +78,7 @@ impl Origin { ) -> Result<(), Error> { loop { // `biased` so a pending close always wins over a ready announcement. - let moq_net::announce::Update { path, broadcast } = tokio::select! { + let update = tokio::select! { biased; _ = &mut close => return Ok(()), next = consumer.next() => match next { @@ -88,11 +88,10 @@ impl Origin { }; // Hold the lock only to buffer the announcement; release it before the callback. - // Only Active carries a broadcast; Ended does not. let announced_id = State::lock() .origin .announced - .insert((path.to_string(), broadcast.is_some()))?; + .insert((update.prefix.to_string(), update.active))?; callback.call(announced_id); } } @@ -167,11 +166,21 @@ impl Origin { path: String, mut close: oneshot::Receiver<()>, ) -> Result<(), Error> { - // `biased` so a pending close always wins over a ready announcement. + // `routed_broadcast` rides out the churn between a route covering the path + // and the path actually resolving (failover, an advertise-only announce + // racing its handler). `biased` so a pending close always wins. let broadcast = tokio::select! { biased; _ = &mut close => return Ok(()), - found = consumer.announced_broadcast(path.as_str()) => found.ok_or(Error::BroadcastNotFound)?, + resolved = consumer.routed_broadcast(path.as_str()) => match resolved { + Ok(broadcast) => broadcast, + // An unreachable path and a closed origin both mean no broadcast + // can ever arrive here. + Err(moq_net::Error::Unauthorized | moq_net::Error::Closed) => { + return Err(Error::BroadcastNotFound); + } + Err(err) => return Err(err.into()), + }, }; // Hold the lock only to buffer the broadcast; release it before the callback. @@ -246,12 +255,28 @@ impl Origin { Ok(()) } - /// Create a live broadcast at `path` on an origin, returning its producer. + /// Create a live broadcast at `path` on an origin, announcing the exact path. /// /// Errors with [`Error::Moq`] if the path is outside the origin's scope. - pub fn publish(&self, origin: Id, path: P) -> Result { + #[allow(clippy::type_complexity)] + pub fn publish( + &self, + origin: Id, + path: P, + ) -> Result< + ( + moq_net::broadcast::Producer, + moq_net::origin::Producer, + moq_net::PathOwned, + moq_net::announce::Producer, + ), + Error, + > { let origin = self.active.get(origin).ok_or(Error::OriginNotFound)?; - Ok(origin.create_broadcast(path, moq_net::broadcast::Route::new().with_announce(true))?) + let path = path.as_path().to_owned(); + let broadcast = origin.create_broadcast(&path)?; + let announcement = origin.announce(&path, Default::default())?; + Ok((broadcast, origin.clone(), path, announcement)) } pub fn close(&mut self, origin: Id) -> Result<(), Error> { diff --git a/rs/libmoq/src/publish.rs b/rs/libmoq/src/publish.rs index 2d79939adc2..69551e297ce 100644 --- a/rs/libmoq/src/publish.rs +++ b/rs/libmoq/src/publish.rs @@ -16,6 +16,12 @@ use crate::{Error, Id, NonZeroSlab}; /// which is what keeps the two from writing over each other. struct Broadcast { producer: moq_net::broadcast::Producer, + /// How to (re-)announce the exact path: the origin handle and path this + /// broadcast was published under, so `set_announce` can toggle the route. + origin: moq_net::origin::Producer, + path: moq_net::PathOwned, + /// The live route advertisement, absent while unannounced. + announcement: Option, catalog: moq_mux::catalog::Producer, video: BTreeMap>, audio: BTreeMap>, @@ -70,14 +76,23 @@ pub struct Publish { } impl Publish { - /// Store an origin-created broadcast producer, attaching the catalog track every - /// libmoq broadcast carries. - pub fn create(&mut self, mut broadcast: moq_net::broadcast::Producer) -> Result { + /// Store an origin-created broadcast producer (with its announcement), + /// attaching the catalog track every libmoq broadcast carries. + pub fn create( + &mut self, + mut broadcast: moq_net::broadcast::Producer, + origin: moq_net::origin::Producer, + path: moq_net::PathOwned, + announcement: moq_net::announce::Producer, + ) -> Result { let catalog = moq_mux::catalog::Producer::with_catalog(&mut broadcast, moq_mux::catalog::hang::Catalog::default())?; let id = self.broadcasts.insert(Broadcast { producer: broadcast, + origin, + path, + announcement: Some(announcement), catalog, video: BTreeMap::new(), audio: BTreeMap::new(), @@ -85,12 +100,18 @@ impl Publish { Ok(id) } - /// Set whether the broadcast is announced (announced by its origin), keeping the rest - /// of its route (hops, cost). + /// Set whether the broadcast's exact path is announced as a route. The + /// broadcast itself stays reachable by exact path either way. pub fn set_announce(&mut self, broadcast: Id, announce: bool) -> Result<(), Error> { let broadcast = self.broadcasts.get_mut(broadcast).ok_or(Error::BroadcastNotFound)?; - let route = broadcast.producer.consume().route(); - broadcast.producer.set_route(route.with_announce(announce))?; + match (announce, broadcast.announcement.is_some()) { + (true, false) => { + let route = moq_net::origin::Route::default(); + broadcast.announcement = Some(broadcast.origin.announce(&broadcast.path, route)?); + } + (false, true) => broadcast.announcement = None, + _ => {} + } Ok(()) } @@ -129,6 +150,7 @@ impl Publish { mut catalog, video, audio, + .. } = self.broadcasts.remove(broadcast).ok_or(Error::BroadcastNotFound)?; // Retire the caller's renditions while the catalog track is still open, so their removal is // published rather than warned about once `finish` has closed it. diff --git a/rs/moq-bench/src/connection.rs b/rs/moq-bench/src/connection.rs index 8c3387bdcbf..df8cf040034 100644 --- a/rs/moq-bench/src/connection.rs +++ b/rs/moq-bench/src/connection.rs @@ -108,6 +108,7 @@ pub async fn run(ctx: Connection) { }; let mut broadcasts = Vec::new(); + let mut announcements = Vec::new(); let mut own = HashSet::new(); let mut tasks = JoinSet::new(); @@ -124,7 +125,7 @@ pub async fn run(ctx: Connection) { }; for (relative, path) in paths { - let mut broadcast = match publish.create_broadcast(&path, broadcast::Route::new().with_announce(true)) { + let mut broadcast = match publish.create_broadcast(&path) { Ok(broadcast) => broadcast, Err(err) => { tracing::error!(connection, %err, "failed to create broadcast"); @@ -138,9 +139,18 @@ pub async fn run(ctx: Connection) { continue; } }; + let announcement = match publish.announce(&path, Default::default()) { + Ok(announcement) => announcement, + Err(err) => { + tracing::error!(connection, %err, "failed to announce broadcast"); + continue; + } + }; own.insert(relative); - // Hold the broadcast producer for the connection's lifetime so it stays announced. + // Hold the broadcast producer and its announcement for the connection's + // lifetime so it stays published and advertised. broadcasts.push(broadcast); + announcements.push(announcement); let stats = stats.clone(); tasks.spawn(produce(connection, path, rolled, track, stats)); @@ -278,20 +288,20 @@ async fn produce( /// The relay announces its own broadcasts too (`.stats/...` when stats publishing /// is on, which production relays enable), and a subscription slot burned on one /// of those is never retried, so an unscoped consumer starves the subscribe side. -fn discover(consume: &moq_net::origin::Producer, name: &str) -> moq_net::announce::Consumer { +fn discover(consume: &moq_net::origin::Producer, name: &str) -> moq_net::origin::Consumer { consume .consume() .with_root(name) .expect("origin must permit the bench namespace") - .announced() } /// Wait for one exact broadcast and drain it for the lifetime of the source. async fn subscribe_named(consume: moq_net::origin::Consumer, path: String, stats: Arc) -> anyhow::Result<()> { - let broadcast = consume - .announced_broadcast(path.as_str()) + consume + .routed(path.as_str()) .await .ok_or_else(|| anyhow::anyhow!("target broadcast was never announced: {path}"))?; + let broadcast = consume.request_broadcast(path.as_str()).await?; drain(broadcast, &stats).await } @@ -308,12 +318,13 @@ async fn subscribe_named(consume: moq_net::origin::Consumer, path: String, stats /// second startup window of the run, and the whole swarm is subscribed within /// two of them. async fn subscribe( - mut announced: moq_net::announce::Consumer, + consume: moq_net::origin::Consumer, own: HashSet, want: u64, startup: Duration, stats: Arc, ) -> anyhow::Result<()> { + let mut announced = consume.announced(); let mut tasks = JoinSet::new(); let mut seen: HashSet = HashSet::new(); let mut pool = Vec::new(); @@ -329,36 +340,44 @@ async fn subscribe( biased; _ = &mut deadline => break, update = announced.next() => { - let Some(moq_net::announce::Update { path, broadcast }) = update else { break }; - let Some(broadcast) = broadcast else { continue }; - let path = path.as_str().to_string(); + let Some(update) = update else { break }; + if !update.active { + continue; + } + let path = update.prefix.as_path().as_str().to_string(); if own.contains(&path) || !seen.insert(path.clone()) { continue; } eligible += 1; - reservoir_push(&mut pool, want as usize, eligible, (path, broadcast)); + reservoir_push(&mut pool, want as usize, eligible, path); } } } let mut selected = pool.len() as u64; - for (path, broadcast) in pool { + for path in pool { + let Ok(broadcast) = consume.request_broadcast(path.as_str()).await else { + continue; + }; spawn_drain(&mut tasks, path, broadcast, stats.clone()); } // Top up from late announcements, first-come: the pool was too small, so // there is nothing to spread over. while selected < want { - let Some(moq_net::announce::Update { path, broadcast }) = announced.next().await else { + let Some(update) = announced.next().await else { break; }; - let Some(broadcast) = broadcast else { + if !update.active { continue; - }; - let path = path.as_str().to_string(); + } + let path = update.prefix.as_path().as_str().to_string(); if own.contains(&path) || !seen.insert(path.clone()) { continue; } + let Ok(broadcast) = consume.request_broadcast(path.as_str()).await else { + continue; + }; selected += 1; spawn_drain(&mut tasks, path, broadcast, stats.clone()); } @@ -685,25 +704,21 @@ mod tests { let origin = moq_tokio::origin::spawn(Hop::random()); // The relay-internal broadcast: announced, but with no bench data track. - let _internal = origin - .create_broadcast(".stats/node/host", broadcast::Route::new().with_announce(true)) - .unwrap(); + let _internal = origin.create_broadcast(".stats/node/host").unwrap(); + let _announce_internal = origin.announce(".stats/node/host", Default::default()).unwrap(); // Our own broadcast: in the namespace, but excluded via the `own` set // (paths relative to the namespace, matching the scoped announce consumer). - let _previous = origin - .create_broadcast("bench/previous/0/0", broadcast::Route::new().with_announce(true)) - .unwrap(); + let _previous = origin.create_broadcast("bench/previous/0/0").unwrap(); + let _announce_previous = origin.announce("bench/previous/0/0", Default::default()).unwrap(); - let _own = origin - .create_broadcast("bench/current/9/9", broadcast::Route::new().with_announce(true)) - .unwrap(); + let _own = origin.create_broadcast("bench/current/9/9").unwrap(); + let _announce_own = origin.announce("bench/current/9/9", Default::default()).unwrap(); let own = HashSet::from(["9/9".to_string()]); // One legitimate peer under the bench namespace with a single finished group. - let mut peer = origin - .create_broadcast("bench/current/0/0", broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut peer = origin.create_broadcast("bench/current/0/0").unwrap(); + let _announce_peer = origin.announce("bench/current/0/0", Default::default()).unwrap(); let mut track = peer.create_track(TRACK, None).unwrap(); let mut group = track.append_group().unwrap(); group @@ -729,9 +744,8 @@ mod tests { let consume = origin.consume(); let task = tokio::spawn(subscribe_named(consume, "bench/run/chat".into(), stats.clone())); - let mut broadcast = origin - .create_broadcast("bench/run/chat", broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut broadcast = origin.create_broadcast("bench/run/chat").unwrap(); + let _announce_broadcast = origin.announce("bench/run/chat", Default::default()).unwrap(); let mut track = broadcast.create_track(TRACK, None).unwrap(); tokio::task::yield_now().await; let mut group = track.append_group().unwrap(); diff --git a/rs/moq-boy/src/input.rs b/rs/moq-boy/src/input.rs index b0fd3b69d06..68ef72548df 100644 --- a/rs/moq-boy/src/input.rs +++ b/rs/moq-boy/src/input.rs @@ -61,17 +61,21 @@ pub enum Command { /// Handles discovered viewers: subscribes to their command tracks. pub async fn handle_viewers( - viewer_origin: &mut moq_net::announce::Consumer, + viewer_origin: &moq_net::origin::Consumer, cmd_tx: &tokio::sync::mpsc::Sender, ) -> anyhow::Result<()> { + let mut announced = viewer_origin.announced(); loop { - let Some(moq_net::announce::Update { path, broadcast }) = viewer_origin.next().await else { + let Some(update) = announced.next().await else { break; }; - let viewer_id = path.to_string(); + let viewer_id = update.prefix.to_string(); - if let Some(broadcast) = broadcast { + if update.active { + let Ok(broadcast) = viewer_origin.request_broadcast(update.prefix.as_path()).await else { + continue; + }; tracing::info!(%viewer_id, "viewer connected"); let cmd_tx = cmd_tx.clone(); let vid = viewer_id.clone(); diff --git a/rs/moq-boy/src/main.rs b/rs/moq-boy/src/main.rs index 35bb0eec90f..fb5e1c167ad 100644 --- a/rs/moq-boy/src/main.rs +++ b/rs/moq-boy/src/main.rs @@ -234,18 +234,20 @@ async fn run(config: &Config) -> Result<()> { // Create the broadcast on the publish origin; the live route announces it. let broadcast_path = format!("{game_prefix}/{name}"); let mut broadcast = publish_origin - .create_broadcast(&broadcast_path, moq_net::broadcast::Route::new().with_announce(true)) + .create_broadcast(&broadcast_path) .context("failed to create broadcast")?; + let _announce_broadcast = publish_origin + .announce(&broadcast_path, Default::default()) + .context("failed to announce broadcast")?; // Consume origin: viewer broadcasts under the viewer prefix. // JS publishes viewer feedback at "{viewer_prefix}/{name}/{viewerId}" let viewer_path = format!("{viewer_prefix}/{name}"); let consume_origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let mut viewer_consumer = consume_origin + let viewer_consumer = consume_origin .with_root(&viewer_path) .expect("viewer prefix should be valid") - .consume() - .announced(); + .consume(); tracing::info!(%url, %name, broadcast = %broadcast_path, "connecting to relay"); @@ -300,7 +302,7 @@ async fn run(config: &Config) -> Result<()> { Err(join) => Err(join.into()), }, res = reconnect.closed() => res.map_err(Into::into), - res = input::handle_viewers(&mut viewer_consumer, &cmd_tx) => res, + res = input::handle_viewers(&viewer_consumer, &cmd_tx) => res, }; // Cleanly close the broadcast so subscribers see a normal end rather than diff --git a/rs/moq-cli/src/cluster.rs b/rs/moq-cli/src/cluster.rs index 777f208e89b..22c10a4a09c 100644 --- a/rs/moq-cli/src/cluster.rs +++ b/rs/moq-cli/src/cluster.rs @@ -602,8 +602,9 @@ mod tests { let origin_b = moq_tokio::origin::spawn(moq_net::Hop::random()); // Published before the session exists; announcements flow once it connects. - let _from_a = origin_a - .create_broadcast("from-a", moq_net::broadcast::Route::new().with_announce(true)) + let _from_a = origin_a.create_broadcast("from-a").expect("failed to create broadcast"); + let _announce_from_a = origin_a + .announce("from-a", Default::default()) .expect("failed to create broadcast"); let (server, peer) = listener(); @@ -632,12 +633,13 @@ mod tests { .await .expect("timed out waiting for announcement") .expect("origin closed"); - assert_eq!(update.path.as_str(), "from-a"); + assert_eq!(update.prefix.as_path().as_str(), "from-a"); // And the reverse direction over the same session. This stream replays a's // own "from-a" first, so read until the remote broadcast shows up. - let _from_b = origin_b - .create_broadcast("from-b", moq_net::broadcast::Route::new().with_announce(true)) + let _from_b = origin_b.create_broadcast("from-b").expect("failed to create broadcast"); + let _announce_from_b = origin_b + .announce("from-b", Default::default()) .expect("failed to create broadcast"); let mut announced_on_a = origin_a.consume().announced(); loop { @@ -645,7 +647,7 @@ mod tests { .await .expect("timed out waiting for announcement") .expect("origin closed"); - if update.path.as_str() == "from-b" { + if update.prefix.as_path().as_str() == "from-b" { break; } } @@ -657,8 +659,9 @@ mod tests { async fn mesh_rejects_a_dial_without_the_proof() { let origin_a = moq_tokio::origin::spawn(moq_net::Hop::random()); let origin_b = moq_tokio::origin::spawn(moq_net::Hop::random()); - let _from_b = origin_b - .create_broadcast("from-b", moq_net::broadcast::Route::new().with_announce(true)) + let _from_b = origin_b.create_broadcast("from-b").expect("failed to create broadcast"); + let _announce_from_b = origin_b + .announce("from-b", Default::default()) .expect("failed to create broadcast"); let (server, peer) = listener(); @@ -698,7 +701,10 @@ mod tests { async fn a_mesh_only_listener_refuses_ordinary_clients() { let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); let _published = origin - .create_broadcast("secret-stream", moq_net::broadcast::Route::new().with_announce(true)) + .create_broadcast("secret-stream") + .expect("failed to create broadcast"); + let _announce_published = origin + .announce("secret-stream", Default::default()) .expect("failed to create broadcast"); let (server, peer) = listener(); diff --git a/rs/moq-cli/src/complete.rs b/rs/moq-cli/src/complete.rs index cded3b7b35e..73e211715ef 100644 --- a/rs/moq-cli/src/complete.rs +++ b/rs/moq-cli/src/complete.rs @@ -486,13 +486,13 @@ fn broadcasts(_ctx: CompleteCtx<'_>) -> CompletionFuture<'static> { let mut until = deadline; while let Ok(Some(update)) = timeout_at(until, announced.next()).await { until = deadline.min(Instant::now() + SETTLE); - let path = update.path.to_string(); + let path = update.prefix.to_string(); // The root broadcast is the connection path itself, which an unset // `--broadcast` already names; there is no word to insert for it. if path.is_empty() { continue; } - match update.broadcast.is_some() { + match update.active { true => live.insert(path), false => live.remove(&path), }; @@ -579,11 +579,11 @@ async fn catalog( path: &str, format: CatalogFormat, ) -> Option { - // `announced_broadcast` rather than a plain lookup: the announcement is still in - // flight right after connecting, and asking on the spot reports a live broadcast - // as unroutable. + // Wait for a covering route rather than asking on the spot: the announcement is + // still in flight right after connecting, and an immediate request reports a live + // broadcast as unroutable. let consumer = origin.consume(); - consumer.announced_broadcast(path).await?; + consumer.routed(path).await?; let mut stream = moq_mux::Source::new(consumer, path).catalog(format).await.ok()?; stream.next().await.ok()? @@ -773,8 +773,8 @@ mod tests { #[tokio::test] async fn the_environment_cannot_ask_for_a_moq_side() { let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let route = moq_net::broadcast::Route::new().with_announce(true); - let _alpha = origin.create_broadcast("alpha", route).expect("alpha"); + let _alpha = origin.create_broadcast("alpha").expect("alpha"); + let _announce_alpha = origin.announce("alpha", Default::default()).expect("alpha"); let connect = relay(&origin); // The same reachable relay, named only by the environment. @@ -868,9 +868,10 @@ mod tests { async fn a_relay_on_the_line_answers_broadcast() { let _env = EnvGuard::clear(&["MOQ_CONNECT"]); let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let route = moq_net::broadcast::Route::new().with_announce(true); - let _alpha = origin.create_broadcast("alpha", route.clone()).expect("alpha"); - let _nested = origin.create_broadcast("room/beta", route).expect("beta"); + let _alpha = origin.create_broadcast("alpha").expect("alpha"); + let _announce_alpha = origin.announce("alpha", Default::default()).expect("alpha"); + let _nested = origin.create_broadcast("room/beta").expect("beta"); + let _announce_nested = origin.announce("room/beta", Default::default()).expect("beta"); let connect = relay(&origin); let found = complete(&format!("moq {connect} --broadcast ")).await; @@ -892,13 +893,13 @@ mod tests { use hang::catalog::{AudioCodec, AudioConfig, H264, VideoConfig}; let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let route = moq_net::broadcast::Route::new().with_announce(true); // Two broadcasts with different renditions, so a completer reading the wrong // one fails loudly instead of matching by luck. let mut keep = Vec::new(); for (path, video, audio) in [("wanted", "hd", "stereo"), ("other", "sd", "mono")] { - let mut broadcast = origin.create_broadcast(path, route.clone()).expect("broadcast"); + let mut broadcast = origin.create_broadcast(path).expect("broadcast"); + let announcement = origin.announce(path, Default::default()).expect("broadcast"); let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast).expect("catalog"); let mut edit = catalog.lock(); edit.video.renditions.insert( @@ -914,7 +915,7 @@ mod tests { .renditions .insert(audio.to_string(), AudioConfig::new(AudioCodec::Opus, 48_000, 2)); edit.commit().expect("publish the catalog"); - keep.push((broadcast, catalog)); + keep.push((broadcast, catalog, announcement)); } // The global names `other`; the stage overrides it, exactly as the invocation @@ -938,8 +939,8 @@ mod tests { async fn the_catalog_format_on_the_line_is_honored() { let _env = EnvGuard::clear(&["MOQ_CONNECT"]); let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let route = moq_net::broadcast::Route::new().with_announce(true); - let mut broadcast = origin.create_broadcast("room", route).expect("broadcast"); + let mut broadcast = origin.create_broadcast("room").expect("broadcast"); + let _announce_broadcast = origin.announce("room", Default::default()).expect("broadcast"); let mut track = broadcast .create_track(moq_msf::DEFAULT_NAME, moq_net::track::Info::default()) diff --git a/rs/moq-cli/src/hls.rs b/rs/moq-cli/src/hls.rs index 9251fbc8599..ae4da8af35e 100644 --- a/rs/moq-cli/src/hls.rs +++ b/rs/moq-cli/src/hls.rs @@ -48,14 +48,15 @@ pub async fn import( playlist: String, max_age: Option, ) -> anyhow::Result<()> { - let mut producer = origin - .create_broadcast(&name, moq_net::broadcast::Route::new().with_announce(true)) - .context("failed to create broadcast")?; + let mut producer = origin.create_broadcast(&name).context("failed to create broadcast")?; - // Create catalog tracks before the broadcast becomes visible so a subscriber - // can consume the catalog as soon as it observes the announcement. + // Create catalog tracks before announcing so a subscriber can consume the + // catalog as soon as it observes the announcement. let config = moq_mux::catalog::Config::default().with_max_age(max_age); let catalog = moq_mux::catalog::Producer::with_config(&mut producer, config)?; + let _announcement = origin + .announce(&name, Default::default()) + .context("failed to announce broadcast")?; let mut importer = moq_hls::import::Import::new(producer, catalog, moq_hls::import::Config::new(playlist))?; diff --git a/rs/moq-cli/src/main.rs b/rs/moq-cli/src/main.rs index 1c134284f12..fff3774e156 100644 --- a/rs/moq-cli/src/main.rs +++ b/rs/moq-cli/src/main.rs @@ -473,10 +473,13 @@ fn spawn_import( if let Some(format) = import.source.stdin_format() { warn_if_missing_format(&name); - let broadcast = origin - .create_broadcast(&name, moq_net::broadcast::Route::new().with_announce(true)) - .context("failed to create broadcast")?; - local = Some(Publish::new(broadcast, &format, max_age)?); + let broadcast = origin.create_broadcast(&name).context("failed to create broadcast")?; + let publish = Publish::new(broadcast, &format, max_age)?.with_announcement( + origin + .announce(&name, Default::default()) + .context("failed to announce broadcast")?, + ); + local = Some(publish); } else { match import.source { ImportSource::Hls(hls) => { @@ -519,10 +522,13 @@ fn spawn_import( #[cfg(feature = "capture")] ImportSource::Capture(capture) => { warn_if_missing_format(&name); - let broadcast = origin - .create_broadcast(&name, moq_net::broadcast::Route::new().with_announce(true)) - .context("failed to create broadcast")?; - local = Some(Publish::capture(broadcast, &capture, bandwidth, max_age)?); + let broadcast = origin.create_broadcast(&name).context("failed to create broadcast")?; + let publish = Publish::capture(broadcast, &capture, bandwidth, max_age)?.with_announcement( + origin + .announce(&name, Default::default()) + .context("failed to announce broadcast")?, + ); + local = Some(publish); } _ => unreachable!("container formats are handled by stdin_format above"), } @@ -609,7 +615,7 @@ async fn run_stdout(consumer: moq_net::origin::Consumer, name: String, args: Sub // resolves it (and any sibling broadcast a rendition's `broadcast` field references, // e.g. "./source") through the origin. consumer - .announced_broadcast(&name) + .routed(&name) .await .ok_or_else(|| anyhow::anyhow!("origin closed before broadcast `{name}` was announced"))?; diff --git a/rs/moq-cli/src/play.rs b/rs/moq-cli/src/play.rs index 0f6b0a87850..00bc32e3768 100644 --- a/rs/moq-cli/src/play.rs +++ b/rs/moq-cli/src/play.rs @@ -167,7 +167,7 @@ pub fn run( } } -/// Wait for `broadcast` to be announced on `origin`, then subscribe to it. +/// Wait for a route to cover `broadcast` on `origin`, then subscribe to it. /// /// The wait is the whole point. Subscribing goes through /// `origin::Consumer::request_broadcast`, which resolves `Unroutable` on the @@ -176,7 +176,7 @@ pub fn run( /// window is already up, so this shows as a black frame rather than as a hang. async fn subscribe(origin: moq_net::origin::Consumer, broadcast: &str) -> anyhow::Result { origin - .announced_broadcast(broadcast) + .routed(broadcast) .await .with_context(|| format!("origin closed before broadcast `{broadcast}` was announced"))?; @@ -967,9 +967,8 @@ mod tests { let parked = tokio::time::timeout(Duration::from_secs(60), &mut waiting).await; assert!(parked.is_err(), "expected to still be waiting on the announcement"); - let _broadcast = origin - .create_broadcast("room.hang", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let _broadcast = origin.create_broadcast("room.hang").unwrap(); + let _announce_broadcast = origin.announce("room.hang", Default::default()).unwrap(); waiting.await.unwrap(); } diff --git a/rs/moq-cli/src/publish.rs b/rs/moq-cli/src/publish.rs index 2854e84f037..556806b5533 100644 --- a/rs/moq-cli/src/publish.rs +++ b/rs/moq-cli/src/publish.rs @@ -213,11 +213,16 @@ pub struct Publish { // tracks and importers don't. Only the capture path also writes through it. #[cfg_attr(not(feature = "capture"), allow(dead_code))] broadcast: moq_net::broadcast::Producer, + // Keeps the broadcast's exact-path route advertised for the same lifetime. + // Attached after construction so the announce lands with the tracks in place. + _announcement: Option, } impl Publish { /// Build a publisher decoding the given container format from stdin into - /// `broadcast` (typically created on the origin that announces it). + /// `broadcast`. Announce the path afterwards (see [`Self::with_announcement`]): + /// this constructor creates the catalog tracks, so announcing after it lands + /// the advertisement with the tracks already in place. pub fn new( mut broadcast: moq_net::broadcast::Producer, format: &PublishFormat, @@ -236,6 +241,7 @@ impl Publish { return Ok(Self { source: Source::Stream(PublishDecoder::Ts(Box::new(ts))), broadcast, + _announcement: None, }); } @@ -261,7 +267,11 @@ impl Publish { } }; - Ok(Self { source, broadcast }) + Ok(Self { + source, + broadcast, + _announcement: None, + }) } /// Build a publisher capturing local devices (camera/screen and microphone). @@ -290,9 +300,19 @@ impl Publish { Ok(Self { source: Source::Capture { catalog, video, audio }, broadcast, + _announcement: None, }) } + /// Hold the broadcast's advertisement for this publisher's lifetime. + /// + /// Announce after construction, so the route lands with the catalog tracks + /// already in place. + pub fn with_announcement(mut self, announcement: moq_net::announce::Producer) -> Self { + self._announcement = Some(announcement); + self + } + /// Drive the source until stdin EOF (or the capture devices stop). pub async fn run(self) -> anyhow::Result<()> { match self.source { @@ -503,9 +523,8 @@ mod tests { async fn manufacture_input() -> Vec { // Create the broadcast on a throwaway origin so the exporter can resolve it by path. let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let mut broadcast = origin - .create_broadcast("cli", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut broadcast = origin.create_broadcast("cli").unwrap(); + let _announce_broadcast = origin.announce("cli", Default::default()).unwrap(); settle().await; let mut catalog = moq_mux::catalog::Producer::with_catalog(&mut broadcast, Catalog::::default()).unwrap(); @@ -595,9 +614,7 @@ mod tests { // streams land in the broadcast instead of being dropped by the media-only path. // The broadcast is created on a throwaway origin so the exporter can resolve it by path. let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let broadcast = origin - .create_broadcast("cli", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let broadcast = origin.create_broadcast("cli").unwrap(); settle().await; let mut publish = Publish::new(broadcast, &PublishFormat::Ts, None).unwrap(); #[allow(irrefutable_let_patterns)] diff --git a/rs/moq-cli/src/rtc.rs b/rs/moq-cli/src/rtc.rs index 2469ebe31c3..49cf493b7e9 100644 --- a/rs/moq-cli/src/rtc.rs +++ b/rs/moq-cli/src/rtc.rs @@ -88,8 +88,14 @@ pub async fn connect_import(target: ImportTarget, url: Url) -> anyhow::Result<() let name = &target.name; let producer = target .origin - .create_broadcast(name, moq_net::broadcast::Route::new().with_announce(true)) + .create_broadcast(name) .context("failed to create broadcast")?; + // The WHEP pull fills the tracks as they arrive; announce up front so viewers + // can discover the broadcast while it connects. + let _announcement = target + .origin + .announce(name, Default::default()) + .context("failed to announce broadcast")?; tracing::info!(%url, %name, "WHEP client pulling"); notify_ready(); @@ -105,7 +111,7 @@ pub async fn connect_export(origin: moq_net::origin::Consumer, url: Url, name: S // Confirm the broadcast is reachable (and wait for it to be announced) before dialing; // the egress re-resolves it (and any referenced sibling broadcast) through the origin. origin - .announced_broadcast(&name) + .routed(&name) .await .with_context(|| format!("origin closed before broadcast `{name}` was announced"))?; diff --git a/rs/moq-cli/src/rtmp.rs b/rs/moq-cli/src/rtmp.rs index bf36eed37d6..b2ec96c58d5 100644 --- a/rs/moq-cli/src/rtmp.rs +++ b/rs/moq-cli/src/rtmp.rs @@ -131,7 +131,7 @@ pub async fn connect_export( // Confirm the broadcast is reachable (and wait for it to be announced) before dialing; // the FLV export re-resolves it (and any referenced sibling broadcast) through the origin. origin - .announced_broadcast(&name) + .routed(&name) .await .with_context(|| format!("origin closed before broadcast `{name}` was announced"))?; diff --git a/rs/moq-cli/src/transcode.rs b/rs/moq-cli/src/transcode.rs index 0a56f789b38..9ceda700f3b 100644 --- a/rs/moq-cli/src/transcode.rs +++ b/rs/moq-cli/src/transcode.rs @@ -118,29 +118,24 @@ pub async fn run(moq: MoqSide, args: Args, net: Net) -> anyhow::Result<()> { .with_subscriber(remote.clone()) .connect(url); - // Wait for the source to be announced rather than for the session to connect: - // `request_broadcast` answers on the spot, so asking the moment a session exists - // races the announcement that makes the path routable. + // Wait for the source to be announced and resolve it: `request_broadcast` on its + // own answers on the spot, so asking the moment a session exists races the + // announcement that makes the path routable; `routed_broadcast` also rides out a + // covering route retracting mid-resolution (failover churn). // // Raced against the session ending, since the wait itself never fails: the origin // outlives the session here, so a rejected token or an exhausted retry budget would // otherwise leave us waiting for an announcement that can never arrive. let consumer = remote.consume(); - tokio::select! { - announced = consumer.announced_broadcast(&source_path) => { - announced.context("origin closed before the source broadcast was announced")?; + let source = tokio::select! { + source = consumer.routed_broadcast(&source_path) => { + source.context("source broadcast unavailable")? } closed = session.closed() => { closed.context("session failed before the source broadcast was announced")?; anyhow::bail!("session closed before the source broadcast was announced"); } - } - - // Resolve it for real; the session subscribes upstream on demand. - let source = consumer - .request_broadcast(&source_path) - .await - .context("source broadcast unavailable")?; + }; let mut config = moq_transcode::Config::default(); if !args.rungs.is_empty() { @@ -165,8 +160,11 @@ pub async fn run(moq: MoqSide, args: Args, net: Net) -> anyhow::Result<()> { config.source = source_path.relative(&output_path).filter(|rel| !rel.is_empty()); let output = publish - .create_broadcast(&output_path, moq_net::broadcast::Route::new().with_announce(true)) + .create_broadcast(&output_path) .context("failed to create the derivative broadcast")?; + let _announce_output = publish + .announce(&output_path, Default::default()) + .context("failed to announce the derivative broadcast")?; tracing::info!(source = %source_path, output = %output_path, "transcoding"); tokio::select! { diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index 12864f3b38c..6945fc3e3e7 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -5,7 +5,6 @@ use bytes::Buf; use crate::error::MoqError; use crate::ffi::Task; use crate::media::*; -use crate::origin::MoqRoute; use crate::producer::MoqTrackInfo; fn timestamp_us(timestamp: moq_net::Timestamp) -> Result { @@ -151,44 +150,6 @@ impl MoqBroadcastConsumer { } } -/// A watch over a broadcast's route. Created by `MoqBroadcastConsumer::route_updates`. -#[derive(uniffi::Object)] -pub struct MoqRouteWatch { - task: Task, -} - -struct RouteWatch { - inner: moq_net::broadcast::Consumer, -} - -impl RouteWatch { - async fn next(&mut self) -> Result, MoqError> { - match self.inner.route_changed().await { - Ok(route) => Ok(Some(route.into())), - // A broadcast has no abort; Dropped (every producer gone) is its clean end. - Err(moq_net::Error::Dropped) => Ok(None), - Err(e) => Err(e.into()), - } - } -} - -#[uniffi::export] -impl MoqRouteWatch { - /// Wait for the next route: the current one on the first call, then each change. - /// - /// Returns `None` once the broadcast ends (every producer gone). - pub async fn next(&self) -> Result, MoqError> { - self.task.run(|mut state| async move { state.next().await }).await - } - - /// Cancel all current and future `next()` calls. - /// - /// Terminal: the subscription is released here, not when the handle is. - pub fn cancel(&self) { - self.task.cancel(); - } -} - #[derive(uniffi::Object)] pub struct MoqCatalogConsumer { task: Task, @@ -229,23 +190,6 @@ impl Media { #[uniffi::export] impl MoqBroadcastConsumer { - /// The route the broadcast currently takes to reach this origin. - pub fn route(&self) -> MoqRoute { - self.inner.route().into() - } - - /// Watch the broadcast's route for changes. - /// - /// The returned watch yields the current route first, then every update - /// (e.g. an upstream failover), so a loop observes the full history from now. - pub fn route_updates(&self) -> Arc { - Arc::new(MoqRouteWatch { - task: Task::new(RouteWatch { - inner: self.inner.clone(), - }), - }) - } - /// Resolve a catalog rendition's `broadcast` reference to the broadcast serving its track. /// /// `reference` is [`MoqVideo::broadcast`] / [`MoqAudio::broadcast`]: absent or empty names diff --git a/rs/moq-ffi/src/origin.rs b/rs/moq-ffi/src/origin.rs index 7cd92e0504b..ce19cd6c69c 100644 --- a/rs/moq-ffi/src/origin.rs +++ b/rs/moq-ffi/src/origin.rs @@ -13,46 +13,41 @@ pub struct MoqOriginOptions { pub cache_capacity_bytes: Option, } -/// The path a broadcast takes to reach this origin, and how preferable it is. +/// A path-prefix route: an advertisement that content under `prefix` can be served. /// -/// Dynamic: it changes when the serving route fails over or the publisher -/// re-advertises itself. Publish changes with `MoqBroadcastProducer::set_route` -/// and observe them with `MoqBroadcastConsumer::route_updates`. +/// Announce one with `MoqOriginProducer::announce` and observe them with +/// `MoqOriginConsumer::announced`. A route claims capability, not inventory: by +/// convention a publisher announces each broadcast's exact path, so subscribers +/// can enumerate broadcasts, while a service announces one short prefix and +/// answers whatever is requested beneath it. #[derive(Clone, Default, uniffi::Record)] pub struct MoqRoute { - /// Hop IDs of the relay hops the broadcast traversed, oldest first. + /// Hop ids of the relay hops the route traversed, oldest first. #[uniffi(default = [])] pub hops: Vec, - /// Preference among routes serving the same broadcast: lower wins. A publisher + /// Preference among routes covering the same prefix: lower wins. A publisher /// sets its production cost here: zero for content it is already producing, /// larger for content it would have to start producing on demand. #[uniffi(default = 0)] pub cost: u64, - /// Whether the broadcast is announced: advertised to subscribers via the origin. - /// An unannounced broadcast stays reachable by exact path for subscribes and fetches. - #[uniffi(default = false)] - pub announce: bool, } -impl From for MoqRoute { - fn from(route: moq_net::broadcast::Route) -> Self { +impl From for MoqRoute { + fn from(route: moq_net::origin::Route) -> Self { Self { hops: route.hops.iter().map(|origin| origin.id()).collect(), - // The relay mesh prices a route twice (see `broadcast::Cost`); an + // The relay mesh prices a route twice (see `origin::Cost`); an // application only ever wants what pulling it costs today. cost: route.cost.warm, - announce: route.announce, } } } -impl TryFrom for moq_net::broadcast::Route { +impl TryFrom for moq_net::origin::Route { type Error = MoqError; fn try_from(route: MoqRoute) -> Result { - let mut out = moq_net::broadcast::Route::new() - .with_cost(route.cost) - .with_announce(route.announce); + let mut out = moq_net::origin::Route::default().with_cost(route.cost); for id in route.hops { let origin = moq_net::Hop::new(id).map_err(|e| MoqError::InvalidRoute(e.to_string()))?; out = out @@ -92,9 +87,6 @@ pub struct MoqBroadcastRequest { struct Announced { inner: moq_net::announce::Consumer, - /// The same rooted cursor `inner` was drawn from, so an announced broadcast can resolve a - /// catalog reference to a sibling under that root. - origin: moq_net::origin::Consumer, } struct OriginDynamic { @@ -110,27 +102,18 @@ impl OriginDynamic { impl Announced { async fn next(&mut self) -> Result>, MoqError> { - loop { - match self.inner.next().await { - // Skip unannounce events; this surface only reports availability. A - // replacement arrives as an unannounce/announce pair, so the caller - // still sees a single announcement carrying the new broadcast. - Some(moq_net::announce::Update { path, broadcast }) => { - let Some(broadcast) = broadcast else { - continue; - }; - return Ok(Some(Arc::new(MoqAnnouncement { - path: path.to_string(), - broadcast: Arc::new(MoqBroadcastConsumer::routed(broadcast, self.origin.clone())), - }))); - } - None => return Ok(None), - } + match self.inner.next().await { + Some(update) => Ok(Some(Arc::new(MoqAnnouncement { + prefix: update.prefix.as_path().to_string(), + route: update.route.into(), + active: update.active, + }))), + None => Ok(None), } } } -/// Waits for one exact path, delegating to [`moq_net::origin::Consumer::announced_broadcast`]. +/// Waits for a route covering one exact path, then resolves it. struct AnnouncedBroadcast { origin: moq_net::origin::Consumer, path: moq_net::PathOwned, @@ -138,18 +121,32 @@ struct AnnouncedBroadcast { impl AnnouncedBroadcast { async fn available(&mut self) -> Result, MoqError> { - match self.origin.announced_broadcast(&self.path).await { - Some(broadcast) => Ok(Arc::new(MoqBroadcastConsumer::routed(broadcast, self.origin.clone()))), - None => Err(MoqError::Closed), - } + // `routed_broadcast` rides out the churn between a route covering the path + // and the path actually resolving (failover, an advertise-only announce + // racing its handler). + let broadcast = self.origin.routed_broadcast(&self.path).await?; + Ok(Arc::new(MoqBroadcastConsumer::routed(broadcast, self.origin.clone()))) } } -/// A broadcast announcement from an origin. +/// A route announcement (or retraction) from an origin. +/// +/// Carries no broadcast: resolve a specific path with +/// `MoqOriginConsumer::request_broadcast` (after this announcement proves it is +/// covered). The application decides which paths name broadcasts. #[derive(uniffi::Object)] pub struct MoqAnnouncement { - path: String, - broadcast: Arc, + prefix: String, + route: MoqRoute, + active: bool, +} + +/// A live route advertisement, from `MoqOriginProducer::announce`. +/// +/// The route stays advertised until `cancel` is called or the handle drops. +#[derive(uniffi::Object)] +pub struct MoqAnnounce { + inner: std::sync::Mutex>, } /// Waits for a specific broadcast to be announced. @@ -253,10 +250,10 @@ impl MoqOriginProducer { /// Create a broadcast at `path` on this origin, returning the producer that feeds it. /// - /// The broadcast starts announced: the origin advertises the path so subscribers can discover - /// it, becoming visible shortly after this returns. Toggle discoverability with - /// [`MoqBroadcastProducer::set_announce`]; an unannounced broadcast stays reachable by exact - /// path for subscribes and fetches without being announced. + /// The broadcast starts announced: the origin advertises the exact path as a route so + /// subscribers can discover it, becoming visible shortly after this returns. Toggle + /// discoverability with [`MoqBroadcastProducer::set_announce`]; an unannounced broadcast + /// stays reachable by exact path for subscribes and fetches without being announced. /// /// [`MoqBroadcastProducer::finish`] unpublishes immediately. Dropping the producer /// without finishing also unpublishes, but subscribers observe the end as a @@ -264,28 +261,69 @@ impl MoqOriginProducer { pub fn create_broadcast(&self, path: String) -> Result, MoqError> { let _guard = crate::ffi::enter(); // Surfaces Error::Unauthorized (out of scope) via the MoqError::Protocol conversion. - let broadcast = self - .inner - .create_broadcast(path.as_str(), moq_net::broadcast::Route::new().with_announce(true))?; - Ok(Arc::new(MoqBroadcastProducer::from_inner(broadcast)?)) + let broadcast = self.inner.create_broadcast(path.as_str())?; + let announcement = self.inner.announce(path.as_str(), Default::default())?; + Ok(Arc::new(MoqBroadcastProducer::from_inner_announced( + broadcast, + Some(crate::producer::AnnounceState { + origin: self.inner.clone(), + path: moq_net::Path::new(&path).to_owned(), + announcement: Some(announcement), + }), + )?)) + } + + /// Advertise a route: a claim that paths under `prefix` can be served. + /// + /// The route is visible to subscribers until the returned handle is cancelled + /// (or dropped). Announcing is independent of `create_broadcast`: announce one + /// short prefix and serve requests beneath it with [`Self::dynamic`], or + /// advertise extra exact paths. + pub fn announce(&self, prefix: String, route: MoqRoute) -> Result, MoqError> { + let _guard = crate::ffi::enter(); + let route: moq_net::origin::Route = route.try_into()?; + let announcement = self.inner.announce(prefix.as_str(), route)?; + Ok(Arc::new(MoqAnnounce { + inner: std::sync::Mutex::new(Some(announcement)), + })) + } +} + +#[uniffi::export] +impl MoqAnnounce { + /// Re-price the route in place: replace its hops and cost. The prefix cannot + /// change; announce a new route instead. + pub fn update(&self, route: MoqRoute) -> Result<(), MoqError> { + let _guard = crate::ffi::enter(); + let route: moq_net::origin::Route = route.try_into()?; + let guard = self.inner.lock().unwrap(); + let announcement = guard.as_ref().ok_or(MoqError::Closed)?; + announcement.update(route)?; + Ok(()) + } + + /// Retract the route. Terminal: the advertisement is withdrawn here, not when + /// the handle is released. + pub fn cancel(&self) { + let _guard = crate::ffi::enter(); + self.inner.lock().unwrap().take(); } } #[uniffi::export] impl MoqOriginConsumer { - /// Subscribe to all broadcast announcements under a prefix. + /// Subscribe to all route announcements under a prefix. pub fn announced(&self, prefix: String) -> Result, MoqError> { let _guard = crate::ffi::enter(); let origin = self.inner.with_root(prefix).ok_or(MoqError::Unauthorized)?; Ok(Arc::new(MoqAnnounced { task: Task::new(Announced { inner: origin.announced(), - origin, }), })) } - /// Wait for a specific broadcast to be announced by path. + /// Wait for a route to cover `path`, then resolve the broadcast there. /// /// 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. @@ -311,10 +349,11 @@ impl MoqOriginConsumer { /// Request a broadcast by path, resolving as soon as it can be served. /// - /// Returns a broadcast already reachable by exact path immediately, whether announced or not; - /// otherwise falls back to a dynamic handler on the origin (if any) and resolves once it serves - /// the broadcast, or errors if nothing can serve it. Unlike `announced_broadcast`, this does - /// *not* wait indefinitely for a future announcement. Drop the returned future to cancel. + /// Resolution order: a local broadcast at the exact path, then the best announced route + /// covering the path (served on demand by the session that announced it), then a dynamic + /// handler on the origin (if any). Errors if nothing can serve it. Unlike + /// `announced_broadcast`, this does *not* wait for a future announcement. 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. @@ -395,9 +434,7 @@ impl MoqBroadcastRequest { #[uniffi::export] impl MoqAnnounced { - /// Get the next broadcast announcement. Returns `None` when the origin is closed. - /// - /// Use `broadcast.closed()` to learn when a broadcast is unannounced. + /// Get the next route announcement or retraction. Returns `None` when the origin is closed. pub async fn next(&self) -> Result>, MoqError> { self.task.run(|mut state| async move { state.next().await }).await } @@ -412,14 +449,20 @@ impl MoqAnnounced { #[uniffi::export] impl MoqAnnouncement { - /// The path of the announced broadcast. + /// The covered prefix, relative to the `announced` call's prefix. pub fn path(&self) -> String { - self.path.clone() + self.prefix.clone() + } + + /// The route serving the prefix: its hops and cost. + pub fn route(&self) -> MoqRoute { + self.route.clone() } - /// The broadcast consumer. - pub fn broadcast(&self) -> Arc { - self.broadcast.clone() + /// Whether the route is active (`true`) or was retracted (`false`). A repeated + /// active announcement for the same prefix is a metadata update. + pub fn active(&self) -> bool { + self.active } } diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index a03b7badf76..e94997281b7 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -6,7 +6,6 @@ use crate::consumer::{MoqBroadcastConsumer, MoqGroupConsumer, MoqSubscription, M use crate::error::MoqError; use crate::ffi::Task; use crate::media::{MoqAudioInit, MoqContainerFormat, MoqContainerInit, MoqFrame, MoqVideoInit, MoqVideoProperties}; -use crate::origin::MoqRoute; /// Publisher-side track properties, mirroring [`moq_net::track::Info`]. /// @@ -73,6 +72,18 @@ pub(crate) struct BroadcastProducer { // Carries the untyped `Extra` extension so callers can attach application catalog // sections by name (the only extension shape that crosses the FFI boundary). pub(crate) catalog: moq_mux::catalog::Producer, + // How to (re-)announce the exact path, for origin-created broadcasts. + // `None` for a standalone broadcast, which has no origin to announce on. + pub(crate) announce: Option, +} + +/// The origin handle and path an origin-created broadcast was published under, +/// so `set_announce` can toggle its route. +pub(crate) struct AnnounceState { + pub(crate) origin: moq_net::origin::Producer, + pub(crate) path: moq_net::PathOwned, + /// The live advertisement, absent while unannounced. + pub(crate) announcement: Option, } /// A whole-frame importer for one codec track. @@ -154,11 +165,24 @@ impl TrackDynamicProducer { impl MoqBroadcastProducer { /// Wrap a `moq_net::broadcast::Producer` (standalone or origin-created), attaching /// the catalog track every FFI broadcast carries. - pub(crate) fn from_inner(mut broadcast: moq_net::broadcast::Producer) -> Result { + pub(crate) fn from_inner(broadcast: moq_net::broadcast::Producer) -> Result { + Self::from_inner_announced(broadcast, None) + } + + /// [`Self::from_inner`], carrying the origin/path/announcement state that lets + /// `set_announce` toggle an origin-created broadcast's route. + pub(crate) fn from_inner_announced( + mut broadcast: moq_net::broadcast::Producer, + announce: Option, + ) -> Result { let catalog = moq_mux::catalog::Producer::with_catalog(&mut broadcast, moq_mux::catalog::hang::Catalog::default())?; Ok(Self { - state: std::sync::Mutex::new(Some(BroadcastProducer { broadcast, catalog })), + state: std::sync::Mutex::new(Some(BroadcastProducer { + broadcast, + catalog, + announce, + })), }) } @@ -235,27 +259,25 @@ impl MoqBroadcastProducer { Ok(Arc::new(Self::from_inner(moq_net::broadcast::Info::new().produce())?)) } - /// Update the broadcast's route: the hop chain, cost, and announce flag it advertises. - /// - /// Use this as conditions shift (e.g. a standby transcoder lowering its cost - /// once it is warm); consumers observe the change via - /// `MoqBroadcastConsumer::route_updates` and sessions forward it downstream. - pub fn set_route(&self, route: MoqRoute) -> Result<(), MoqError> { - let _guard = crate::ffi::enter(); - let route = route.try_into()?; - self.with_state(|state| Ok(state.broadcast.set_route(route)?)) - } - - /// Set whether the broadcast is announced, keeping the rest of its route (hops, cost). + /// Set whether the broadcast's exact path is announced as a route. /// /// The origin advertises the path only while announced; an unannounced /// broadcast stays reachable by exact path for subscribes and fetches. This is /// how a publisher goes on and off the air without tearing down the broadcast. + /// Errors with `Closed` on a standalone broadcast (no origin to announce on). pub fn set_announce(&self, announce: bool) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); self.with_state(|state| { - let route = state.broadcast.consume().route(); - Ok(state.broadcast.set_route(route.with_announce(announce))?) + let announce_state = state.announce.as_mut().ok_or(MoqError::Closed)?; + match (announce, announce_state.announcement.is_some()) { + (true, false) => { + let route = moq_net::origin::Route::default(); + announce_state.announcement = Some(announce_state.origin.announce(&announce_state.path, route)?); + } + (false, true) => announce_state.announcement = None, + _ => {} + } + Ok(()) }) } diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 73e5fce3b14..63c2573f7f5 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -8,7 +8,6 @@ use crate::audio::{ }; use crate::consumer::MoqBroadcastConsumer; use crate::consumer::MoqFetchGroupOptions; -use crate::consumer::MoqRouteWatch; use crate::consumer::MoqSubscription; use crate::error::MoqError; use crate::json::{MoqJsonSnapshotConfig, MoqJsonStreamConfig}; @@ -1010,6 +1009,36 @@ fn audio_rejects_bad_init_bytes() { ); } +/// A route can cover the awaited path while nothing serves it (an advertise-only +/// announce with no fallback), and it can retract before the resolution lands. +/// That churn must keep the wait alive rather than surface as a spurious +/// Unroutable; the wait resolves once something real serves the path. +#[tokio::test] +async fn announced_broadcast_survives_an_unservable_route() { + let origin = MoqOriginProducer::new(MoqOriginOptions::default()); + let consumer = origin.consume(); + + // Advertise-only: covers the path, serves nothing (and no dynamic fallback). + let route = origin.announce("live".into(), MoqRoute::default()).unwrap(); + + let announced = consumer.announced_broadcast("live".into()).unwrap(); + let pending = tokio::spawn(async move { announced.available().await }); + + // Give the wait time to observe the unservable coverage; it must ride it out. + tokio::time::sleep(std::time::Duration::from_millis(50)).await; + assert!(!pending.is_finished(), "an unservable route must not resolve the wait"); + + // The cover retracts (failover churn), then the real broadcast lands. + route.cancel(); + let broadcast = origin.create_broadcast("live".into()).unwrap(); + tokio::time::timeout(TIMEOUT, pending) + .await + .expect("timed out waiting for the real broadcast") + .expect("task") + .expect("resolves once something serves the path"); + broadcast.finish().unwrap(); +} + #[tokio::test] async fn create_broadcast_announces() { let origin = MoqOriginProducer::new(MoqOriginOptions::default()); @@ -1115,7 +1144,7 @@ async fn announced_broadcasts_resolve_siblings_under_the_prefix() { .unwrap() .expect("the origin should keep announcing"); if announcement.path() == "pub" { - break announcement.broadcast(); + break await_announced(&consumer, "a/pub").await; } }; @@ -1200,31 +1229,25 @@ async fn set_announce_toggles_announcement() { let consumer = origin.consume(); let broadcast = origin.create_broadcast("live".into()).unwrap(); - let announced = consumer.announced_broadcast("live".into()).unwrap(); - let bc = tokio::time::timeout(TIMEOUT, announced.available()) - .await - .expect("timed out waiting for the announcement") - .unwrap(); - - // The consumer observes the live flag through the route. Skip intermediate - // updates and wait for the flag itself, since route propagation is asynchronous. - async fn wait_live(watch: &MoqRouteWatch, announce: bool) { + // The consumer observes the flag through the announce stream: an active + // announcement, then its retraction. + let announced = consumer.announced("".into()).unwrap(); + async fn wait_live(announced: &MoqAnnounced, announce: bool) { loop { - let route = tokio::time::timeout(TIMEOUT, watch.next()) + let announcement = tokio::time::timeout(TIMEOUT, announced.next()) .await - .expect("timed out waiting for a route update") + .expect("timed out waiting for an announce update") .unwrap() - .expect("broadcast ended while waiting for a route"); - if route.announce == announce { + .expect("origin ended while waiting for an announce update"); + if announcement.path() == "live" && announcement.active() == announce { return; } } } - let watch = bc.route_updates(); - wait_live(&watch, true).await; + wait_live(&announced, true).await; broadcast.set_announce(false).unwrap(); - wait_live(&watch, false).await; + wait_live(&announced, false).await; // Non-live: unannounced, but still reachable by exact path. tokio::time::timeout(TIMEOUT, consumer.request_broadcast("live".into())) @@ -1280,7 +1303,7 @@ async fn local_publish_consume_audio() { assert_eq!(announcement.path(), "live"); - let broadcast_consumer = announcement.broadcast(); + let broadcast_consumer = await_announced(&consumer, &announcement.path()).await; let catalog_consumer = broadcast_consumer.subscribe_catalog().await.unwrap(); let catalog = tokio::time::timeout(TIMEOUT, catalog_consumer.next()) @@ -1337,7 +1360,7 @@ async fn video_publish_consume() { .unwrap() .expect("expected announcement"); - let broadcast_consumer = announcement.broadcast(); + let broadcast_consumer = await_announced(&consumer, &announcement.path()).await; let catalog_consumer = broadcast_consumer.subscribe_catalog().await.unwrap(); let catalog = tokio::time::timeout(TIMEOUT, catalog_consumer.next()) @@ -1447,7 +1470,7 @@ async fn video_raw_publish_consume() { .unwrap() .expect("expected announcement"); - let broadcast_consumer = announcement.broadcast(); + let broadcast_consumer = await_announced(&consumer, &announcement.path()).await; let catalog_consumer = broadcast_consumer.subscribe_catalog().await.unwrap(); let catalog = tokio::time::timeout(TIMEOUT, catalog_consumer.next()) .await @@ -1561,7 +1584,11 @@ async fn video_raw_publish_from_many_threads() { .expect("timed out") .unwrap() .expect("expected announcement"); - let catalog_consumer = announcement.broadcast().subscribe_catalog().await.unwrap(); + let catalog_consumer = await_announced(&consumer, &announcement.path()) + .await + .subscribe_catalog() + .await + .unwrap(); let catalog = tokio::time::timeout(TIMEOUT, catalog_consumer.next()) .await .expect("timed out") @@ -1654,7 +1681,7 @@ async fn multiple_frames_ordering() { .unwrap() .unwrap(); - let broadcast_consumer = announcement.broadcast(); + let broadcast_consumer = await_announced(&consumer, &announcement.path()).await; let catalog_consumer = broadcast_consumer.subscribe_catalog().await.unwrap(); let catalog = tokio::time::timeout(TIMEOUT, catalog_consumer.next()) .await @@ -1711,7 +1738,7 @@ async fn catalog_update_on_new_track() { .unwrap() .unwrap(); - let broadcast_consumer = announcement.broadcast(); + let broadcast_consumer = await_announced(&consumer, &announcement.path()).await; let catalog_consumer = broadcast_consumer.subscribe_catalog().await.unwrap(); let catalog1 = tokio::time::timeout(TIMEOUT, catalog_consumer.next()) @@ -1765,7 +1792,11 @@ async fn announced_broadcast() { .expect("expected announcement"); assert_eq!(announcement.path(), "test/broadcast"); - let _catalog = announcement.broadcast().subscribe_catalog().await.unwrap(); + let _catalog = await_announced(&consumer, &announcement.path()) + .await + .subscribe_catalog() + .await + .unwrap(); // Finish so consumers observe a deliberate end (the canonical end for a // publisher; dropping without finish reads as a failure). _broadcast.finish().unwrap(); @@ -1981,7 +2012,7 @@ fn without_runtime() { let announced = consumer.announced("".into()).unwrap(); let announcement = pollster::block_on(announced.next()).unwrap().unwrap(); assert_eq!(announcement.path(), "test"); - let _bc = announcement.broadcast(); + let _bc = pollster::block_on(consumer.request_broadcast("test".into())).unwrap(); let client = MoqClient::new(); client.set_tls_disable_verify(true); @@ -2059,7 +2090,7 @@ async fn server_client_roundtrip() { assert_eq!(announcement.path(), "hello"); // Subscribe to the audio track and verify a frame round-trips. - let bc = announcement.broadcast(); + let bc = await_announced(&consumer, "hello").await; let catalog_consumer = bc.subscribe_catalog().await.unwrap(); let catalog = tokio::time::timeout(TIMEOUT, catalog_consumer.next()) .await diff --git a/rs/moq-gst/src/sink/session.rs b/rs/moq-gst/src/sink/session.rs index 57985f2826b..89b21b47817 100644 --- a/rs/moq-gst/src/sink/session.rs +++ b/rs/moq-gst/src/sink/session.rs @@ -224,6 +224,8 @@ pub(crate) struct Session { /// This publication's completion. The task moves it to `Failed` on a fatal transport error, so the /// pad streaming threads stop feeding a dead session without consulting the element. completion: CompletionHandle, + /// The route advertising the broadcast; dropping it retracts. + _announcement: moq_net::announce::Producer, } impl Session { @@ -242,10 +244,8 @@ impl Session { let _rt = RUNTIME.enter(); let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let mut broadcast = origin.create_broadcast( - &settings.broadcast, - moq_net::broadcast::Route::new().with_announce(true), - )?; + let mut broadcast = origin.create_broadcast(&settings.broadcast)?; + let announcement = origin.announce(&settings.broadcast, moq_net::origin::Route::default())?; let catalog = moq_mux::catalog::Producer::new(&mut broadcast)?; let status = Arc::new(Status::default()); @@ -286,6 +286,7 @@ impl Session { send_bandwidth, recv_bandwidth, completion, + _announcement: announcement, }, SessionRegistration { gate }, broadcast, diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index 830e47449a9..d74f868d0ca 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -367,12 +367,13 @@ async fn run_session( .established() .await?; - // Wait for the broadcast to be announced. Synchronous lookup would race the gossip of - // announcements that happens after the session is established. + // Wait for a route to cover the broadcast. Synchronous lookup would race the gossip + // of announcements that happens after the session is established. tracing::info!(broadcast = %settings.broadcast, "waiting for broadcast to be announced"); let broadcast = tokio::select! { - broadcast = origin_consumer.announced_broadcast(&settings.broadcast) => broadcast - .context("broadcast not allowed or origin closed")?, + routed = origin_consumer.routed_broadcast(&settings.broadcast) => { + routed.context("broadcast unavailable")? + } _ = shutdown.changed() => return Ok(()), }; diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index 8d2bd230e0a..0faabb512bd 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -416,9 +416,8 @@ mod tests { #[tokio::test] async fn escaping_broadcast_reference_is_not_advertised() { let origin = produce_origin(); - let _broadcast = origin - .create_broadcast("a/pub", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let _broadcast = origin.create_broadcast("a/pub").expect("publish allowed"); + let _announce_broadcast = origin.announce("a/pub", Default::default()).expect("publish allowed"); settle().await; let source = moq_mux::Source::new(origin.consume(), "a/pub"); let upstream = Upstream { @@ -442,9 +441,8 @@ mod tests { #[tokio::test] async fn serves_playlist_and_segments_from_the_timeline() { let origin = produce_origin(); - let mut broadcast = origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let mut broadcast = origin.create_broadcast("live").expect("publish allowed"); + let _announce_broadcast = origin.announce("live", Default::default()).expect("publish allowed"); settle().await; let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); @@ -519,9 +517,8 @@ mod tests { #[tokio::test] async fn serves_dash_manifest_and_time_addressed_segments() { let origin = produce_origin(); - let mut broadcast = origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let mut broadcast = origin.create_broadcast("live").expect("publish allowed"); + let _announce_broadcast = origin.announce("live", Default::default()).expect("publish allowed"); settle().await; let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); @@ -600,9 +597,8 @@ mod tests { #[tokio::test] async fn dash_manifest_turns_static_when_finished() { let origin = produce_origin(); - let mut broadcast = origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let mut broadcast = origin.create_broadcast("live").expect("publish allowed"); + let _announce_broadcast = origin.announce("live", Default::default()).expect("publish allowed"); settle().await; let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); @@ -661,9 +657,8 @@ mod tests { #[tokio::test] async fn target_duration_covers_the_window_without_a_declared_bound() { let origin = produce_origin(); - let mut broadcast = origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let mut broadcast = origin.create_broadcast("live").expect("publish allowed"); + let _announce_broadcast = origin.announce("live", Default::default()).expect("publish allowed"); settle().await; let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); @@ -698,9 +693,8 @@ mod tests { #[tokio::test] async fn audio_and_video_segments_are_aligned() { let origin = produce_origin(); - let mut broadcast = origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let mut broadcast = origin.create_broadcast("live").expect("publish allowed"); + let _announce_broadcast = origin.announce("live", Default::default()).expect("publish allowed"); settle().await; let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); @@ -783,9 +777,8 @@ mod tests { #[tokio::test] async fn dropping_the_broadcaster_keeps_a_cursor_drainable() { let origin = produce_origin(); - let mut broadcast = origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let mut broadcast = origin.create_broadcast("live").expect("publish allowed"); + let _announce_broadcast = origin.announce("live", Default::default()).expect("publish allowed"); settle().await; let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); @@ -853,9 +846,8 @@ mod tests { origin: &moq_net::origin::Producer, payload: &'static [u8], ) -> (Box, hang::catalog::VideoConfig) { - let mut broadcast = origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let mut broadcast = origin.create_broadcast("live").expect("publish allowed"); + let _announce_broadcast = origin.announce("live", Default::default()).expect("publish allowed"); let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); let reserved = catalog.reserve(); @@ -962,9 +954,8 @@ mod tests { #[tokio::test] async fn removing_a_rendition_ends_its_segment_cursor() { let origin = produce_origin(); - let broadcast = origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let broadcast = origin.create_broadcast("live").expect("publish allowed"); + let _announce_broadcast = origin.announce("live", Default::default()).expect("publish allowed"); let source = moq_mux::Source::new(origin.consume(), "live"); settle().await; let upstream = Upstream { @@ -1005,9 +996,8 @@ mod tests { #[tokio::test] async fn dropping_the_broadcaster_releases_its_renditions() { let origin = produce_origin(); - let mut broadcast = origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let mut broadcast = origin.create_broadcast("live").expect("publish allowed"); + let _announce_broadcast = origin.announce("live", Default::default()).expect("publish allowed"); settle().await; let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); @@ -1062,9 +1052,8 @@ mod tests { #[tokio::test] async fn record_cursors_yield_renditions_and_segments() { let origin = produce_origin(); - let mut broadcast = origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let mut broadcast = origin.create_broadcast("live").expect("publish allowed"); + let _announce_broadcast = origin.announce("live", Default::default()).expect("publish allowed"); settle().await; let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); diff --git a/rs/moq-hls/src/server/mod.rs b/rs/moq-hls/src/server/mod.rs index cfb37b6cdb7..5c1c60cc553 100644 --- a/rs/moq-hls/src/server/mod.rs +++ b/rs/moq-hls/src/server/mod.rs @@ -99,10 +99,10 @@ impl Server { } } - // Confirm the broadcast is announced (and in scope) before building a broadcaster; - // `Broadcaster::new` re-resolves it through the origin, which also lets a rendition's - // catalog `broadcast` field reference a sibling broadcast. - tokio::time::timeout(RESOLVE_TIMEOUT, self.inner.origin.announced_broadcast(name)) + // Confirm a route covers the broadcast (and it is in scope) before building a + // broadcaster; `Broadcaster::new` re-resolves it through the origin, which also + // lets a rendition's catalog `broadcast` field reference a sibling broadcast. + tokio::time::timeout(RESOLVE_TIMEOUT, self.inner.origin.routed(name)) .await .ok() .flatten()?; @@ -241,9 +241,8 @@ mod tests { async fn closed_broadcaster() -> Arc { let origin = produce_origin(); - let mut producer = origin - .create_broadcast("gone", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let mut producer = origin.create_broadcast("gone").expect("publish allowed"); + let _announce_producer = origin.announce("gone", Default::default()).expect("publish allowed"); settle().await; let source = moq_mux::Source::new(origin.consume(), "gone"); let broadcaster = Broadcaster::new(source, Config::default()) @@ -267,9 +266,8 @@ mod tests { .lock() .unwrap() .insert("live".to_string(), stale.clone()); - let _producer = origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let _producer = origin.create_broadcast("live").expect("publish allowed"); + let _announce_producer = origin.announce("live", Default::default()).expect("publish allowed"); settle().await; let fresh = server.broadcaster("live").await.expect("broadcast announced"); @@ -283,9 +281,8 @@ mod tests { let origin = produce_origin(); let server = Server::new(origin.consume(), Config::default()); let old = closed_broadcaster().await; - let mut new_producer = origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) - .expect("publish allowed"); + let mut new_producer = origin.create_broadcast("live").expect("publish allowed"); + let _announce_new_producer = origin.announce("live", Default::default()).expect("publish allowed"); settle().await; let new = Broadcaster::new(moq_mux::Source::new(origin.consume(), "live"), Config::default()) .await diff --git a/rs/moq-mux/src/catalog/hang/consumer.rs b/rs/moq-mux/src/catalog/hang/consumer.rs index 43df7be9eb3..ce011ac3084 100644 --- a/rs/moq-mux/src/catalog/hang/consumer.rs +++ b/rs/moq-mux/src/catalog/hang/consumer.rs @@ -159,9 +159,7 @@ mod test { /// resolves against. fn publish_catalog(published: Catalog<()>) -> Result> { let origin = crate::source::produce_origin(); - let mut broadcast = origin - .create_broadcast("a/pub", moq_net::broadcast::Route::new()) - .expect("broadcast should create"); + let mut broadcast = origin.create_broadcast("a/pub").expect("broadcast should create"); let mut track = broadcast .create_track(hang::Catalog::DEFAULT_NAME, hang::Catalog::default_track_info()) .expect("catalog track should create"); diff --git a/rs/moq-mux/src/source.rs b/rs/moq-mux/src/source.rs index b2e04289f47..617774c8913 100644 --- a/rs/moq-mux/src/source.rs +++ b/rs/moq-mux/src/source.rs @@ -263,9 +263,8 @@ mod tests { #[tokio::test] async fn no_override_targets_catalog_broadcast() { let origin = produce_origin(); - let _producer = origin - .create_broadcast("a/pub", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let _producer = origin.create_broadcast("a/pub").unwrap(); + let _announce_producer = origin.announce("a/pub", Default::default()).unwrap(); settle().await; let source = Source::new(origin.consume(), "a/pub"); @@ -287,9 +286,8 @@ mod tests { #[tokio::test] async fn subscribe_track_resolves_catalog_broadcast() { let origin = produce_origin(); - let mut producer = origin - .create_broadcast("a/pub", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut producer = origin.create_broadcast("a/pub").unwrap(); + let _announce_producer = origin.announce("a/pub", Default::default()).unwrap(); // The track must exist for the subscription to resolve (SUBSCRIBE_OK). let _video = producer.create_track("video", None).unwrap(); settle().await; @@ -304,9 +302,8 @@ mod tests { #[tokio::test] async fn self_reference_targets_catalog_broadcast() { let origin = produce_origin(); - let mut producer = origin - .create_broadcast("a/pub", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut producer = origin.create_broadcast("a/pub").unwrap(); + let _announce_producer = origin.announce("a/pub", Default::default()).unwrap(); let _video = producer.create_track("video", None).unwrap(); settle().await; @@ -324,15 +321,13 @@ mod tests { async fn escaping_reference_is_rejected() { let origin = produce_origin(); - let mut catalog = origin - .create_broadcast("a/pub", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut catalog = origin.create_broadcast("a/pub").unwrap(); + let _announce_catalog = origin.announce("a/pub", Default::default()).unwrap(); let _catalog_video = catalog.create_track("video", None).unwrap(); // The broadcast an escaping reference would land on if it clamped at the root. - let mut clamped = origin - .create_broadcast("elsewhere", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut clamped = origin.create_broadcast("elsewhere").unwrap(); + let _announce_clamped = origin.announce("elsewhere", Default::default()).unwrap(); let _clamped_video = clamped.create_track("video", None).unwrap(); settle().await; @@ -413,13 +408,11 @@ mod tests { async fn subscribe_track_resolves_referenced_broadcast() { let origin = produce_origin(); - let _catalog = origin - .create_broadcast("a/pub", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let _catalog = origin.create_broadcast("a/pub").unwrap(); + let _announce_catalog = origin.announce("a/pub", Default::default()).unwrap(); - let mut referenced = origin - .create_broadcast("a/source", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut referenced = origin.create_broadcast("a/source").unwrap(); + let _announce_referenced = origin.announce("a/source", Default::default()).unwrap(); let _video = referenced.create_track("video", None).unwrap(); settle().await; @@ -437,16 +430,11 @@ mod tests { async fn dot_resolves_output_parent() { let origin = produce_origin(); - let _catalog = origin - .create_broadcast( - "a/source/transcode", - moq_net::broadcast::Route::new().with_announce(true), - ) - .unwrap(); + let _catalog = origin.create_broadcast("a/source/transcode").unwrap(); + let _announce_catalog = origin.announce("a/source/transcode", Default::default()).unwrap(); - let mut referenced = origin - .create_broadcast("a/source", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut referenced = origin.create_broadcast("a/source").unwrap(); + let _announce_referenced = origin.announce("a/source", Default::default()).unwrap(); let _video = referenced.create_track("video", None).unwrap(); settle().await; @@ -462,13 +450,11 @@ mod tests { async fn dot_resolves_one_segment_catalog_to_root() { let origin = produce_origin(); - let _catalog = origin - .create_broadcast("top", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let _catalog = origin.create_broadcast("top").unwrap(); + let _announce_catalog = origin.announce("top", Default::default()).unwrap(); - let mut root = origin - .create_broadcast("", moq_net::broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut root = origin.create_broadcast("").unwrap(); + let _announce_root = origin.announce("", Default::default()).unwrap(); let _video = root.create_track("video", None).unwrap(); settle().await; diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index 795b108f5de..55c96a107dc 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -772,7 +772,7 @@ mod tests { /// `connect` must not depend on the peer answering. A peer that opens the announce /// stream and then says nothing (or promises a count it never delivers) used to hold /// `connect` for the life of the session, since it waited for the initial announce - /// set. Resolving a path you need is `announced_broadcast`'s job, which waits for + /// set. Resolving a path you need is `routed`'s job, which waits for /// that path rather than for the peer to finish talking. #[tokio::test(start_paused = true)] async fn connect_does_not_wait_for_the_peer_to_announce() { diff --git a/rs/moq-net/src/ietf/cluster.rs b/rs/moq-net/src/ietf/cluster.rs index ed3e9b3a898..8e07b336daf 100644 --- a/rs/moq-net/src/ietf/cluster.rs +++ b/rs/moq-net/src/ietf/cluster.rs @@ -12,7 +12,7 @@ //! ROUTE_COST of that path, as Key-Value-Pair message parameters. //! //! The semantics are the same ones moq-lite carries natively (see -//! [`crate::broadcast::Route`]); this module is only the moq-transport binding. +//! [`crate::origin::Route`]); this module is only the moq-transport binding. //! Negotiated on draft-17+ only, where SETUP is a Key-Value-Pair block. use bytes::Buf; @@ -173,17 +173,16 @@ impl Advert { /// carrying the broadcast advertises zero here just as it does on lite-06. There /// is nowhere to put the cold path, so it stays [`Cost::UNKNOWN`] and this route /// never outranks one whose cold cost is actually known. - pub fn route(&self, link_cost: u64) -> crate::broadcast::Route { - let advertised = crate::broadcast::Cost { + pub fn route(&self, link_cost: u64) -> crate::origin::Route { + let advertised = crate::origin::Cost { warm: self.cost, - ..crate::broadcast::Cost::UNKNOWN + ..crate::origin::Cost::UNKNOWN }; - let mut route = crate::broadcast::Route::new() + // The prefix travels separately: it is stamped where the advertisement + // attaches (the namespace). + crate::origin::Route::default() .with_hops(self.hops.hops().clone()) .with_cost(advertised.charged(link_cost)) - .with_announce(true); - route.advertised = advertised; - route } } @@ -448,13 +447,12 @@ mod tests { let route = advert.route(3); assert_eq!(route.cost.warm, 7); assert_eq!(&route.hops, hop_path(&[1, 2]).hops()); - assert!(route.announce); let absurd = Advert { hops: hop_path(&[1]), cost: u64::MAX, }; - assert_eq!(absurd.route(10).cost.warm, crate::broadcast::MAX_COST); + assert_eq!(absurd.route(10).cost.warm, crate::origin::MAX_COST); } /// Negotiating the extension and declaring an identity are separate questions, and a diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index fec8f7be106..8daf3243e25 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -35,20 +35,12 @@ fn serving_subscription(subscriber_priority: u8) -> Subscription { /// A broadcast whose route table is watched for changes in what we advertise: the /// namespace becoming (un)advertisable, or its path or cost moving. struct Watched { - broadcast: crate::broadcast::Consumer, - /// Demand edges re-price the serving route without a route change (see - /// [`crate::broadcast::outgoing_cost`]), so the loop watches this too. - demand: crate::broadcast::Demand, + /// The route last announced for this namespace, as the origin delivered it. + route: crate::origin::Route, /// What the peer currently holds for this namespace, or [`Advert::None`] while it /// is filtered. A selection that differs is worth a wire message; one that matches /// is not. sent: Advert, - /// When demand drained while a zero cost was advertised. Restoring the cold cost is - /// deferred by [`crate::broadcast::COST_LINGER`] past this, so viewer churn does not - /// flap routing across the mesh; demand returning in the window cancels it. - idle_at: Option, - /// Set once the broadcast errors, so a dead entry stops being polled. - dead: bool, /// The peer should hold this namespace but does not: it refused the request, or we /// could not get a stream to make it on. Nothing about that clears on its own, so the /// loop comes back to it on a timer. @@ -96,29 +88,14 @@ impl Refused { } impl Watched { - fn new(broadcast: crate::broadcast::Consumer) -> Self { + fn new(route: crate::origin::Route) -> Self { Self { - demand: broadcast.demand(), - broadcast, + route, sent: Advert::None, - idle_at: None, - dead: false, deferred: false, refused: Refused::No, } } - - /// Record what the peer now holds, retiring any linger the old advertisement armed. - /// - /// Only a discounted advertisement has a cost to restore. Leaving `idle_at` set past - /// one that isn't would keep [`Publisher::linger_deadline`] handing back an expired - /// instant that nothing ever clears, and the announce loops would spin on it. - fn set_sent(&mut self, sent: Advert) { - if !sent.discounted() { - self.idle_at = None; - } - self.sent = sent; - } } /// What to advertise to this peer for one broadcast. @@ -147,21 +124,6 @@ impl Advert { _ => None, } } - - /// Whether this advertisement carries a zero cost, which is what the serving-route - /// discount produces and what the linger is watching to restore. - fn discounted(&self) -> bool { - matches!(self, Self::Cluster(advert) if advert.cost == 0) - } -} - -/// What a watched broadcast reported. -enum Watch { - /// Its route table or demand moved; re-run the selection. - Changed(crate::PathOwned), - /// Demand just drained while a discounted cost was advertised. The cold cost is - /// restored once the linger expires, not now, so viewer churn does not flap routing. - Idle(crate::PathOwned), } /// How long to wait for a stream to advertise one namespace on. @@ -244,15 +206,8 @@ impl Namespaces { enum NamespaceEvent { /// The session or stream ended, with the result to surface. Closed(Result<(), Error>), - /// An origin-level (un)announce, `None` once the announce stream ends. + /// An origin-level route (un)announce, `None` once the announce stream ends. Update(Option), - /// A watched broadcast's route table or demand moved; re-run the selection. - Routes(crate::PathOwned), - /// A watched broadcast's demand drained; start its linger. - Idle(crate::PathOwned), - /// The linger sleep fired without an expired entry (it was canceled, or a later - /// deadline remains): restart the turn so the next deadline arms a fresh sleep. - Linger, /// The retry sleep fired: re-offer whatever the peer should be holding and isn't. Retry, } @@ -268,7 +223,7 @@ pub(super) struct Publisher Advert { - let routes = watch.broadcast.routes(); - let exclude = self.exclude(peer); - - for (route, serving) in crate::broadcast::advertisable_routes(&routes, self.self_hop, exclude) { - if !peer.negotiated() { - return Advert::Plain; - } - - // The Cluster extension has room for the warm cost only; a peer on this - // wire learns nothing about the cold path (see `cluster::Advert::route`). - let cost = crate::broadcast::outgoing_cost(&watch.demand, route, serving).warm; - // Our own Hop ID is always the last entry, so the peer reconstructs the full - // path. A chain with no room left is a loop in all but name; try the next route. - match cluster::Advert::forward(&route.hops, cost, self.self_hop) { - Ok(advert) => return Advert::Cluster(advert), - Err(_) => continue, - } + /// The origin's announce cursor already filters routes through the peer + /// (control-plane split horizon); this only shapes what the wire can carry. + fn select(&self, route: &crate::origin::Route, peer: &cluster::Peer) -> Advert { + // A route that already passed through us is a reflection. The origin + // filters these on receive, so this is defensive. + if self.self_origin != crate::Hop::UNKNOWN && route.hops.contains(&self.self_origin) { + return Advert::None; } - Advert::None - } - - /// Poll every watched broadcast for a change in what it should advertise, reporting - /// the first changed path. - /// - /// Two things move it: the route table (a failover, a standby attaching, a - /// re-price) and demand on the serving route (which switches the discount on and - /// off). `fired` is the linger deadline's verdict for this turn. - fn poll_watched( - watched: &mut HashMap, - fired: Option, - waiter: &kio::Waiter, - ) -> Poll { - for (path, watch) in watched.iter_mut() { - if watch.dead { - continue; - } - match watch.broadcast.poll_routes_changed(waiter) { - Poll::Ready(Ok(())) => return Poll::Ready(Watch::Changed(path.clone())), - // A dying broadcast has no further route changes; the origin's - // unannounce is what removes the entry. - Poll::Ready(Err(_)) => { - watch.dead = true; - continue; - } - Poll::Pending => {} - } - - // Only a cost-carrying advertisement re-prices on demand; a plain one has - // nowhere to put the discount, so watching demand would fire forever. - if !matches!(watch.sent, Advert::Cluster(_)) { - continue; - } - - if !watch.sent.discounted() { - // Not discounted: demand arriving is what applies the discount. - if let Poll::Ready(Ok(())) = watch.demand.poll_used(waiter) { - return Poll::Ready(Watch::Changed(path.clone())); - } - continue; - } - - match watch.idle_at { - // Demand coming back within the linger cancels the restore; fall through - // to re-arm the unused watch. - Some(_) if watch.demand.is_used() => watch.idle_at = None, - // The linger expired: restore the cold cost. - Some(at) if fired.is_some_and(|now| now >= at + crate::broadcast::COST_LINGER) => { - watch.idle_at = None; - return Poll::Ready(Watch::Changed(path.clone())); - } - // Still lingering: the sleep owns the wakeup, and `poll_used` re-arms - // the cancel check above. - Some(_) => { - let _ = watch.demand.poll_used(waiter); - continue; - } - None => {} - } - - // Demand just drained. Start the linger rather than re-pricing now, and end - // the turn so the caller arms a deadline for it. - if let Poll::Ready(Ok(())) = watch.demand.poll_unused(waiter) { - return Poll::Ready(Watch::Idle(path.clone())); - } + if !peer.negotiated() { + return Advert::Plain; } - Poll::Pending - } - /// The earliest deferred cost-restore across every watched broadcast. - fn linger_deadline(watched: &HashMap) -> Option { - watched - .values() - .filter_map(|watch| watch.idle_at) - .min() - .map(|at| at + crate::broadcast::COST_LINGER) + // The Cluster extension has room for the warm cost only; a peer on this + // wire learns nothing about the cold path (see `cluster::Advert::route`). + let cost = route.cost.clamped().warm; + // Our own Hop ID is always the last entry, so the peer reconstructs the full + // path. A chain with no room left is a loop in all but name. + match cluster::Advert::forward(&route.hops, cost, self.self_origin) { + Ok(advert) => Advert::Cluster(advert), + Err(_) => Advert::None, + } } /// Handle an incoming bidi stream dispatched by the session. @@ -862,7 +739,7 @@ where let Some(watch) = watched.get(suffix) else { return Ok(()); }; - let advert = self.select(watch, peer); + let advert = self.select(&watch.route, peer); let refused = watch.refused; let wanted = advert.wanted(); let held = watch.sent.wanted(); @@ -960,7 +837,7 @@ where // anything else it should hold and does not comes back on one. watch.refused = refused; watch.deferred = wanted && !sent.wanted() && refused.pending(); - watch.set_sent(sent); + watch.sent = sent; } Ok(()) } @@ -1283,8 +1160,6 @@ where ) -> Result<(), Error> { let mut announced = origin.announced(); - let mut linger = crate::runtime::Deadline::new(&self.runtime); - // When to re-offer whatever the peer should hold and doesn't, and how long to wait // the next time that fails. Jittered so a relay's namespaces don't all come back on // the same tick. @@ -1292,11 +1167,9 @@ where let mut retry_at: Option = None; let mut retry_delay = RETRY_BASE; - // Stream updates (origin (un)announces plus watched route and demand - // changes), bailing if the peer closes its side first. + // Stream updates (origin route (un)announces), bailing if the peer closes + // its side first. let res = loop { - linger.set(Self::linger_deadline(&ns.watched)); - match ns.watched.values().any(|watch| watch.deferred) { // Arm on the edge, so a turn that changes nothing else doesn't push the // deadline out forever. @@ -1309,9 +1182,7 @@ where retry.set(retry_at); let event = { - // Split the borrow so the close watch and the route sweep can both run in - // the same turn. - let Namespaces { target, watched, .. } = &mut ns; + let Namespaces { target, .. } = &mut ns; kio::wait(|waiter| { let mut cx = std::task::Context::from_waker(waiter.waker()); if let Poll::Ready(res) = target.poll_closed(&mut cx) { @@ -1323,25 +1194,13 @@ where if retry.poll(waiter).is_ready() { return Poll::Ready(NamespaceEvent::Retry); } - // Stamped per poll rather than kept: the turn always ends in a - // `Ready` below once it fires, so it never has to survive. - let fired = linger.poll(waiter).is_ready().then(|| self.runtime.now()); - match Self::poll_watched(watched, fired, waiter) { - Poll::Ready(Watch::Changed(path)) => return Poll::Ready(NamespaceEvent::Routes(path)), - Poll::Ready(Watch::Idle(path)) => return Poll::Ready(NamespaceEvent::Idle(path)), - Poll::Pending => {} - } - match fired.is_some() { - true => Poll::Ready(NamespaceEvent::Linger), - false => Poll::Pending, - } + Poll::Pending }) .await }; match event { NamespaceEvent::Closed(res) => break res, - NamespaceEvent::Linger => continue, NamespaceEvent::Retry => { retry_at = None; retry_delay = (retry_delay * 2).min(RETRY_MAX); @@ -1371,36 +1230,31 @@ where stream.writer.finish()?; return stream.writer.closed().await; } - NamespaceEvent::Update(Some(crate::announce::Update { path, broadcast })) => { + NamespaceEvent::Update(Some(update)) => { + let path = update.prefix.as_path().to_owned(); let suffix = path .strip_prefix(&prefix) - .expect("origin returned invalid path") + .expect("origin returned invalid prefix") .to_owned(); - let path = path.to_owned(); - match broadcast { - Some(broadcast) => { - ns.watched.insert(suffix.clone(), Watched::new(broadcast)); - self.sync_namespace(&mut ns, &suffix, &path).await?; - } - None => { - // Only close out namespaces the peer actually saw. - let held = ns.watched.remove(&suffix).is_some_and(|watch| watch.sent.wanted()); - if held { - tracing::debug!(broadcast = %self.origin.absolute(&path), "namespace_done"); - self.withdraw_namespace(&mut ns.target, &mut ns.requests, suffix) - .await?; + if update.active { + // A repeat for a live suffix is a metadata update: keep the + // peer's refusal state and re-run the selection. + match ns.watched.get_mut(&suffix) { + Some(watch) => watch.route = update.route, + None => { + ns.watched.insert(suffix.clone(), Watched::new(update.route)); } } - } - } - NamespaceEvent::Routes(suffix) => { - let path = prefix.join(&suffix); - self.sync_namespace(&mut ns, &suffix, &path).await?; - } - NamespaceEvent::Idle(suffix) => { - if let Some(watch) = ns.watched.get_mut(&suffix) { - watch.idle_at = Some(self.runtime.now()); + self.sync_namespace(&mut ns, &suffix, &path).await?; + } else { + // Only close out namespaces the peer actually saw. + let held = ns.watched.remove(&suffix).is_some_and(|watch| watch.sent.wanted()); + if held { + tracing::debug!(route = %self.origin.absolute(&path), "namespace_done"); + self.withdraw_namespace(&mut ns.target, &mut ns.requests, suffix) + .await?; + } } } } @@ -1986,7 +1840,6 @@ mod tests { use super::*; use crate::lite::test_transport::SinkSession; use crate::model::ProduceTest; - use crate::runtime::Timers as _; use futures::FutureExt; /// The tokio-backed test runtime. Its transport parameter is phantom, so one @@ -2055,7 +1908,7 @@ mod tests { ) -> ( Publisher, origin::Consumer, - Vec, + Vec, ) { let other = crate::Hop::new(778).unwrap(); let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); @@ -2075,26 +1928,15 @@ mod tests { let mut echoed_hops = crate::Hops::new(); echoed_hops.push(assigned).unwrap(); let echoed = origin - .create_broadcast( - "from/peer", - crate::broadcast::Route::new() - .with_hops(echoed_hops) - .with_announce(true), - ) + .announce("from/peer", crate::origin::Route::default().with_hops(echoed_hops)) .unwrap(); let mut local_hops = crate::Hops::new(); local_hops.push(other).unwrap(); let local = origin - .create_broadcast( - "from/us", - crate::broadcast::Route::new().with_hops(local_hops).with_announce(true), - ) + .announce("from/us", crate::origin::Route::default().with_hops(local_hops)) .unwrap(); - // Broadcast visibility is deferred until the executor ticks. - tokio::time::sleep(Duration::from_millis(1)).await; - (publisher, consumer, vec![echoed, local]) } @@ -2109,11 +1951,12 @@ mod tests { let peer = cluster::Peer::default(); - let echoed = consumer.get_broadcast("from/peer").unwrap(); - assert!(!publisher.select(&Watched::new(echoed), &peer).wanted()); + // The cursor is what filters: an excluded consumer never sees the echoed route. + let mut announced = consumer.excluding(assigned).announced(); + let local = announced.assert_next_active("from/us"); + announced.assert_next_wait(); - let local = consumer.get_broadcast("from/us").unwrap(); - assert_eq!(publisher.select(&Watched::new(local), &peer), Advert::Plain); + assert_eq!(publisher.select(&local, &peer), Advert::Plain); } /// Declaring the reserved 0 turns the extension on while naming nobody, so the @@ -2170,71 +2013,23 @@ mod tests { let mut hops = crate::Hops::new(); hops.push(crate::Hop::UNKNOWN).unwrap(); let _echoed = origin - .create_broadcast( - "from/peer", - crate::broadcast::Route::new().with_hops(hops).with_announce(true), - ) + .announce("from/peer", crate::origin::Route::default().with_hops(hops)) .unwrap(); - tokio::time::sleep(std::time::Duration::from_millis(1)).await; let peer = cluster::Peer { hop: Some(crate::Hop::UNKNOWN), cost: None, }; - let echoed = consumer.get_broadcast("from/peer").unwrap(); + // The excluding cursor cannot match hop 0 (it names nobody), so the route + // still reaches this peer's stream. + let mut announced = consumer.excluding(publisher.exclude(&peer)).announced(); + let echoed = announced.assert_next_active("from/peer"); assert!( - publisher.select(&Watched::new(echoed), &peer).wanted(), + publisher.select(&echoed, &peer).wanted(), "known gap: the assigned identity is not in the chain, so nothing filters it", ); } - /// A drained broadcast arms a linger so the cold cost is restored after a grace - /// period. If the advertisement stops being discounted before that fires, the - /// linger must go with it: an expired deadline that nothing clears makes - /// `linger_deadline` hand back the same instant every turn, and the announce loops - /// spin on it forever. - #[tokio::test] - async fn linger_clears_when_the_advert_stops_being_discounted() { - let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); - let broadcast = origin - .clone() - .create_broadcast("cam", crate::broadcast::Route::announced()) - .unwrap(); - - let mut watch = Watched::new(broadcast.consume()); - let hops = crate::Hops::try_from(vec![crate::Hop::new(7).unwrap()]).unwrap(); - - // Discounted (cost 0) and drained: the linger is running. - watch.set_sent(Advert::Cluster(cluster::Advert { - hops: cluster::HopPath::new(hops.clone()), - cost: 0, - })); - watch.idle_at = Some(TestRuntime::new().now()); - let watched = HashMap::from([(crate::Path::new("cam").to_owned(), watch)]); - assert!(Publisher::::linger_deadline(&watched).is_some()); - - // A re-priced advertisement has a cost to advertise, so there is nothing left - // to restore. - let mut watch = watched.into_values().next().unwrap(); - watch.set_sent(Advert::Cluster(cluster::Advert { - hops: cluster::HopPath::new(hops), - cost: 9, - })); - let watched = HashMap::from([(crate::Path::new("cam").to_owned(), watch)]); - assert_eq!( - Publisher::::linger_deadline(&watched), - None, - "a non-discounted advert must not leave a deadline behind" - ); - - // So does one that stopped being advertisable at all. - let mut watch = watched.into_values().next().unwrap(); - watch.idle_at = Some(TestRuntime::new().now()); - watch.set_sent(Advert::None); - let watched = HashMap::from([(crate::Path::new("cam").to_owned(), watch)]); - assert_eq!(Publisher::::linger_deadline(&watched), None); - } - /// A same-path source can splice into (or detach from) an existing broadcast /// without an origin-level (un)announce, silently flipping `advertisable`. /// Namespace forwarding must follow: advertise when a clean route appears, @@ -2258,15 +2053,13 @@ mod tests { Version::Draft16, ); - // The broadcast starts with only a route through the assigned peer. + // The prefix starts with only a route through the assigned peer. let mut tainted_hops = crate::Hops::new(); tainted_hops.push(assigned).unwrap(); let _tainted = origin - .create_broadcast( + .announce( "route-flip-cam", - crate::broadcast::Route::new() - .with_hops(tainted_hops) - .with_announce(true), + crate::origin::Route::default().with_hops(tainted_hops), ) .unwrap(); settle().await; @@ -2283,15 +2076,12 @@ mod tests { assert!(futures::poll!(run.as_mut()).is_pending()); assert_eq!(occurrences(&log, b"route-flip-cam"), 0); - // A clean source splices in: no origin announce fires, only the route table - // changes. The namespace must now be advertised. + // A clean route joins the same prefix: the excluded cursor now has a best + // visible route, so the namespace must be advertised. let mut clean_hops = crate::Hops::new(); clean_hops.push(clean_publisher).unwrap(); let clean = origin - .create_broadcast( - "route-flip-cam", - crate::broadcast::Route::new().with_hops(clean_hops).with_announce(true), - ) + .announce("route-flip-cam", crate::origin::Route::default().with_hops(clean_hops)) .unwrap(); settle().await; assert!(futures::poll!(run.as_mut()).is_pending()); @@ -2301,7 +2091,7 @@ mod tests { "NAMESPACE after a clean route joins" ); - // The clean source detaches, leaving only the tainted route: withdrawn. + // The clean route retracts, leaving only the tainted one: withdrawn. drop(clean); settle().await; assert!(futures::poll!(run.as_mut()).is_pending()); @@ -2343,9 +2133,7 @@ mod tests { const VERSION: Version = Version::Draft17; let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); - let _cam = origin - .create_broadcast("lonely-cam", crate::broadcast::Route::announced()) - .unwrap(); + let _cam = origin.announce("lonely-cam", crate::origin::Route::default()).unwrap(); settle().await; // Every stream is answered with the same refusal, so a retry would show up as a @@ -2434,9 +2222,7 @@ mod tests { let consumer = origin.consume(); // Announced before the peer subscribes: it must only hit the wire after. - let early = origin - .create_broadcast("early-cam", crate::broadcast::Route::announced()) - .unwrap(); + let early = origin.announce("early-cam", crate::origin::Route::default()).unwrap(); settle().await; // Stream 1 is the peer's SUBSCRIBE_NAMESPACE (the peer stays quiet after); @@ -2477,9 +2263,7 @@ mod tests { ); // A later announce reaches the same subscription. - let _late = origin - .create_broadcast("late-cam", crate::broadcast::Route::announced()) - .unwrap(); + let _late = origin.announce("late-cam", crate::origin::Route::default()).unwrap(); for _ in 0..100 { assert!(futures::poll!(run.as_mut()).is_pending()); if occurrences(&log, b"late-cam") >= 1 { @@ -2521,9 +2305,7 @@ mod tests { const VERSION: Version = Version::Draft17; let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); - let _local = origin - .create_broadcast("local-cam", crate::broadcast::Route::announced()) - .unwrap(); + let _local = origin.announce("local-cam", crate::origin::Route::default()).unwrap(); settle().await; // The only stream is the PUBLISH_NAMESPACE request we open ourselves. @@ -2569,9 +2351,7 @@ mod tests { const VERSION: Version = Version::Draft17; let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); - let _cam = origin - .create_broadcast("cam", crate::broadcast::Route::announced()) - .unwrap(); + let _cam = origin.announce("cam", crate::origin::Route::default()).unwrap(); settle().await; // Stream 1 is the peer's SUBSCRIBE_NAMESPACE; stream 2, if opened at all, is our @@ -2643,9 +2423,7 @@ mod tests { const VERSION: Version = Version::Draft14; let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); - let first = origin - .create_broadcast("first-cam", crate::broadcast::Route::announced()) - .unwrap(); + let first = origin.announce("first-cam", crate::origin::Route::default()).unwrap(); settle().await; // Open: the peer still has credit for the first advertisement, and answers it. @@ -2680,9 +2458,7 @@ mod tests { // Credit runs out, and a second namespace wants a stream we cannot get. set_gate(&gate, false); - let _second = origin - .create_broadcast("second-cam", crate::broadcast::Route::announced()) - .unwrap(); + let _second = origin.announce("second-cam", crate::origin::Route::default()).unwrap(); settle().await; // Retiring the first frees a slot and needs no new stream, so the loop has to reach @@ -2728,18 +2504,10 @@ mod tests { let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); - // Every route flows through the peer's own identity, so split horizon says this - // must never be advertised back to it: `select` wants nothing, which is what the - // peer already holds. + // A route that already passed through us must never be forwarded: `select` + // wants nothing, which is what the peer already holds. let mut hops = crate::Hops::new(); - hops.push(assigned).unwrap(); - let _echoed = origin - .create_broadcast( - "from/peer", - crate::broadcast::Route::new().with_hops(hops).with_announce(true), - ) - .unwrap(); - settle().await; + hops.push(crate::Hop::new(1).unwrap()).unwrap(); let session = crate::lite::test_transport::SinkSession::new(Default::default()); let publisher = Publisher::new( @@ -2755,8 +2523,7 @@ mod tests { // The state a refused or failed offer leaves behind: the peer holds nothing, and // the loop is coming back to it on a timer. let suffix: crate::PathOwned = crate::Path::new("from/peer").to_owned(); - let broadcast = origin.consume().get_broadcast("from/peer").unwrap(); - let mut watch = Watched::new(broadcast); + let mut watch = Watched::new(crate::origin::Route::default().with_hops(hops)); watch.deferred = true; let mut ns = Namespaces::new(cluster::Peer::default(), Target::Requests(None)); @@ -2778,9 +2545,7 @@ mod tests { const VERSION: Version = Version::Draft17; let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); - let cam = origin - .create_broadcast("solo-cam", crate::broadcast::Route::announced()) - .unwrap(); + let cam = origin.announce("solo-cam", crate::origin::Route::default()).unwrap(); settle().await; // Refused with a wait far longer than any backoff the loop would take on its own. @@ -2809,10 +2574,10 @@ mod tests { } assert_eq!(occurrences(&log, b"solo-cam"), 1, "the advertisement never went out"); - // A second route makes the advertisement worth re-pricing, which is a path back - // into the reconciliation that does not go through the retry timer. + // A cheaper second route makes the advertisement worth re-pricing, which is a + // path back into the reconciliation that does not go through the retry timer. let _standby = origin - .create_broadcast("solo-cam", crate::broadcast::Route::announced()) + .announce("solo-cam", crate::origin::Route::default().with_cost(0)) .unwrap(); for _ in 0..100 { @@ -2841,9 +2606,7 @@ mod tests { const VERSION: Version = Version::Draft17; let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); - let cam = origin - .create_broadcast("solo-cam", crate::broadcast::Route::announced()) - .unwrap(); + let cam = origin.announce("solo-cam", crate::origin::Route::default()).unwrap(); settle().await; let session = @@ -2896,12 +2659,8 @@ mod tests { const VERSION: Version = Version::Draft14; let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); - let _first = origin - .create_broadcast("first-cam", crate::broadcast::Route::announced()) - .unwrap(); - let _second = origin - .create_broadcast("second-cam", crate::broadcast::Route::announced()) - .unwrap(); + let _first = origin.announce("first-cam", crate::origin::Route::default()).unwrap(); + let _second = origin.announce("second-cam", crate::origin::Route::default()).unwrap(); settle().await; // Every stream opens and then goes silent: an exhausted script parks rather than @@ -2948,9 +2707,7 @@ mod tests { const VERSION: Version = Version::Draft14; let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); - let _cam = origin - .create_broadcast("lonely-cam", crate::broadcast::Route::announced()) - .unwrap(); + let _cam = origin.announce("lonely-cam", crate::origin::Route::default()).unwrap(); settle().await; // Closed from the start: the peer has granted nothing. diff --git a/rs/moq-net/src/ietf/session.rs b/rs/moq-net/src/ietf/session.rs index a322dd73c09..4972c552f46 100644 --- a/rs/moq-net/src/ietf/session.rs +++ b/rs/moq-net/src/ietf/session.rs @@ -102,7 +102,7 @@ where // detection works. Read BEFORE the placeholders below: their ids are random and // identify nothing, so declaring one would compare incoming paths against an // identity no other session shares. - let self_hop = self_hop(publish.as_ref(), subscribe.as_ref()); + let self_origin = self_origin(publish.as_ref(), subscribe.as_ref()); // moq-transport threads concrete origins through the publisher/subscriber. // An unset half gets an empty origin: an empty publish origin announces @@ -151,7 +151,7 @@ where control, peer_hop, peer_setup.clone(), - self_hop, + self_origin, cost, version, tasks.clone(), @@ -276,7 +276,7 @@ where let session = session.clone(); let goaway = goaway.clone(); async move { - if let Err(err) = run_setup(runtime, session, version, path, self_hop, cost, goaway).await { + if let Err(err) = run_setup(runtime, session, version, path, self_origin, cost, goaway).await { tracing::warn!(%err, "setup send error"); } std::future::pending::<()>().await; @@ -301,7 +301,7 @@ where control, peer_hop, peer_setup.clone(), - self_hop, + self_origin, cost, version, tasks, @@ -437,10 +437,10 @@ pub struct PeerSetup { /// The Hop ID this session declares and detects loops against. /// -/// Both halves of a session share the process's Hop ID, so either one names +/// Both halves of a session share the process's origin identity, so either one names /// it; the publish half is just the usual one to be set. A session with neither half /// has no content to route, so a throwaway id is all it can offer. -fn self_hop(publish: Option<&origin::Consumer>, subscribe: Option<&origin::Producer>) -> Hop { +fn self_origin(publish: Option<&origin::Consumer>, subscribe: Option<&origin::Producer>) -> Hop { publish .map(|origin| **origin) .or_else(|| subscribe.map(|origin| **origin)) @@ -511,7 +511,7 @@ fn peer_from_params(params: &ietf::Parameters, version: Version) -> Result( @@ -519,7 +519,7 @@ async fn run_setup, - self_hop: Hop, + self_origin: Hop, cost: Option, goaway: crate::goaway::Protocol, ) -> Result<(), Error> { @@ -533,7 +533,7 @@ async fn run_setup) -> usize { let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); - let _cam = origin - .create_broadcast("solo-cam", crate::broadcast::Route::new().with_announce(true)) - .unwrap(); + let _cam = origin.announce("solo-cam", crate::origin::Route::default()).unwrap(); // An open gate: an unsolicited PUBLISH_NAMESPACE can reach the wire. let gate = kio::Producer::new(true); @@ -1116,14 +1114,14 @@ mod tests { let ours = crate::Hop::new(42).unwrap(); let publish = crate::origin::Info::new(ours).produce(); - assert_eq!(self_hop(Some(&publish.consume()), None), ours, "the publish half"); + assert_eq!(self_origin(Some(&publish.consume()), None), ours, "the publish half"); let subscribe = crate::origin::Info::new(ours).produce(); - assert_eq!(self_hop(None, Some(&subscribe)), ours, "the subscribe half alone"); + assert_eq!(self_origin(None, Some(&subscribe)), ours, "the subscribe half alone"); // Neither half: nothing to route, so any id will do as long as it is ours. let publish = crate::origin::Info::new(ours).produce(); - assert_eq!(self_hop(Some(&publish.consume()), Some(&subscribe)), ours); + assert_eq!(self_origin(Some(&publish.consume()), Some(&subscribe)), ours); } /// Drive `start` against a peer whose incoming streams die before their first diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 528b5b9755b..b6e9e581bb6 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -182,52 +182,26 @@ enum Detach { } struct BroadcastState { - // The source feeding this broadcast into our origin: finish() on a - // deliberate unannounce, dropping (a dying session) aborts it. Either way - // the origin unannounces once the last source detaches. - producer: crate::model::broadcast::SourceGuard, + // The route announced into our origin for this namespace, post-charge. + route: crate::origin::Route, + + // The live advertisement; dropping it retracts the route. + announcement: crate::announce::Producer, // active number of PUBLISH_NAMESPACE messages. count: usize, - // The first entry of the advertised path: the original publisher. `None` on an - // advertisement that carried no path at all, which is every one on a session - // without the MoQ Cluster extension. See [`Advertised::publisher`]. - publisher: Option, + // One minted source per requested path under the namespace: finish() on a + // deliberate unannounce, dropping (a dying session) aborts them so viewers + // observe the loss as an error. + sources: HashMap, } /// What one advertisement said, once its parameters are resolved against the session. struct Advertised { - /// The route it describes, with this link's price already charged. - route: broadcast::Route, - - /// The original publisher: the first entry of HOP_PATH. Two advertisements that - /// share a non-zero one carry interchangeable content, so a new path splices in. - /// A different one, or `Some(Hop::UNKNOWN)` (which identifies nothing), is a - /// distinct publisher reusing the namespace and must not splice. That comparison - /// only applies between separate advertisements; see [`Arrival`]. - /// - /// `None` when the advertisement carried no path, so there is no identity to - /// compare and nothing ever replaces the source on identity grounds. That covers - /// base moq-transport entirely: PUBLISH_NAMESPACE and NAMESPACE for one namespace - /// are then two messages describing a single source, not two publishers. - publisher: Option, -} - -/// How an advertisement relates to whatever already holds the path. -#[derive(Clone, Copy, PartialEq, Eq)] -enum Arrival { - /// A separate advertisement for a path another one already holds: a - /// PUBLISH_NAMESPACE alongside a NAMESPACE. Nothing links the two but the publisher - /// identity, so only a matching, real one proves they carry the same content. - Separate, - - /// A repeat of the advertisement already holding the path, on the stream that - /// carries it. That stream is the continuity: the peer never retracted the - /// advertisement, so only a *changed* publisher is a new publisher. The expected - /// repeat is a repricing, and a peer that withholds its identity reprices as often - /// as any other. - Repeat, + /// The route it describes, with this link's price already charged. The prefix + /// is stamped where the advertisement attaches (the namespace). + route: crate::origin::Route, } #[derive(Clone)] @@ -250,10 +224,10 @@ pub(super) struct Subscriber, peer_setup: peer::PeerSetup, - self_hop: crate::Hop, + self_origin: crate::Hop, cost: Option, version: Version, tasks: Tasks, @@ -324,8 +298,8 @@ where session, origin, control, - session_hop: peer_hop.unwrap_or(crate::Hop::UNKNOWN), - self_hop, + session_origin: peer_hop.unwrap_or(crate::Hop::UNKNOWN), + self_origin, peer_setup, cost, state: Default::default(), @@ -367,16 +341,15 @@ where /// its true length and can out-rank a longer-looking but genuinely shorter one. /// Price such a link with [`crate::Client::with_cost`] rather than trusting the /// default. - fn session_route(&self, peer: &cluster::Peer) -> broadcast::Route { + fn session_route(&self, peer: &cluster::Peer) -> crate::origin::Route { let mut hops = crate::Hops::new(); - hops.push(self.session_hop) + hops.push(self.session_origin) .expect("an empty hop chain has room for one entry"); - broadcast::Route::new() + crate::origin::Route::default() .with_hops(hops) // A peer with no Cluster extension advertises no cost at all, so its cold // path is unknown rather than free. - .with_cost(broadcast::Cost::UNKNOWN.charged(cluster::link_cost(self.cost, peer))) - .with_announce(true) + .with_cost(crate::origin::Cost::UNKNOWN.charged(cluster::link_cost(self.cost, peer))) } /// The route an advertisement describes, or `None` when it must be discarded. @@ -389,17 +362,15 @@ where let Some(advert) = advert else { return Some(Advertised { route: self.session_route(peer), - publisher: None, }); }; - if advert.loops(self.self_hop) { + if advert.loops(self.self_origin) { return None; } Some(Advertised { route: advert.route(cluster::link_cost(self.cost, peer)), - publisher: Some(advert.hops.hops().iter().next().copied().unwrap_or(crate::Hop::UNKNOWN)), }) } @@ -1032,125 +1003,80 @@ where Ok(()) } - /// Attach a source for one newly advertised path, bumping its refcount. + /// Attach the route for one newly advertised namespace, bumping its refcount. /// - /// `route` is what the advertisement described (see [`Self::route`]), or `None` for - /// a PUBLISH, which carries no path of its own and must not flatten the route an - /// advertisement already set. Pair with [`Self::stop_announce`]. - fn start_announce(&mut self, path: PathOwned, advert: Advertised) -> Result { + /// Pair with [`Self::stop_announce`]. + fn start_announce(&mut self, path: PathOwned, advert: Advertised) -> Result<(), Error> { let mut state = self.state.lock(); let existing = state.broadcasts.contains_key(&path); - let producer = self.attach(&mut state, path.clone(), advert, Arrival::Separate)?; + self.attach(&mut state, path.clone(), advert)?; if existing && let Some(entry) = state.broadcasts.get_mut(&path) { - // The path was already attached, so this is one more advertisement for it. - // A replacement carries the previous count forward, so the increment still - // applies; only a freshly created entry starts at one and skips this. + // The path was already attached, so this is one more advertisement for + // it; only a freshly created entry starts at one and skips this. entry.count += 1; } - Ok(producer) + Ok(()) } - /// Apply a changed advertisement to a path that is already attached. + /// Apply a changed advertisement to a namespace that is already attached. /// - /// An update replaces the advertisement atomically: the refcount does not move, and - /// no subscription is torn down merely because one arrived. A changed original - /// publisher is the exception, since that content is not interchangeable. + /// An update replaces the advertisement atomically: the refcount does not move, + /// and no subscription is torn down merely because one arrived. fn update_announce(&mut self, path: PathOwned, advert: Advertised) -> Result<(), Error> { let mut state = self.state.lock(); if !state.broadcasts.contains_key(&path) { return Err(Error::NotFound); } - self.attach(&mut state, path, advert, Arrival::Repeat)?; + self.attach(&mut state, path, advert)?; Ok(()) } - /// Create or update the source for one path, leaving the refcount to the caller. + /// Create or update the announced route for one namespace, leaving the + /// refcount to the caller. /// - /// The ingress announce stats (announced / announced_bytes) are driven in the model - /// by `create_broadcast`'s route transitions below. - fn attach( - &self, - state: &mut State, - path: PathOwned, - advert: Advertised, - arrival: Arrival, - ) -> Result { - let Advertised { mut route, publisher } = advert; + /// This is the semantic heart of the mapping: a moq-transport namespace IS a + /// prefix route, so a PUBLISH_NAMESPACE advertises the whole prefix and paths + /// beneath it materialize on demand. + fn attach(&self, state: &mut State, path: PathOwned, advert: Advertised) -> Result<(), Error> { + let Advertised { mut route } = advert; // A namespace published after the peer's GOAWAY starts out draining, so - // a late arrival on a dying connection can't take over as primary. The - // per-source task only ever moves a route in this direction, so there is - // no race between the two. + // a late arrival on a dying connection can't take over as primary. if self.going_away.is_set() { - route.cost = broadcast::Cost::DRAIN; - } - - // A different original publisher means a distinct broadcast has taken over this - // namespace. Its content is not interchangeable, so detach the old source and - // attach fresh instead of splicing the route in place; cached tracks and - // subscriptions must not carry over. The refcount rides along: the same - // advertisements still reference this path. - // - // Both sides must be known for the comparison to mean anything. A session - // without the MoQ Cluster extension has no identity on either, so nothing ever - // replaces there: its PUBLISH_NAMESPACE and NAMESPACE for one namespace are two - // messages about a single source, and replacing on the second would tear down - // what the first attached. - let mut carried = None; - if let Entry::Occupied(entry) = state.broadcasts.entry(path.clone()) - && let (Some(old), Some(new)) = (entry.get().publisher, publisher) - && match arrival { - // Two advertisements, so identity is the only link between them and - // UNKNOWN is no link at all: unrelated publishers all present the same - // one. Take the later as replacing the earlier. - Arrival::Separate => old != new || new == crate::Hop::UNKNOWN, - // One advertisement, repeated on the stream that carries it. Continuity - // is the stream, not the identity, so an unchanged UNKNOWN stays put; a - // peer that never named itself would otherwise lose every subscription - // each time it repriced. - Arrival::Repeat => old != new, - } { - tracing::debug!(broadcast = %self.origin.absolute(&path), "publisher changed; replacing the source"); - carried = Some(entry.get().count); - entry.remove().producer.finish(); + route.cost = crate::origin::Cost::DRAIN; } match state.broadcasts.entry(path.clone()) { Entry::Occupied(entry) => { - let mut producer = entry.get().producer.producer(); - producer.set_route(route)?; - Ok(producer) + // A repeat is a repricing: update the route in place. In-flight + // tracks keep flowing. + let entry = entry.into_mut(); + entry.route = route.clone(); + entry.announcement.update(route)?; + Ok(()) } Entry::Vacant(entry) => { - // Propagates Error::Unauthorized if the path is out of scope. - let broadcast = self.origin.create_broadcast(&path, route)?; - - // Register the dynamic handler synchronously: the broadcast only - // becomes visible to consumers after this function returns to the - // executor, so the origin's first track dispatch finds a handler - // (mirrors the note in lite::Subscriber). - let dynamic = broadcast.dynamic(); + // Propagates Error::Unauthorized if the namespace is out of scope. + let (announcement, server) = self.origin.announce_served(&path, route.clone())?; entry.insert(BroadcastState { - producer: crate::model::broadcast::SourceGuard::new(broadcast.clone()), - count: carried.unwrap_or(1), - publisher, + route, + announcement, + count: 1, + sources: HashMap::new(), }); - tracing::debug!(broadcast = %self.origin.absolute(&path), "announce"); + tracing::debug!(route = %self.origin.absolute(&path), "announce"); let this = self.clone(); self.tasks.push(async move { - // stop_announce is the authoritative remover: it drops the entry (and - // its producer) once the announce refcount hits zero, which is what - // makes run_broadcast exit. Removing here too would let a stale task - // delete a freshly re-announced entry for the same path. - if let Err(err) = this.run_broadcast(path, dynamic).await { - tracing::debug!(%err, "error running broadcast"); - } + // stop_announce is the authoritative remover: it drops the entry + // (retracting the route) once the announce refcount hits zero, + // which is what makes run_route exit. + this.run_route(path, server).await; }); - Ok(broadcast) + Ok(()) } } } @@ -1162,13 +1088,16 @@ where Entry::Occupied(mut entry) => { entry.get_mut().count -= 1; if entry.get().count == 0 { - tracing::debug!(broadcast = %self.origin.absolute(&path), ?detach, "unannounced"); - let producer = entry.remove().producer; - match detach { - Detach::Graceful => producer.finish(), - // Dropping the guard aborts the source, so the loss reads as an - // error rather than a clean end. - Detach::Abrupt => drop(producer), + tracing::debug!(route = %self.origin.absolute(&path), ?detach, "unannounced"); + // Dropping the entry retracts the route (its announcement drops). + let removed = entry.remove(); + for (_, source) in removed.sources { + match detach { + Detach::Graceful => source.finish(), + // Dropping the guard aborts the source, so the loss reads + // as an error rather than a clean end. + Detach::Abrupt => {} + } } } } @@ -1178,6 +1107,82 @@ where Ok(()) } + /// Serve materialization requests for one announced namespace: mint a source + /// per requested path and serve its track requests until the route is + /// retracted or the session dies. + async fn run_route(&self, path: PathOwned, mut server: crate::model::RouteServer) { + let mut broadcasts = TaskSet::owned(); + let mut closed_session = self.session.clone(); + loop { + let next = broadcasts + .drive(|waiter| { + let mut cx = std::task::Context::from_waker(waiter.waker()); + if closed_session.poll_closed(&mut cx).is_ready() { + return Poll::Ready(None); + } + // A draining peer usually stops publishing namespaces, so react + // to the GOAWAY itself; waiting for another message would leave + // the route primary until the session finally closed. + // Idempotent, since the signal stays set. + if self.going_away.poll(waiter).is_ready() { + self.drain_route(&path); + } + server.poll_requested_broadcast(waiter).map(Some) + }) + .await; + + let request = match next { + Some(Ok(request)) => request, + // Retracted or torn down: no request will ever arrive again. + Some(Err(_)) | None => break, + }; + + // The request path is absolute; the wire (and our origin handle) speak + // paths relative to the session's root. + let requested = match request.path().strip_prefix(self.origin.root()) { + Some(requested) => requested.to_owned(), + None => continue, + }; + let source = self.origin.create_source(&requested); + let dynamic = source.dynamic(); + request.accept(&source); + + // Retain the source so a retraction can finish it. If the route was + // retracted since, the guard drops here and consumers observe the abort. + { + let mut state = self.state.lock(); + let Some(entry) = state.broadcasts.get_mut(&path) else { + continue; + }; + entry + .sources + .insert(requested.clone(), crate::model::broadcast::SourceGuard::new(source)); + } + + let this = self.clone(); + broadcasts.push(async move { + if let Err(err) = this.run_broadcast(requested.borrow(), dynamic).await { + tracing::debug!(%err, "error running broadcast"); + } + }); + } + } + + /// Re-price one attached route to a draining cost (the peer sent a GOAWAY): + /// every other candidate outranks it while it stays selectable as the last + /// path. Idempotent, since the signal stays set. + fn drain_route(&self, path: &PathOwned) { + let mut state = self.state.lock(); + let Some(entry) = state.broadcasts.get_mut(path) else { + return; + }; + if entry.route.cost == crate::origin::Cost::DRAIN { + return; + } + entry.route.cost = crate::origin::Cost::DRAIN; + let _ = entry.announcement.update(entry.route.clone()); + } + async fn run_broadcast(&self, path: Path<'_>, mut broadcast: broadcast::Dynamic) -> Result<(), Error> { let mut subscribes = TaskSet::owned(); let mut closed_session = self.session.clone(); @@ -1188,13 +1193,6 @@ where if closed_session.poll_closed(&mut cx).is_ready() { return Poll::Ready(None); } - // A draining peer usually stops publishing namespaces, so react to - // the signal itself; waiting for another message would leave the - // route primary until the session finally closed. Idempotent, since - // the signal stays set and this task wakes for other reasons too. - if self.going_away.poll(waiter).is_ready() { - broadcast.drain(); - } broadcast.poll_requested_track(waiter).map(Some) }) .await; @@ -1990,18 +1988,18 @@ mod tests { // and errors here, which the assertions below name far better than a poll // would. let _ = futures::poll!(run.as_mut()); - if consumer.get_broadcast("rootns/cam/x.hang").is_some() { + if routed_now(&consumer, "rootns/cam/x.hang").is_some() { break; } settle().await; } assert!( - consumer.get_broadcast("rootns/cam/x.hang").is_some(), + routed_now(&consumer, "rootns/cam/x.hang").is_some(), "the reply mounts under the root once", ); assert!( - consumer.get_broadcast("rootns/rootns/cam/x.hang").is_none(), + routed_now(&consumer, "rootns/rootns/cam/x.hang").is_none(), "the root was applied twice", ); } @@ -2648,15 +2646,13 @@ mod tests { ); let advert = subscriber.route(None, &cluster::Peer::default()).expect("route"); - let _producer = subscriber + subscriber .start_announce(crate::Path::new("room/host").to_owned(), advert) .unwrap(); - // Broadcast visibility is deferred until the executor ticks. - tokio::time::sleep(Duration::from_millis(1)).await; - - let broadcast = consumer.get_broadcast("room/host").unwrap(); - let hops: Vec<_> = broadcast.routes()[0].hops.iter().copied().collect(); + let mut announced = consumer.announced(); + let route = announced.assert_next_active("room/host"); + let hops: Vec<_> = route.hops.iter().copied().collect(); assert_eq!(hops, vec![assigned]); } @@ -2670,9 +2666,9 @@ mod tests { async fn reflected_announce_does_not_evict_the_source_we_publish() { let session = crate::lite::test_transport::SinkSession::new(Default::default()); let peer = crate::Hop::new(777).unwrap(); - let self_hop = crate::Hop::new(1).unwrap(); + let self_origin = crate::Hop::new(1).unwrap(); - let origin = crate::origin::Info::new(self_hop).produce(); + let origin = crate::origin::Info::new(self_origin).produce(); let consumer = origin.consume(); let mut announced = consumer.announced(); @@ -2681,21 +2677,13 @@ mod tests { // is what records that the peer has been offered these paths. let mut publishing = consumer.clone().excluding(peer).announced(); - // What we are publishing to the peer: a real upstream, announced. + // What we are publishing to the peer: a real upstream route. let upstream = crate::Hops::try_from(vec![crate::Hop::new(7).unwrap()]).unwrap(); let _source = origin - .create_broadcast( - "room/host", - crate::broadcast::Route::new() - .with_hops(upstream.clone()) - .with_announce(true), - ) + .announce("room/host", crate::origin::Route::default().with_hops(upstream.clone())) .unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - announced.assert_next_some("room/host"); - // Held for as long as the path is advertised, exactly as the publisher holds - // it in its `Watched` entry. The exclusion lives on this handle. - let _advertised = publishing.assert_next_some("room/host"); + announced.assert_next_active("room/host"); + let _advertised = publishing.assert_next_active("room/host"); // The peer reflects it back over the subscribe direction, which carries no // hop chain of its own. @@ -2707,25 +2695,22 @@ mod tests { Control::new(None, false), Some(peer), peer::PeerSetup::default(), - self_hop, + self_origin, None, Version::Draft14, tasks, Default::default(), ); let advert = subscriber.route(None, &cluster::Peer::default()).expect("route"); - let _reflected = subscriber + subscriber .start_announce(crate::Path::new("room/host").to_owned(), advert) .unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - // No announce churn, and the path still resolves to the upstream route, which - // is the one the publish direction can advertise back to the peer. + // No announce churn: the upstream route stays the best one, on both cursors. announced.assert_next_wait(); - let broadcast = consumer.get_broadcast("room/host").unwrap(); - let routes = broadcast.routes(); - assert_eq!(routes.len(), 1, "the reflection must park, not attach"); - assert_eq!(routes[0].hops, upstream); + publishing.assert_next_wait(); + let route = routed_now(&consumer, "room/host").expect("still routed"); + assert_eq!(route.hops, upstream); } /// The assigned identity is a content identity too, so a second session dialing @@ -2736,9 +2721,9 @@ mod tests { #[tokio::test] async fn reconnecting_peer_joins_the_front_it_replaces() { let peer = crate::Hop::new(777).unwrap(); - let self_hop = crate::Hop::new(1).unwrap(); + let self_origin = crate::Hop::new(1).unwrap(); - let origin = crate::origin::Info::new(self_hop).produce(); + let origin = crate::origin::Info::new(self_origin).produce(); let consumer = origin.consume(); let mut announced = consumer.announced(); @@ -2752,42 +2737,41 @@ mod tests { Control::new(None, false), Some(peer), peer::PeerSetup::default(), - self_hop, + self_origin, None, Version::Draft14, tasks, Default::default(), ); let advert = subscriber.route(None, &cluster::Peer::default()).expect("route"); - let producer = subscriber + subscriber .start_announce(crate::Path::new("room/host").to_owned(), advert) .unwrap(); - (subscriber, producer) + subscriber }; - let _first = connect(); - tokio::time::sleep(Duration::from_millis(1)).await; - announced.assert_next_some("room/host"); + let first = connect(); + announced.assert_next_active("room/host"); - // The peer reconnects before the old session is retired. + // The peer reconnects before the old session is retired: an identical route + // from the fresh session joins without any consumer-visible churn. let _second = connect(); - tokio::time::sleep(Duration::from_millis(1)).await; + announced.assert_next_wait(); - // It joined: no announce churn, and both routes are in the table so the front - // can fail over the moment the stale one dies. + // The stale session finally retracting leaves the fresh route standing. + drop(first); announced.assert_next_wait(); - let routes = consumer.get_broadcast("room/host").unwrap().routes(); - assert_eq!(routes.len(), 2, "a reconnect must join, not park or replace"); + assert!(routed_now(&consumer, "room/host").is_some()); } fn cluster_subscriber( - self_hop: crate::Hop, + self_origin: crate::Hop, ) -> ( Subscriber, crate::origin::Producer, ) { let session = crate::lite::test_transport::SinkSession::new(Default::default()); - let origin = crate::origin::Info::new(self_hop).produce(); + let origin = crate::origin::Info::new(self_origin).produce(); let (tasks, task_set) = crate::util::TaskSet::new(); // The set only drains announce-serving tasks; the tests here drive the model // directly, so leaking it keeps the handles alive without a spawner. @@ -2800,7 +2784,7 @@ mod tests { Control::new(None, false), None, peer::PeerSetup::default(), - self_hop, + self_origin, None, Version::Draft19, tasks, @@ -2809,6 +2793,12 @@ mod tests { (subscriber, origin) } + /// The current best route covering `path`, if any (synchronous peek). + fn routed_now(consumer: &crate::origin::Consumer, path: &str) -> Option { + use futures::FutureExt; + consumer.routed(path).now_or_never().flatten() + } + fn hop_path(ids: &[u64]) -> cluster::HopPath { let hops = ids.iter().map(|&id| crate::Hop::new(id).unwrap()).collect::>(); cluster::HopPath::new(crate::Hops::try_from(hops).unwrap()) @@ -2837,19 +2827,16 @@ mod tests { "the link's price is added to the advertised cost" ); assert_eq!(advertised.route.hops, hop_path(&[7, 9]).hops().clone()); - assert!(advertised.route.announce); - assert_eq!(advertised.publisher, Some(crate::Hop::new(7).unwrap())); let mut subscriber = subscriber; subscriber .start_announce(crate::Path::new("room/host").to_owned(), advertised) .unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - let broadcast = consumer.get_broadcast("room/host").unwrap(); - let hops: Vec<_> = broadcast.routes()[0].hops.iter().map(|h| h.id()).collect(); + let route = routed_now(&consumer, "room/host").expect("routed"); + let hops: Vec<_> = route.hops.iter().map(|h| h.id()).collect(); assert_eq!(hops, vec![7, 9]); - assert_eq!(broadcast.routes()[0].cost.warm, 7); + assert_eq!(route.cost.warm, 7); } /// An advertisement whose path already contains our own Hop ID looped back: @@ -2945,8 +2932,8 @@ mod tests { settle().await; assert!( - consumer.get_broadcast("x.hang").is_none(), - "an ended stream must close the broadcast, not leave a stale route", + routed_now(&consumer, "x.hang").is_none(), + "an ended stream must retract the route, not leave a stale one", ); } @@ -2963,10 +2950,9 @@ mod tests { settle().await; subscriber.stop_announce(path, Detach::Graceful).unwrap(); - settle().await; assert!( - consumer.get_broadcast("room/host").is_none(), - "an explicit NAMESPACE_DONE must close the broadcast", + routed_now(&consumer, "room/host").is_none(), + "an explicit NAMESPACE_DONE must retract the route", ); } @@ -3021,7 +3007,7 @@ mod tests { settle().await; assert!( - consumer.get_broadcast("room/host").is_none(), + routed_now(&consumer, "room/host").is_none(), "an explicit withdrawal must close the broadcast", ); } @@ -3077,7 +3063,7 @@ mod tests { settle().await; assert!( - consumer.get_broadcast("room/host").is_none(), + routed_now(&consumer, "room/host").is_none(), "a broken stream must close the broadcast, not leave a stale route", ); } @@ -3107,7 +3093,7 @@ mod tests { subscriber.stop_announce(path.clone(), Detach::Abrupt).unwrap(); settle().await; assert!( - consumer.get_broadcast("room/host").is_some(), + routed_now(&consumer, "room/host").is_some(), "the broadcast must survive while an owner remains", ); @@ -3115,7 +3101,7 @@ mod tests { subscriber.stop_announce(path, Detach::Graceful).unwrap(); settle().await; assert!( - consumer.get_broadcast("room/host").is_none(), + routed_now(&consumer, "room/host").is_none(), "the last owner out must close the broadcast", ); } @@ -3156,82 +3142,31 @@ mod tests { let consumer = origin.consume(); let path = crate::Path::new("room/host").to_owned(); - let first = crate::broadcast::Route::new() - .with_hops(hop_path(&[7, 9]).hops().clone()) - .with_cost(4) - .with_announce(true); let first = Advertised { - route: first, - publisher: Some(crate::Hop::new(7).unwrap()), + route: crate::origin::Route::default() + .with_hops(hop_path(&[7, 9]).hops().clone()) + .with_cost(4), }; subscriber.start_announce(path.clone(), first).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - let original = consumer.get_broadcast("room/host").unwrap(); + assert!(routed_now(&consumer, "room/host").is_some()); - // Same publisher (hop 7), new path and cost: the route updates in place. - let rerouted = crate::broadcast::Route::new() - .with_hops(hop_path(&[7, 11]).hops().clone()) - .with_cost(2) - .with_announce(true); + // A new chain and cost: the route updates in place. let rerouted = Advertised { - route: rerouted, - publisher: Some(crate::Hop::new(7).unwrap()), + route: crate::origin::Route::default() + .with_hops(hop_path(&[7, 11]).hops().clone()) + .with_cost(2), }; subscriber.update_announce(path.clone(), rerouted).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - let broadcast = consumer.get_broadcast("room/host").unwrap(); - let hops: Vec<_> = broadcast.routes()[0].hops.iter().map(|h| h.id()).collect(); + let route = routed_now(&consumer, "room/host").expect("routed"); + let hops: Vec<_> = route.hops.iter().map(|h| h.id()).collect(); assert_eq!(hops, vec![7, 11]); - assert_eq!(broadcast.routes()[0].cost.warm, 2); - assert!(!original.is_closed(), "the source survived the update"); + assert_eq!(route.cost.warm, 2); // One advertisement, so one unannounce detaches it. If the update had bumped the - // refcount, this would leave the source stranded. - subscriber.stop_announce(path, Detach::Graceful).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - assert!(consumer.get_broadcast("room/host").is_none()); - } - - /// A different original publisher is not interchangeable content, so the source is - /// replaced rather than spliced. The refcount rides along: the same advertisements - /// still reference the path. - #[tokio::test] - async fn cluster_publisher_change_replaces_the_source() { - let (mut subscriber, origin) = cluster_subscriber(crate::Hop::new(1).unwrap()); - let consumer = origin.consume(); - let path = crate::Path::new("room/host").to_owned(); - - let first = crate::broadcast::Route::new() - .with_hops(hop_path(&[7, 9]).hops().clone()) - .with_announce(true); - let first = Advertised { - route: first, - publisher: Some(crate::Hop::new(7).unwrap()), - }; - subscriber.start_announce(path.clone(), first).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - let original = consumer.get_broadcast("room/host").unwrap(); - - let taken_over = crate::broadcast::Route::new() - .with_hops(hop_path(&[8, 9]).hops().clone()) - .with_announce(true); - let taken_over = Advertised { - route: taken_over, - publisher: Some(crate::Hop::new(8).unwrap()), - }; - subscriber.update_announce(path.clone(), taken_over).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - - assert!(original.is_closed(), "the old source was detached"); - let broadcast = consumer.get_broadcast("room/host").unwrap(); - let hops: Vec<_> = broadcast.routes()[0].hops.iter().map(|h| h.id()).collect(); - assert_eq!(hops, vec![8, 9]); - - // Still one advertisement, so one unannounce is all it takes. + // refcount, this would leave the route stranded. subscriber.stop_announce(path, Detach::Graceful).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - assert!(consumer.get_broadcast("room/host").is_none()); + assert!(routed_now(&consumer, "room/host").is_none()); } /// Regression: a publisher that declares no identity of its own contributes @@ -3263,49 +3198,34 @@ mod tests { &peer, ) .expect("route"); - assert_eq!( - advertised.publisher, - Some(crate::Hop::UNKNOWN), - "an anonymous publisher has no identity to carry", - ); subscriber.start_announce(path.clone(), advertised).unwrap(); - tokio::time::sleep(std::time::Duration::from_millis(1)).await; - let original = consumer.get_broadcast("room/host").unwrap(); + assert!(routed_now(&consumer, "room/host").is_some()); // The peer re-advertises the same path cheaper: it started carrying it. let repriced = subscriber .route(Some(&cluster::Advert { hops, cost: 1 }), &peer) .expect("route"); subscriber.update_announce(path.clone(), repriced).unwrap(); - tokio::time::sleep(std::time::Duration::from_millis(1)).await; - assert!( - !original.is_closed(), - "a repricing update must not tear down the source" - ); - let broadcast = consumer.get_broadcast("room/host").unwrap(); - let routes = broadcast.routes(); - assert_eq!(routes.len(), 1, "the update replaced the route, it did not add one"); + let route = routed_now(&consumer, "room/host").expect("still routed"); assert_eq!( - routes[0].cost, - crate::broadcast::Cost { + route.cost, + crate::origin::Cost { warm: 1, - ..crate::broadcast::Cost::UNKNOWN + ..crate::origin::Cost::UNKNOWN }, "the repriced warm cost arrives; the Cluster extension has nowhere to carry a cold cost, so it stays unknown rather than reading as the publisher's own zero" ); // One advertisement, so one unannounce detaches it. subscriber.stop_announce(path, Detach::Graceful).unwrap(); - tokio::time::sleep(std::time::Duration::from_millis(1)).await; - assert!(consumer.get_broadcast("room/host").is_none()); + assert!(routed_now(&consumer, "room/host").is_none()); } - /// Two *separate* advertisements have nothing linking them but the publisher, and - /// `Hop::UNKNOWN` links nothing: any number of unrelated publishers present it. - /// So the later one replaces the earlier, unlike the repeat above. + /// Two *separate* advertisements for one namespace refcount a single route: + /// it takes both retractions to retract it. #[tokio::test(start_paused = true)] - async fn separate_anonymous_adverts_replace_the_source() { + async fn separate_adverts_refcount_the_route() { let (mut subscriber, origin) = cluster_subscriber(crate::Hop::new(1).unwrap()); let consumer = origin.consume(); let path = crate::Path::new("room/host").to_owned(); @@ -3320,23 +3240,17 @@ mod tests { let first = subscriber.route(Some(&advert), &peer).expect("route"); subscriber.start_announce(path.clone(), first).unwrap(); - tokio::time::sleep(std::time::Duration::from_millis(1)).await; - let original = consumer.get_broadcast("room/host").unwrap(); + assert!(routed_now(&consumer, "room/host").is_some()); let second = subscriber.route(Some(&advert), &peer).expect("route"); subscriber.start_announce(path.clone(), second).unwrap(); - tokio::time::sleep(std::time::Duration::from_millis(1)).await; - - assert!(original.is_closed(), "the old source was detached"); - assert!(consumer.get_broadcast("room/host").is_some()); + assert!(routed_now(&consumer, "room/host").is_some()); - // Two advertisements, so it takes two unannounces to detach. + // Two advertisements, so it takes two unannounces to retract. subscriber.stop_announce(path.clone(), Detach::Graceful).unwrap(); - tokio::time::sleep(std::time::Duration::from_millis(1)).await; - assert!(consumer.get_broadcast("room/host").is_some()); + assert!(routed_now(&consumer, "room/host").is_some()); subscriber.stop_announce(path, Detach::Graceful).unwrap(); - tokio::time::sleep(std::time::Duration::from_millis(1)).await; - assert!(consumer.get_broadcast("room/host").is_none()); + assert!(routed_now(&consumer, "room/host").is_none()); } /// Regression: without the MoQ Cluster extension an advertisement carries no path, @@ -3353,26 +3267,19 @@ mod tests { // What a PUBLISH_NAMESPACE with no cluster parameters resolves to. let first = subscriber.route(None, &peer).expect("route"); - assert_eq!(first.publisher, None, "no path means no identity to compare"); subscriber.start_announce(path.clone(), first).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - let original = consumer.get_broadcast("room/host").unwrap(); + assert!(routed_now(&consumer, "room/host").is_some()); // The NAMESPACE for the same namespace arrives second. let second = subscriber.route(None, &peer).expect("route"); subscriber.start_announce(path.clone(), second).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - - assert!(!original.is_closed(), "the source survived the second advertisement"); - assert!(consumer.get_broadcast("room/host").is_some()); + assert!(routed_now(&consumer, "room/host").is_some()); - // Two advertisements, so it takes two unannounces to detach. + // Two advertisements, so it takes two unannounces to retract. subscriber.stop_announce(path.clone(), Detach::Graceful).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - assert!(consumer.get_broadcast("room/host").is_some()); + assert!(routed_now(&consumer, "room/host").is_some()); subscriber.stop_announce(path, Detach::Graceful).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - assert!(consumer.get_broadcast("room/host").is_none()); + assert!(routed_now(&consumer, "room/host").is_none()); } /// An update replaces the advertisement it repeats. When the replacement loops back @@ -3380,8 +3287,8 @@ mod tests { /// would leave subscriptions on a path the peer no longer offers. #[tokio::test] async fn reflected_replacement_retracts_the_route() { - let self_hop = crate::Hop::new(5).unwrap(); - let (mut subscriber, origin) = cluster_subscriber(self_hop); + let self_origin = crate::Hop::new(5).unwrap(); + let (mut subscriber, origin) = cluster_subscriber(self_origin); let consumer = origin.consume(); let path = crate::Path::new("room/host").to_owned(); let peer = cluster::Peer { @@ -3395,8 +3302,7 @@ mod tests { }; let advert = subscriber.route(Some(&clean), &peer).expect("route"); subscriber.start_announce(path.clone(), advert).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - assert!(consumer.get_broadcast("room/host").is_some()); + assert!(routed_now(&consumer, "room/host").is_some()); // The peer re-advertises the namespace over a path that now flows through us. let looped = cluster::Advert { @@ -3410,9 +3316,8 @@ mod tests { // That supersedes the advertisement it repeats, so the old route is retired. subscriber.stop_announce(path, Detach::Graceful).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; assert!( - consumer.get_broadcast("room/host").is_none(), + routed_now(&consumer, "room/host").is_none(), "the superseded route must not stay attached" ); } @@ -3447,7 +3352,7 @@ mod tests { /// Build a subscriber whose peer replays `updates` on one PUBLISH_NAMESPACE stream, /// with the advertisement already attached. async fn reflected_harness( - self_hop: crate::Hop, + self_origin: crate::Hop, request_id: RequestId, peer: &cluster::Peer, attached: &cluster::Advert, @@ -3460,7 +3365,7 @@ mod tests { const VERSION: Version = Version::Draft19; let script = publish_namespace_updates(request_id, "room/host", updates).await; let session = crate::lite::test_transport::ScriptedSession::new(script); - let origin = crate::origin::Info::new(self_hop).produce(); + let origin = crate::origin::Info::new(self_origin).produce(); let consumer = origin.consume(); let (tasks, task_set) = crate::util::TaskSet::new(); // The tests drive the loop directly, so nothing spawns; leaking keeps the @@ -3474,7 +3379,7 @@ mod tests { Control::new(None, false), None, peer::PeerSetup::default(), - self_hop, + self_origin, None, VERSION, tasks, @@ -3484,8 +3389,7 @@ mod tests { let path = crate::Path::new("room/host").to_owned(); let advert = subscriber.route(Some(attached), peer).expect("route"); subscriber.start_announce(path, advert).unwrap(); - settle().await; - assert!(consumer.get_broadcast("room/host").is_some(), "attached to start with"); + assert!(routed_now(&consumer, "room/host").is_some(), "attached to start with"); let stream = Stream::open(&mut session.clone(), VERSION).await.unwrap(); (subscriber, consumer, stream) @@ -3519,13 +3423,13 @@ mod tests { /// sibling shares it, which the draft answers with "discard", not PROTOCOL_VIOLATION. #[tokio::test] async fn a_reflected_update_detaches_but_keeps_the_stream() { - let self_hop = crate::Hop::new(5).unwrap(); + let self_origin = crate::Hop::new(5).unwrap(); let request_id = RequestId(1); let peer = peer_9(); let (clean, looped) = clean_and_looped(); let (mut subscriber, consumer, mut stream) = - reflected_harness(self_hop, request_id, &peer, &clean, &[Some(looped)]).await; + reflected_harness(self_origin, request_id, &peer, &clean, &[Some(looped)]).await; let path = crate::Path::new("room/host").to_owned(); let mut attached = true; @@ -3543,7 +3447,7 @@ mod tests { futures::poll!(run.as_mut()).is_pending(), "the stream must stay open after a reflected update" ); - if consumer.get_broadcast("room/host").is_none() { + if routed_now(&consumer, "room/host").is_none() { break; } settle().await; @@ -3551,7 +3455,7 @@ mod tests { } assert!( - consumer.get_broadcast("room/host").is_none(), + routed_now(&consumer, "room/host").is_none(), "an unusable path must not stay attached" ); assert!(!attached, "the caller must not release it a second time"); @@ -3561,13 +3465,13 @@ mod tests { /// reason the stream stays open. #[tokio::test] async fn a_clean_update_after_a_reflection_reattaches() { - let self_hop = crate::Hop::new(5).unwrap(); + let self_origin = crate::Hop::new(5).unwrap(); let request_id = RequestId(1); let peer = peer_9(); let (clean, looped) = clean_and_looped(); let (mut subscriber, consumer, mut stream) = reflected_harness( - self_hop, + self_origin, request_id, &peer, &clean, @@ -3598,7 +3502,7 @@ mod tests { assert!(attached, "the clean path must re-attach"); assert!( - consumer.get_broadcast("room/host").is_some(), + routed_now(&consumer, "room/host").is_some(), "the namespace is routable again", ); } @@ -3620,18 +3524,16 @@ mod tests { subscriber.start_announce(path.clone(), advert).unwrap(); live.insert(path); } - tokio::time::sleep(Duration::from_millis(1)).await; - assert!(consumer.get_broadcast("room/a").is_some()); - assert!(consumer.get_broadcast("room/b").is_some()); + assert!(routed_now(&consumer, "room/a").is_some()); + assert!(routed_now(&consumer, "room/b").is_some()); // What the stream's exit path does with whatever it still holds. for path in live { subscriber.stop_announce(path, Detach::Graceful).unwrap(); } - tokio::time::sleep(Duration::from_millis(1)).await; - assert!(consumer.get_broadcast("room/a").is_none(), "room/a leaked a refcount"); - assert!(consumer.get_broadcast("room/b").is_none(), "room/b leaked a refcount"); + assert!(routed_now(&consumer, "room/a").is_none(), "room/a leaked a refcount"); + assert!(routed_now(&consumer, "room/b").is_none(), "room/b leaked a refcount"); } /// PUBLISH offers one track, but a source attaches per namespace and serves every @@ -3677,7 +3579,7 @@ mod tests { tokio::time::sleep(Duration::from_millis(1)).await; assert!( - consumer.get_broadcast("room/host").is_none(), + routed_now(&consumer, "room/host").is_none(), "a rejected PUBLISH must not announce a broadcast" ); // Encode the reply we expect rather than matching the reason alone, so the error code diff --git a/rs/moq-net/src/lite/announce.rs b/rs/moq-net/src/lite/announce.rs index b3e017a4436..f3a7b67e888 100644 --- a/rs/moq-net/src/lite/announce.rs +++ b/rs/moq-net/src/lite/announce.rs @@ -1,7 +1,7 @@ use bytes::{Buf, BufMut}; use num_enum::{IntoPrimitive, TryFromPrimitive}; -use crate::{Hop, Hops, Path, broadcast::Cost, coding::*}; +use crate::{Hop, Hops, Path, coding::*, origin::Cost}; use super::{Message, Version}; @@ -336,14 +336,14 @@ impl Message for AnnounceInit<'_> { /// Sent by the publisher as the first message on an announce stream, before any /// individual Announce messages. Lite05+ only; the successor to [`AnnounceInit`]. /// -/// `hop` is the responder's session Hop ID. In Lite05 the publisher no +/// `origin` is the responder's session origin id. In Lite05 the publisher no /// longer stamps it onto each Announce's hop chain; the subscriber appends it on /// receipt instead. `active` is the number of currently-active broadcasts the /// publisher sends as the initial set immediately after this message, letting the /// receiver block until the initial set has arrived. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct AnnounceOk { - pub hop: Hop, + pub origin: Hop, pub active: u64, } @@ -353,9 +353,9 @@ impl Message for AnnounceOk { return Err(DecodeError::Version); } - let hop = Hop::decode(r, version)?; + let origin = Hop::decode(r, version)?; let active = u64::decode(r, version)?; - Ok(Self { hop, active }) + Ok(Self { origin, active }) } fn encode_msg(&self, w: &mut W, version: Version) -> Result<(), EncodeError> { @@ -363,7 +363,7 @@ impl Message for AnnounceOk { return Err(EncodeError::Version); } - self.hop.encode(w, version)?; + self.origin.encode(w, version)?; self.active.encode(w, version) } } @@ -436,7 +436,7 @@ mod tests { #[test] fn announce_ok_round_trip() { let msg = AnnounceOk { - hop: Hop::new(42).unwrap(), + origin: Hop::new(42).unwrap(), active: 3, }; assert_eq!(round_trip(&msg), msg); @@ -445,7 +445,7 @@ mod tests { #[test] fn announce_ok_zero_active() { let msg = AnnounceOk { - hop: Hop::new(7).unwrap(), + origin: Hop::new(7).unwrap(), active: 0, }; assert_eq!(round_trip(&msg), msg); @@ -568,7 +568,7 @@ mod tests { #[test] fn charged_cost_stays_encodable() { let mut buf = Vec::new(); - Cost::new(crate::broadcast::MAX_COST) + Cost::new(crate::origin::MAX_COST) .charged(1) .encode(&mut buf, Version::Lite06Wip) .expect("a charged cost must stay encodable"); @@ -596,7 +596,7 @@ mod tests { } } - // Lite04/05 carry the subscriber's Hop ID so the publisher can skip reflected + // Lite04/05 carry the subscriber's origin id so the publisher can skip reflected // announces before they hit the wire. #[test] fn announce_request_carries_exclude_hop_on_lite05() { @@ -631,7 +631,7 @@ mod tests { #[test] fn announce_ok_rejects_old_versions() { let msg = AnnounceOk { - hop: Hop::new(1).unwrap(), + origin: Hop::new(1).unwrap(), active: 0, }; let mut buf = bytes::BytesMut::new(); @@ -646,19 +646,19 @@ mod tests { // Encode a well-formed message then patch the origin to 0 on the wire. let mut buf = bytes::BytesMut::new(); AnnounceOk { - hop: Hop::new(1).unwrap(), + origin: Hop::new(1).unwrap(), active: 0, } .encode(&mut buf, Version::Lite05) .unwrap(); - // Hop ID 1 sits right after the size prefix; rewrite it to 0. + // origin id 1 sits right after the size prefix; rewrite it to 0. let bytes = &buf[..]; let mut patched = bytes.to_vec(); // size(1 byte) | origin varint(1 byte = 0x01) | active varint(1 byte) patched[1] = 0x00; let mut slice = &patched[..]; let got = AnnounceOk::decode(&mut slice, Version::Lite05).unwrap(); - assert_eq!(got.hop.id(), 0); + assert_eq!(got.origin.id(), 0); assert_eq!(got.active, 0); } } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 9ae50da8bc7..7f3c5c3ec55 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -19,38 +19,6 @@ use crate::{ use super::Version; -/// Publisher-side bookkeeping for one announced path, so upstream route changes -/// forward as a restart. `sent` is the hop chain last written to the peer, or -/// `None` while the announce is filtered (reflected or excluded). -struct WatchedRoute { - consumer: crate::broadcast::Consumer, - /// Demand edges re-price the route without a route change, so the announce - /// loop watches this alongside `route_changed`. - demand: crate::broadcast::Demand, - path: crate::PathOwned, - sent: Option, - /// When demand drained while a zero cost was advertised. The restart that - /// restores the cold cost is deferred by [`COST_LINGER`] past this, so - /// viewer churn doesn't flap routing across the mesh; demand returning in - /// the window cancels the restore. - idle_at: Option, -} - -/// What the peer currently holds for a path: the forwarded hop chain plus, on -/// lite-06+, the route cost. A fresh route that differs in either is worth a wire -/// message; one that matches is not. -#[derive(Clone)] -struct SentRoute { - hops: Hops, - cost: crate::broadcast::Cost, - /// Whether this is the route we actually serve from (the table's first - /// entry) rather than a standby selected because the serving chain flows - /// through the peer. Only a serving advertisement carries the demand - /// discount, so only it re-prices on demand edges; watching demand for a - /// standby would fire forever without ever changing the advertised cost. - serving: bool, -} - pub(super) struct PublisherConfig { /// The runtime that arms the publisher's timers. pub runtime: R, @@ -60,7 +28,7 @@ pub(super) struct PublisherConfig { session: S, origin: origin::Consumer, - self_hop: Hop, - // The peer's SETUP, read for the Hop ID it declared. Used to serve the + self_origin: Hop, + // The peer's SETUP, read for the origin id it declared. Used to serve the // peer from a source whose chain excludes them, keeping the data plane on // the same split-horizon rule as the announces we send them. peer_setup: super::PeerSetup, @@ -174,13 +142,13 @@ impl Publisher Publisher { /// Test shim: drive one announce-interest stream like the old `run_announce`. - #[allow(clippy::too_many_arguments)] async fn run_announce( - runtime: R, stream: &mut Stream, origin: &origin::Consumer, announced: &mut announce::Consumer, prefix: impl AsPath, - self_hop: Hop, - exclude_hop: u64, + self_origin: Hop, version: Version, ) -> Result<(), Error> { - let mut run = AnnounceRun::new(runtime, prefix.as_path().to_owned(), exclude_hop, self_hop, version); + let mut run = AnnounceRun::new(prefix.as_path().to_owned(), self_origin, version); kio::wait(|waiter| run.poll(stream, origin, announced, waiter)).await } } @@ -259,7 +224,7 @@ enum ControlState, }, - Announce(AnnounceServe), + Announce(AnnounceServe), Subscribe(SubscribeServe), Fetch(FetchServe), TrackInfo(TrackInfoServe), @@ -292,11 +257,9 @@ impl Control ControlState::Announce(AnnounceServe::new( - self.shared.clone(), - self.runtime.clone(), - stream, - )), + lite::ControlType::Announce => { + ControlState::Announce(AnnounceServe::new(self.shared.clone(), stream)) + } lite::ControlType::Subscribe => { ControlState::Subscribe(SubscribeServe::new(self.shared.clone(), stream)) } @@ -483,36 +446,33 @@ impl ProbeServe< /// Serves one announce-interest stream: the initial set, then updates as routes, /// demand, and the origin change. -struct AnnounceServe { +struct AnnounceServe { shared: Arc>, - // Cloned into the run loop, whose linger deadline it arms. - runtime: R, stream: Option>, - state: AnnounceState, + state: AnnounceState, } // A state machine's enum is its storage: one transient instance per stream, so the // big variant is the working state, not padding held in bulk. #[allow(clippy::large_enum_variant)] -enum AnnounceState { +enum AnnounceState { /// Reading the ANNOUNCE_REQUEST. Decode, - /// Waiting on the peer's SETUP for the session-wide excluded Hop ID + /// Waiting on the peer's SETUP for the session-wide excluded origin /// (lite-05, whose wire carries no per-stream exclude_hop). ExcludeHop { prefix: crate::PathOwned }, /// Streaming announce updates. Run { origin: origin::Consumer, announced: announce::Consumer, - run: AnnounceRun, + run: AnnounceRun, }, } -impl AnnounceServe { - fn new(shared: Arc>, runtime: R, stream: Stream) -> Self { +impl AnnounceServe { + fn new(shared: Arc>, stream: Stream) -> Self { Self { shared, - runtime, stream: Some(stream), state: AnnounceState::Decode, } @@ -532,7 +492,7 @@ impl AnnounceSer // parameter, the same identity the subscribe path excludes. A peer that // declares nothing falls back to the identity the caller assigned it // (`with_peer_hop`), if any. - let assigned = self.shared.peer_hop.map(|hop| hop.id()).unwrap_or(0); + let assigned = self.shared.peer_hop.map(|origin| origin.id()).unwrap_or(0); if self.shared.version.has_exclude_hop() { let exclude_hop = match interest.exclude_hop { 0 => assigned, @@ -591,59 +551,25 @@ impl AnnounceSer Err(_) => origin, }; let announced = origin.announced(); - let run = AnnounceRun::new( - self.runtime.clone(), - prefix, - exclude_hop, - self.shared.self_hop, - self.shared.version, - ); + let run = AnnounceRun::new(prefix, self.shared.self_origin, self.shared.version); self.state = AnnounceState::Run { origin, announced, run }; } } -/// One announce-loop turn: either an (un)announce from the origin, a route -/// change on an already-announced broadcast, or a demand edge re-pricing -/// one. A route turn re-reads the broadcast's route table and re-runs the -/// per-peer selection; `Err` means the broadcast is gone. -enum Op { - Announce(Option), - Route(crate::PathOwned, Result<(), Error>), - Idle(crate::PathOwned), - /// The linger sleep fired without an expired entry (it was canceled, - /// or a later deadline remains): restart the turn so the next - /// deadline arms a fresh sleep. - Linger, -} - /// The announce loop's state, minus the handles it borrows per poll so the test /// shim can supply its own. -struct AnnounceRun { - // Arms the linger deadline and stamps idle instants. - runtime: R, +struct AnnounceRun { prefix: crate::PathOwned, - exclude_hop: u64, - self_hop: Hop, + self_origin: Hop, version: Version, // Lite06+: announce ids. Every `active` we send implicitly assigns the next // per-stream ordinal, and `ended` references the id instead of repeating the - // path. Keyed by suffix; only announces that actually hit the wire get an id - // (filtered ones were never seen by the peer). + // path. Only announces that actually hit the wire get an id (filtered ones + // were never seen by the peer). next_announce_id: u64, - announce_ids: HashMap, - // Lite05+: watch every announced broadcast's route and forward changes as a - // restart, so an upstream failover re-advertises downstream instead of the - // peer keeping a stale hop chain. Keyed by suffix; filtered announces are - // watched too, since an update can cross the forwarding filter either way. - watched: HashMap, - // Pre-restart versions (Lite01-04) never populate `watched`, but the - // broadcast consumer handed out by an excluding cursor carries the - // ExclusionGuard that keeps the front marked as exposed to this peer. Hold - // it for as long as the peer holds the advertisement, or the guard releases - // right after the Active is written and a reflected UNKNOWN route can - // replace the incumbent after all. - held: HashMap, - linger: crate::runtime::Deadline, + // The routes the peer currently holds, keyed by suffix. The value is the + // announce id on versions that assign them. + live: HashMap>, phase: AnnouncePhase, } @@ -655,23 +581,89 @@ enum AnnouncePhase { Closing, } -impl AnnounceRun { - fn new(runtime: R, prefix: crate::PathOwned, exclude_hop: u64, self_hop: Hop, version: Version) -> Self { +impl AnnounceRun { + fn new(prefix: crate::PathOwned, self_origin: Hop, version: Version) -> Self { Self { prefix, - exclude_hop, - self_hop, + self_origin, version, next_announce_id: 0, - announce_ids: HashMap::new(), - watched: HashMap::new(), - held: HashMap::new(), - linger: crate::runtime::Deadline::new(&runtime), - runtime, + live: HashMap::new(), phase: AnnouncePhase::Init, } } + /// The suffix an update travels under on this stream. + fn suffix(&self, prefix: &crate::origin::Prefix) -> crate::PathOwned { + prefix + .as_path() + .strip_prefix(&self.prefix) + .expect("origin returned invalid prefix") + .to_owned() + } + + /// The chain and cost to put on the wire for `route`, or `None` when it must + /// not be forwarded. + fn outgoing(&self, route: &crate::origin::Route, absolute: &crate::Path) -> Option<(Hops, crate::origin::Cost)> { + let mut hops = route.hops.clone(); + + // A route that already passed through us is a reflection. The origin + // filters these on receive, so this is defensive. + if self.self_origin != Hop::UNKNOWN && hops.contains(&self.self_origin) { + tracing::debug!(route = %absolute, "dropping reflected route"); + return None; + } + + // Lite05+ moves the self-stamp to the receiver, which appends our id (reported + // once via AnnounceOk) on receipt. Older versions stamp it here, dropping if the + // chain is full. + if !self.version.has_announce_ok() && hops.push(self.self_origin).is_err() { + tracing::warn!(route = %absolute, "dropping announce; hop chain at MAX_HOPS (possible loop)"); + return None; + } + + // Pre-lite-06 wires carry no cost at all, leaving hop count as the + // effective metric exactly as before. + let cost = match self.version.has_route_cost() { + true => route.cost.clamped(), + false => crate::origin::Cost::UNKNOWN, + }; + Some((hops, cost)) + } + + /// The next announce id, on versions that assign them. + fn assign_id(&mut self) -> Option { + if !self.version.has_announce_id() { + return None; + } + let id = self.next_announce_id; + self.next_announce_id += 1; + Some(id) + } + + /// Retract the peer's advertisement for `suffix`, if it holds one. + fn retract( + &mut self, + stream: &mut Stream, + suffix: crate::PathOwned, + absolute: &crate::Path, + ) -> Result<(), Error> { + let Some(id) = self.live.remove(&suffix) else { + // Filtered on the way out; the peer never saw it. + return Ok(()); + }; + tracing::debug!(route = %absolute, "unannounce"); + match id { + Some(id) => stream.writer.buffer(&lite::AnnounceBroadcast::EndedId { id })?, + // An ended announce doesn't need hops; the receiver matches on path only. + None => stream.writer.buffer(&lite::AnnounceBroadcast::Ended { + suffix: suffix.as_path(), + hops: Hops::new(), + })?, + } + Ok(()) + } + /// Buffer the version-specific initial burst: ANNOUNCE_INIT (Lite01/02) or /// ANNOUNCE_OK plus the initial actives (lite-05+). fn init( @@ -684,37 +676,23 @@ impl AnnounceRun { Version::Lite01 | Version::Lite02 => { let mut init = Vec::new(); - // Send ANNOUNCE_INIT as the first message with all currently active paths + // Send ANNOUNCE_INIT as the first message with all currently active routes. // We use `try_next()` to synchronously get the initial updates. - while let Some(crate::announce::Update { path, broadcast }) = announced.try_next() { - let suffix = path - .strip_prefix(&self.prefix) - .expect("origin returned invalid path") - .to_owned(); - let absolute = origin.absolute(&path).to_owned(); - - if let Some(broadcast) = broadcast { - // The same per-peer selection as the live loop: an initial path - // with no advertisable route (a reflection, or every hop through - // the peer's assigned identity) is filtered like a live announce. - let selected = select_route( - &broadcast.routes(), - &broadcast.demand(), - self.self_hop, - self.exclude_hop, - self.version, - &absolute, - ); - if selected.is_none() { + while let Some(update) = announced.try_next() { + let suffix = self.suffix(&update.prefix); + let absolute = origin.absolute(update.prefix.as_path()).to_owned(); + + if update.active { + if self.outgoing(&update.route, &absolute.as_path()).is_none() { continue; } - tracing::debug!(broadcast = %absolute, "announce"); + tracing::debug!(route = %absolute, "announce"); if !init.contains(&suffix) { init.push(suffix); } } else { - // A potential race. - tracing::debug!(broadcast = %absolute, "unannounce"); + // A potential race: a just-announced route already retracted. + tracing::debug!(route = %absolute, "unannounce"); init.retain(|p| p != &suffix); } } @@ -727,74 +705,39 @@ impl AnnounceRun { // stashing suffix+hops so we can both COUNT them for AnnounceOk and re-send // them afterward. The receiver stamps our origin onto each hop chain, so we // forward the stored chain as-is (no self push here). - let mut initial: Vec<(crate::PathOwned, SentRoute)> = Vec::new(); - while let Some(crate::announce::Update { path, broadcast }) = announced.try_next() { - let suffix = path - .strip_prefix(&self.prefix) - .expect("origin returned invalid path") - .to_owned(); - let absolute = origin.absolute(&path).to_owned(); - - match broadcast { - Some(broadcast) => { - let routes = broadcast.routes(); - let demand = broadcast.demand(); - // Watch even the announces we filter below: a later route update - // can cross the forwarding filter in either direction. - self.watched.insert( - suffix.clone(), - WatchedRoute { - consumer: broadcast.clone(), - demand: demand.clone(), - path: path.clone(), - sent: None, - idle_at: None, - }, - ); - // The same per-peer selection as the live loop, so the count - // matches exactly what we send. - let Some(route) = select_route( - &routes, - &demand, - self.self_hop, - self.exclude_hop, - self.version, - &absolute, - ) else { - continue; - }; - tracing::debug!(broadcast = %absolute, "announce"); - initial.retain(|(s, _)| s != &suffix); - initial.push((suffix, route)); - } - None => { - // A potential race: a just-announced path already unannounced. - tracing::debug!(broadcast = %absolute, "unannounce"); - self.watched.remove(&suffix); - initial.retain(|(s, _)| s != &suffix); - } + let mut initial: Vec<(crate::PathOwned, Hops, crate::origin::Cost)> = Vec::new(); + while let Some(update) = announced.try_next() { + let suffix = self.suffix(&update.prefix); + let absolute = origin.absolute(update.prefix.as_path()).to_owned(); + + if update.active { + let Some((hops, cost)) = self.outgoing(&update.route, &absolute.as_path()) else { + continue; + }; + tracing::debug!(route = %absolute, "announce"); + initial.retain(|(s, ..)| s != &suffix); + initial.push((suffix, hops, cost)); + } else { + // A potential race: a just-announced route already retracted. + tracing::debug!(route = %absolute, "unannounce"); + initial.retain(|(s, ..)| s != &suffix); } } - // Report our Hop ID (stamped onto hops by the receiver, not us) + // Report our origin id (stamped onto hops by the receiver, not us) // and the count of initial announces that follow immediately. let ok = lite::AnnounceOk { - hop: self.self_hop, + origin: self.self_origin, active: initial.len() as u64, }; stream.writer.buffer(&ok)?; - for (suffix, route) in &initial { - if self.version.has_announce_id() { - self.announce_ids.insert(suffix.clone(), self.next_announce_id); - self.next_announce_id += 1; - } - if let Some(entry) = self.watched.get_mut(suffix) { - entry.sent = Some(route.clone()); - } + for (suffix, hops, cost) in initial { + let id = self.assign_id(); + self.live.insert(suffix.clone(), id); stream.writer.buffer(&lite::AnnounceBroadcast::Active { suffix: suffix.as_path(), - hops: route.hops.clone(), - cost: route.cost, + hops, + cost, })?; } } @@ -815,8 +758,6 @@ impl AnnounceRun { announced: &mut announce::Consumer, waiter: &kio::Waiter, ) -> Poll> { - use crate::broadcast::COST_LINGER; - let mut cx = Context::from_waker(waiter.waker()); if matches!(self.phase, AnnouncePhase::Init) { @@ -832,350 +773,68 @@ impl AnnounceRun { return stream.writer.poll_closed(&mut cx); } - // The earliest deferred cost-restore, if any entry's linger is running. - self.linger.set( - self.watched - .values() - .filter_map(|entry| entry.idle_at) - .min() - .map(|at| at + COST_LINGER), - ); + if let Poll::Ready(res) = stream.reader.poll_closed(&mut cx) { + return Poll::Ready(res); + } + let Poll::Ready(next) = announced.poll_next(waiter) else { + return Poll::Pending; + }; - let op = 'turn: { - if let Poll::Ready(res) = stream.reader.poll_closed(&mut cx) { - return Poll::Ready(res); - } - if let Poll::Ready(next) = announced.poll_next(waiter) { - break 'turn Op::Announce(next); - } - // Stamped per turn rather than kept: the turn always ends in an op - // below once it fires, so it never has to survive. - let fired = self.linger.poll(waiter).is_ready().then(|| self.runtime.now()); - // Poll every watched broadcast for a route-table change; each - // wake rescans the map, which announce-control rates make fine. - for (suffix, entry) in self.watched.iter_mut() { - if let Poll::Ready(res) = entry.consumer.poll_routes_changed(waiter) { - break 'turn Op::Route(suffix.clone(), res); - } - // Demand edges re-price the route without a route change: - // watch the direction opposite the advertised cost. Closure - // is ignored here; the route watch above surfaces it. - if !self.version.has_route_cost() { - continue; - } - let Some(sent) = &entry.sent else { continue }; - // The demand discount only applies to the serving route: - // a standby advertised to an excluded peer keeps its own - // cost, so demand edges can never re-price it. - if !sent.serving { - continue; - } - if sent.cost.warm != 0 { - if let Poll::Ready(Ok(())) = entry.demand.poll_used(waiter) { - break 'turn Op::Route(suffix.clone(), Ok(())); - } - continue; - } - match entry.idle_at { - // Demand coming back within the linger cancels the - // restore; fall through to re-arm the unused watch. - Some(_) if entry.demand.is_used() => entry.idle_at = None, - // The linger expired: re-price via the route path. - Some(at) if fired.is_some_and(|now| now >= at + COST_LINGER) => { - entry.idle_at = None; - break 'turn Op::Route(suffix.clone(), Ok(())); - } - // Still lingering: the sleep owns the wakeup, and - // `poll_used` re-arms the cancel check above. - Some(_) => { - let _ = entry.demand.poll_used(waiter); - continue; - } - None => {} - } - if let Poll::Ready(Ok(())) = entry.demand.poll_unused(waiter) { - break 'turn Op::Idle(suffix.clone()); - } - } - match fired { - Some(_) => Op::Linger, - None => return Poll::Pending, - } + let Some(update) = next else { + // The buffer is empty (flushed at the loop top), so FIN now and + // wait for the acknowledgement. + stream.writer.finish()?; + self.phase = AnnouncePhase::Closing; + continue; }; - match op { - Op::Announce(None) => { - // The buffer is empty (flushed at the loop top), so FIN now and - // wait for the acknowledgement. - stream.writer.finish()?; - self.phase = AnnouncePhase::Closing; - } - Op::Announce(Some(crate::announce::Update { path, broadcast })) => { - let suffix = path - .strip_prefix(&self.prefix) - .expect("origin returned invalid path") - .to_owned(); - let absolute = origin.absolute(&path).to_owned(); - - match broadcast { - Some(active) => { - let routes = active.routes(); - let demand = active.demand(); - if lite::restart_supported(self.version) { - // Watch even if filtered below: a route update can cross - // the forwarding filter in either direction. - self.watched.insert( - suffix.clone(), - WatchedRoute { - consumer: active.clone(), - demand: demand.clone(), - path: path.clone(), - sent: None, - idle_at: None, - }, - ); - } - let Some(route) = select_route( - &routes, - &demand, - self.self_hop, - self.exclude_hop, - self.version, - &absolute, - ) else { - continue; - }; - tracing::debug!(broadcast = %absolute, "announce"); - if self.version.has_announce_id() { - let prev = self.announce_ids.insert(suffix.clone(), self.next_announce_id); - debug_assert!(prev.is_none(), "announce id still assigned for a new announce"); - self.next_announce_id += 1; - } - if let Some(entry) = self.watched.get_mut(&suffix) { - entry.sent = Some(route.clone()); - } - if !lite::restart_supported(self.version) { - self.held.insert(suffix.clone(), active.clone()); - } - stream.writer.buffer(&lite::AnnounceBroadcast::Active { - suffix, - hops: route.hops, - cost: route.cost, - })?; - } - None => { - tracing::debug!(broadcast = %absolute, "unannounce"); - // A watched entry with `sent: None` means the peer holds no live - // advertisement (a route-filter retract already sent its Ended); - // repeating the Ended would be a spurious wire message. Pre-watch - // versions never populate `watched`, so they keep sending the - // Ended even for announces filtered above. - let retracted = self.watched.remove(&suffix).is_some_and(|entry| entry.sent.is_none()); - self.held.remove(&suffix); - if self.version.has_announce_id() { - // Retract by id; nothing to send if the announce was filtered and - // the peer never saw it (an unknown id is a protocol violation). - if let Some(id) = self.announce_ids.remove(&suffix) { - stream.writer.buffer(&lite::AnnounceBroadcast::EndedId { id })?; - } - } else if !retracted { - // An ended announce doesn't need hops; the receiver matches on path only. - stream.writer.buffer(&lite::AnnounceBroadcast::Ended { - suffix, - hops: Hops::new(), - })?; - } - } - } - } - Op::Route(suffix, res) => { - if res.is_err() { - // The broadcast is gone; the origin delivers the Ended itself. - self.watched.remove(&suffix); - continue; - } - let Some(entry) = self.watched.get_mut(&suffix) else { - continue; - }; - // Any re-price supersedes a pending cost-restore; a stale - // timestamp would spin the linger sleep forever. - entry.idle_at = None; - let absolute = origin.absolute(&entry.path).to_owned(); - let routes = entry.consumer.routes(); - let hops = select_route( - &routes, - &entry.demand, - self.self_hop, - self.exclude_hop, - self.version, - &absolute, - ); - let sent = entry.sent.clone(); - match (hops, sent) { - // Neither the forwarded chain nor the cost moved: nothing to - // send. The serving flag may still have flipped (a failover - // onto the already-advertised standby), so store it for the - // demand watches without a wire message. - (Some(route), Some(sent)) if route.hops == sent.hops && route.cost == sent.cost => { - entry.sent = Some(route); - } - // The chain or the cost changed (an upstream failover, a repriced - // link, or a broadcast going hot): restart, so the peer updates its - // route in place instead of re-resolving. - (Some(route), Some(_)) => { - tracing::debug!(broadcast = %absolute, "reannounce"); - if self.version.has_announce_id() { - // The id exists for every live advertisement; a panic here would - // silently kill the announce loop (the peer keeps stale routes), - // so a bookkeeping bug degrades to a skipped restart instead. - let Some(id) = self.announce_ids.get(&suffix).copied() else { - debug_assert!(false, "announced path without an announce id"); - tracing::warn!(broadcast = %absolute, "restart without an announce id; skipping"); - continue; - }; - entry.sent = Some(route.clone()); - stream.writer.buffer(&lite::AnnounceBroadcast::Restart { - id, - hops: route.hops, - cost: route.cost, - })?; - } else { - // Lite05: a duplicate ANNOUNCE for a live path is the restart. - entry.sent = Some(route.clone()); - stream.writer.buffer(&lite::AnnounceBroadcast::Active { - suffix, - hops: route.hops, - cost: route.cost, - })?; - } - } - // Previously filtered, now forwardable: a fresh announce. - (Some(route), None) => { - tracing::debug!(broadcast = %absolute, "announce"); - if self.version.has_announce_id() { - self.announce_ids.insert(suffix.clone(), self.next_announce_id); - self.next_announce_id += 1; - } - entry.sent = Some(route.clone()); - stream.writer.buffer(&lite::AnnounceBroadcast::Active { - suffix, - hops: route.hops, - cost: route.cost, - })?; - } - // The new chain must not be forwarded (it now loops through the - // peer, or the peer excluded it): retract. - (None, Some(_)) => { - tracing::debug!(broadcast = %absolute, "unannounce (filtered route)"); - entry.sent = None; - if self.version.has_announce_id() { - if let Some(id) = self.announce_ids.remove(&suffix) { - stream.writer.buffer(&lite::AnnounceBroadcast::EndedId { id })?; - } - } else { - stream.writer.buffer(&lite::AnnounceBroadcast::Ended { - suffix, - hops: Hops::new(), - })?; - } + let suffix = self.suffix(&update.prefix); + let absolute = origin.absolute(update.prefix.as_path()).to_owned(); + + if !update.active { + self.retract(stream, suffix, &absolute.as_path())?; + continue; + } + + match self.outgoing(&update.route, &absolute.as_path()) { + Some((hops, cost)) => match self.live.get(&suffix) { + // A metadata update on a live advertisement: restart it in + // place (lite-05 restarts via a duplicate ANNOUNCE). + Some(&id) if lite::restart_supported(self.version) => { + tracing::debug!(route = %absolute, "reannounce"); + match id { + Some(id) => stream + .writer + .buffer(&lite::AnnounceBroadcast::Restart { id, hops, cost })?, + None => stream.writer.buffer(&lite::AnnounceBroadcast::Active { + suffix: suffix.as_path(), + hops, + cost, + })?, } - // Still filtered: keep watching. - (None, None) => {} } - } - // Demand drained while advertising zero: start the linger. The - // restore rides the deadline unless demand returns first. - Op::Idle(suffix) => { - if let Some(entry) = self.watched.get_mut(&suffix) { - entry.idle_at = Some(self.runtime.now()); + // Pre-restart versions have no way to update a live + // advertisement; the peer keeps the original chain. + Some(_) => {} + None => { + tracing::debug!(route = %absolute, "announce"); + let id = self.assign_id(); + self.live.insert(suffix.clone(), id); + stream.writer.buffer(&lite::AnnounceBroadcast::Active { + suffix: suffix.as_path(), + hops, + cost, + })?; } - } - // The linger sleep's job is done; the next turn arms the next - // deadline (or none). - Op::Linger => {} + }, + // The chain must not be forwarded (reflected, or full): retract + // whatever the peer holds. + None => self.retract(stream, suffix, &absolute.as_path())?, } } } } -/// Pick the route to advertise to this peer: the most preferred announced -/// route whose hop chain avoids both the peer (`exclude_hop`) and ourselves -/// (a reflection), with the outgoing chain and cost ready for the wire. -/// -/// `routes` is the broadcast's table in preference order with the serving -/// (active) route first, so the peer usually receives exactly what we serve -/// everyone; a peer that the active chain flows through receives the best -/// standby instead of nothing. The subscribe path picks its source by the -/// same exclusion (see `origin::Consumer::excluding`), which is what keeps -/// the advertised chain truthful and the mesh loop-free. -/// -/// Returns `None` when no route qualifies: every chain loops through the -/// peer or us, or none is announced. -fn select_route( - routes: &[crate::broadcast::Route], - demand: &crate::broadcast::Demand, - self_hop: Hop, - exclude_hop: u64, - version: Version, - absolute: &crate::Path, -) -> Option { - let exclude = match exclude_hop { - 0 => Hop::UNKNOWN, - id => Hop::new(id).unwrap_or(Hop::UNKNOWN), - }; - - for (route, serving) in crate::broadcast::advertisable_routes(routes, self_hop, exclude) { - let mut hops = route.hops.clone(); - // Lite05+ moves the self-stamp to the receiver, which appends our id (reported - // once via AnnounceOk) on receipt. Older versions stamp it here, dropping if the - // chain is full. - if !version.has_announce_ok() && hops.push(self_hop).is_err() { - tracing::warn!(broadcast = %absolute, "dropping announce; hop chain at MAX_HOPS (possible loop)"); - continue; - } - let cost = outgoing_cost(version, demand, route, serving); - return Some(SentRoute { hops, cost, serving }); - } - tracing::debug!(broadcast = %absolute, %exclude_hop, "no advertisable route for this peer"); - None -} - -/// The cost to advertise for a route, alongside its outgoing hop chain. -/// -/// While the broadcast has demand, the *serving* (active) route costs zero: -/// our ingress is already paid for (or, for a local standby publisher, the -/// work is already running), so one more subscriber only pays the link to -/// reach us. A standby advertised to a peer the active chain flows through -/// keeps its own accumulated cost: serving that peer means opening a fresh -/// ingest, which is not already paid for. Otherwise we forward the -/// accumulated route cost unchanged, which for a standby publisher is its -/// production cost and for a pure forwarder is the price of the fetch a -/// subscription would trigger. -/// -/// A ceiling-cost route pierces the carrying discount. For a drain (the -/// ceiling's primary producer) the paid-for ingress is going away, so -/// advertising zero would keep pulling subscribers onto a path about to -/// vanish when a peer with any other edge should move now, while the seam is -/// seamless. The rule keys on the value, not the reason: the reason does not -/// travel on the wire, and a cost that saturated through charges marks a -/// path of last resort all the same. -/// -/// The receiving side adds its own link price on top, so we never account for -/// the link we are sending over. Pre-lite-06 peers get nothing (the field isn't -/// on their wire), leaving hop count as the metric exactly as before. -fn outgoing_cost( - version: Version, - demand: &crate::broadcast::Demand, - route: &crate::broadcast::Route, - serving: bool, -) -> crate::broadcast::Cost { - if !version.has_route_cost() { - return crate::broadcast::Cost::UNKNOWN; - } - - crate::broadcast::outgoing_cost(demand, route, serving) -} - /// Serves one TRACK stream: resolve the track, answer with its TRACK_INFO, FIN. struct TrackInfoServe { shared: Arc>, @@ -1189,7 +848,7 @@ struct TrackInfoServe { enum TrackInfoState { Decode, /// Resolving the split-horizon origin (waits on the peer's SETUP). - Origin { + Hop { msg: lite::Track<'static>, }, /// Resolving the broadcast (may wait on a dynamic handler). @@ -1253,15 +912,14 @@ impl TrackInfoServe { self.absolute = self.shared.origin.absolute(&msg.broadcast).to_owned(); self.track = msg.track.to_string(); tracing::debug!(broadcast = %self.absolute, track = %self.track, "track info requested"); - self.state = TrackInfoState::Origin { msg }; + self.state = TrackInfoState::Hop { msg }; } - TrackInfoState::Origin { .. } => { + TrackInfoState::Hop { .. } => { // The peer requested this exact path, so it has already seen an // announcement for it. `request_broadcast` resolves it immediately, or // falls back to an `origin::Dynamic` handler (as in SubscribeServe). let origin = ready!(self.shared.poll_serving_origin(waiter)); - let TrackInfoState::Origin { msg } = std::mem::replace(&mut self.state, TrackInfoState::Decode) - else { + let TrackInfoState::Hop { msg } = std::mem::replace(&mut self.state, TrackInfoState::Decode) else { unreachable!() }; let requesting = origin.request_broadcast(&msg.broadcast).into_inner(); @@ -1316,7 +974,7 @@ struct SubscribeServe { enum SubscribeState { Decode, /// Resolving the split-horizon origin (waits on the peer's SETUP). - Origin { + Hop { msg: lite::Subscribe<'static>, }, /// Resolving the broadcast (may wait on a dynamic handler). @@ -1391,17 +1049,16 @@ impl SubscribeServe { self.track = msg.track.to_string(); tracing::info!(id = self.id, broadcast = %self.absolute, track = %self.track, "subscribed started"); - self.state = SubscribeState::Origin { msg }; + self.state = SubscribeState::Hop { msg }; } - SubscribeState::Origin { .. } => { + SubscribeState::Hop { .. } => { // We just received a subscribe for this exact path, so by definition the // peer has already seen an announcement for it. `request_broadcast` // resolves an announced broadcast immediately; if it isn't announced it // falls back to an `origin::Dynamic` handler (or resolves to an error // when there is none). let origin = ready!(self.shared.poll_serving_origin(waiter)); - let SubscribeState::Origin { msg } = std::mem::replace(&mut self.state, SubscribeState::Decode) - else { + let SubscribeState::Hop { msg } = std::mem::replace(&mut self.state, SubscribeState::Decode) else { unreachable!() }; let requesting = origin.request_broadcast(&msg.broadcast).into_inner(); @@ -1540,7 +1197,7 @@ struct FetchServe { enum FetchState { Decode, /// Resolving the split-horizon origin (waits on the peer's SETUP). - Origin { + Hop { msg: lite::Fetch<'static>, }, /// Resolving the broadcast (may wait on a dynamic handler). @@ -1623,14 +1280,14 @@ impl FetchServe { self.group = msg.group; tracing::info!(broadcast = %self.absolute, track = %self.track, group = %self.group, "fetch started"); - self.state = FetchState::Origin { msg }; + self.state = FetchState::Hop { msg }; } - FetchState::Origin { .. } => { + FetchState::Hop { .. } => { // The peer fetched this exact path, so it has already seen an // announcement for it. `request_broadcast` resolves it immediately, or // falls back to an `origin::Dynamic` handler (as in SubscribeServe). let origin = ready!(self.shared.poll_serving_origin(waiter)); - let FetchState::Origin { msg } = std::mem::replace(&mut self.state, FetchState::Decode) else { + let FetchState::Hop { msg } = std::mem::replace(&mut self.state, FetchState::Decode) else { unreachable!() }; let requesting = origin.request_broadcast(&msg.broadcast).into_inner(); @@ -1960,10 +1617,8 @@ mod test { } } -/// The announce loop's demand/linger state machine: a drained broadcast keeps -/// advertising zero for `COST_LINGER` before the restart that restores its cold -/// cost, demand returning in the window cancels the restore, and a route change -/// supersedes it. Time is paused, so the 5s linger is deterministic. +/// The announce loop: forwarding route announcements, metadata restarts, and +/// retractions onto the wire. #[cfg(test)] mod announce_test { use super::*; @@ -1974,21 +1629,11 @@ mod announce_test { /// The tokio-backed test runtime, matching the fake transport. type TestRuntime = crate::runtime::tokio_test::Tokio; + type TestPublisher = Publisher; const VERSION: Version = Version::Lite06Wip; - /// The broadcast's cold cost: what the route advertises without demand. - const COLD: u64 = 7; - - /// What the harness route advertises with no demand, and with it: the carrying - /// discount zeroes the warm half only, so the cold path keeps flowing and peers - /// can still rank this relay against another warm one. - const COLD_COST: crate::broadcast::Cost = crate::broadcast::Cost::new(COLD); - const WARM_COST: crate::broadcast::Cost = crate::broadcast::Cost { warm: 0, cold: COLD }; - - /// The original publisher stamped on every harness route: content identity is - /// keyed on the first hop, so a route change that should ride through as a - /// restart must keep it. + /// The hops stamped on every harness route. fn pub_hops() -> Hops { Hops::try_from(vec![Hop::new(9).unwrap()]).unwrap() } @@ -2053,13 +1698,11 @@ mod announce_test { } struct Harness { - /// Held for the whole test: dropping the origin producer unannounces - /// every broadcast under it, which would end the announce loop. + /// Held for the whole test: dropping the origin producer retracts every + /// route under it, which would end the announce loop. origin: origin::Producer, - /// The publishing side: route changes go in here. - source: crate::broadcast::Producer, - /// A downstream viewer: its `track()` handles are the broadcast's demand. - downstream: crate::broadcast::Consumer, + /// The initial announcement; drop to retract, update to restart. + announcement: crate::announce::Producer, wire: Wire, task: tokio::task::JoinHandle>, } @@ -2072,63 +1715,21 @@ mod announce_test { self.wire.assert_quiet(); assert!(!self.task.is_finished(), "the announce loop ended unexpectedly"); } - - /// Announce a second broadcast once the loop is already running, with a - /// viewer attached so it advertises warm. Returns the producer (kept - /// alive by the caller) and the viewer handle whose drop drains demand. - async fn announce(&mut self, name: &str) -> (crate::broadcast::Producer, track::Consumer) { - let source = self - .origin - .create_broadcast( - name, - crate::broadcast::Route::new() - .with_hops(pub_hops()) - .with_cost(COLD) - .with_announce(true), - ) - .unwrap(); - let downstream = self.origin.consume().announced_broadcast(name).await.unwrap(); - let track = downstream.track("video").unwrap(); - settle().await; - - // It announces cold, then immediately re-prices warm for the viewer. - match self.wire.take_announces().as_slice() { - [ - lite::AnnounceBroadcast::Active { cost: first, .. }, - lite::AnnounceBroadcast::Restart { cost: second, .. }, - ] => { - assert_eq!(*first, COLD_COST); - assert_eq!(*second, WARM_COST); - } - // The viewer may already be attached when the announce is built. - [lite::AnnounceBroadcast::Active { cost, .. }] => assert_eq!(*cost, WARM_COST), - other => panic!("expected {name} to announce, got {other:?}"), - } - - (source, track) - } } async fn settle() { tokio::time::sleep(Duration::from_millis(1)).await; } - /// Announce one broadcast with cold cost [`COLD`] and run the announce loop - /// against it, optionally with a viewer already attached (so the initial - /// announce goes out warm, at cost zero). - async fn harness(demand: bool) -> (Harness, Option) { + /// Announce one route with cost 7 and run the announce loop against it. + async fn harness() -> Harness { let origin = Hop::new(1).unwrap().produce(); - let source = origin - .create_broadcast( + let announcement = origin + .announce( "cam", - crate::broadcast::Route::new() - .with_hops(pub_hops()) - .with_cost(COLD) - .with_announce(true), + crate::origin::Route::default().with_hops(pub_hops()).with_cost(7), ) .unwrap(); - let downstream = origin.consume().announced_broadcast("cam").await.unwrap(); - let track = demand.then(|| downstream.track("video").unwrap()); let log = Log::default(); let writes = log.writes.clone(); @@ -2139,475 +1740,142 @@ mod announce_test { }; let task = tokio::spawn(async move { let mut announced = consumer.announced(); - let self_hop = *consumer; - Publisher::run_announce( - TestRuntime::new(), - &mut stream, - &consumer, - &mut announced, - "", - self_hop, - 0, - VERSION, - ) - .await + let self_origin = *consumer; + TestPublisher::run_announce(&mut stream, &consumer, &mut announced, "", self_origin, VERSION).await }); settle().await; let mut wire = Wire { writes, cursor: 0 }; assert_eq!(wire.take_ok().active, 1, "expected one initial announce"); - let expected = if demand { WARM_COST } else { COLD_COST }; match wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::Active { cost, .. }] => assert_eq!(*cost, expected), + [lite::AnnounceBroadcast::Active { suffix, hops, cost }] => { + assert_eq!(suffix.as_str(), "cam"); + assert_eq!(hops, &pub_hops()); + assert_eq!(*cost, crate::origin::Cost::new(7)); + } other => panic!("expected the initial announce, got {other:?}"), } - ( - Harness { - origin, - source, - downstream, - wire, - task, - }, - track, - ) - } - - /// Demand draining while zero is advertised must not re-price immediately: - /// the restore waits out the linger, so viewer churn doesn't flap routing. - #[tokio::test(start_paused = true)] - async fn drain_defers_the_cold_restore() { - let (h, track) = harness(true).await; - - drop(track); - settle().await; - h.assert_idle(); - - // Still inside the linger window: still quiet. - tokio::time::sleep(Duration::from_secs(3)).await; - h.assert_idle(); - } - - /// Demand returning within the linger cancels the pending restore, and the - /// next drain starts a fresh window rather than inheriting the old deadline. - /// - /// The second drain is what makes the cancellation observable. Silence alone - /// can't distinguish "the deadline was cleared" from "it fired but re-priced - /// to the same zero cost, so nothing went out": both are quiet. By draining - /// again at t=4s, an uncancelled t=0 deadline would fire at t=5s with demand - /// already gone, sending the restart a full four seconds early. - #[tokio::test(start_paused = true)] - async fn demand_return_cancels_the_restore() { - let (mut h, track) = harness(true).await; - - // t=0: demand drains, arming the restore for t=5s. - drop(track); - tokio::time::sleep(Duration::from_secs(3)).await; - - // t=3s: a new viewer inside the window cancels it. - let track = h.downstream.track("video").unwrap(); - tokio::time::sleep(Duration::from_secs(1)).await; - - // t=4s: drained again, so the restore is due at t=9s, not t=5s. - drop(track); - tokio::time::sleep(Duration::from_secs(2)).await; - - // t=6s: past the stale deadline. A restart here means it was never cleared. - h.assert_idle(); - - // t=10s: past the fresh deadline, so the restore finally lands. - tokio::time::sleep(Duration::from_secs(4)).await; - match h.wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::Restart { id: 0, cost, .. }] => assert_eq!(*cost, COLD_COST), - other => panic!("expected the restore on the fresh deadline, got {other:?}"), + Harness { + origin, + announcement, + wire, + task, } } - /// Each lingering broadcast restores on its own deadline: the loop sleeps - /// until the *earliest* pending restore, not the latest. - /// - /// With one broadcast the deadline scan is trivially correct, so this stages - /// two with staggered drains. Taking the maximum instead would hold the first - /// broadcast's restore back until the second's deadline. + /// A live announce goes out as an Active with a fresh id; its retraction + /// references the id. #[tokio::test(start_paused = true)] - async fn staggered_lingers_restore_independently() { - let (mut h, first) = harness(true).await; - let (_second_source, second) = h.announce("cam2").await; - - // t=0: the first drains, due at t=5s. - drop(first); - tokio::time::sleep(Duration::from_secs(2)).await; - h.assert_idle(); + async fn announce_and_retract() { + let mut h = harness().await; - // t=2s: the second drains, due at t=7s. - drop(second); - tokio::time::sleep(Duration::from_secs(4)).await; - - // t=6s: only the first has expired. + let late = h + .origin + .announce("mic", crate::origin::Route::default().with_hops(pub_hops())) + .unwrap(); + settle().await; match h.wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::Restart { id: 0, cost, .. }] => assert_eq!(*cost, COLD_COST), - other => panic!("expected only the first restore, got {other:?}"), + [lite::AnnounceBroadcast::Active { suffix, .. }] => assert_eq!(suffix.as_str(), "mic"), + other => panic!("expected an announce, got {other:?}"), } - // t=8s: now the second's own deadline has passed. - tokio::time::sleep(Duration::from_secs(2)).await; + drop(late); + settle().await; match h.wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::Restart { id: 1, cost, .. }] => assert_eq!(*cost, COLD_COST), - other => panic!("expected the second restore, got {other:?}"), + // "cam" took id 0 in the initial burst, so "mic" is id 1. + [lite::AnnounceBroadcast::EndedId { id: 1 }] => {} + other => panic!("expected the retraction, got {other:?}"), } + h.assert_idle(); } - /// An expired linger sends exactly one restart restoring the cold cost. + /// A metadata update restarts the advertisement in place, keeping its id. #[tokio::test(start_paused = true)] - async fn linger_expiry_restores_the_cold_cost() { - let (mut h, track) = harness(true).await; - - drop(track); - tokio::time::sleep(Duration::from_secs(6)).await; + async fn update_restarts_in_place() { + let mut h = harness().await; + h.announcement + .update(crate::origin::Route::default().with_hops(pub_hops()).with_cost(3)) + .unwrap(); + settle().await; match h.wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::Restart { id: 0, cost, .. }] => assert_eq!(*cost, COLD_COST), - other => panic!("expected one cold-cost restart, got {other:?}"), + [lite::AnnounceBroadcast::Restart { id: 0, hops, cost }] => { + assert_eq!(hops, &pub_hops()); + assert_eq!(*cost, crate::origin::Cost::new(3)); + } + other => panic!("expected a restart, got {other:?}"), } - - // The restore is a one-shot: the loop settles back to idle. - tokio::time::sleep(Duration::from_secs(30)).await; h.assert_idle(); } - /// A route change during the linger supersedes the pending restore: the - /// restart it triggers carries the new chain (and, with demand still gone, - /// the cold cost), and the old deadline then passes without a second one. + /// An identical update never reaches the wire: the origin coalesces it away. #[tokio::test(start_paused = true)] - async fn route_change_supersedes_the_linger() { - let (mut h, track) = harness(true).await; - - drop(track); - tokio::time::sleep(Duration::from_secs(3)).await; - h.wire.assert_quiet(); - - // An upstream failover mid-linger: a new chain with the same first hop - // (the same original publisher reached another way). - let hops = Hops::try_from(vec![Hop::new(9).unwrap(), Hop::new(12).unwrap()]).unwrap(); - h.source - .set_route( - crate::broadcast::Route::new() - .with_hops(hops.clone()) - .with_cost(COLD) - .with_announce(true), - ) + async fn identical_update_is_quiet() { + let h = harness().await; + h.announcement + .update(crate::origin::Route::default().with_hops(pub_hops()).with_cost(7)) .unwrap(); settle().await; - - match h.wire.take_announces().as_slice() { - [ - lite::AnnounceBroadcast::Restart { - id: 0, - hops: sent, - cost, - }, - ] => { - assert_eq!(sent, &hops); - assert_eq!(*cost, COLD_COST); - } - other => panic!("expected the failover restart, got {other:?}"), - } - - // The pending restore went with it: the old deadline passes silently. - tokio::time::sleep(Duration::from_secs(30)).await; h.assert_idle(); } - /// The warm edge has no hysteresis: a viewer arriving on a cold - /// advertisement re-prices to zero immediately. + /// A route whose chain contains the excluded peer is invisible to that peer's + /// announce stream (control-plane split horizon via the cursor). #[tokio::test(start_paused = true)] - async fn demand_reprices_warm_immediately() { - let (mut h, _) = harness(false).await; - - let _track = h.downstream.track("video").unwrap(); - settle().await; + async fn excluded_routes_are_filtered() { + let peer = Hop::new(42).unwrap(); + let origin = Hop::new(1).unwrap().produce(); - match h.wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::Restart { id: 0, cost, .. }] => assert_eq!(*cost, WARM_COST), - other => panic!("expected the warm restart, got {other:?}"), - } - } + let tainted = Hops::try_from(vec![peer]).unwrap(); + let _tainted = origin + .announce("echoed", crate::origin::Route::default().with_hops(tainted)) + .unwrap(); + let _clean = origin + .announce("local", crate::origin::Route::default().with_hops(pub_hops())) + .unwrap(); - /// Spawn `run_announce` against the origin with the given `exclude_hop`, - /// capturing the wire. The per-peer variant of the `harness` setup. - fn spawn_announce( - consumer: origin::Consumer, - exclude_hop: u64, - ) -> (Wire, tokio::task::JoinHandle>) { let log = Log::default(); let writes = log.writes.clone(); + let consumer = origin.consume().excluding(peer); let mut stream = Stream:: { writer: Writer::new(SinkSend::new(log), VERSION), reader: Reader::new(PendingRecv, VERSION), }; let task = tokio::spawn(async move { let mut announced = consumer.announced(); - let self_hop = *consumer; - Publisher::run_announce( - TestRuntime::new(), - &mut stream, - &consumer, - &mut announced, - "", - self_hop, - exclude_hop, - VERSION, - ) - .await + let self_origin = *consumer; + TestPublisher::run_announce(&mut stream, &consumer, &mut announced, "", self_origin, VERSION).await }); - (Wire { writes, cursor: 0 }, task) - } - - /// A peer the active chain flows through receives the best clean standby - /// instead of nothing, and at the standby's own cost: the warm discount - /// applies only to the route we would actually serve everyone else from, - /// since serving this peer means opening a fresh ingest. - #[tokio::test(start_paused = true)] - async fn excluded_peer_receives_the_standby() { - let peer = Hop::new(33).unwrap(); - let origin = Hop::new(1).unwrap().produce(); - - // Active: free, but its chain flows through the peer. Standby: the same - // publisher reached directly, at its cold cost. - let tainted = Hops::try_from(vec![Hop::new(9).unwrap(), peer]).unwrap(); - let _a = origin - .create_broadcast( - "cam", - crate::broadcast::Route::new() - .with_hops(tainted.clone()) - .with_announce(true), - ) - .unwrap(); - settle().await; - let _b = origin - .create_broadcast( - "cam", - crate::broadcast::Route::new() - .with_hops(pub_hops()) - .with_cost(COLD) - .with_announce(true), - ) - .unwrap(); - settle().await; - - // A viewer warms the broadcast, so the serving route advertises zero. - let downstream = origin.consume().announced_broadcast("cam").await.unwrap(); - let _track = downstream.track("video").unwrap(); settle().await; - // An ordinary peer gets the active route, discounted for the demand. - let (mut wire, _task) = spawn_announce(origin.consume(), 0); - settle().await; - assert_eq!(wire.take_ok().active, 1); - match wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::Active { hops, cost, .. }] => { - assert_eq!(hops, &tainted); - assert_eq!(*cost, crate::broadcast::Cost::default()); - } - other => panic!("expected the active route, got {other:?}"), - } - - // The peer in the active chain gets the standby, undiscounted. - let (mut wire, _task) = spawn_announce(origin.consume(), peer.id()); - settle().await; - assert_eq!(wire.take_ok().active, 1); + let mut wire = Wire { writes, cursor: 0 }; + assert_eq!(wire.take_ok().active, 1, "only the clean route is announced"); match wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::Active { hops, cost, .. }] => { - assert_eq!(hops, &pub_hops()); - assert_eq!(*cost, COLD_COST); - } - other => panic!("expected the standby route, got {other:?}"), + [lite::AnnounceBroadcast::Active { suffix, .. }] => assert_eq!(suffix.as_str(), "local"), + other => panic!("expected the clean announce, got {other:?}"), } + task.abort(); } - /// A relay carrying a broadcast via its peer initially has nothing to - /// advertise to that peer; a standby with the same original publisher - /// attaching later must go out as a fresh announce, giving the peer the - /// route it needs to fail over (#2473, e2e finding 1). The active source - /// dying afterward changes nothing on this stream: the standby is already - /// the advertised route, so the failover is invisible to the peer. + /// A cost past the wire ceiling is clamped rather than rejected. #[tokio::test(start_paused = true)] - async fn standby_attach_announces_to_excluded_peer() { - let peer = Hop::new(33).unwrap(); - let origin = Hop::new(1).unwrap().produce(); - - // The active route: the broadcast as carried via the peer itself. - let via_peer = Hops::try_from(vec![Hop::new(9).unwrap(), peer]).unwrap(); - let source_a = origin - .create_broadcast( - "cam", - crate::broadcast::Route::new().with_hops(via_peer).with_announce(true), - ) - .unwrap(); - settle().await; - - // The peer sees nothing: its own hop is on the only route. - let (mut wire, task) = spawn_announce(origin.consume(), peer.id()); - settle().await; - assert_eq!(wire.take_ok().active, 0); - wire.assert_quiet(); - - // The standby (same first hop, reached directly) attaches later: a - // fresh announce toward the peer. - let _source_b = origin - .create_broadcast( - "cam", - crate::broadcast::Route::new() + async fn cost_clamps_to_the_wire_ceiling() { + let mut h = harness().await; + h.announcement + .update( + crate::origin::Route::default() .with_hops(pub_hops()) - .with_cost(COLD) - .with_announce(true), + .with_cost(u64::MAX), ) .unwrap(); settle().await; - match wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::Active { hops, cost, .. }] => { - assert_eq!(hops, &pub_hops()); - assert_eq!(*cost, COLD_COST); + match h.wire.take_announces().as_slice() { + [lite::AnnounceBroadcast::Restart { cost, .. }] => { + assert_eq!(*cost, crate::origin::Cost::new(crate::origin::MAX_COST)); } - other => panic!("expected the standby announce, got {other:?}"), + other => panic!("expected a clamped restart, got {other:?}"), } - - // The active source dying promotes the standby locally; the peer's - // advertisement is already that standby, so the wire stays quiet. - source_a.abort(Error::Dropped).unwrap(); - settle().await; - wire.assert_quiet(); - assert!(!task.is_finished(), "the announce loop ended unexpectedly"); - } - - /// The route swinging into the peer's chain retracts the announce (no clean - /// standby remains), and swinging back out re-announces fresh. - #[tokio::test(start_paused = true)] - async fn retracts_when_route_swings_through_peer() { - let peer = Hop::new(33).unwrap(); - let origin = Hop::new(1).unwrap().produce(); - let mut source = origin - .create_broadcast( - "cam", - crate::broadcast::Route::new() - .with_hops(pub_hops()) - .with_cost(COLD) - .with_announce(true), - ) - .unwrap(); - settle().await; - - let (mut wire, task) = spawn_announce(origin.consume(), peer.id()); - settle().await; - assert_eq!(wire.take_ok().active, 1); - match wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::Active { hops, .. }] => assert_eq!(hops, &pub_hops()), - other => panic!("expected the initial announce, got {other:?}"), - } - - // The same publisher, now reached through the peer: nothing left to - // advertise to them. - let through_peer = Hops::try_from(vec![Hop::new(9).unwrap(), peer]).unwrap(); - source - .set_route( - crate::broadcast::Route::new() - .with_hops(through_peer) - .with_cost(COLD) - .with_announce(true), - ) - .unwrap(); - settle().await; - match wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::EndedId { id: 0 }] => {} - other => panic!("expected the retract, got {other:?}"), - } - - // Swinging back out is a fresh announce with the next id. - source - .set_route( - crate::broadcast::Route::new() - .with_hops(pub_hops()) - .with_cost(COLD) - .with_announce(true), - ) - .unwrap(); - settle().await; - match wire.take_announces().as_slice() { - [lite::AnnounceBroadcast::Active { hops, .. }] => assert_eq!(hops, &pub_hops()), - other => panic!("expected the re-announce, got {other:?}"), - } - assert!(!task.is_finished(), "the announce loop ended unexpectedly"); - } - - /// A locally created route may set `Route::cost` past what a varint can carry, - /// since nothing validates the public field. The advertised cost has to clamp, - /// or forwarding the announce fails to encode and takes the announce stream - /// with it. - #[test] - fn outgoing_cost_clamps_to_the_wire_ceiling() { - use crate::broadcast; - - let mut producer = broadcast::Info::new().produce(); - producer - .set_route(broadcast::Route::announced().with_cost(u64::MAX)) - .unwrap(); - let consumer = producer.consume(); - let route = consumer.route(); - let demand = consumer.demand(); - - let cost = outgoing_cost(Version::Lite06Wip, &demand, &route, false); - assert_eq!(cost, broadcast::Cost::new(broadcast::MAX_COST)); - - let mut buf = Vec::new(); - cost.encode(&mut buf, Version::Lite06Wip) - .expect("an advertised cost must always encode"); - } - - /// A draining serving route must advertise its drain cost even while the - /// broadcast has demand. The carrying discount exists because the ingress is - /// already paid for; a draining ingress is going away, and masking it with - /// zero would keep downstream peers glued to a path about to vanish instead - /// of migrating to another edge while the handover is seamless. - #[test] - fn outgoing_cost_advertises_a_drain_despite_demand() { - use crate::broadcast; - - let mut producer = broadcast::Info::new().produce(); - producer - .set_route(broadcast::Route::announced().with_cost(broadcast::DRAIN_COST)) - .unwrap(); - let consumer = producer.consume(); - let route = consumer.route(); - let demand = consumer.demand(); - - // A consumed track: demand.is_used() is true, which is exactly the case - // that used to collapse the cost to zero. - let track = producer.create_track("video", None).unwrap(); - let _reader = track.consume(); - assert!(demand.is_used(), "the consumed track should register demand"); - - let cost = outgoing_cost(Version::Lite06Wip, &demand, &route, true); - assert_eq!(cost, broadcast::Cost::DRAIN); - - // A drain that arrived over the wire propagates through a carrying relay: - // the upstream's ceiling plus our link price saturates back to the - // ceiling, which pierces this hop's discount too. Without that, each - // carrying hop would re-mask the drain as cost 0. - let forwarded = broadcast::Cost::DRAIN.charged(5); - producer - .set_route(broadcast::Route::announced().with_cost(forwarded)) - .unwrap(); - let route = consumer.route(); - let cost = outgoing_cost(Version::Lite06Wip, &demand, &route, true); - assert_eq!(cost, broadcast::Cost::DRAIN); - - // A healthy serving route with demand still gets the carrying discount, on - // the warm half only: the cold path is what a peer ranks us by. - producer.set_route(broadcast::Route::announced().with_cost(7)).unwrap(); - let route = consumer.route(); - let cost = outgoing_cost(Version::Lite06Wip, &demand, &route, true); - assert_eq!(cost, broadcast::Cost { warm: 0, cold: 7 }); } } @@ -3719,7 +2987,7 @@ mod tests { /// The tokio-backed test runtime, matching the fake transport. type TestRuntime = crate::runtime::tokio_test::Tokio; - /// A peer that declares no Hop ID in its SETUP is split-horizoned by the identity + /// A peer that declares no origin in its SETUP is split-horizoned by the identity /// the caller assigned it, on the data plane and not just the announce filter. /// Otherwise it can subscribe its way back to content that already flowed through /// it, which is the loop the announce filter exists to prevent. @@ -3731,28 +2999,17 @@ mod tests { let mut echoed_hops = Hops::new(); echoed_hops.push(assigned).unwrap(); - let _echoed = origin - .create_broadcast( - "echoed", - crate::broadcast::Route::new() - .with_hops(echoed_hops) - .with_announce(true), - ) + let (_echoed, _echoed_server) = origin + .announce_served("echoed", crate::origin::Route::default().with_hops(echoed_hops)) .unwrap(); let mut local_hops = Hops::new(); local_hops.push(upstream).unwrap(); - let _local = origin - .create_broadcast( - "local", - crate::broadcast::Route::new().with_hops(local_hops).with_announce(true), - ) + let (_local, _local_server) = origin + .announce_served("local", crate::origin::Route::default().with_hops(local_hops)) .unwrap(); - // Broadcast visibility is deferred until the executor ticks. - tokio::time::sleep(std::time::Duration::from_millis(1)).await; - - // A SETUP that declares no Hop ID of its own, so only the assigned one applies. + // A SETUP that declares no origin of its own, so only the assigned one applies. let peer_setup = crate::lite::PeerSetup::default(); peer_setup.set(crate::lite::Setup::default()); let (_, goaway) = crate::goaway::Handle::new(true); @@ -3768,12 +3025,13 @@ mod tests { }); let serving = kio::wait(|waiter| publisher.shared.poll_serving_origin(waiter)).await; + use futures::FutureExt; assert!( - serving.get_broadcast("echoed").is_none(), + serving.request_broadcast("echoed/x").now_or_never().unwrap().is_err(), "served the peer its own route" ); assert!( - serving.get_broadcast("local").is_some(), + serving.request_broadcast("local/x").now_or_never().is_none(), "withheld an independent route" ); } @@ -3786,47 +3044,34 @@ mod tests { async fn announce_init_applies_route_selection() { let assigned = crate::Hop::new(777).unwrap(); let clean_publisher = crate::Hop::new(778).unwrap(); - let self_hop = crate::Hop::new(1).unwrap(); - let origin = crate::origin::Info::new(self_hop).produce(); + let self_origin = crate::Hop::new(1).unwrap(); + let origin = crate::origin::Info::new(self_origin).produce(); let mut tainted_hops = Hops::new(); tainted_hops.push(assigned).unwrap(); let _tainted = origin - .create_broadcast( - "echoed", - crate::broadcast::Route::new() - .with_hops(tainted_hops) - .with_announce(true), - ) + .announce("echoed", crate::origin::Route::default().with_hops(tainted_hops)) .unwrap(); let mut clean_hops = Hops::new(); clean_hops.push(clean_publisher).unwrap(); let _clean = origin - .create_broadcast( - "local", - crate::broadcast::Route::new().with_hops(clean_hops).with_announce(true), - ) + .announce("local", crate::origin::Route::default().with_hops(clean_hops)) .unwrap(); - // Broadcast visibility is deferred until the executor ticks. - tokio::time::sleep(Duration::from_millis(1)).await; - let gate = kio::Producer::new(true); let session = SinkSession::gated_bi(gate.consume()); let log = session.log.clone(); let mut stream = Stream::open(&mut session.clone(), Version::Lite01).await.unwrap(); - let consumer = origin.consume(); + let consumer = origin.consume().excluding(assigned); let mut announced = consumer.announced(); - let mut run = std::pin::pin!(Publisher::run_announce( - TestRuntime::new(), + let mut run = std::pin::pin!(Publisher::::run_announce( &mut stream, &consumer, &mut announced, crate::Path::new(""), - self_hop, - assigned.id(), + self_origin, Version::Lite01, )); assert!(futures::poll!(run.as_mut()).is_pending()); diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 0c984ef3fa2..6fd77f15f1e 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -47,12 +47,12 @@ pub(super) struct Subscriber { origin: origin::Producer, recv_bandwidth: Option, - // Session-level Hop ID shared with the Publisher. Used to drop reflected + // Session-level origin id shared with the Publisher. Used to drop reflected // announces: any incoming announce whose hop chain already passed through us // has looped, so it is neither used as a route nor forwarded. On lite-04/05 // we also ask the peer to filter them out (AnnounceRequest.exclude_hop) so // they never hit the wire, but this check is what makes it correct. - self_hop: crate::Hop, + self_origin: crate::Hop, // The origin stamped into the hop chain of broadcasts from versions that // don't carry real hop ids on the wire (Lite01/02/03), and into the // placeholder entries Lite03 sends in place of real ids. @@ -65,10 +65,10 @@ pub(super) struct Subscriber { // accepted session a fresh id so its routes are at least distinguishable from // another session's, while a client only assigns one it knows out of band. Either // way the peer never learns the id, so only we can exclude it for loop detection. - session_hop: crate::Hop, + session_origin: crate::Hop, // The identity assigned to the peer by the caller (`Client::with_peer_hop`, // or the per-session default a server hands every request), standing in wherever - // the peer declines to declare one (an AnnounceOk reporting Hop ID 0). + // the peer declines to declare one (an AnnounceOk reporting origin id 0). peer_hop: Option, subscribes: Lock>, next_id: Arc, @@ -97,13 +97,13 @@ impl Subscriber { // origin we publish into so it matches the relay identity across // every session sharing that origin, required for cross-session // loop detection. - let self_hop = *config.origin; + let self_origin = *config.origin; Self { session: config.session, origin: config.origin, recv_bandwidth: config.recv_bandwidth, - self_hop, - session_hop: config.peer_hop.unwrap_or(crate::Hop::UNKNOWN), + self_origin, + session_origin: config.peer_hop.unwrap_or(crate::Hop::UNKNOWN), peer_hop: config.peer_hop, subscribes: Default::default(), next_id: Default::default(), @@ -243,11 +243,10 @@ impl Subscriber { // The route cost off the wire, i.e. as the peer advertised it. // [`Cost::UNKNOWN`] before lite-06, leaving the hop chain as the only // routing input as before. - cost: crate::broadcast::Cost, - // This link's price, added to the wire cost; the pre-charge value is kept - // on the route so the origin's handover gate can tell a warm peer apart. + cost: crate::origin::Cost, + // This link's price, added to the wire cost. link_cost: u64, - // Lite05+: the announce sender's Hop ID (from AnnounceOk). The sender no + // Lite05+: the announce sender's origin id (from AnnounceOk). The sender no // longer stamps itself onto the chain, so we append it here to reconstruct // the full `[src...sender]` chain Lite04 stored. None for older versions, // where the sender already appended itself. @@ -289,7 +288,7 @@ impl Subscriber { // via AnnounceRequest.exclude_hop, but that is only an optimization: // this is the authoritative cluster-loop check, and the only one on // every other version. - if hops.contains(&self.self_hop) { + if hops.contains(&self.self_origin) { tracing::debug!(broadcast = %self.log_path(&path), "dropping reflected announce"); return Ok(false); } @@ -302,7 +301,7 @@ impl Subscriber { // // The rewrite fails if the chain already names this session, which would put one // id in it twice: a loop, and one a cluster receiver must close the session over. - if self.version_lacks_hops() && hops.replace_first(crate::Hop::UNKNOWN, self.session_hop).is_err() { + if self.version_lacks_hops() && hops.replace_first(crate::Hop::UNKNOWN, self.session_origin).is_err() { tracing::debug!(broadcast = %self.log_path(&path), "dropping announce reflected by its session"); return Ok(false); } @@ -313,55 +312,39 @@ impl Subscriber { // caller can assign an identity via `with_peer_hop`, substituted where // the AnnounceOk is read). if hops.is_empty() { - hops.push(self.session_hop) + hops.push(self.session_origin) .expect("an empty hop chain always has room for one entry, and repeats nothing"); } - tracing::debug!(broadcast = %self.log_path(&path), hops = hops.len(), "announce"); + tracing::debug!(route = %self.log_path(&path), hops = hops.len(), "announce"); - // The first hop of the reconstructed chain identifies the original - // publisher; a later restart advertising a different first hop is a new - // broadcast, not an alternate route to this one. - let publisher = hops.iter().next().copied().unwrap_or(self.session_hop); - - // Create this session's source feeding the origin-owned broadcast at the - // path. The first source creates and announces the broadcast; later sources - // (other sessions announcing the same path) join it silently as standbys. - // An error means the path is outside our scope, so don't serve it. - // Reflections are already filtered above. + // Announce this session's route into the origin: paths under the prefix + // resolve through this session on demand. An error means the prefix is + // disjoint from our scope, so don't serve it. Reflections are already + // filtered above. let route = self.announced_route(hops, cost, link_cost); - let Ok(source) = self.origin.create_broadcast(&path, route) else { + let Ok((announcement, server)) = self.origin.announce_served(&path, route.clone()) else { return Ok(false); }; - // Serve the origin's track requests for this source in the background; the - // announce loop keeps the producer so an unannounce can finish it. - let _ = self.sources.try_push((path.clone(), source.dynamic())); - announced.attach(path, AnnouncedRoute::new(source, publisher)); + announced.attach(path, AnnouncedRoute::new(route, announcement, server)); Ok(true) } - /// The route to attach to a broadcast this peer announced, charging our link's - /// price on top of the cost it advertised. + /// The route to announce for a prefix this peer advertised, charging our + /// link's price on top of the cost it advertised. /// /// Once the peer has sent a GOAWAY every route it announces starts out draining, /// including a restart of one already attached: a connection on its way out must /// not win selection, however good the path it advertises looks. - fn announced_route( - &self, - hops: crate::Hops, - cost: crate::broadcast::Cost, - link_cost: u64, - ) -> crate::broadcast::Route { - let mut route = crate::broadcast::Route::new() + fn announced_route(&self, hops: crate::Hops, cost: crate::origin::Cost, link_cost: u64) -> crate::origin::Route { + let mut route = crate::origin::Route::default() .with_hops(hops) - .with_cost(cost.charged(link_cost)) - .with_announce(true); - route.advertised = cost; + .with_cost(cost.charged(link_cost)); if self.going_away.is_set() { - route.cost = crate::broadcast::Cost::DRAIN; + route.cost = crate::origin::Cost::DRAIN; } route @@ -386,9 +369,9 @@ impl Subscriber { path: PathOwned, mut hops: crate::Hops, // The route cost off the wire and this link's price. See `start_announce`. - cost: crate::broadcast::Cost, + cost: crate::origin::Cost, link_cost: u64, - // Lite05+: the announce sender's Hop ID (from AnnounceOk), appended here to + // Lite05+: the announce sender's origin id (from AnnounceOk), appended here to // rebuild the full chain since the sender no longer stamps itself. None for older // versions. See `start_announce`. responder_origin: Option, @@ -400,9 +383,9 @@ impl Subscriber { Some(responder) => { (responder != crate::Hop::UNKNOWN && hops.contains(&responder)) || hops.push(responder).is_err() - || hops.contains(&self.self_hop) + || hops.contains(&self.self_origin) } - None => hops.contains(&self.self_hop), + None => hops.contains(&self.self_origin), }; if reflected { tracing::debug!(broadcast = %self.log_path(&path), "dropping reflected restart"); @@ -410,35 +393,21 @@ impl Subscriber { return Ok(false); } - tracing::debug!(broadcast = %self.log_path(&path), hops = hops.len(), "restart"); - let publisher = hops.iter().next().copied().unwrap_or(self.session_hop); + tracing::debug!(route = %self.log_path(&path), hops = hops.len(), "restart"); let metadata = self.announced_route(hops, cost, link_cost); - match announced.attached(&path) { - Some(entry) if entry.publisher != publisher || publisher == crate::Hop::UNKNOWN => { - // A different original publisher, or no identity at all (UNKNOWN - // never proves continuity): a brand-new broadcast may have replaced - // the old one at this path. Detach gracefully (downstream unannounces - // if this was the last source) and attach fresh below; cached - // TRACK_INFO and subscriptions must not carry over. - announced.declined(path.clone()); - } - Some(entry) => { - // Same publisher, new path: update the source's route in place. - // In-flight tracks keep flowing; the origin only hands over if the - // winning source changed. - entry.set_route(metadata); - return Ok(true); - } - None => {} + // A restart is a metadata update: the route keeps its prefix (and its + // served paths) and re-prices in place. In-flight tracks keep flowing. + if let Some(entry) = announced.attached(&path) { + entry.update(metadata); + return Ok(true); } - let Ok(source) = self.origin.create_broadcast(&path, metadata) else { + let Ok((announcement, server)) = self.origin.announce_served(&path, metadata.clone()) else { announced.declined(path); return Ok(false); }; - let _ = self.sources.try_push((path.clone(), source.dynamic())); - announced.attach(path, AnnouncedRoute::new(source, publisher)); + announced.attach(path, AnnouncedRoute::new(metadata, announcement, server)); Ok(true) } @@ -1153,7 +1122,7 @@ impl AnnouncePrefix { // filter. stream.writer.buffer(&lite::AnnounceRequest { prefix: self.prefix.as_path(), - exclude_hop: self.subscriber.self_hop.id(), + exclude_hop: self.subscriber.self_origin.id(), })?; self.state = PrefixState::Send { stream }; } @@ -1171,7 +1140,7 @@ impl AnnouncePrefix { }; } PrefixState::ReadOk { stream } => { - // Lite05+: the publisher reports its own Hop ID, which we stamp onto + // Lite05+: the publisher reports its own origin id, which we stamp onto // every received Announce's hop chain since it no longer does so itself. // Its `active` count marks where the initial set ends; nothing here needs // that boundary, so it is read and dropped. Callers that must not race an @@ -1180,9 +1149,9 @@ impl AnnouncePrefix { let ok = ready!(stream.reader.poll_decode::(&mut cx))?; // A peer may legally report id 0 (no identity). When the caller assigned // it one, stand that in so the route isn't loop-blind. - let origin = match ok.hop.id() { - 0 => self.subscriber.peer_hop.unwrap_or(ok.hop), - _ => ok.hop, + let origin = match ok.origin.id() { + 0 => self.subscriber.peer_hop.unwrap_or(ok.origin), + _ => ok.origin, }; let PrefixState::ReadOk { stream } = std::mem::replace(&mut self.state, PrefixState::Open) else { unreachable!() @@ -1228,7 +1197,7 @@ impl AnnouncePrefix { self.subscriber.start_announce( path.clone(), crate::Hops::new(), - crate::broadcast::Cost::UNKNOWN, + crate::origin::Cost::UNKNOWN, 0, run.responder_origin, &mut run.announced, @@ -1241,21 +1210,42 @@ impl AnnouncePrefix { self.state = PrefixState::Run { stream, run }; } PrefixState::Run { stream, run } => { + // A draining peer usually stops announcing, so react to the + // GOAWAY itself; waiting for another message would leave the + // route primary until the session finally closed. Idempotent, + // since the signal stays set. + if self.subscriber.going_away.poll(waiter).is_ready() { + run.announced.drain(); + } + // Drain every buffered announce BEFORE serving requests: a route + // this pass attaches must have its request queue polled (and this + // machine's waiter registered on it) below, in the same pass. + // Serving first and then parking on the decode would strand a + // request that arrives in between: its wake finds no waiter, and + // nothing else re-polls this machine. loop { - let Some(announce) = - ready!(stream.reader.poll_decode_maybe::(&mut cx))? - else { - // The publisher FINed: it has nothing (more) to announce for this - // prefix (e.g. a publish-only peer). That's a clean completion of - // this announce stream, not a session error, so finish our side - // and return Ok. Tearing down only the announce stream is correct - // since no further progress can be made, but we must not - // propagate an error that would kill the whole connection. - stream.writer.finish().ok(); - return Poll::Ready(Ok(())); - }; - self.subscriber.handle_announce(&self.prefix, announce, run)?; + match stream.reader.poll_decode_maybe::(&mut cx) { + Poll::Ready(Ok(Some(announce))) => { + self.subscriber.handle_announce(&self.prefix, announce, run)?; + } + Poll::Ready(Ok(None)) => { + // The publisher FINed: it has nothing (more) to announce for this + // prefix (e.g. a publish-only peer). That's a clean completion of + // this announce stream, not a session error, so finish our side + // and return Ok. Tearing down only the announce stream is correct + // since no further progress can be made, but we must not + // propagate an error that would kill the whole connection. + stream.writer.finish().ok(); + return Poll::Ready(Ok(())); + } + Poll::Ready(Err(err)) => return Poll::Ready(Err(err)), + Poll::Pending => break, + } } + // Materialize requested paths under the attached routes; leaves the + // waiter registered on every route's request queue. + run.announced.poll_serve(&self.subscriber, waiter); + return Poll::Pending; } } } @@ -1297,13 +1287,6 @@ impl kio::Task for SourceServe { // Session gone. return Poll::Ready(()); } - // A draining peer usually stops announcing, so react to the signal - // itself; waiting for another message would leave the route primary - // until the session finally closed. Idempotent, since the signal - // stays set and this task wakes for other reasons too. - if self.subscriber.going_away.poll(waiter).is_ready() { - self.dynamic.drain(); - } match self.dynamic.poll_requested_track(waiter) { Poll::Ready(Ok(request)) => { let serve = TrackServe { @@ -1868,7 +1851,7 @@ mod tests { .start_announce( path.clone(), crate::Hops::new(), - crate::broadcast::Cost::default(), + crate::origin::Cost::default(), 0, Some(assigned), &mut announced, @@ -1884,7 +1867,7 @@ mod tests { subscriber.start_announce( path, reflected, - crate::broadcast::Cost::default(), + crate::origin::Cost::default(), 0, Some(assigned), &mut announced, @@ -1929,7 +1912,7 @@ mod tests { .start_announce( path.clone(), hops, - crate::broadcast::Cost::default(), + crate::origin::Cost::default(), 0, None, &mut announced @@ -1943,7 +1926,7 @@ mod tests { fresh.push(crate::Hop::new(7).unwrap()).unwrap(); assert!( matches!( - subscriber.start_announce(path, fresh, crate::broadcast::Cost::default(), 0, None, &mut announced), + subscriber.start_announce(path, fresh, crate::origin::Cost::default(), 0, None, &mut announced), Err(Error::ProtocolViolation) ), "a declined announce still holds its path, so a second start for it is a violation", @@ -1976,7 +1959,7 @@ mod tests { .start_announce( path.clone(), reflected, - crate::broadcast::Cost::default(), + crate::origin::Cost::default(), 0, Some(assigned), &mut announced, @@ -1992,7 +1975,7 @@ mod tests { .start_announce( path, hops, - crate::broadcast::Cost::default(), + crate::origin::Cost::default(), 0, Some(assigned), &mut announced, @@ -2022,7 +2005,7 @@ mod tests { going_away: Default::default(), }); - // The sender reports Hop ID 0, so it takes the assigned identity, and its chain + // The sender reports origin 0, so it takes the assigned identity, and its chain // already carries that identity: the route came back through it. let mut hops = crate::Hops::new(); hops.push(assigned).unwrap(); @@ -2032,7 +2015,7 @@ mod tests { .start_announce( Path::new("room/host").to_owned(), hops, - crate::broadcast::Cost::default(), + crate::origin::Cost::default(), 0, Some(assigned), &mut announced, @@ -2072,7 +2055,7 @@ mod tests { .start_announce( Path::new("room/host").to_owned(), crate::Hops::new(), - crate::broadcast::Cost::UNKNOWN, + crate::origin::Cost::UNKNOWN, 0, None, &mut announced, @@ -2080,15 +2063,14 @@ mod tests { .unwrap(); assert!(accepted); - // Broadcast visibility is deferred until the executor ticks. - tokio::time::sleep(Duration::from_millis(1)).await; - - let broadcast = consumer.get_broadcast("room/host").unwrap(); - let hops: Vec<_> = broadcast.routes()[0].hops.iter().copied().collect(); + // The route is announced synchronously. + let mut cursor = consumer.announced(); + let route = cursor.assert_next_active("room/host"); + let hops: Vec<_> = route.hops.iter().copied().collect(); assert_eq!(hops, vec![assigned]); } - /// A peer with no assigned identity is attributed the reserved Hop ID 0 + /// A peer with no assigned identity is attributed the reserved origin 0 /// (UNKNOWN). This layer never mints one of its own: whether an anonymous peer /// gets an identity, and whether two of its sessions share it, is the caller's /// policy, and a minted id here would be indistinguishable from a declared one. @@ -2101,16 +2083,16 @@ mod tests { .start_announce( Path::new("room/host").to_owned(), crate::Hops::new(), - crate::broadcast::Cost::UNKNOWN, + crate::origin::Cost::UNKNOWN, 0, None, &mut announced, ) .unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - let broadcast = consumer.get_broadcast("room/host").unwrap(); - let hops: Vec<_> = broadcast.routes()[0].hops.iter().copied().collect(); + let mut cursor = consumer.announced(); + let route = cursor.assert_next_active("room/host"); + let hops: Vec<_> = route.hops.iter().copied().collect(); assert_eq!(hops, vec![crate::Hop::UNKNOWN]); } @@ -2130,12 +2112,10 @@ mod tests { (subscriber, consumer) } - /// An UNKNOWN (0) first hop identifies nothing, so a restart advertising - /// UNKNOWN again may be a different publisher entirely: the old broadcast must - /// be replaced, not updated in place. Regression: plain `==` on the publisher - /// id treated 0 == 0 as content-continuous and spliced unrelated broadcasts. + /// A restart re-prices the announced route in place: consumers observe another + /// active update with the new metadata rather than a retract-and-announce. #[tokio::test] - async fn unknown_publisher_restart_replaces() { + async fn restart_updates_the_route_in_place() { let (mut subscriber, consumer) = restart_subscriber(SinkSession::new(Default::default())); let mut announced = Announced::default(); @@ -2144,83 +2124,40 @@ mod tests { .start_announce( path.clone(), crate::Hops::new(), - crate::broadcast::Cost::UNKNOWN, + crate::origin::Cost::UNKNOWN, 0, - Some(crate::Hop::UNKNOWN), + Some(crate::Hop::new(7).unwrap()), &mut announced, ) .unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - let before = consumer.get_broadcast("room/host").unwrap(); - - subscriber - .restart_announce( - path, - crate::Hops::new(), - crate::broadcast::Cost::UNKNOWN, - 0, - Some(crate::Hop::UNKNOWN), - &mut announced, - ) - .unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - - assert!(before.is_closed(), "an UNKNOWN restart must replace the broadcast"); - assert!( - consumer.get_broadcast("room/host").is_some(), - "the fresh source re-attaches" - ); - } - - /// The counterpart: a real (non-zero) publisher id restarting is a route - /// change for the same content, so the broadcast survives in place. - #[tokio::test] - async fn known_publisher_restart_updates_in_place() { - let (mut subscriber, consumer) = restart_subscriber(SinkSession::new(Default::default())); - let publisher = crate::Hop::new(7).unwrap(); - let mut announced = Announced::default(); - let path = Path::new("room/host").to_owned(); - subscriber - .start_announce( - path.clone(), - crate::Hops::new(), - crate::broadcast::Cost::UNKNOWN, - 0, - Some(publisher), - &mut announced, - ) - .unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - let before = consumer.get_broadcast("room/host").unwrap(); + let mut cursor = consumer.announced(); + cursor.assert_next_active("room/host"); subscriber .restart_announce( path, crate::Hops::new(), - crate::broadcast::Cost::new(5), + crate::origin::Cost::new(5), 0, - Some(publisher), + Some(crate::Hop::new(7).unwrap()), &mut announced, ) .unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - assert!( - !before.is_closed(), - "a known publisher restart keeps the broadcast live" - ); + let route = cursor.assert_next_active("room/host"); + assert_eq!(route.cost, crate::origin::Cost::new(5).charged(0)); } - /// An announce stream that dies without an explicit `ended` closes the broadcast + /// An announce stream that dies without an explicit `ended` retracts the route /// as promptly as an explicit retraction: a route into a dead session must not - /// stay announced, so viewers observe the loss instead of a stale route. + /// stay announced. /// - /// This falls out of `Announced` being a local whose route guards drop, + /// This falls out of `Announced` being a local whose announcements drop, /// which is exactly what makes it worth pinning: a refactor that hoisted the map /// to the session (outliving the stream) would leak the announcement instead. #[tokio::test(start_paused = true)] - async fn a_lost_announce_stream_closes_the_broadcast() { + async fn a_lost_announce_stream_retracts_the_route() { let origin = crate::origin::Info::new(crate::Hop::new(1).unwrap()).produce(); let consumer = origin.consume(); let mut subscriber = Subscriber::new(SubscriberConfig { @@ -2241,45 +2178,37 @@ mod tests { .start_announce( path.clone(), hops, - crate::broadcast::Cost::default(), + crate::origin::Cost::default(), 1, None, &mut announced, ) .unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - assert!(consumer.get_broadcast("room/host").is_some()); + let mut cursor = consumer.announced(); + cursor.assert_next_active("room/host"); // The stream ends without retracting anything: the map dies with it and the - // broadcast closes. + // route retracts. drop(announced); - tokio::time::sleep(Duration::from_millis(1)).await; - assert!( - consumer.get_broadcast("room/host").is_none(), - "an abnormal stream loss must close the broadcast", - ); + cursor.assert_next_ended("room/host"); - // An explicit retraction closes it the same way. + // An explicit retraction retracts it the same way. let hops = crate::Hops::try_from(vec![crate::Hop::new(7).unwrap()]).unwrap(); let mut announced = Announced::default(); subscriber .start_announce( path.clone(), hops, - crate::broadcast::Cost::default(), + crate::origin::Cost::default(), 1, None, &mut announced, ) .unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; + cursor.assert_next_active("room/host"); assert!(announced.contains(&path), "the announce was not recorded"); announced.retire(&path); - tokio::time::sleep(Duration::from_millis(1)).await; - assert!( - consumer.get_broadcast("room/host").is_none(), - "an explicit retraction must close the broadcast", - ); + cursor.assert_next_ended("room/host"); } } @@ -2393,34 +2322,95 @@ impl Announced { route.finish(); } } + + /// Serve queued requests on every attached route: mint a source per requested + /// path, hand its dynamic to the driver's serve machines, and answer the + /// requester with its consumer. + fn poll_serve(&mut self, subscriber: &Subscriber, waiter: &kio::Waiter) { + let root = subscriber.origin.root().to_owned(); + for entry in self.0.values_mut().flatten() { + while let Poll::Ready(Ok(request)) = entry.server.poll_requested_broadcast(waiter) { + // The request path is absolute; the wire (and our origin handle) + // speak paths relative to the session's root. + let Some(path) = request.path().strip_prefix(&root) else { + // Outside our root: nothing we could name on the wire. + continue; + }; + let path = path.to_owned(); + let source = subscriber.origin.create_source(&path); + let _ = subscriber.sources.try_push((path.clone(), source.dynamic())); + request.accept(&source); + entry + .sources + .insert(path, crate::model::broadcast::SourceGuard::new(source)); + } + } + } + + /// Re-price every attached route to a draining cost (the peer sent a GOAWAY). + fn drain(&mut self) { + for entry in self.0.values_mut().flatten() { + entry.drain(); + } + } } -/// The source created for one received announce, remembering the publisher -/// identity (the first hop of the reconstructed chain) so a restart can tell an -/// alternate route to the same broadcast from a brand-new broadcast. +/// One received announce: the route announced into the origin, its request +/// queue, and the sources minted to serve requested paths beneath it. struct AnnouncedRoute { - source: crate::model::broadcast::SourceGuard, - publisher: crate::Hop, + /// The route as last announced (post-charge), so a drain can re-price it + /// without recomputing the chain. + route: crate::origin::Route, + announcement: crate::announce::Producer, + server: crate::model::RouteServer, + /// One minted source per requested path, finished on a clean retraction and + /// aborted (via drop) when the session dies. + sources: HashMap, + /// Whether the GOAWAY drain already re-priced this route. + drained: bool, } impl AnnouncedRoute { - fn new(source: crate::broadcast::Producer, publisher: crate::Hop) -> Self { + fn new( + route: crate::origin::Route, + announcement: crate::announce::Producer, + server: crate::model::RouteServer, + ) -> Self { Self { - source: crate::model::broadcast::SourceGuard::new(source), - publisher, + route, + announcement, + server, + sources: HashMap::new(), + drained: false, } } - /// The peer deliberately retracted the path: finish the source so the origin - /// detaches it immediately (unannouncing downstream if it was the last). + /// The peer deliberately retracted the route: finish the minted sources so + /// their consumers observe a clean end, and retract the announcement. fn finish(self) { - self.source.finish(); + for (_, source) in self.sources { + source.finish(); + } } - /// Update the source's advertised route in place (a restart on the same - /// publisher). - fn set_route(&mut self, route: crate::broadcast::Route) { - self.source.set_route(route); + /// Update the announced route in place (a restart). + fn update(&mut self, route: crate::origin::Route) { + self.route = route.clone(); + self.drained = false; + let _ = self.announcement.update(route); + } + + /// Re-price the route to [`crate::origin::Cost::DRAIN`] (the peer sent a + /// GOAWAY): every other candidate outranks it while it stays selectable as + /// the last path. Idempotent, since the signal stays set. + fn drain(&mut self) { + if self.drained { + return; + } + self.drained = true; + let mut route = self.route.clone(); + route.cost = crate::origin::Cost::DRAIN; + let _ = self.announcement.update(route); } } @@ -2995,8 +2985,11 @@ enum ServeMode { impl ServeLoop { fn new(serve: &TrackServe, request: track::Request, info: track::Info, timescale: Option) -> Self { + // Register the fetch handler before accepting: `accept` releases the + // request's own fetch gate, and a cache-miss fetch queued while TRACK_INFO + // was in flight would be drained as NotFound in the gap. + let dynamic = request.dynamic(); let serving = request.accept(info); - let dynamic = serving.dynamic(); Self { serving, dynamic, diff --git a/rs/moq-net/src/model/broadcast.rs b/rs/moq-net/src/model/broadcast.rs index 33f1c66a524..82f7d8bc6ae 100644 --- a/rs/moq-net/src/model/broadcast.rs +++ b/rs/moq-net/src/model/broadcast.rs @@ -5,25 +5,22 @@ //! fill. Both handles are refcounted clones of one broadcast, which closes on //! [`Producer::finish`] or when the last producer drops. //! -//! [Info] is the static metadata; [Route] is the dynamic path the broadcast takes to -//! reach an origin, including whether it is announced to subscribers. +//! [Info] is the broadcast's static metadata, fixed for its lifetime. use crate::{stats, track}; use std::{ collections::{HashMap, VecDeque}, sync::Arc, task::{Poll, ready}, - time::Duration, }; use crate::Error; -use super::{Hop, Hops, Requests, WeakCache}; +use super::{Requests, WeakCache}; /// A collection of media tracks that can be published and subscribed to. /// /// Create via [`Info::produce`] to obtain both [`Producer`] and [`Consumer`] pair. -/// This is the broadcast's static identity, fixed for its lifetime; the path it -/// takes to get here is the dynamic [`Route`], observed via [`Consumer::route`]. +/// This is the broadcast's static identity, fixed for its lifetime. #[derive(Clone, Debug, Default)] #[non_exhaustive] pub struct Info { @@ -65,288 +62,6 @@ impl Info { } } -/// The highest value either half of a [`Cost`] can take, and where cost -/// accumulation saturates. -/// -/// The ceiling is the wire's, not the model's: lite-06 carries each cost as a QUIC -/// varint, which tops out at 2^62-1, so a larger value could be selected on but -/// never forwarded. -pub const MAX_COST: u64 = (1 << 62) - 1; - -/// The cost given to a route whose session is draining, so every other candidate -/// outranks it while it stays selectable as the last path to the content. -/// -/// A session sets this on its routes when its peer sends a GOAWAY. Draining is -/// deliberately not a distinct state: cost is the whole mechanism, so a route -/// whose accumulated cost saturates the wire ceiling ranks (and is treated) -/// identically, as a path of last resort. -/// -/// It is [`MAX_COST`] rather than a value beyond it for the reason above: a -/// draining route is still announced downstream, so its cost has to fit the wire. -pub const DRAIN_COST: u64 = MAX_COST; - -/// What pulling a broadcast via a route costs, in two magnitudes that accumulate -/// together and are compared in that order: lower [`warm`](Self::warm) wins, and -/// [`cold`](Self::cold) breaks the tie. -/// -/// Both are the same path priced against different cache states. `warm` is what one -/// more subscription would actually cost the mesh *right now*, so it collapses to -/// zero at any relay already carrying the broadcast: those upstream legs exist and -/// nobody re-pays for them. `cold` prices the identical path as if nothing were -/// cached, so it keeps flowing through a warm relay unchanged. -/// -/// Routing optimizes `warm`, which is what deduplicates a cluster onto one copy. But -/// once two relays are both warm they both advertise zero, and `warm` alone can no -/// longer say which of them should be the one that pulls: `cold` does, by naming the -/// relay whose own upstream is cheapest. It is also the stable quantity the origin's -/// handover gate descends, since adopting a parent adds a link to your own cold cost -/// and so can never leave you outranking it. Compare EIGRP's reported vs feasible -/// distance, which splits the same job the same way. -#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord)] -#[non_exhaustive] -pub struct Cost { - /// The cost of pulling the broadcast via this route as the mesh stands today, - /// accumulated per link and discounted to zero at every relay already carrying - /// it. Lower wins. - /// - /// The original publisher seeds it with its production cost (zero for a live - /// publish, something large for a standby that would have to start working, like - /// a cold transcoder), and each link adds its own configured price as the - /// announcement crosses it, so a route over a metered backbone ranks worse than - /// an equal-length one within a datacenter. - pub warm: u64, - - /// The same path with every warm discount removed: what pulling the broadcast - /// would cost if no relay along it were carrying anything. - /// - /// Accumulates exactly like [`warm`](Self::warm) but never restarts, so it stays - /// meaningful after the discount has flattened `warm` to zero. [`MAX_COST`] when - /// the peer's wire cannot express it (pre-lite-06, or the MoQ Cluster extension), - /// which ranks last rather than pretending the path is free. - pub cold: u64, -} - -impl Cost { - /// Both magnitudes at `cost`: an undiscounted route, which is what a publisher - /// seeding its production cost means. - pub const fn new(cost: u64) -> Self { - Self { warm: cost, cold: cost } - } - - /// The cost of a draining route: the ceiling in both magnitudes, so every other - /// candidate outranks it. See [`DRAIN_COST`]. - pub const DRAIN: Self = Self::new(DRAIN_COST); - - /// What a peer advertises when its wire has no room for a cost at all: free to - /// reach (leaving hop count as the effective metric, exactly as before route - /// cost existed) with an unknown cold path. - pub(crate) const UNKNOWN: Self = Self { - warm: 0, - cold: MAX_COST, - }; - - /// Add a link's price to both magnitudes, saturating at the largest cost the - /// wire can carry so a huge cost sorts last instead of wrapping around to best. - pub(crate) fn charged(self, link_cost: u64) -> Self { - Self { - warm: self.warm.saturating_add(link_cost).min(MAX_COST), - cold: self.cold.saturating_add(link_cost).min(MAX_COST), - } - } - - /// The cost to advertise from a relay that is actively carrying the broadcast: - /// nothing extra to serve one more subscriber, on the same cold path as before. - pub(crate) fn discounted(self) -> Self { - Self { - warm: 0, - cold: self.cold, - } - } - - /// Clamp both magnitudes to what a varint can carry, since a locally created - /// route can name an arbitrary `u64`. - pub(crate) fn clamped(self) -> Self { - Self { - warm: self.warm.min(MAX_COST), - cold: self.cold.min(MAX_COST), - } - } -} - -impl From for Cost { - fn from(cost: u64) -> Self { - Self::new(cost) - } -} - -/// The path a broadcast takes to reach this origin, and how preferable it is. -/// -/// Unlike [`Info`], the route is dynamic: it changes when the serving session fails -/// over, the upstream topology shifts, or the publisher re-advertises itself. -/// Publish a change with [`Producer::set_route`] and observe one with -/// [`Consumer::route_changed`]; downstream sessions forward updates as a restart -/// on the wire, so route churn never looks like a new broadcast. -#[derive(Clone, Debug, Default, PartialEq, Eq)] -#[non_exhaustive] -pub struct Route { - /// The chain of origins the broadcast has traversed, oldest first. Each relay - /// appends its own [`crate::Hop`] when forwarding; used for loop detection - /// and as the selection tie-break. - pub hops: Hops, - - /// What pulling the broadcast via this route costs, accumulated per link: - /// lower wins, with ties broken by hop length, then a deterministic hash, and - /// finally the most recently attached route. See [`Cost`]. - /// - /// Selection accepts any value, but only [`MAX_COST`] of it survives a hop: - /// forwarding clamps to what a varint can carry, so a cost set beyond the - /// ceiling ranks last locally and is advertised as the ceiling. - /// - /// Carried on the wire from lite-06. Older peers report neither magnitude, which - /// reads as free to reach with an unknown cold path, leaving the hop-count - /// tie-break as the effective metric exactly as before. - pub cost: Cost, - - /// The cost as the announcing peer advertised it, before this link's charge was - /// added to [`Self::cost`]. Local bookkeeping, never forwarded. - /// - /// A zero [`warm`](Cost::warm) on a chain of two or more hops means the - /// announcing relay is actively carrying the broadcast, and its - /// [`cold`](Cost::cold) is then the rank the origin's handover gate descends. - pub(crate) advertised: Cost, - - /// Whether the broadcast should be announced: advertised to consumers via - /// [`crate::origin::Consumer::announced`] while this is the best route. A - /// non-announced broadcast stays reachable by exact path for subscribes and - /// fetches (e.g. serving cached or on-demand content), so toggling this via - /// [`Producer::set_route`] announces or unannounces without touching the - /// broadcast itself. Defaults to `false`. - pub announce: bool, -} - -impl Route { - /// An unannounced direct route: no hops, best cost. - /// - /// The broadcast is reachable only by its exact path, so subscribers must already - /// know it exists. Use [`announced`](Self::announced) to advertise it instead. - pub fn new() -> Self { - Self::default() - } - - /// An announced direct route: no hops, best cost. - /// - /// The broadcast is advertised to subscribers via - /// [`crate::origin::Consumer::announced`] while this is the best route, on top of - /// staying reachable by exact path. Use [`new`](Self::new) to keep it unadvertised. - pub fn announced() -> Self { - Self { - announce: true, - ..Self::default() - } - } - - /// Append a hop to the chain, oldest first. - /// - /// Fails with [`crate::InvalidHop`] for a hop the wire would reject: one past the - /// chain's length cap, or one already in it, which is a loop. - pub fn with_hop(mut self, hop: super::Hop) -> Result { - self.hops.push(hop)?; - Ok(self) - } - - /// Replace the hop chain. - pub fn with_hops(mut self, hops: Hops) -> Self { - self.hops = hops; - self - } - - /// Set the cost: lower wins among routes serving the same broadcast. - /// - /// A bare `u64` prices the route undiscounted (both halves of [`Cost`] alike), - /// which is what a publisher seeding its production cost means. - pub fn with_cost(mut self, cost: impl Into) -> Self { - self.cost = cost.into(); - self - } - - /// Set whether the broadcast is announced via this route. - pub fn with_announce(mut self, announce: bool) -> Self { - self.announce = announce; - self - } -} - -/// How long a drained broadcast keeps advertising a zero cost before restoring its -/// cold one. -/// -/// Pure hysteresis: demand edges arrive exactly (via [`Demand`]), but re-pricing the -/// instant the last viewer leaves would flap routing across the mesh on viewer churn. -pub(crate) const COST_LINGER: Duration = Duration::from_secs(5); - -/// The routes advertisable to one peer, best first: the announced ones whose hop chain -/// avoids both the peer (`exclude`) and ourselves (a reflection), each paired with -/// whether it is the serving route. -/// -/// `routes` is the broadcast's table in preference order with the serving (active) -/// route first, so a peer usually receives exactly what we serve everyone; a peer the -/// active chain flows through receives the best standby instead of nothing. The -/// subscribe path picks its source by the same exclusion (see -/// [`origin::Consumer::excluding`](super::origin::Consumer::excluding)), which keeps -/// the advertised chain truthful and the mesh loop-free. -/// -/// Callers take the first entry they can actually stamp themselves onto, since a chain -/// already at `MAX_HOPS` has no room and almost certainly means a loop. Empty when -/// every chain loops through the peer or us, or none is announced. -/// [`Hop::UNKNOWN`] identifies nothing, so it excludes nothing and is never a loop. -pub(crate) fn advertisable_routes( - routes: &[Route], - self_hop: Hop, - exclude: Hop, -) -> impl Iterator { - routes.iter().enumerate().filter_map(move |(index, route)| { - // Offline routes are reachable by exact path but never advertised. - if !route.announce { - return None; - } - if exclude != Hop::UNKNOWN && route.hops.contains(&exclude) { - return None; - } - if self_hop != Hop::UNKNOWN && route.hops.contains(&self_hop) { - return None; - } - Some((route, index == 0)) - }) -} - -/// The cost to advertise for a route. -/// -/// While the broadcast has demand, the *serving* (active) route costs zero: our -/// ingress is already paid for (or, for a local standby publisher, the work is already -/// running), so one more subscriber only pays the links below us. That is what lets a -/// cluster deduplicate onto a warm copy. A standby advertised to a peer the active -/// chain flows through keeps its own accumulated cost, since serving that peer means -/// opening a fresh ingest. Otherwise we forward the accumulated cost unchanged. -/// -/// A ceiling-cost route pierces the carrying discount. For a drain (the ceiling's -/// primary producer), advertising zero would keep pulling subscribers onto a path -/// about to vanish. The rule keys on the value because the reason does not travel on -/// the wire, and a cost that saturated through charges is a last-resort path too. -/// -/// Only [`Cost::warm`] is discounted. [`Cost::cold`] prices the same path against an -/// empty cache, so it flows through unchanged and keeps saying which warm relay sits -/// closest to the publisher once every discount has flattened `warm` to zero. -/// -/// The receiving side adds its own link price on top, so this never accounts for the -/// link we are sending over. The result is clamped to the largest wire varint because -/// locally created routes can name an arbitrary `u64`. -pub(crate) fn outgoing_cost(demand: &Demand, route: &Route, serving: bool) -> Cost { - let cost = route.cost.clamped(); - match serving && demand.is_used() && cost.warm < DRAIN_COST { - true => cost.discounted(), - false => cost, - } -} - #[derive(Default)] struct BroadcastState { // Weak references for deduplication. Doesn't prevent track auto-close. @@ -365,21 +80,6 @@ struct BroadcastState { // joined across per-session tracks. `None` for an ordinary broadcast. spliced: Option, - // The path the broadcast currently takes to reach us, bumping `route_epoch` - // on every change so consumers can watch for updates. - route: Route, - route_epoch: u64, - - // Every route currently attached at this path, in preference order with the - // serving (active) route first. Mirrored from the origin's source table for - // route-fed broadcasts so sessions can pick a different route per peer; an - // ordinary broadcast holds just its own route. `routes_epoch` bumps on any - // table change, including ones that leave the active route untouched (a - // standby attaching or repricing), which is why it is tracked separately - // from `route_epoch`. - routes: Vec, - routes_epoch: u64, - // Set by an explicit `Producer::finish()` or `Producer::abort()` so `Drop` can // tell a deliberate shutdown apart from a producer dropped by accident. closing: bool, @@ -623,49 +323,6 @@ impl Producer { ) } - /// Set the broadcast's [`Route`]: the hop chain and cost it advertises. - /// - /// Call this when the path to the content changes (an upstream failover) or the - /// publisher's preference changes (e.g. a transcoder warming up lowers its - /// cost). Consumers observe the change via [`Consumer::route_changed`] and - /// sessions forward it downstream as a restart, never as a new broadcast. - /// Setting the current route again is a no-op. - pub fn set_route(&mut self, route: Route) -> Result<(), Error> { - let mut state = self.state.lock(); - if state.route == route { - return Ok(()); - } - state.route = route.clone(); - state.route_epoch += 1; - // An ordinary broadcast's table is just its own route; a route-fed one is - // overwritten by the next `set_routes` from the origin. - state.routes = vec![route]; - state.routes_epoch += 1; - Ok(()) - } - - /// Replace the full route table, in preference order with the active route - /// first. Set by the origin's front on every source-table change; the active - /// route doubles as the broadcast's advertised [`Route`]. - /// - /// `routes` must be non-empty. A front whose table empties is on its way out, - /// and it unannounces and aborts rather than advertising a "no route" route, - /// so there is no such value to publish here. - pub(crate) fn set_routes(&mut self, routes: Vec) { - debug_assert!(!routes.is_empty(), "set_routes requires a non-empty table"); - let mut state = self.state.lock(); - if let Some(active) = routes.first() - && state.route != *active - { - state.route = active.clone(); - state.route_epoch += 1; - } - if state.routes != routes { - state.routes = routes; - state.routes_epoch += 1; - } - } - /// Poll for the next spliced track awaiting a serving route, returning its name /// and logical producer. Route-fed broadcasts only. pub(crate) fn poll_spliced_assigned(&self, waiter: &kio::Waiter) -> Poll<(Arc, super::resume::Producer)> { @@ -700,10 +357,7 @@ impl Producer { info: self.info.clone(), alive: self.alive.token.consume(), state: self.state.clone(), - route_seen: None, - routes_seen: None, stats: stats::Scope::default(), - exclusion: None, } } @@ -822,11 +476,6 @@ impl SourceGuard { } } - /// A clone of the guarded producer. - pub fn producer(&self) -> Producer { - self.producer.clone().expect("guard holds a producer until finished") - } - /// End the source deliberately: the origin detaches it immediately, /// unannouncing the path if it was the last. pub fn finish(mut self) { @@ -834,13 +483,6 @@ impl SourceGuard { producer.finish(); } } - - /// Update the source's advertised route in place. - pub fn set_route(&mut self, route: Route) { - if let Some(producer) = &mut self.producer { - let _ = producer.set_route(route); - } - } } impl Drop for SourceGuard { @@ -901,35 +543,6 @@ impl Dynamic { &self.info } - /// Bump this source's route to [`Cost::DRAIN`], keeping its hop chain and - /// announce flag. - /// - /// Called when the session feeding the source receives a GOAWAY, so the origin - /// hands live subscriptions to any other route at the next group boundary - /// rather than riding a connection that is about to close and losing the group - /// in flight. The draining route stays selectable, so a broadcast with no - /// alternative keeps being served until the session actually ends. - /// - /// It lives here rather than on [`Producer`] because the handler is what each - /// wire's per-source task already holds, so nothing has to keep a second - /// producer clone alive just to reach the route. - /// - /// Idempotent: the signal stays set, so a task may call this on every wakeup. - pub(crate) fn drain(&mut self) { - let mut state = self.state.lock(); - if state.route.cost == Cost::DRAIN { - return; - } - - state.route.cost = Cost::DRAIN; - state.route_epoch += 1; - - // An ordinary source's table is just its own route, and the origin reads the - // table rather than the route when ranking, so both have to move together. - state.routes = vec![state.route.clone()]; - state.routes_epoch += 1; - } - /// Poll for the next consumer-requested track, without blocking. /// /// Returns [`Error::Closed`] once the broadcast was deliberately ended @@ -968,10 +581,7 @@ impl Dynamic { info: self.info.clone(), alive: self.alive.token.consume(), state: self.state.clone(), - route_seen: None, - routes_seen: None, stats: stats::Scope::default(), - exclusion: None, } } @@ -1035,21 +645,10 @@ pub struct Consumer { alive: kio::Consumer<()>, // Track registry plus request queue; `track()` reads the registry and enqueues requests. state: kio::Shared, - // The route epoch last yielded by `route_changed`, so each consumer clone - // observes the current route first and every change after it exactly once. - route_seen: Option, - // Same cursor for the full route table (`routes_changed`), tracked separately - // because the table can change without the active route moving. - routes_seen: Option, // Egress stats scope, set by a tagged `origin::Consumer` at the broadcast // handoff. Inherited by the tracks subscribed through this handle. Empty (no-op) // for an untagged broadcast. stats: stats::Scope, - // Keeps the origin's front off routes that flow back through the peer this - // handle was resolved for, released when the last clone drops. Only set on the - // shared front of a route-fed broadcast, and only for a peer that declared an - // origin; `None` everywhere else. - exclusion: Option>, } impl Clone for Consumer { @@ -1058,25 +657,12 @@ impl Clone for Consumer { info: self.info.clone(), alive: self.alive.clone(), state: self.state.clone(), - // Reset the cursor so the clone observes the current route first, - // even if the original already drained `route_changed`. - route_seen: None, - routes_seen: None, stats: self.stats.clone(), - exclusion: self.exclusion.clone(), } } } impl Consumer { - /// Attach the guard that keeps the origin's front off routes flowing back - /// through the peer this handle was resolved for. Set once, at the origin's - /// broadcast handoff; the guard is shared by every clone of this handle. - pub(crate) fn with_exclusion(mut self, guard: Arc) -> Self { - self.exclusion = Some(guard); - self - } - /// Attach an egress stats scope, inherited by the tracks subscribed through this /// handle. Set by a tagged `origin::Consumer` at the broadcast handoff. pub(crate) fn with_stats(mut self, scope: stats::Scope) -> Self { @@ -1105,66 +691,6 @@ impl Consumer { &self.info } - /// The [`Route`] the broadcast currently takes to reach this origin. - pub fn route(&self) -> Route { - self.state.read().route.clone() - } - - /// Poll for a route change. See [`Self::route_changed`]. - pub fn poll_route_changed(&mut self, waiter: &kio::Waiter) -> Poll> { - let seen = self.route_seen; - if let Poll::Ready(state) = self.state.poll(waiter, |state| { - if seen != Some(state.route_epoch) { - Poll::Ready(()) - } else { - Poll::Pending - } - }) { - self.route_seen = Some(state.route_epoch); - return Poll::Ready(Ok(state.route.clone())); - } - // No pending change: surface the broadcast's end instead of parking forever. - ready!(self.alive.poll_closed(waiter)); - Poll::Ready(Err(Error::Dropped)) - } - - /// Wait for the broadcast's [`Route`] to change. - /// - /// The first call returns the current route immediately; each later call blocks - /// until it changes again, so a loop observes the initial value followed by - /// every update. Returns [`Error::Dropped`] once every producer is gone. - pub async fn route_changed(&mut self) -> Result { - kio::wait(|waiter| self.poll_route_changed(waiter)).await - } - - /// Every route currently attached at this path, in preference order with the - /// serving (active) route first. An ordinary broadcast holds just its own - /// route; a route-fed one mirrors the origin's source table so sessions can - /// advertise a different route per peer. - pub(crate) fn routes(&self) -> Vec { - self.state.read().routes.clone() - } - - /// Poll for any change to the route table, including ones that leave the - /// active route untouched (a standby attaching, detaching, or repricing). - /// The first call is ready immediately; read the table with [`Self::routes`]. - pub(crate) fn poll_routes_changed(&mut self, waiter: &kio::Waiter) -> Poll> { - let seen = self.routes_seen; - if let Poll::Ready(state) = self.state.poll(waiter, |state| { - if seen != Some(state.routes_epoch) { - Poll::Ready(()) - } else { - Poll::Pending - } - }) { - self.routes_seen = Some(state.routes_epoch); - return Poll::Ready(Ok(())); - } - // No pending change: surface the broadcast's end instead of parking forever. - ready!(self.alive.poll_closed(waiter)); - Poll::Ready(Err(Error::Dropped)) - } - /// Get a handle to a track on this broadcast. pub fn track(&self, name: &str) -> Result { // Rebind the track to *this* handle's view of the broadcast, so a catalog track @@ -1248,14 +774,6 @@ impl Consumer { Ok(consumer) } - /// A watch-only handle to the broadcast's demand. See [`Demand`]. - pub(crate) fn demand(&self) -> Demand { - Demand { - alive: self.alive.weak(), - state: self.state.clone(), - } - } - /// Block until the broadcast is closed, by [`Producer::finish`], /// [`Producer::abort`], or every producer dropping, and return the cause. /// @@ -1333,10 +851,7 @@ impl WeakConsumer { info: self.info.clone(), alive: self.alive.consume(), state: self.state.clone(), - route_seen: None, - routes_seen: None, stats: stats::Scope::default(), - exclusion: None, } } } @@ -1438,6 +953,7 @@ impl Consumer { #[cfg(test)] mod test { use super::*; + use std::time::Duration; /// Await with a timeout so a missed demand wake fails the test instead of /// hanging it (time is paused, so the timeout fires instantly when idle). @@ -1751,33 +1267,6 @@ mod test { again.assert_is_clone(&track.subscribe(None)); } - // Cloning a `Consumer` resets its route cursor: a clone that inherited the - // original's `route_seen` would skip the initial-value delivery that - // `route_changed` promises. - #[tokio::test] - async fn route_clone_observes_current_route() { - let mut producer = Info::new().produce(); - let mut consumer = producer.consume(); - - // Drain the initial route, then a change. - consumer.route_changed().await.unwrap(); - let route = Route::new().with_cost(7); - producer.set_route(route.clone()).unwrap(); - assert_eq!(consumer.route_changed().await.unwrap(), route); - - // The original is fully drained: no update pending. - assert!(consumer.route_changed().now_or_never().is_none()); - - // A clone starts fresh, yielding the current route immediately. - let mut clone = consumer.clone(); - let seen = clone - .route_changed() - .now_or_never() - .expect("clone should observe the current route immediately") - .unwrap(); - assert_eq!(seen, route); - } - // Cloning a `Dynamic` and dropping the clone must not flip the handler // count to zero. The relay's lite subscriber clones the // dynamic per spawned subscribe; if Clone skipped the increment, the @@ -1795,85 +1284,4 @@ mod test { // instead of failing with NotFound. let _fut = subscribe_pending!(consumer, "track1"); } - - /// Draining moves only the cost: the hop chain and announce flag have to - /// survive, or the origin would treat the source as a different path (or stop - /// advertising it) rather than as the same one on its way out. - #[tokio::test] - async fn drain_costs_the_route_without_disturbing_it() { - let mut producer = Info::new().produce(); - let mut consumer = producer.consume(); - let mut dynamic = producer.dynamic(); - - let hops = crate::Hops::try_from(vec![crate::Hop::new(7).unwrap()]).unwrap(); - producer - .set_route(Route::new().with_hops(hops.clone()).with_cost(42).with_announce(true)) - .unwrap(); - - let before = consumer.route_changed().await.unwrap(); - assert_eq!(before.cost, Cost::new(42)); - - dynamic.drain(); - - let after = consumer.route_changed().await.unwrap(); - assert_eq!(after.cost, Cost::DRAIN); - assert_eq!(after.hops, hops, "draining must not change the path"); - assert!(after.announce, "a draining route stays advertised"); - - // The origin ranks off the route table, so it has to move with the route. - assert_eq!(consumer.routes(), vec![after]); - } - - /// The signal stays set, so the per-source task calls this on every wakeup. A - /// repeat must not bump the epoch, or each wakeup would look like a route - /// change and churn the origin. - #[tokio::test] - async fn drain_is_idempotent() { - let producer = Info::new().produce(); - let mut consumer = producer.consume(); - let mut dynamic = producer.dynamic(); - - dynamic.drain(); - assert_eq!(consumer.route_changed().await.unwrap().cost, Cost::DRAIN); - - dynamic.drain(); - assert!( - consumer.route_changed().now_or_never().is_none(), - "a redundant drain must not look like a route change" - ); - } - - /// Charging a link accumulates onto both halves, saturating rather than wrapping - /// so a bogus peer sorts last, not first. The ceiling is the largest cost a - /// varint can carry, so whatever a peer advertises, the sum we forward still - /// encodes (see `charged_cost_stays_encodable`). - #[test] - fn cost_charge_saturates() { - assert_eq!(Cost { warm: 4, cold: 6 }.charged(5), Cost { warm: 9, cold: 11 }); - assert_eq!(Cost::new(u64::MAX).charged(10), Cost::new(MAX_COST)); - - // An unknown cold path stays unknown however many links it crosses, so it - // can never accumulate its way into outranking a path we actually know. - assert_eq!(Cost::UNKNOWN.charged(3).cold, MAX_COST); - } - - /// The carrying discount is the whole warm/cold split: it zeroes what one more - /// subscriber pays and leaves the cold path intact, which is what still ranks - /// two relays that have both discounted to zero. - #[test] - fn cost_discount_keeps_the_cold_path() { - assert_eq!(Cost { warm: 6, cold: 6 }.discounted(), Cost { warm: 0, cold: 6 }); - } - - /// A draining cost still has to fit the wire, since the route keeps being - /// announced downstream while it drains. - #[test] - fn drain_cost_is_encodable() { - use crate::coding::Encode; - - let mut buf = Vec::new(); - Cost::DRAIN - .encode(&mut buf, crate::lite::Version::Lite06Wip) - .expect("a draining route is still forwarded, so its cost must encode"); - } } diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index cf0a549b453..635a8bb2711 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -32,15 +32,17 @@ pub use bytes::*; pub use datagram::*; pub use time::*; -/// Publishing and consuming the set of broadcasts routed through an origin. +/// Publishing broadcasts, announcing routes, and consuming both through an origin. pub mod origin { - pub use super::origin_impl::{Consumer, Driver, Dynamic, Info, Producer, Request, Requesting, Run}; + pub use super::origin_impl::{ + Consumer, Cost, DRAIN_COST, Driver, Dynamic, Info, MAX_COST, Prefix, Producer, Request, Requesting, Route, Run, + }; } -/// Subscribing to broadcast (un)announcements from an origin. +/// Subscribing to route (un)announcements from an origin. pub mod announce { pub use super::origin_impl::{ - AnnounceConsumer as Consumer, AnnounceProducer as Producer, OriginAnnounce as Update, + AnnounceConsumer as Consumer, AnnounceProducer as Producer, AnnounceUpdate as Update, }; } @@ -48,5 +50,8 @@ pub mod announce { // module; keep them flat at the crate root. pub use origin_impl::{Consume, Hop, Hops, InvalidHop}; +// The per-route request queue handed to sessions by `origin::Producer::announce_served`. +pub(crate) use origin_impl::RouteServer; + #[cfg(test)] pub(crate) use origin_impl::ProduceTest; diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 2a6770058ab..8bb590a846c 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -2,7 +2,7 @@ use crate::{broadcast, cache, stats, track}; use kio::Pollable; use std::{ cmp::Reverse, - collections::{BTreeMap, HashMap, HashSet}, + collections::{BTreeMap, BTreeSet, HashMap, HashSet}, fmt, sync::Arc, sync::atomic::{AtomicU64, Ordering}, @@ -25,10 +25,8 @@ use crate::{ /// One relay's identity in a broadcast's hop chain: a 62-bit varint on the wire. /// /// Names a *hop*, not an [`origin::Producer`](Producer): a relay's routing table is the -/// origin, and this is the id it stamps into [`broadcast::Route::hops`] as an -/// announcement passes through, so a receiver can spot its own id and reject a loop. -/// Its own id lives in [`Info::id`]; the SETUP parameter that carries it session-wide is -/// `Hop` too. +/// origin, and this is the id it stamps into a route's hop chain as an announcement +/// passes through, so a receiver can spot its own id and reject a loop. /// /// Local hops are built with [`Hop::new`] or [`Hop::random`], both of which guarantee a /// non-zero id so loop detection can work. Remote peers may still send `0`; it is legal @@ -70,7 +68,7 @@ impl Hop { Self { id } } - /// Return the hop's wire id. + /// Return the origin's wire id. pub fn id(self) -> u64 { self.id } @@ -136,7 +134,7 @@ impl Default for Info { } impl Info { - /// Config for the given Hop ID with no byte target and the default idle expiry. + /// Config for the given origin id with no byte target and the default idle expiry. pub fn new(id: Hop) -> Self { Self { id, ..Self::default() } } @@ -163,7 +161,7 @@ impl Info { } impl From for Info { - /// Config for the given Hop ID with the defaults of [`Info::new`]. + /// Config for the given origin id with the defaults of [`Info::new`]. fn from(id: Hop) -> Self { Self::new(id) } @@ -205,7 +203,7 @@ where } } -/// Maximum number of hops a [`Hops`] chain can hold. +/// Maximum number of origins (hops) an [`Hops`] can hold. /// /// Caps pathological or loop-induced announcements at a reasonable cluster /// diameter; appending past this limit returns [`InvalidHop::TooMany`] rather than @@ -267,7 +265,7 @@ impl Hops { Self(Vec::new()) } - /// Append a [`Hop`], rejecting anything a conforming receiver would. + /// Append an [`Hop`], rejecting anything a conforming receiver would. /// /// Fails with [`InvalidHop::TooMany`] once the list is full, and with /// [`InvalidHop::Duplicate`] for an id already in the chain, which is a loop. The @@ -343,8 +341,8 @@ impl TryFrom> for Hops { return Err(InvalidHop::TooMany); } // MAX_HOPS is 32, so the quadratic scan is cheaper than allocating a set. - for (i, origin) in v.iter().enumerate() { - if *origin != Hop::UNKNOWN && v[i + 1..].contains(origin) { + for (i, hop) in v.iter().enumerate() { + if *hop != Hop::UNKNOWN && v[i + 1..].contains(hop) { return Err(InvalidHop::Duplicate); } } @@ -395,6 +393,189 @@ where } } +/// The highest value either half of a [`Cost`] can take, and where cost +/// accumulation saturates. +/// +/// The ceiling is the wire's, not the model's: lite-06 carries each cost as a QUIC +/// varint, which tops out at 2^62-1, so a larger value could be selected on but +/// never forwarded. +pub const MAX_COST: u64 = (1 << 62) - 1; + +/// The cost given to a route whose session is draining, so every other candidate +/// outranks it while it stays selectable as the last path to the content. +/// +/// A session sets this on its routes when its peer sends a GOAWAY. Draining is +/// deliberately not a distinct state: cost is the whole mechanism, so a route +/// whose accumulated cost saturates the wire ceiling ranks (and is treated) +/// identically, as a path of last resort. +/// +/// It is [`MAX_COST`] rather than a value beyond it for the reason above: a +/// draining route is still announced downstream, so its cost has to fit the wire. +pub const DRAIN_COST: u64 = MAX_COST; + +/// What pulling content via a route costs, in two magnitudes that accumulate +/// together and are compared in that order: lower [`warm`](Self::warm) wins, and +/// [`cold`](Self::cold) breaks the tie. +/// +/// Both are the same path priced against different cache states. `warm` is what one +/// more subscription would cost the mesh right now; `cold` prices the identical +/// path as if nothing were cached, so it stays meaningful once discounts have +/// flattened `warm`. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord)] +#[non_exhaustive] +pub struct Cost { + /// The cost of pulling content via this route as the mesh stands today, + /// accumulated per link. Lower wins. + /// + /// The original publisher seeds it with its production cost (zero for a live + /// publish, something large for a standby that would have to start working, like + /// a cold transcoder), and each link adds its own configured price as the + /// announcement crosses it, so a route over a metered backbone ranks worse than + /// an equal-length one within a datacenter. + pub warm: u64, + + /// The same path with every warm discount removed: what pulling the content + /// would cost if no relay along it were carrying anything. + /// + /// Accumulates exactly like [`warm`](Self::warm) but never restarts. [`MAX_COST`] + /// when the peer's wire cannot express it (pre-lite-06, or the MoQ Cluster + /// extension), which ranks last rather than pretending the path is free. + pub cold: u64, +} + +impl Cost { + /// Both magnitudes at `cost`: an undiscounted route, which is what a publisher + /// seeding its production cost means. + pub const fn new(cost: u64) -> Self { + Self { warm: cost, cold: cost } + } + + /// The cost of a draining route: the ceiling in both magnitudes, so every other + /// candidate outranks it. See [`DRAIN_COST`]. + pub const DRAIN: Self = Self::new(DRAIN_COST); + + /// What a peer advertises when its wire has no room for a cost at all: free to + /// reach (leaving hop count as the effective metric, exactly as before route + /// cost existed) with an unknown cold path. + pub(crate) const UNKNOWN: Self = Self { + warm: 0, + cold: MAX_COST, + }; + + /// Add a link's price to both magnitudes, saturating at the largest cost the + /// wire can carry so a huge cost sorts last instead of wrapping around to best. + pub(crate) fn charged(self, link_cost: u64) -> Self { + Self { + warm: self.warm.saturating_add(link_cost).min(MAX_COST), + cold: self.cold.saturating_add(link_cost).min(MAX_COST), + } + } + + /// Clamp both magnitudes to what a varint can carry, since a locally created + /// route can name an arbitrary `u64`. + pub(crate) fn clamped(self) -> Self { + Self { + warm: self.warm.min(MAX_COST), + cold: self.cold.min(MAX_COST), + } + } +} + +impl From for Cost { + fn from(cost: u64) -> Self { + Self::new(cost) + } +} + +/// What a route covers: a path prefix, matched per segment. +/// +/// `room/` covers `room/alice` (and `room/` itself), but a prefix is never half a +/// segment. Opaque so coverage can grow richer matching (wildcard patterns) +/// without a breaking change: construct one from a path and ask it questions. +/// Anything path-like converts into one, so `announce("room/", route)` reads +/// naturally. +#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)] +pub struct Prefix(PathOwned); + +impl Prefix { + /// A prefix covering `path` and every path beneath it. + pub fn new(prefix: impl AsPath) -> Self { + Self(prefix.as_path().to_owned()) + } + + /// Whether this prefix covers `path`: it is a segment-wise prefix of it, + /// including the exact path itself. + pub fn covers(&self, path: impl AsPath) -> bool { + path.as_path().has_prefix(&self.0) + } + + /// The prefix as a path, e.g. to display, compare, or join. + pub fn as_path(&self) -> Path<'_> { + self.0.as_path() + } +} + +impl From for Prefix { + fn from(prefix: T) -> Self { + Self::new(prefix) + } +} + +impl std::fmt::Display for Prefix { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + self.0.fmt(f) + } +} + +/// The path a route took through the mesh and what using it costs. +/// +/// The metadata half of an advertisement: [`Producer::announce`] pairs it with +/// the [`Prefix`] it covers, and [`Consumer::announced`] yields both. A route +/// claims capability, not inventory: it says paths under its prefix are +/// servable, never that any specific broadcast exists. The common convention is +/// that a publisher announces each broadcast's exact path, so subscribers can +/// enumerate broadcasts; a service instead announces one short prefix and +/// answers whatever is requested beneath it. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +#[non_exhaustive] +pub struct Route { + /// The chain of origins the route has traversed, oldest first. Each relay + /// appends its own [`crate::Hop`] when forwarding; used for loop detection + /// and as the selection tie-break. + pub hops: Hops, + + /// What pulling content via this route costs, accumulated per link: lower wins, + /// with ties broken by hop length, then a deterministic hash, and finally the + /// most recently announced route. See [`Cost`]. + pub cost: Cost, +} + +impl Route { + /// Append a hop to the chain, oldest first. + /// + /// Fails with [`crate::InvalidHop`] for a hop the wire would reject: one past the + /// chain's length cap, or one already in it, which is a loop. + pub fn with_hop(mut self, hop: Hop) -> Result { + self.hops.push(hop)?; + Ok(self) + } + + /// Replace the hop chain. + pub fn with_hops(mut self, hops: Hops) -> Self { + self.hops = hops; + self + } + + /// Set the cost: lower wins among routes covering the same prefix. + /// + /// A bare `u64` prices the route undiscounted (both halves of [`Cost`] alike), + /// which is what a publisher seeding its production cost means. + pub fn with_cost(mut self, cost: impl Into) -> Self { + self.cost = cost.into(); + self + } +} + static NEXT_CONSUMER_ID: AtomicU64 = AtomicU64::new(0); #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] @@ -406,71 +587,27 @@ impl ConsumerId { } } -// The origin-owned broadcast at a leaf: the spliced broadcast consumers see, -// the table of sources feeding it, and whether the path is currently announced. -// `announced` is gated on the best source's `live` flag; a non-announced entry -// is still returned by lookups, so an offline broadcast stays reachable for -// subscribes and fetches. +// The origin-owned broadcast at a leaf: the spliced broadcast consumers see and +// the table of local sources feeding it. Local broadcasts are reachable by exact +// path; whether anything is *advertised* is a separate concern, owned by the +// route table (see [`Producer::announce`]). struct OriginBroadcast { - path: PathOwned, /// The shared, spliced broadcast; its `consume()` is what consumers get. broadcast: broadcast::Producer, /// The source table, shared with every source watcher and the front task. /// Also the broadcast's identity for stale-teardown checks. state: kio::Producer, - announced: bool, -} - -/// How long a relay waits before re-parenting onto a source reached through a -/// session. -/// -/// Re-parenting is the one move that can cycle: relays that each decide to pull -/// from the next leave the broadcast with no source at all. A truthful hop chain -/// makes that impossible, because the loop would be visible in the chain and -/// dropped. What defeats the chain is simultaneity: relays deciding inside one -/// propagation window all read chains and costs that predate every one of those -/// decisions, so no advertisement yet contains the loop they are about to form. -/// -/// Costs make it worse rather than causing it. A relay reports its own cost, and -/// a report still in flight can be lower than what its sender would say now, so a -/// ring of relays can each rank a stale neighbour below themselves. Rising costs -/// are the whole hazard: if costs only fell, a stale value would only ever make a -/// peer look worse than it is, which is safe. -/// -/// So a relay sits on the decision instead of acting on it, and re-evaluates when -/// the wait expires. The wait is not there to stagger the relays, which a uniform -/// delay cannot do; it is there to outlast the propagation of the very costs it is -/// deciding on, so the re-evaluation runs on current numbers and usually no longer -/// wants to move. That makes the sizing rule simply "longer than an announcement -/// takes to cross the mesh", which this clears by a wide margin in any topology -/// where relays talk to each other at all. -pub(crate) const HANDOVER_HOLD: Duration = Duration::from_millis(500); - -/// Ordering key used to pick the active route among broadcasts at the same path. -/// -/// Lower wins. Shorter hop chains sort first (routing prefers the shortest path); -/// remaining ties break on a deterministic hash of the broadcast name and hop -/// chain. Every node in the cluster, given the same candidate routes, converges -/// on the same winner: the hops are forwarded unchanged, and the hash is -/// build-stable. Mixing the name in spreads equal routes across different -/// upstreams rather than funneling onto one. -fn route_key(name: &Path, hops: &Hops) -> (usize, u64) { - (hops.len(), fnv_key(name, hops.iter().copied())) } -/// FNV-1a over the broadcast name and a sequence of Hop IDs. +/// FNV-1a over a path and a sequence of origin ids. /// /// FNV-1a, not the std hasher: its output is fixed across Rust versions and /// builds, which matters when nodes run mismatched binaries during a rolling /// deploy and still need to agree on the same route. SEED is a custom basis /// (any nonzero u64 works, the textbook one is just as arbitrary); FNV_PRIME is -/// the standard FNV-64 prime and should stay put. -/// -/// Two callers, two different id sequences: [`route_key`] hashes a route's hop -/// chain to pick among *routes*, and [`FrontState::handover_allowed`] hashes a -/// single relay's origin to pick among *relays*. Mixing the name in spreads -/// equal candidates across different winners rather than funneling onto one. -fn fnv_key(name: &Path, hops: impl IntoIterator) -> u64 { +/// the standard FNV-64 prime and should stay put. Mixing the path in spreads +/// equal routes across different upstreams rather than funneling onto one. +fn fnv_key(name: &Path, origins: impl IntoIterator) -> u64 { const SEED: u64 = 0x420C0DECB00B; // 420 C0DEC B00B const FNV_PRIME: u64 = 0x0000_0100_0000_01b3; @@ -478,8 +615,8 @@ fn fnv_key(name: &Path, hops: impl IntoIterator) -> u64 { for &byte in name.as_str().as_bytes() { hash = (hash ^ u64::from(byte)).wrapping_mul(FNV_PRIME); } - for hop in hops { - for &byte in &hop.id().to_le_bytes() { + for origin in origins { + for &byte in &origin.id().to_le_bytes() { hash = (hash ^ u64::from(byte)).wrapping_mul(FNV_PRIME); } } @@ -487,255 +624,199 @@ fn fnv_key(name: &Path, hops: impl IntoIterator) -> u64 { hash } -/// Full ordering key for an attached route: announced routes first (an actively -/// published source beats an offline one), then the [`broadcast::Cost`] of pulling -/// via the route, then the [`route_key`] hop ordering, and finally the newest -/// source to attach. Lower wins. -/// -/// Cost is a pair, so this is really two comparisons: the warm cost, then the cold -/// one. The second matters exactly when the first ties, which is what happens once -/// two relays both carry the broadcast and both advertise zero. Their cold costs -/// then say which of them sits closer to the publisher, and the subscriber takes -/// that one. -/// -/// Hop length stays the tie-break below both, and it is measuring the same thing -/// the cold cost measures, just without the prices: how far away the content is. -/// So the cold cost is strictly the better answer and goes first. Peers that never -/// carry a cost (pre-lite-06, or a plain local publish) share one cold value, so -/// they tie there and rank exactly as they did before route cost existed, on hop -/// length, which bounds same-datacenter chains to a single hop. -/// -/// Recency is the last word, so it only separates routes that are identical in -/// every advertised respect: same hop chain, same cost. That is a publisher -/// reconnecting over a fresh session while its old one is still being kept alive -/// by the transport, and the new session is the one actually carrying frames, so -/// it wins the moment it attaches instead of after the QUIC idle timeout finally -/// retires the corpse. Local attach order never leaks into cluster convergence: -/// routes it can reorder are indistinguishable downstream, since what is -/// forwarded is the chain and cost, which are equal by construction here. -fn route_order(name: &Path, route: &FrontRoute) -> (bool, broadcast::Cost, usize, u64, Reverse) { - let (len, hash) = route_key(name, &route.route.hops); - (!route.route.announce, route.route.cost, len, hash, Reverse(route.id)) +/// Ordering key for a route entry covering one prefix. Lower wins: the cheapest +/// cost, then the shortest hop chain, then a deterministic hash of the prefix and +/// chain so every node converges on the same winner, and finally the newest +/// announcement, so a reconnect under an otherwise identical route wins the +/// moment it lands instead of after the transport retires the old session. +fn route_order(prefix: &Path, entry: &RouteEntry) -> (Cost, usize, u64, Reverse) { + ( + entry.cost, + entry.hops.len(), + fnv_key(prefix, entry.hops.iter().copied()), + Reverse(entry.id), + ) } +/// The `(hops, cost)` metadata an announce cursor delivers alongside a prefix. +type RouteMeta = (Hops, Cost); + /// One coalesced update queued for an `AnnounceConsumer`. /// -/// At most one entry exists per path, so a slow consumer's pending set is bounded -/// by the number of distinct paths. `UnannounceAnnounce` preserves the signal -/// that a broadcast genuinely went away and a different one took its place (the -/// consumer must see the `None` before the `Some`), while a stale `Announce` -/// cancels with a subsequent `unannounce` because the consumer has not yet -/// observed it. +/// At most one entry exists per prefix, so a slow consumer's pending set is +/// bounded by the number of distinct prefixes. A metadata change on a live route +/// overwrites the pending `Announce` (or is delivered as another active update), +/// while `UnannounceAnnounce` preserves a real retract-then-announce sequence. enum PendingUpdate { - Announce(broadcast::Consumer), - Unannounce, - UnannounceAnnounce(broadcast::Consumer), + Announce(RouteMeta), + Unannounce(RouteMeta), + UnannounceAnnounce { old: RouteMeta, new: RouteMeta }, } -/// Pending updates keyed by path. `BTreeMap` keeps memory strictly bounded by -/// the number of distinct paths with outstanding work (collapsed pairs are +/// Pending updates keyed by prefix. `BTreeMap` keeps memory strictly bounded by +/// the number of distinct prefixes with outstanding work (collapsed pairs are /// fully erased) and gives a deterministic lexicographic delivery order so /// tests can predict it. #[derive(Default)] struct OriginConsumerState { pending: BTreeMap, + /// Prefixes whose most recently delivered update was an announce. A pending + /// `Announce` is ambiguous on its own: it is an unseen initial announce (a + /// retraction cancels it entirely) or a metadata update on a route the + /// consumer already observed (a retraction must still be delivered). + delivered: BTreeSet, /// Set by the origin's teardown: the cursor drains `pending`, then reports - /// the end instead of parking forever on a tree that can never fire again. + /// the end instead of parking forever on a table that can never fire again. ended: bool, } impl OriginConsumerState { - fn apply_announce(&mut self, path: PathOwned, broadcast: broadcast::Consumer) { + fn apply_announce(&mut self, path: PathOwned, meta: RouteMeta) { let new = match self.pending.remove(&path) { - // First announce, or a stale announce being replaced. - None | Some(PendingUpdate::Announce(_)) => PendingUpdate::Announce(broadcast), - // Consumer needs to observe the unannounce before this announce. - Some(PendingUpdate::Unannounce | PendingUpdate::UnannounceAnnounce(_)) => { - PendingUpdate::UnannounceAnnounce(broadcast) + // First announce, a stale announce being replaced, or a metadata update. + None | Some(PendingUpdate::Announce(_)) => PendingUpdate::Announce(meta), + // Consumer needs to observe the retraction before this announce. + Some(PendingUpdate::Unannounce(old) | PendingUpdate::UnannounceAnnounce { old, .. }) => { + PendingUpdate::UnannounceAnnounce { old, new: meta } } }; self.pending.insert(path, new); } - fn apply_unannounce(&mut self, path: PathOwned) { + fn apply_unannounce(&mut self, path: PathOwned, last: RouteMeta) { match self.pending.remove(&path) { - // Consumer has not seen the pending announce; drop both entirely. - Some(PendingUpdate::Announce(_)) => {} - None | Some(PendingUpdate::Unannounce) => { - self.pending.insert(path, PendingUpdate::Unannounce); + // The pending announce was never delivered and neither was any earlier + // one, so the pair cancels entirely. + Some(PendingUpdate::Announce(_)) if !self.delivered.contains(&path) => {} + // Either nothing is pending or the pending announce was a metadata + // update on a delivered route; the consumer still owes a retraction. + None | Some(PendingUpdate::Announce(_) | PendingUpdate::Unannounce(_)) => { + self.pending.insert(path, PendingUpdate::Unannounce(last)); } - // The embedded announce cancels with this unannounce; the consumer still - // needs the leading unannounce. - Some(PendingUpdate::UnannounceAnnounce(_)) => { - self.pending.insert(path, PendingUpdate::Unannounce); + // The embedded announce cancels with this retraction; the consumer still + // needs the leading one. + Some(PendingUpdate::UnannounceAnnounce { old, .. }) => { + self.pending.insert(path, PendingUpdate::Unannounce(old)); } } } /// Take one update to deliver to the consumer, if any. - fn take(&mut self) -> Option { + fn take(&mut self) -> Option { let path = self.pending.keys().next()?.clone(); - let broadcast = match self.pending.remove(&path).unwrap() { - PendingUpdate::Announce(broadcast) => Some(broadcast), - PendingUpdate::Unannounce => None, - PendingUpdate::UnannounceAnnounce(broadcast) => { - // Deliver the unannounce now; leave the trailing announce pending so - // the next take returns it for the same path. - self.pending.insert(path.clone(), PendingUpdate::Announce(broadcast)); - None + let (meta, active) = match self.pending.remove(&path).unwrap() { + PendingUpdate::Announce(meta) => { + self.delivered.insert(path.clone()); + (meta, true) + } + PendingUpdate::Unannounce(meta) => { + self.delivered.remove(&path); + (meta, false) + } + PendingUpdate::UnannounceAnnounce { old, new } => { + // Deliver the retraction now; leave the trailing announce pending so + // the next take returns it for the same prefix. + self.delivered.remove(&path); + self.pending.insert(path.clone(), PendingUpdate::Announce(new)); + (old, false) } }; - Some(OriginAnnounce { path, broadcast }) + Some(AnnounceUpdate { + prefix: Prefix(path), + route: Route { + hops: meta.0, + cost: meta.1, + }, + active, + }) } } -#[derive(Clone)] -struct AnnounceConsumerNotify { - root: PathOwned, - state: kio::Producer, - /// The peer this stream advertises to, when it is scoped to one (see - /// [`Consumer::excluding`]). Every broadcast handed out registers an - /// [`ExclusionGuard`] for it, which is what tells the front it is exposed to that - /// peer even before they subscribe. - exclude: Option, +/// One announced route in the origin's table, absolute prefix. +struct RouteEntry { + id: u64, + prefix: PathOwned, + hops: Hops, + cost: Cost, + /// The queue requests under this route are served from, when the announcer + /// serves content on demand (a session). `None` for an advertise-only + /// announcement, whose requests fall through to the origin's fallback handler. + server: Option>, } -impl AnnounceConsumerNotify { - fn announce(&self, path: impl AsPath, broadcast: broadcast::Consumer, front: &kio::Producer) { - let path = path.as_path().strip_prefix(&self.root).unwrap().to_owned(); - - // Advertising a path to a peer exposes the front to them, so register the - // exclusion now rather than waiting for them to subscribe. A reflection can - // come back before any subscription does, and the front has to already know - // the route it arrives on leads to a peer we are feeding. - let broadcast = match self.exclude.and_then(|peer| ExclusionGuard::new(front, peer)) { - Some(guard) => broadcast.with_exclusion(guard), - None => broadcast, - }; +/// A per-announcer request queue: what materializes a requested path on demand. +/// +/// Shared by every requester resolving through the owning route (or, for the +/// origin's fallback, every requester with no covering route) and the handler +/// draining it, so both sides work under one lock. +#[derive(Default)] +struct ServeState { + // Result channels for pending requests, keyed by absolute path so concurrent + // `request_broadcast` calls for the same path coalesce onto one channel. + requests: Requests>, - self.state - .write() - .ok() - .expect("consumer closed") - .apply_announce(path, broadcast); - } + // Broadcasts the handler has already served, kept weakly so a repeat request for the + // same path resolves to a shared clone instead of re-invoking the handler (which would + // open a duplicate upstream subscription). Weak so a served broadcast still closes once + // its real consumers drop. The cache reclaims closed entries incrementally on insert, so a + // long-lived origin serving many distinct one-shot paths stays bounded by the live count. + served: WeakCache, - fn unannounce(&self, path: impl AsPath) { - let path = path.as_path().strip_prefix(&self.root).unwrap().to_owned(); - self.state.write().ok().expect("consumer closed").apply_unannounce(path); - } + // Set when the announcement is retracted or the origin tears down: new requests + // fail immediately and the handler observes the end instead of parking forever. + closed: bool, } -struct NotifyNode { - parent: Option>, - - // Consumers that are subscribed to this node. - // We store a consumer ID so we can remove it easily when it closes. - consumers: HashMap, +/// One registered announce cursor: which prefixes it may see, how they are +/// re-rooted, and the per-cursor delivery buffer. +struct TableCursor { + /// The prefix stripped from every delivered path. + root: PathOwned, + /// The absolute prefixes this cursor is scoped to (its token / scope). A route + /// is visible where it intersects one of these, clamped to the intersection. + allowed: Vec, + /// Skip routes whose hop chain contains this peer (control-plane split horizon). + exclude: Option, + /// The delivery buffer, drained by the cursor's `poll_next`. + state: kio::Producer, + /// The last delivered best route per presented (absolute) prefix, for change + /// detection: `(entry id, hops, cost)`. + // entry id, metadata, and whether the entry could serve requests: the last + // is part of the dedupe key (see `sync_cursor`) but never leaves the model. + current: HashMap, } -impl NotifyNode { - fn new(parent: Option>) -> Self { - Self { - parent, - consumers: HashMap::new(), - } - } - - /// `state` is the announced front's source table, so a consumer scoped to a peer - /// can register its [`ExclusionGuard`] against it (see - /// [`AnnounceConsumerNotify::announce`]). - fn announce(&mut self, path: impl AsPath, broadcast: &broadcast::Consumer, state: &kio::Producer) { - for consumer in self.consumers.values() { - consumer.announce(path.as_path(), broadcast.clone(), state); - } - - if let Some(parent) = &self.parent { - parent.lock().announce(path, broadcast, state); - } - } - - fn unannounce(&mut self, path: impl AsPath) { - for consumer in self.consumers.values() { - consumer.unannounce(path.as_path()); - } - - if let Some(parent) = &self.parent { - parent.lock().unannounce(path); - } +impl TableCursor { + /// Where `prefix` presents on this cursor: the intersection of the route's + /// prefix with each allowed scope, absolute. Empty when disjoint. + fn presented(&self, prefix: &Path) -> Vec { + self.allowed + .iter() + .filter_map(|allowed| intersect_prefix(prefix, &allowed.as_path())) + .collect() } -} - -/// Keeps a peer registered in [`FrontState::excluded`] for as long as it holds the -/// shared front, so the front stays off routes that flow back through it. -/// -/// Carried by the [`broadcast::Consumer`] handed to that peer and shared by its -/// clones, so the registration ends when the last of them drops. A guard whose -/// front has already closed is inert. -pub(crate) struct ExclusionGuard { - state: kio::Producer, - peer: Hop, -} -impl ExclusionGuard { - /// Register `peer` and return the guard that releases it, or `None` if the - /// front is closing (nothing left to keep off a route). - fn new(state: &kio::Producer, peer: Hop) -> Option> { - let mut s = state.write().ok()?; - if s.closed { - return None; + /// Whether this cursor may observe `entry` at all (split horizon). + fn visible(&self, entry: &RouteEntry) -> bool { + match self.exclude { + Some(peer) if peer != Hop::UNKNOWN => !entry.hops.contains(&peer), + _ => true, } - let count = { - let count = s.excluded.entry(peer).or_default(); - *count += 1; - *count - }; - // A first registration can taint the active route; the front task owns - // the reselect (see `FrontState::excluded_changed`). - if count == 1 { - s.excluded_changed = true; - } - drop(s); - Some(Arc::new(Self { - state: state.clone(), - peer, - })) } } -impl Drop for ExclusionGuard { - fn drop(&mut self) { - let Ok(mut state) = self.state.write() else { return }; - if let std::collections::hash_map::Entry::Occupied(mut entry) = state.excluded.entry(self.peer) { - match entry.get() { - 1 => { - entry.remove(); - // The last reader leaving can free a better route; the - // front task owns the reselect. - state.excluded_changed = true; - } - n => *entry.get_mut() = n - 1, - } - } +/// The intersection of two path prefixes: the longer one when one contains the +/// other (segment-wise), `None` when they are disjoint. +fn intersect_prefix(a: &Path, b: &Path) -> Option { + if a.has_prefix(b) { + Some(a.to_owned()) + } else if b.has_prefix(a) { + Some(b.to_owned()) + } else { + None } } -/// How a path resolves against the announce tree for one consumer. -/// -/// `Excluded` is deliberately not folded into `Missing`: they mean opposite -/// things to a caller holding a dynamic handler. Missing is "nobody here, go -/// ask"; excluded is "here, but not for you", and asking a handler to route it -/// anyway is how a split-horizon violation gets in through the back door. -enum Resolved { - /// A broadcast this consumer may read: the shared front, or a single source - /// pinned because the front holds a route back through the requester. - Found(broadcast::Consumer), - /// The path is live, but every route to it flows through the requester. - Excluded, - /// Nothing is published at the path, or it is outside the consumer's scope. - Missing, -} - struct OriginNode { // The origin-owned broadcast published at this node, if any (see // [`Producer::create_broadcast`]). @@ -743,17 +824,13 @@ struct OriginNode { // Nested nodes, one level down the tree. nested: HashMap>, - - // Unfortunately, to notify consumers we need to traverse back up the tree. - notify: Lock, } impl OriginNode { - fn new(parent: Option>) -> Self { + fn new() -> Self { Self { broadcast: None, nested: HashMap::new(), - notify: Lock::new(NotifyNode::new(parent)), } } @@ -768,117 +845,28 @@ impl OriginNode { match self.nested.get(dir) { Some(next) => next.clone(), None => { - let next = Lock::new(OriginNode::new(Some(self.notify.clone()))); + let next = Lock::new(OriginNode::new()); self.nested.insert(dir.to_string(), next.clone()); next } } } - /// Toggle the announce state of this leaf's broadcast, notifying consumers on - /// a change. The identity check keeps a stale front from toggling its - /// successor. - fn set_announced(&mut self, expect: &kio::Producer, announce: bool) { - let Some(existing) = &mut self.broadcast else { return }; - if !existing.state.same_channel(expect) || existing.announced == announce { - return; - } - existing.announced = announce; - let path = existing.path.clone(); - let consumer = existing.broadcast.consume(); - let state = existing.state.clone(); - let mut notify = self.notify.lock(); - if announce { - notify.announce(&path, &consumer, &state); - } else { - notify.unannounce(&path); - } - } - - fn consume(&mut self, id: ConsumerId, mut notify: AnnounceConsumerNotify) { - self.consume_initial(&mut notify); - self.notify.lock().consumers.insert(id, notify); - } - - fn consume_initial(&mut self, notify: &mut AnnounceConsumerNotify) { - // Only announced (live) broadcasts replay; offline ones are reachable by - // exact path but never advertised. - if let Some(broadcast) = &self.broadcast - && broadcast.announced - { - notify.announce(&broadcast.path, broadcast.broadcast.consume(), &broadcast.state); - } - - // Recursively subscribe to all nested nodes. - for nested in self.nested.values() { - nested.lock().consume_initial(notify); - } - } - - fn resolve_broadcast(&self, rest: impl AsPath, exclude: Option) -> Resolved { + fn resolve_broadcast(&self, rest: impl AsPath) -> Option { let rest = rest.as_path(); if let Some((dir, rest)) = rest.next_part() { - let Some(node) = self.nested.get(dir) else { - return Resolved::Missing; - }; + let node = self.nested.get(dir)?; let node = node.lock(); - return node.resolve_broadcast(&rest, exclude); + return node.resolve_broadcast(&rest); } - let Some(broadcast) = self.broadcast.as_ref() else { - return Resolved::Missing; - }; - let Some(origin) = exclude else { - return Resolved::Found(broadcast.broadcast.consume()); - }; - - // Data-plane split horizon: never serve a requester from a source whose - // chain flows through them (they'd receive their own bytes back, or worse, - // a subscription cycle). - // - // The shared spliced front is safe only while *no* attached route is - // tainted for the requester: the front picks per track and re-picks on - // failover, so a tainted route anywhere in the table is one the front may - // serve them from. Checking the whole table rather than just the active - // route is what keeps that honest at this instant; the guard registered - // below keeps it honest afterwards, holding the front off a route through - // this peer for as long as they are reading it. Otherwise pin them to the - // best clean source. A pinned broadcast skips the front's re-splicing, - // which is fine: the requester is itself a relay (only a forwarder's origin - // can appear in a chain) and re-splices via its own front when the pinned - // source dies. - let state = broadcast.state.read(); - if !state.routes.iter().any(|r| r.route.hops.contains(&origin)) { - drop(state); - let shared = broadcast.broadcast.consume(); - return match ExclusionGuard::new(&broadcast.state, origin) { - Some(guard) => Resolved::Found(shared.with_exclusion(guard)), - // The front closed between the lookup and the registration; it - // serves nothing now, so there is nothing to keep off a route. - None => Resolved::Found(shared), - }; - } - match state - .dispatch(Some(origin)) - .and_then(|clean| state.routes.iter().find(|r| r.id == clean)) - { - Some(route) => Resolved::Found(route.source.clone()), - None => Resolved::Excluded, - } - } - - fn unconsume(&mut self, id: ConsumerId) { - self.notify.lock().consumers.remove(&id).expect("consumer not found"); - if self.is_empty() { - //tracing::warn!("TODO: empty node; memory leak"); - // This happens when consuming a path that is not being broadcasted. - } + Some(self.broadcast.as_ref()?.broadcast.consume()) } - /// Remove the broadcast at `relative` if it is `expect`, unannouncing it if - /// needed and pruning empty nodes on the way back up. The identity check - /// keeps a stale teardown from clobbering a replacement. + /// Remove the broadcast at `relative` if it is `expect`, pruning empty nodes on + /// the way back up. The identity check keeps a stale teardown from clobbering a + /// replacement. fn remove(&mut self, expect: &kio::Producer, relative: impl AsPath) { let relative = relative.as_path(); @@ -895,15 +883,12 @@ impl OriginNode { } else if let Some(existing) = &self.broadcast && existing.state.same_channel(expect) { - let existing = self.broadcast.take().expect("checked above"); - if existing.announced { - self.notify.lock().unannounce(&existing.path); - } + self.broadcast = None; } } fn is_empty(&self) -> bool { - self.broadcast.is_none() && self.nested.is_empty() && self.notify.lock().consumers.is_empty() + self.broadcast.is_none() && self.nested.is_empty() } } @@ -985,30 +970,36 @@ impl OriginNodes { impl Default for OriginNodes { fn default() -> Self { Self { - nodes: vec![("".into(), Lock::new(OriginNode::new(None)))], + nodes: vec![("".into(), Lock::new(OriginNode::new()))], } } } -/// A path and the broadcast now available there, delivered by [`AnnounceConsumer`]. -#[derive(Clone)] -pub struct OriginAnnounce { - /// The path of the broadcast, relative to the consuming cursor's root. - pub path: PathOwned, - /// The broadcast now available at that path, or `None` if it is no longer available. - /// - /// A replacement (a relay failover, or a shorter hop path arriving) is delivered as a - /// `None` followed by a `Some`, never as a swap in place. A route change alone is invisible here (the handles stay - /// valid); observe it via [`broadcast::Consumer::route_changed`]. - pub broadcast: Option, +/// A route announcement or retraction, delivered by [`AnnounceConsumer`]. +/// +/// An announcement carries no broadcast: it advertises that content under +/// [`prefix`](Self::prefix) is servable. Resolve a specific path with +/// [`Consumer::request_broadcast`]; the application decides which paths name +/// broadcasts. +#[derive(Clone, Debug)] +pub struct AnnounceUpdate { + /// What the route covers, relative to the consuming cursor's root. A route + /// announced above the cursor's scope is clamped to that scope, which is the + /// exact set of covered paths the cursor may see. + pub prefix: Prefix, + /// The route serving the prefix. On a retraction this carries its last + /// advertised metadata. + pub route: Route, + /// `false` when the route was retracted. A repeated `true` for the same + /// prefix is a metadata update (new hops or cost), delivered in place. + pub active: bool, } -/// Announces broadcasts to consumers over the network. +/// Publishes broadcasts and announces routes into an origin. #[derive(Clone)] pub struct Producer { - // Identity for this origin. Appended to broadcast hops when - // re-announcing so downstream relays can detect loops and prefer the - // shortest path. + // Identity for this origin. Appended to route hops when re-announcing so + // downstream relays can detect loops and prefer the shortest path. info: Hop, // The roots of the tree that we are allowed to publish. @@ -1018,10 +1009,9 @@ pub struct Producer { // The prefix that is automatically stripped from all paths. root: PathOwned, - // Fallback request queue, shared with every derived consumer. Separate from - // `nodes` because dynamic broadcasts are never announced: they only resolve a - // consumer's `request_broadcast` when no live announcement exists. - dynamic: kio::Shared, + // The origin's shared state: the route table, announce cursors, and the + // fallback request queue. Shared with every derived consumer. + shared: kio::Shared, // The cache pool inherited by broadcasts created under this origin (sessions // mint their remote broadcasts with it). Unbounded by default. @@ -1069,13 +1059,13 @@ impl Producer { pub fn new(info: Info) -> (Self, Driver) { let (tasks, set) = TaskSet::new(); let nodes = OriginNodes::default(); - let dynamic = kio::Shared::::default(); + let shared = kio::Shared::::default(); let timers = TimersSlot::default(); let producer = Self { info: info.id, nodes: nodes.clone(), root: PathOwned::default(), - dynamic: dynamic.clone(), + shared: shared.clone(), pool: info.pool, cache_duration: info.cache_duration, default_max_age: info.default_max_age, @@ -1087,7 +1077,7 @@ impl Producer { state: DriverState { set, nodes, - dynamic, + shared, done: false, }, timers, @@ -1132,7 +1122,7 @@ impl Producer { info, nodes: OriginNodes { nodes: Vec::new() }, root: PathOwned::default(), - dynamic: kio::Shared::default(), + shared: kio::Shared::default(), pool: cache::Pool::default(), cache_duration: Duration::MAX, default_max_age: track::DEFAULT_MAX_AGE, @@ -1144,74 +1134,49 @@ impl Producer { /// Create a broadcast at `path`, fed through the returned producer. /// - /// This is the sole way content enters an origin. The returned - /// [`broadcast::Producer`] is a route source: the origin owns the broadcast + /// This is how local content enters an origin. The returned + /// [`broadcast::Producer`] is a source: the origin owns the broadcast /// consumers actually see, and splices its tracks across every source created - /// at the same path (other local publishers, or sessions attaching announces - /// from the network), always serving from the best [`broadcast::Route`] (live - /// first, then lowest cost, then shortest hops with a deterministic - /// tie-break, and the newest source among otherwise equal routes). When the - /// best source changes, tracks resume from the replacement at the first - /// missing group; consumers never observe the swap. - /// - /// Splicing requires the same content identity: every source at a path must - /// share the first hop of its route, which is a promise that they produce - /// interchangeable tracks. An *announced* source arriving with a different - /// first hop is a replacement instead: it takes the path immediately and - /// consumers see an unannounce followed by an announce, rather than unrelated - /// content spliced into a live subscription. So a publisher reconnecting - /// under a fresh identity displaces the session it replaced right away, - /// without waiting for the transport to notice the old one is gone. An - /// offline source never displaces anything: it ranks below every announced - /// route, so it waits invisibly for the incumbent to end. + /// at the same path, preferring the newest. When the serving source changes, + /// tracks resume from the replacement at the first missing group; consumers + /// never observe the swap. /// - /// `route` is the source's initial metadata; update it with - /// [`broadcast::Producer::set_route`]. The [`broadcast::Route::announce`] flag - /// controls whether the path is announced: a non-live broadcast is invisible - /// to [`Consumer::announced`] but stays reachable by exact path for - /// subscribes and fetches (e.g. serving cached or on-demand content), so - /// toggling `live` announces or unannounces without touching the broadcast. + /// The broadcast is *not* advertised: it is reachable by exact path for + /// subscribes and fetches. Advertise it (or a whole prefix of paths) separately + /// with [`Self::announce`]; the two are independent, so cached or on-demand + /// content can stay reachable without ever being announced. /// - /// The broadcast is visible to consumers (exact lookups and announcements) - /// before this returns; only lifecycle work (route changes, track serving, - /// teardown) waits for the [`Driver`] to be polled. Register a - /// [`broadcast::Producer::dynamic`] handler right away, so the first consumer - /// finds the tracks it serves. + /// The broadcast is visible to exact lookups before this returns; only + /// lifecycle work (track serving, teardown) waits for the [`Driver`] to be + /// polled. Register a [`broadcast::Producer::dynamic`] handler right away, so + /// the first consumer finds the tracks it serves. /// /// End the broadcast with [`broadcast::Producer::finish`]; dropping it /// without finishing also works, but logs a warning. Either way the path - /// closes and unannounces once it was the last source; an - /// unfinished drop additionally aborts the spliced tracks with an error, so - /// consumers observe a failure rather than a clean end. + /// closes once it was the last source; an unfinished drop additionally aborts + /// the spliced tracks with an error, so consumers observe a failure rather + /// than a clean end. /// /// Fails with [`Error::Unauthorized`] if `path` is outside the prefixes this /// producer may publish under (after [`scope`](Self::scope) / /// [`with_root`](Self::with_root)), [`Error::BoundsExceeded`] if the full /// rooted path exceeds [`Path::MAX_PARTS`], or [`Error::Closed`] once the - /// origin's [`Driver`] has been dropped. Callers must not use - /// a route whose hop chain contains this origin's id (it would form a routing - /// loop); relays filter such reflections before they reach here, checked by a - /// `debug_assert`. - pub fn create_broadcast(&self, path: impl AsPath, route: broadcast::Route) -> Result { + /// origin's [`Driver`] has been dropped. + pub fn create_broadcast(&self, path: impl AsPath) -> Result { let path = path.as_path(); // Held across the whole attach: the driver's teardown sets `closed` under // this lock, so a create either completes before the teardown (whose walk // then cleans the entry up) or observes `closed` here and fails. - let lifecycle = self.dynamic.lock(); + let lifecycle = self.shared.lock(); if lifecycle.closed { return Err(Error::Closed); } - debug_assert!( - !route.hops.contains(&self.info), - "create_broadcast called with a looping hop chain", - ); - let (node, rest) = self.nodes.get(&path).ok_or(Error::Unauthorized)?; let full = self.root.join(&path).to_owned(); - // A decoded announce prefix and suffix are each within the wire limit, but their + // A decoded prefix and suffix are each within the wire limit, but their // join might not be. Enforcing here bounds the tree depth and guarantees the path // can be re-encoded when forwarded. if full.parts().count() > Path::MAX_PARTS { @@ -1219,27 +1184,18 @@ impl Producer { } // Resolve the ingress counters once, keyed by the absolute broadcast path. - // The source producer tags its tracks; run_source drives the announce guard - // off route transitions. let ingress = self.stats.ingress(&full); - let mut source = broadcast::Info { + let source = broadcast::Info { origin: self.info(), path: full.clone(), } .produce() .with_stats(ingress.clone()); - source.set_route(route).expect("fresh producer"); - - // Advance the route cursor past its initial observation (the route just - // set) so the watcher below only wakes for actual changes. - let mut consumer = source.consume(); - let Poll::Ready(Ok(route)) = consumer.poll_route_changed(&kio::Waiter::noop()) else { - unreachable!("a fresh source always yields its initial route"); - }; + let consumer = source.consume(); - // Attach synchronously: an eligible source is visible (exact lookups and - // announcements) before this returns; only lifecycle work needs the driver. + // Attach synchronously: the source is visible to exact lookups before this + // returns; only lifecycle work needs the driver. let origin = self.info(); let ctx = AttachContext { origin: &origin, @@ -1254,31 +1210,139 @@ impl Producer { } else { node.lock().leaf(&rest) }; - let first = attach_source(&ctx, &leaf, &consumer, route.clone(), true); - - // Ingress announce guard, opened synchronously with the announcement and - // handed to the watcher, which toggles it on route transitions. - let announce = route.announce.then(|| ingress.announce()); + let (state, broadcast, id) = attach_source(&ctx, &leaf, &consumer); self.tasks.push(run_source(SourceTask { - origin, - node, - full, - rest, source: consumer, - ingress, - tasks: self.tasks.clone(), timers: self.timers.clone(), - route, - announce, leaf, - first, + state, + broadcast, + id, })); drop(lifecycle); Ok(source) } + /// Mint a standalone source broadcast for a served-route request: it carries + /// this origin's identity (cache pool included) and ingress attribution, but + /// is *not* inserted into the broadcast tree. Sessions answer + /// [`RouteServer`] requests with one of these; the requester already holds + /// the request's result channel, so the tree never needs to resolve it. + pub(crate) fn create_source(&self, path: impl AsPath) -> broadcast::Producer { + let path = path.as_path(); + let full = self.root.join(&path).to_owned(); + let ingress = self.stats.ingress(&full); + broadcast::Info { + origin: self.info(), + path: full, + } + .produce() + .with_stats(ingress) + } + + /// Advertise a route: a claim that paths under `prefix` can be served. + /// + /// The advertisement is visible to [`Consumer::announced`] and forwarded by + /// sessions until the returned [`AnnounceProducer`] is dropped. Announcing is + /// independent of [`Self::create_broadcast`], and the right order is + /// create-populate-announce: announce each broadcast's exact path once its + /// tracks exist so subscribers can enumerate broadcasts, or announce one short + /// prefix and serve requests beneath it via [`Self::dynamic`]. + /// + /// The prefix is clamped to the intersection with this producer's allowed + /// scope, so a broad route announced through a narrow token advertises exactly + /// what the token may serve. Fails with [`Error::Unauthorized`] when they are + /// disjoint, and [`Error::Closed`] once the origin's [`Driver`] has been + /// dropped. + pub fn announce(&self, prefix: impl Into, route: Route) -> Result { + self.announce_inner(prefix.into(), route, None) + } + + /// [`Self::announce`], plus a request queue: a consumer resolving a path under + /// this route is handed to the returned server to materialize on demand. + /// Sessions use this for the routes a peer announces to them. + pub(crate) fn announce_served( + &self, + prefix: impl Into, + route: Route, + ) -> Result<(AnnounceProducer, RouteServer), Error> { + let serve = kio::Shared::::default(); + serve.lock().requests.add_handler(); + let server = RouteServer { + root: self.root.clone(), + state: serve.clone(), + }; + let announcement = self.announce_inner(prefix.into(), route, Some(serve))?; + Ok((announcement, server)) + } + + fn announce_inner( + &self, + prefix: Prefix, + route: Route, + server: Option>, + ) -> Result { + debug_assert!( + !route.hops.contains(&self.info), + "announce called with a looping hop chain", + ); + + let meta: RouteMeta = (route.hops, route.cost); + + // Clamp the prefix against each allowed root: the intersection is exactly + // the set of covered paths this producer may claim. One entry per + // intersecting root (a broad route through a multi-prefix token covers each + // of them). + let requested = self.root.join(prefix.as_path()).to_owned(); + if requested.parts().count() > Path::MAX_PARTS { + return Err(BoundsExceeded.into()); + } + let prefixes: Vec = self + .nodes + .nodes + .iter() + .filter_map(|(allowed, _)| { + let allowed = self.root.join(allowed).to_owned(); + intersect_prefix(&requested.as_path(), &allowed.as_path()) + }) + .collect(); + if prefixes.is_empty() { + return Err(Error::Unauthorized); + } + + let mut shared = self.shared.lock(); + if shared.closed { + return Err(Error::Closed); + } + + let mut ids = Vec::with_capacity(prefixes.len()); + for prefix in prefixes { + let id = shared.next_route; + shared.next_route += 1; + shared.routes.push(RouteEntry { + id, + prefix: prefix.clone(), + hops: meta.0.clone(), + cost: meta.1, + server: server.clone(), + }); + shared.sync_route(&prefix.as_path()); + ids.push(id); + } + drop(shared); + + // Ingress announce guard: held for the announcement's lifetime. + let guard = self.stats.ingress(&requested).announce(); + + Ok(AnnounceProducer { + shared: self.shared.clone(), + ids, + _guard: guard, + }) + } + /// Returns a new Producer restricted to publishing under one of `prefixes`. /// /// Returns None if there are no legal prefixes (the requested prefixes are @@ -1290,7 +1354,7 @@ impl Producer { info: self.info, nodes: self.nodes.select(&prefixes)?, root: self.root.clone(), - dynamic: self.dynamic.clone(), + shared: self.shared.clone(), pool: self.pool.clone(), cache_duration: self.cache_duration, default_max_age: self.default_max_age, @@ -1301,15 +1365,15 @@ impl Producer { } /// Create a dynamic handler that picks up [`Consumer::request_broadcast`] - /// calls for paths that are not announced. + /// calls no local broadcast or served route resolves. /// /// This is the origin-level analogue of [`broadcast::Producer::dynamic`]: it serves - /// broadcasts on demand rather than tracks. Crucially the served broadcasts are - /// *not* announced, so [`Consumer::announced`] never sees them; they exist - /// only as a fallback for a consumer that asks for an exact path with no live - /// announcement. Drop the handler (and every clone) to reject pending requests. + /// broadcasts on demand rather than tracks. The served broadcasts are *not* + /// announced; pair the handler with [`Producer::announce`] to advertise the + /// prefix it answers under. Drop the handler (and every clone) to reject + /// pending requests. pub fn dynamic(&self) -> Dynamic { - Dynamic::new(self.info, self.root.clone(), self.dynamic.clone()) + Dynamic::new(self.info, self.root.clone(), self.shared.clone()) } /// Cheap read handle over this origin's broadcast tree. @@ -1323,20 +1387,11 @@ impl Producer { self.info, self.root.clone(), self.nodes.clone(), - self.dynamic.clone(), + self.shared.clone(), stats::Session::default(), ) } - /// Handle to the announcement stream for this producer's subtree. - /// - /// Symmetric counterpart to [`Self::consume`]; call - /// [`AnnounceProducer::consume`] to get an [`AnnounceConsumer`] that - /// receives announce / unannounce events. - pub fn announces(&self) -> AnnounceProducer { - AnnounceProducer::new(self.root.clone(), self.nodes.clone(), self.dynamic.clone()) - } - /// Returns a new Producer that automatically strips out the provided prefix. /// /// Returns None if the provided root is not authorized; when [`Self::scope`] @@ -1348,7 +1403,7 @@ impl Producer { info: self.info, root: self.root.join(&prefix).to_owned(), nodes: self.nodes.root(&prefix)?, - dynamic: self.dynamic.clone(), + shared: self.shared.clone(), pool: self.pool.clone(), cache_duration: self.cache_duration, default_max_age: self.default_max_age, @@ -1375,50 +1430,176 @@ impl Producer { } } -/// The origin's lifecycle work, waiting for the [`crate::Timers`] it runs on. -/// -/// Returned by [`Producer::new`] alongside the producer. Call -/// [`run`](Self::run) with the timers that arm its deadlines (linger, handover -/// holds) and poll the returned [`Run`] for the life of the origin. Route -/// changes, track serving, linger timers, failover, and teardown all run there: -/// exact lookups and eligible announcements still update synchronously in -/// [`Producer::create_broadcast`], but nothing else makes progress without -/// polling. -/// -/// It holds no [`Producer`] clone, so it never keeps the origin alive. -/// Dropping it (before or after `run`) tears the origin down immediately: -/// active fronts abort with [`Error::Dropped`], pending dynamic requests are -/// rejected, announced paths unannounce and announcement cursors end, and later -/// producer mutations fail with [`Error::Closed`]. +/// The write half of an advertisement, from [`Producer::announce`]: a live +/// claim that paths under a [`Prefix`] can be served. /// -/// `moq_tokio::origin::spawn` wraps construction, `run`, and spawning for -/// tokio callers. -#[must_use = "call Driver::run and poll the result or the origin makes no progress"] -pub struct Driver { - state: DriverState, - // The producer's slot, filled by `run` so lifecycle work can mint deadlines. - timers: TimersSlot, +/// Hold it for as long as the route should stay advertised and +/// [`update`](Self::update) it to re-price; dropping it retracts the route, which +/// [`AnnounceConsumer`]s observe and sessions withdraw from their peers. +#[must_use = "dropping an announce::Producer retracts the route"] +pub struct AnnounceProducer { + shared: kio::Shared, + /// The table entries this advertisement created: one per allowed root the + /// requested prefix intersected. + ids: Vec, + /// Ingress announce stats guard, held for the advertisement's lifetime. + _guard: stats::Announce, } -/// Everything the driver polls and tears down, split from the park so the two -/// borrow disjointly. -struct DriverState { - /// Source watchers, fronts, and serve tasks: producers submit, this polls. - set: TaskSet, - /// The whole broadcast tree, for the teardown walk on drop. - nodes: OriginNodes, - /// The dynamic request queue, for rejecting pending requests on drop. - dynamic: kio::Shared, - /// Cached completion so a poll after `Ready` doesn't re-poll the drained set. - done: bool, +impl AnnounceProducer { + /// Re-price the route in place: replace its hops and cost. + /// + /// Consumers observe another active update for the same prefix; sessions + /// forward it as a restart, so route churn never looks like new content. The + /// prefix is fixed at announce time and a [`Route`] cannot name one: to move + /// an advertisement, drop this and announce again. Fails with + /// [`Error::Closed`] once the origin's [`Driver`] has been dropped. + pub fn update(&self, route: Route) -> Result<(), Error> { + let mut shared = self.shared.lock(); + if shared.closed { + return Err(Error::Closed); + } + for id in &self.ids { + // Each entry keeps its clamped prefix; only the metadata moves. + let Some(entry) = shared.routes.iter_mut().find(|entry| entry.id == *id) else { + continue; + }; + entry.hops = route.hops.clone(); + entry.cost = route.cost; + let prefix = entry.prefix.clone(); + shared.sync_route(&prefix.as_path()); + } + Ok(()) + } } -impl Driver { - /// Install the timers and return the runnable driver. - /// - /// The origin's lifecycle work stamps instants and arms deadlines against - /// `timers`; nothing runs until the returned [`Run`] is polled. - pub fn run(self, timers: T) -> Run +impl Drop for AnnounceProducer { + fn drop(&mut self) { + let mut shared = self.shared.lock(); + for id in &self.ids { + let Some(index) = shared.routes.iter().position(|entry| entry.id == *id) else { + continue; + }; + let entry = shared.routes.swap_remove(index); + // Reject anything still waiting on this route's server; a request + // already handed to the handler resolves through its own `Request`. + if let Some(server) = &entry.server { + let mut server = server.lock(); + server.closed = true; + for producer in server.requests.drain_all() { + if let Ok(mut request) = producer.write() { + request.resolved.get_or_insert(Err(Error::Unroutable)); + } + } + } + shared.sync_route(&entry.prefix.as_path()); + } + } +} + +/// The request queue behind a served route, from [`Producer::announce_served`]. +/// +/// Sessions poll it for the paths consumers resolve under the route and +/// materialize each on demand. Dropping it (without the announcement) leaves the +/// route advertised but unservable; drop both to retract. +pub(crate) struct RouteServer { + root: PathOwned, + state: kio::Shared, +} + +impl RouteServer { + /// Poll for the next requested path under this route, without blocking. + /// + /// Returns [`Error::Closed`] once the announcement is retracted or the origin + /// torn down: no request will ever arrive again, so server loops should end. + pub fn poll_requested_broadcast(&mut self, waiter: &kio::Waiter) -> Poll> { + let mut state = ready!(self.state.poll(waiter, |state| { + if state.closed || state.requests.has_queued() { + Poll::Ready(()) + } else { + Poll::Pending + } + })); + + if state.closed { + return Poll::Ready(Err(Error::Closed)); + } + + let path = state.requests.pop().expect("predicate guaranteed a request"); + let producer = state.requests.get(&path).expect("popped key must be pending").clone(); + Poll::Ready(Ok(Request { + path, + producer, + home: RequestHome::Route(self.state.clone()), + })) + } + + /// Returns the prefix that is automatically stripped from requested paths. + #[allow(dead_code)] + pub fn root(&self) -> &Path<'_> { + &self.root + } +} + +impl Drop for RouteServer { + fn drop(&mut self) { + let mut state = self.state.lock(); + if state.requests.remove_handler() { + state.closed = true; + for producer in state.requests.drain_all() { + if let Ok(mut request) = producer.write() { + request.resolved.get_or_insert(Err(Error::Unroutable)); + } + } + } + } +} + +/// The origin's lifecycle work, waiting for the [`crate::Timers`] it runs on. +/// +/// Returned by [`Producer::new`] alongside the producer. Call +/// [`run`](Self::run) with the timers that arm its deadlines (linger, handover +/// holds) and poll the returned [`Run`] for the life of the origin. Route +/// changes, track serving, linger timers, failover, and teardown all run there: +/// exact lookups and eligible announcements still update synchronously in +/// [`Producer::create_broadcast`], but nothing else makes progress without +/// polling. +/// +/// It holds no [`Producer`] clone, so it never keeps the origin alive. +/// Dropping it (before or after `run`) tears the origin down immediately: +/// active fronts abort with [`Error::Dropped`], pending dynamic requests are +/// rejected, announced paths unannounce and announcement cursors end, and later +/// producer mutations fail with [`Error::Closed`]. +/// +/// `moq_tokio::origin::spawn` wraps construction, `run`, and spawning for +/// tokio callers. +#[must_use = "call Driver::run and poll the result or the origin makes no progress"] +pub struct Driver { + state: DriverState, + // The producer's slot, filled by `run` so lifecycle work can mint deadlines. + timers: TimersSlot, +} + +/// Everything the driver polls and tears down, split from the park so the two +/// borrow disjointly. +struct DriverState { + /// Source watchers, fronts, and serve tasks: producers submit, this polls. + set: TaskSet, + /// The whole broadcast tree, for the teardown walk on drop. + nodes: OriginNodes, + /// The route table, announce cursors, and the fallback request queue, for + /// ending everything on drop. + shared: kio::Shared, + /// Cached completion so a poll after `Ready` doesn't re-poll the drained set. + done: bool, +} + +impl Driver { + /// Install the timers and return the runnable driver. + /// + /// The origin's lifecycle work stamps instants and arms deadlines against + /// `timers`; nothing runs until the returned [`Run`] is polled. + pub fn run(self, timers: T) -> Run where T: crate::runtime::Timers + MaybeSend + MaybeSync + 'static, T::Timer: MaybeSend + 'static, @@ -1471,7 +1652,8 @@ impl DriverState { } /// Tear the origin down: cancel the lifecycle work, abort and unpublish every - /// front, end announcement cursors, and reject pending dynamic requests. + /// front, retract every route, end announcement cursors, and reject pending + /// requests. fn teardown(&mut self) { // Cancel queued and running lifecycle work first, so nothing re-attaches // or serves while the walks below empty the tree. @@ -1481,29 +1663,42 @@ impl DriverState { // `create_broadcast` holds across its attach: a concurrent create either // finishes before this (the walk below cleans its entry up) or observes // `closed` and fails with `Closed`. - let pending = { - let mut dynamic = self.dynamic.lock(); - dynamic.closed = true; - dynamic.requests.drain_all() + let (pending, servers, cursors) = { + let mut shared = self.shared.lock(); + shared.closed = true; + let servers: Vec<_> = shared.routes.iter().filter_map(|entry| entry.server.clone()).collect(); + let cursors: Vec<_> = shared.cursors.values().map(|cursor| cursor.state.clone()).collect(); + (shared.fallback.drain_all(), servers, cursors) }; - // Reject every pending dynamic request, including those already handed - // to a handler: the teardown is terminal, so a handler resolving late - // must not beat it (resolution is first-write-wins). + // Reject every pending request, including those already handed to a + // handler: the teardown is terminal, so a handler resolving late must not + // beat it (resolution is first-write-wins). for producer in pending { if let Ok(mut request) = producer.write() { request.resolved.get_or_insert(Err(Error::Dropped)); } } + for server in servers { + let mut server = server.lock(); + server.closed = true; + for producer in server.requests.drain_all() { + if let Ok(mut request) = producer.write() { + request.resolved.get_or_insert(Err(Error::Dropped)); + } + } + } - // Two passes: unannounce every broadcast first, then end the cursors, so - // the final unannounces are still delivered (a cursor drains its pending - // updates before reporting the end). - for (_, node) in &self.nodes.nodes { - teardown_broadcasts(node); + // End the announce cursors: each drains its pending updates, then reports + // the end. Registrations stay (the cursors remove themselves on drop). + for state in cursors { + if let Ok(mut state) = state.write() { + state.ended = true; + } } + for (_, node) in &self.nodes.nodes { - teardown_cursors(node); + teardown_broadcasts(node); } } } @@ -1526,14 +1721,14 @@ impl Future for Run { } } -/// Abort, unpublish, and unannounce every broadcast under `node` with -/// [`Error::Dropped`]. The lifecycle tasks are already cancelled, so this -/// finishes the teardown they would have run. +/// Abort and unpublish every broadcast under `node` with [`Error::Dropped`]. The +/// lifecycle tasks are already cancelled, so this finishes the teardown they +/// would have run. fn teardown_broadcasts(node: &Lock) { - let (entry, notify, children) = { + let (entry, children) = { let mut guard = node.lock(); let children: Vec<_> = guard.nested.values().cloned().collect(); - (guard.broadcast.take(), guard.notify.clone(), children) + (guard.broadcast.take(), children) }; if let Some(mut entry) = entry { // Close the front so anything still holding its table observes the end. @@ -1542,34 +1737,12 @@ fn teardown_broadcasts(node: &Lock) { } entry.broadcast.abort_spliced(Error::Dropped); entry.broadcast.finish(); - if entry.announced { - notify.lock().unannounce(&entry.path); - } } for child in children { teardown_broadcasts(&child); } } -/// End every announcement cursor registered under `node`: each drains its -/// pending updates, then reports closure. Registrations stay in place (the -/// cursors remove themselves on drop); they just never fire again. -fn teardown_cursors(node: &Lock) { - let (notify, children) = { - let guard = node.lock(); - let children: Vec<_> = guard.nested.values().cloned().collect(); - (guard.notify.clone(), children) - }; - for consumer in notify.lock().consumers.values() { - if let Ok(mut state) = consumer.state.write() { - state.ended = true; - } - } - for child in children { - teardown_cursors(&child); - } -} - /// How long a spliced track stays warm after its last reader leaves. /// /// Within the window a returning viewer, or the next of a run of back-to-back @@ -1585,490 +1758,76 @@ fn teardown_cursors(node: &Lock) { const TRACK_IDLE_LINGER: Duration = Duration::from_secs(30); /// One attached source in a [`FrontState`] table. -struct FrontRoute { +struct FrontSource { id: u64, - /// The source's latest [`broadcast::Route`], mirrored from its - /// `route_changed` stream; picks the active source and gates the announce. - route: broadcast::Route, /// The source broadcast tracks are served from. source: broadcast::Consumer, } -/// What a held re-parent is keyed by: the relay it would adopt. -/// -/// An anonymous relay ([`Hop::UNKNOWN`]) identifies nothing, so its route id -/// stands in: another anonymous route is another relay until proven otherwise, -/// and a reconnecting anonymous relay restarts its wait, which is the price of -/// withholding an identity. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -enum HoldKey { - /// The target's announcing relay, when it declared an identity. - Relay(Hop), - /// The target route itself, when its relay is anonymous. - Route(u64), -} - -/// How [`FrontState::pick`] steers around routes tainted for a current reader. -#[derive(Clone, Copy)] -enum Steer { - /// No steering: the caller pins one requester to one source. - Ignore, - /// Prefer clean routes, falling back only when none exist. An offline clean - /// standby is worth trying for a track; one that refuses falls back through - /// the caller's skip set. - Clean, - /// Prefer clean routes only where that preserves an announced route. The - /// pick drives the front's advert, and steering it onto an offline standby - /// would retract the path (see [`FrontState::prefer_untainted`]). - KeepAnnounced, -} - -/// Shared state behind a [`Front`]: the attached sources and which one is active. +/// Shared state behind a front: the attached local sources and which one is +/// active. struct FrontState { - /// Absolute path of the broadcast, mixed into the route tie-break hash. - path: PathOwned, - /// The local origin's identity, the other half of the handover key gate. - self_hop: Hop, - /// Content identity: the original publisher (first hop) shared by every - /// attached source, or `None` for a broadcast produced locally (no hops). - /// Fixed for the front's lifetime; a source with a different first hop is new - /// content, not an alternate route, so it replaces this front (or waits for - /// it, when offline) rather than joining it (see [`attach_source`]). This is - /// the same rule the session layer applies to a restart whose first hop - /// changed. - publisher: Option, - /// The re-parent currently held down: which relay it targets and when the - /// wait started. Keyed to the target relay, so a candidate flapping between - /// two routes to the same relay (a reconnect under a fresh route id - /// included) cannot restart the wait, while a candidate from any other - /// relay starts its own wait instead of inheriting an aged timer it was - /// never held by. See [`HANDOVER_HOLD`]; the front task sleeps on the - /// deadline. - pending: Option<(HoldKey, Instant)>, - - /// Attach counter, handed to each [`FrontRoute`] so [`route_order`] can break - /// an exact tie toward the newest source. - next_route: u64, - routes: Vec, - /// Peers this front is exposed to, refcounted by live [`ExclusionGuard`]s: those - /// reading it through the shared broadcast, and those we merely advertise it to. - /// The resolve-time check only proves the table is clean for a requester at that - /// instant; the front picks per track and re-picks on failover, so without this a - /// route tainted for an attached peer could be adopted underneath them and hand - /// them back their own bytes. Routes through these origins are avoided while any - /// clean alternative exists. - /// - /// Advertising registers a peer too, because a peer that cannot echo our identity - /// back (moq-transport carries no hop ids) may re-advertise the path to us before - /// it ever subscribes. That reflection is otherwise indistinguishable from a rival - /// publisher, and this is what tells [`attach_source`] apart. - excluded: HashMap, - /// Set when `excluded` gained or lost a peer without a reselect. The guards - /// register and release under locks that cannot re-run selection or sync - /// the front, so the front task observes this flag and does both: a peer - /// starting to read can taint the active route out from under it, and one - /// leaving can free a better route. - excluded_changed: bool, - /// The source tracks are dispatched to. Backups park until promoted. + /// Attach counter, handed to each [`FrontSource`] so selection can break a + /// tie toward the newest source. + next_source: u64, + sources: Vec, + /// The source tracks are dispatched to: the newest attached. Backups park + /// until promoted. active: Option, /// Terminal: no more sources may attach and every poller stops. Set - /// synchronously by the detach that empties the table or by an - /// [`attach_source`] takeover. + /// synchronously by the detach that empties the table. closed: bool, } impl FrontState { - /// The one selection primitive every picker goes through: the best route by - /// [`route_order`] among those surviving `keep`, steering around tainted - /// routes per `steer` (see [`Steer`] and [`Self::prefer_untainted`]). - fn pick(&self, keep: impl Fn(&FrontRoute) -> bool, steer: Steer) -> Option { - let candidates: Vec<&FrontRoute> = self.routes.iter().filter(|r| keep(r)).collect(); - let candidates = match steer { - Steer::Ignore => candidates, - Steer::Clean => self.prefer_untainted(&candidates, false), - Steer::KeepAnnounced => self.prefer_untainted(&candidates, true), - }; - candidates - .into_iter() - .min_by_key(|r| route_order(&self.path.as_path(), r)) - .map(|r| r.id) - } - - /// The source new track requests should dispatch to: live first, then lowest - /// cost, then shortest hop chain with a deterministic hash tie-break and the - /// newest source last, skipping routes that flow through a peer currently - /// reading the front while an announced alternative remains. This choice - /// drives the front's advert, so it never trades the announcement away. - fn best_route(&self) -> Option { - self.pick(|_| true, Steer::KeepAnnounced) - } - - /// The source a subscription from `exclude` should dispatch to: the best - /// route whose hop chain does not contain the requester. This is the same - /// selection a session uses to pick what it announces to that peer, and the - /// two being one computation is the loop-freedom invariant: chains stay - /// truthful, so any would-be cycle surfaces the requester's own origin in - /// the candidate chain and is filtered here, at any cycle length. Taints are - /// ignored: this pins one requester to one source rather than serving the - /// shared front. - fn dispatch(&self, exclude: Option) -> Option { - self.pick( - |r| exclude.is_none_or(|origin| !r.route.hops.contains(&origin)), - Steer::Ignore, - ) - } - - /// Whether `route` flows back through a peer this front is exposed to, so serving - /// (or attaching) it would hand that peer its own bytes back. - /// - /// Doubles as the reflection test in [`attach_source`]: a route arriving through a - /// peer we are already advertising this path to is our own broadcast coming home, - /// whatever its chain claims. - fn taints_a_reader(&self, route: &broadcast::Route) -> bool { - route.hops.iter().any(|hop| self.excluded.contains_key(hop)) - } - - /// Narrow `candidates` to the routes clean for every peer currently reading the - /// shared front, unless that would leave nothing, or (with `keep_announced`) - /// cost the front its announcement. - /// - /// Keeping the front off a tainted route is what makes the resolve-time - /// split-horizon check hold for the life of a subscription rather than just at - /// request time. The taint-wide fallback is deliberate: when every route is - /// tainted, the alternative is starving readers the route is perfectly good - /// for, and a peer whose only path runs back through itself has nothing to be - /// served from anyway; it re-resolves to [`Error::Unroutable`] on its next - /// request. - /// - /// `keep_announced` adds a second fallback for the pick that drives the - /// front's advert ([`Self::best_route`]): when every clean route is an offline - /// standby, steering the advert onto one would retract the path, and the - /// retraction drops the very advertisement whose guard made the route look - /// tainted, re-running this selection with the taint gone and oscillating the - /// announcement. Per-track dispatch ([`Self::serve_route`]) leaves it off: an - /// offline standby is worth trying for a track, and one that refuses falls - /// back through the caller's skip set instead. - fn prefer_untainted<'a>(&self, candidates: &[&'a FrontRoute], keep_announced: bool) -> Vec<&'a FrontRoute> { - if self.excluded.is_empty() { - return candidates.to_vec(); - } - let clean: Vec<&FrontRoute> = candidates - .iter() - .copied() - .filter(|r| !self.taints_a_reader(&r.route)) - .collect(); - let keeps = match keep_announced && candidates.iter().any(|r| r.route.announce) { - true => clean.iter().any(|r| r.route.announce), - false => !clean.is_empty(), - }; - match keeps { - true => clean, - false => candidates.to_vec(), - } + /// The newest attached source: the one new work dispatches to. Local sources + /// carry no route metadata, so recency is the whole order: a publisher + /// re-creating a path over a fresh handle wins the moment it attaches instead + /// of waiting for the old handle to be torn down. + fn best_source(&self) -> Option { + self.sources.iter().map(|s| s.id).max() } /// The source one track should be served from: the front's active source - /// unless `skip` rules it out, then the next-best route that survives. + /// unless `skip` rules it out, then the newest source that survives. /// /// Whether a source carries a given track is a per-track property (a standby /// that has not created it yet, a publisher whose encoder is still starting), /// so a source refusing one track is ruled out of that track only, never out - /// of the front. Preferring `active` keeps a servable track on exactly the - /// route [`Self::reselect`] chose, handover gate included. + /// of the front. fn serve_route(&self, skip: impl Fn(u64) -> bool) -> Option { if let Some(active) = self.active && !skip(active) - && let Some(route) = self.routes.iter().find(|r| r.id == active) - && !self.taints_a_reader(&route.route) + && self.sources.iter().any(|s| s.id == active) { return Some(active); } - self.pick(|r| !skip(r.id), Steer::Clean) + self.sources.iter().map(|s| s.id).filter(|id| !skip(*id)).max() } /// Re-pick the active source after the table changed. Serve tasks watch - /// `active` and re-splice on their own, so a cheaper route takes over - /// seamlessly at a group boundary. - /// - /// The one exception is the simultaneous-activation race: two nodes that - /// each pulled the broadcast before seeing the other both advertise zero - /// cost, so each sees the other as cheaper than its own source, and - /// re-parenting onto each other at once leaves the broadcast with no - /// upstream at all. That hazard only exists when both sides are actively - /// carrying, so the gate is scoped to exactly that: while `carrying` (the - /// front has live demand), a better route whose announcing relay is itself - /// carrying (it advertised a zero warm cost from a chain of two or more - /// hops; a chain of one is the original publisher, which can never adopt a - /// route to its own broadcast) displaces an announced incumbent only when - /// [`Self::handover_allowed`] says so. Every other better route, e.g. a - /// forwarder path or an upstream that repriced itself down, is taken - /// immediately. - #[cfg(test)] - fn reselect_now(&mut self, carrying: bool) { - self.active = self.reselect_target(carrying); - self.pending = None; - } - - /// Re-pick the active source after the table changed, holding a warm-sibling - /// adoption down for - /// [`HANDOVER_HOLD`] first. Returns the deadline while one is waiting, which - /// the front task sleeps on so the hold is re-evaluated when it expires. - /// - /// Only the adoption is held down, because only the adoption can cycle. Every - /// other move (a cheaper upstream, a failover, losing the incumbent) applies - /// at once, so ordinary recovery keeps its current latency. - /// - /// The point of the wait is not to stagger the relays, which a uniform delay - /// cannot do. It is that the stale advertisement that motivated the adoption - /// is refreshed while we wait, so the re-evaluation at expiry runs on current - /// costs and usually no longer wants to move at all. - fn reselect(&mut self, carrying: bool, now: Instant) -> Option { - let target = self.reselect_target(carrying); - - // What can cycle is re-parenting onto a source reached through a session, - // since only something we can depend on can depend on us back. Demand is - // deliberately not part of that test: an idle front still records the choice, - // and nothing re-runs the selection when demand arrives, so a selection made - // while idle is simply a cycle that starts later. Nor is hop count, since a - // peer that does not speak the cluster extension is announced as one hop - // however deep the chain behind it really is. Only a local publish, which - // reaches no session at all, is structurally unable to close a loop. - // - // Three exemptions. Losing the incumbent has to apply at once, or the front - // strands itself with nothing to serve from at all. An incumbent that taints - // a reader is the same: `serve_route` already refuses it, so keeping it - // active would only leave `routes_snapshot` advertising a chain the front - // does not serve from. An incumbent that stopped announcing is the same - // kind of repair: keeping it active keeps it first in `routes_snapshot`, - // which retracts the whole path for the hold window while a live route - // sits in the table. None of the three is one end of a mutual adoption, - // which needs both sides to be live parents worth adopting. - // - // A drain is deliberately NOT exempt. It reads like an emergency, but a - // GOAWAY keeps working for many seconds, so waiting costs a little - // optimality rather than any availability, and a correlated drain is exactly - // when several relays re-parent at once off prices that have not landed yet. - // The exemptions also compose: if the drain does become a death, the - // route leaves the table and the lost-incumbent path applies - // immediately, so the wait is bounded by the session it is waiting on. - let held = target != self.active - && self.active.is_some_and(|id| { - self.routes - .iter() - .find(|r| r.id == id) - .is_some_and(|r| r.route.announce && !self.taints_a_reader(&r.route)) - }) && target.is_some_and(|id| { - let last = |id: u64| { - self.routes - .iter() - .find(|r| r.id == id) - .and_then(|r| r.route.hops.iter().last().copied()) - }; - // A fresh session from the relay we already depend on is not a new edge, - // so it cannot close a loop that the current route does not already - // close. Holding it would strand the front on a corpse until the - // transport finally timed it out, which is what the recency order in - // `route_order` exists to prevent. Only a declared identity proves - // "same relay": an anonymous hop matches nothing, so a move between - // two anonymous relays is held like any other. - last(id).is_some() && !same_identity(last(id), self.active.and_then(last)) - }); - - if !held { - self.active = target; - self.pending = None; - return None; - } - - let target = target.expect("a held target is always Some"); - // Timed from when we first wanted to re-parent onto this relay, not from - // when we first wanted this candidate route: a peer that reconnects - // under a fresh route id would otherwise restart the wait on every - // session and postpone the move forever. A candidate from a different - // relay starts its own wait, so a newcomer arriving after an earlier - // candidate's deadline is held too, rather than adopted off a timer it - // never aged against. At expiry we apply whichever candidate wins then, - // which is the re-read the hold exists for. - let key = self.hold_key(target); - let since = match self.pending { - Some((held, since)) if held == key => since, - _ => now, - }; - - let deadline = self.hold_deadline(since); - match deadline.is_some_and(|at| now >= at) { - true => { - self.active = Some(target); - self.pending = None; - None - } - false => { - self.pending = Some((key, since)); - deadline - } - } - } - - /// The identity a hold on adopting route `id` is keyed by (see [`HoldKey`]). - fn hold_key(&self, id: u64) -> HoldKey { - let relay = self - .routes - .iter() - .find(|r| r.id == id) - .and_then(|r| r.route.hops.iter().last().copied()); - match relay { - Some(relay) if relay != Hop::UNKNOWN => HoldKey::Relay(relay), - _ => HoldKey::Route(id), - } - } - - /// When a hold started at `since` comes due: [`HANDOVER_HOLD`] plus a spread of - /// up to half as much again, fixed per relay and broadcast. - /// - /// The hold works by outlasting propagation, so it does not need the spread to - /// be correct. The spread is there so a datacenter re-evaluating the same - /// broadcast does not do it on a single instant, and it reuses the key the - /// handover order already computes, so it costs nothing and stays put across - /// restarts. Added rather than subtracted, so the floor is still - /// [`HANDOVER_HOLD`]. - fn hold_deadline(&self, since: Instant) -> Option { - let spread = (HANDOVER_HOLD / 2).as_millis() as u64; - let key = fnv_key(&self.path.as_path(), [self.self_hop]); - since.checked_add(HANDOVER_HOLD + Duration::from_millis(key % spread.max(1))) - } - - /// The source [`Self::reselect`] would pick, before the hold-down: the best - /// route, unless the handover gate keeps the incumbent. - fn reselect_target(&self, carrying: bool) -> Option { - let best = self.best_route(); - if carrying - && let (Some(best_id), Some(cur_id)) = (best, self.active) - && best_id != cur_id - && let Some(candidate) = self.routes.iter().find(|r| r.id == best_id) - && let Some(incumbent) = self.routes.iter().find(|r| r.id == cur_id) - && incumbent.route.announce - // An incumbent flowing through a peer that reads this front is one - // `serve_route` refuses anyway, so keeping it only makes the advert - // disagree with dispatch. Same reasoning as the hold's exemption. - && !self.taints_a_reader(&incumbent.route) - && candidate.route.advertised.warm == 0 - && candidate.route.hops.len() >= 2 - && !self.handover_allowed(&candidate.route, &incumbent.route) - { - // We outrank the peer: keep our source and let it come to us. - return self.active; - } - best - } - - /// Whether re-parenting onto `candidate` is allowed while actively carrying: - /// the announcing relay's rank must be strictly lower than our own. - /// - /// A relay's rank is `(cold cost, hash of its origin for this broadcast)`: the - /// cold cost of the route it serves from, which is exactly what it advertises, - /// and the hash only to break a tie between equally-rooted relays. Both sides - /// compute the same two ranks from the same inputs (the hash is build-stable), - /// so the comparison resolves the same way everywhere. - /// - /// That makes adoption descend a total order, which is what stops two relays - /// adopting each other: taking a parent adds this link's price to our own cold - /// cost, so once the move lands we rank above the relay we adopted. The cold - /// cost is what carries the topology signal here, since the warm costs of two - /// carrying relays are both zero by construction. Mixing the broadcast name - /// into the hash spreads ownership across a region's relays instead of - /// funneling every broadcast onto the lowest-hashed one. - /// - /// The order is only shared while the costs behind it are. A relay reports its - /// own cold cost, and a report still crossing the mesh can be lower than what - /// that relay would say now, so during a reprice two relays can rank each other - /// from different numbers and both decide to move. [`HANDOVER_HOLD`] is what - /// covers that window; the hash half needs no such care, since it is computed - /// rather than reported and so is never in flight. - /// - /// Two cases are not a new parent at all and are always allowed: a route with - /// no hops (a local publish), and a route from the relay we already serve from, - /// which is that session reconnecting. Only a declared identity proves the - /// latter: an anonymous relay matches nothing, so it takes the rank - /// comparison like any other, where the 0 it declared is what both sides - /// hash. Two fully anonymous relays therefore rank equal and neither moves, - /// which is the cluster draft's rule that equal ids cannot be ordered. - fn handover_allowed(&self, candidate: &broadcast::Route, incumbent: &broadcast::Route) -> bool { - let name = self.path.as_path(); - let Some(peer) = candidate.hops.iter().last().copied() else { - return true; - }; - if same_identity(incumbent.hops.iter().last().copied(), Some(peer)) { - return true; - } - - let theirs = (candidate.advertised.cold, fnv_key(&name, [peer])); - let ours = (incumbent.cost.cold, fnv_key(&name, [self.self_hop])); - theirs < ours - } - - /// Every attached route in preference order with the active one first, - /// mirrored onto the front's broadcast so sessions can advertise (and be - /// served) a different route per peer. The active route leads even when the - /// handover gate kept it over a lower-ordered candidate, so `routes[0]` is - /// always what this node is actually serving from. - fn routes_snapshot(&self) -> Vec { - let mut routes: Vec<&FrontRoute> = self.routes.iter().collect(); - routes.sort_by_key(|r| route_order(&self.path.as_path(), r)); - routes.sort_by_key(|r| Some(r.id) != self.active); - routes.into_iter().map(|r| r.route.clone()).collect() - } -} - -/// Refresh the front's public face after a table change: advertise the best -/// source's route on the spliced broadcast and gate the path's announcement on -/// its `live` flag. -/// -/// Re-reads the table at apply time (rather than applying a value computed under -/// an earlier lock) so concurrent attach/detach/update calls converge on the -/// latest winner regardless of the order their applies land in. An empty table -/// leaves the advert and announce state alone; the front task is closing and -/// unannounces on its way out. -fn sync_front(state: &kio::Producer, broadcast: &broadcast::Producer, leaf: &Lock) { - // Snapshot and apply under the leaf lock: two concurrent syncs would - // otherwise race their applies, letting a stale snapshot land last and - // leave the announce flag (or advert) contradicting the current table. - // Lock order (leaf, then table, then broadcast) matches attach_source. - let mut leaf_guard = leaf.lock(); - let routes = state.read().routes_snapshot(); - if let Some(advert) = routes.first() { - let announce = advert.announce; - broadcast.clone().set_routes(routes); - leaf_guard.set_announced(state, announce); + /// `active` and re-splice on their own, so a replacement takes over seamlessly + /// at a group boundary. + fn reselect(&mut self) { + self.active = self.best_source(); } } -/// Detach source `id`, promoting the next-best source; the tracks it was serving -/// re-splice on their own. Idempotent. +/// Detach source `id`, promoting the newest remaining source; the tracks it was +/// serving re-splice on their own. Idempotent. /// /// Detaching the last source closes the broadcast synchronously, however the /// source ended, which guarantees a following create at the path is a *new* -/// broadcast rather than splicing new content into this one. Failover is a -/// property of sources that overlap in the table (a GOAWAY migration, a -/// redundant publisher), never of a source that might come back later. -fn detach_source( - state: &kio::Producer, - broadcast: &broadcast::Producer, - leaf: &Lock, - id: u64, - timers: &TimersSlot, -) { +/// broadcast rather than splicing new content into this one. +fn detach_source(state: &kio::Producer, broadcast: &broadcast::Producer, leaf: &Lock, id: u64) { let close = { - // Snapshotted before the state lock (lock order: broadcast, then front). - // A demand flip in between only stales this reselect's handover gate, - // which self-corrects on the next table change. - let carrying = broadcast.demand().is_used(); let Ok(mut s) = state.write() else { return }; - let Some(pos) = s.routes.iter().position(|r| r.id == id) else { + let Some(pos) = s.sources.iter().position(|entry| entry.id == id) else { return; }; - s.routes.remove(pos); - s.reselect(carrying, timers.now()); - if s.routes.is_empty() && !s.closed { + s.sources.remove(pos); + s.reselect(); + if s.sources.is_empty() && !s.closed { // Last one out: close now. The front task observes `closed` and // finishes the teardown (unpublish). s.closed = true; @@ -2080,239 +1839,47 @@ fn detach_source( if close { broadcast.abort_spliced(Error::Dropped); } - sync_front(state, broadcast, leaf); -} - -/// Match the ingress announce guard to a route's announce flag: opening bumps -/// the announced counters, dropping bumps the closed ones. See [`run_source`]. -fn sync_announce(guard: &mut Option, announced: bool, ingress: &stats::Scope) { - match (announced, guard.is_some()) { - (true, false) => *guard = Some(ingress.announce()), - (false, true) => *guard = None, - _ => {} - } + // The tree is pruned by the front task once it observes the close. + let _ = leaf; } /// Everything a queued source watcher continues with after -/// [`Producer::create_broadcast`] performed the synchronous first attach. +/// [`Producer::create_broadcast`] performed the synchronous attach. struct SourceTask { - origin: Info, - node: Lock, - /// Absolute path, for the front's identity and log lines. - full: PathOwned, - /// Path relative to `node`, for locating (and later pruning) the leaf. - rest: PathOwned, - /// The source's route cursor, already advanced past its initial observation. + /// The source broadcast, watched for its end. source: broadcast::Consumer, - ingress: stats::Scope, - tasks: Tasks, timers: TimersSlot, - /// The initial route, as create_broadcast observed it. - route: broadcast::Route, - /// Ingress announce guard: held while this source's route is announced. - /// Opened by create_broadcast when the initial route announces; the watcher - /// toggles it on transitions, bumping `announced` / `announced_closed` - /// (+ bytes). Empty scope = no-op. - announce: Option, - /// The leaf the first attach landed on. + /// The leaf the attach landed on. leaf: Lock, - /// The outcome of the synchronous first attach. - first: Attach, + /// The front's source table. + state: kio::Producer, + /// The spliced broadcast the front serves. + broadcast: broadcast::Producer, + /// The source's id in the table. + id: u64, } -/// Owns one source's lifecycle after its synchronous first attach: forwards -/// route updates, re-attaches on publisher swaps and takeovers, and detaches the -/// source when it closes. Queued on the origin's [`Driver`] by -/// [`Producer::create_broadcast`], which performs the first attach itself and -/// hands the outcome in as [`SourceTask::first`] so the watcher never attaches -/// twice. -/// -/// An announced source whose original publisher (first hop) differs from the -/// live front's takes the path over as a fresh broadcast rather than joining; an -/// offline one parks until the front closes. A route update that changes the -/// source's own first hop likewise detaches it and re-runs the attach, so a -/// publisher swap is always a replacement, never a silent splice. +/// Owns one source's lifecycle after its synchronous attach: waits for the +/// source to end (finish, abort, or drop), then detaches it. Queued on the +/// origin's [`Driver`] by [`Producer::create_broadcast`]. async fn run_source(task: SourceTask) { let SourceTask { - origin, - node, - full, - rest, - mut source, - ingress, - tasks, + source, timers, - mut route, - mut announce, leaf, - first, + state, + broadcast, + id, } = task; - let ctx = AttachContext { - origin: &origin, - node: &node, - full: &full, - rest: &rest, - tasks: &tasks, - timers: &timers, - }; - - // Whether this source still has content the live front has not already beaten. - // Cleared when a rival displaces it, so it stands by instead of evicting the - // winner straight back; only a new publisher re-arms it, since a repricing is - // the same content losing the same argument twice. Whether the route is - // announced is a separate gate, owned by `attach_source`. - let mut may_take_over = true; - - // The synchronous first attach, consumed on the first pass; later passes - // re-attach themselves. - let mut first = Some((leaf, first)); - - 'attach: loop { - let (leaf, attach) = match first.take() { - Some(attempt) => attempt, - None => { - // Re-resolved every attempt: between attaches the previous front's - // teardown may have pruned the (then-empty) leaf from the tree, and - // attaching to the stale lock would publish into an orphan that lookups - // can no longer reach. - let leaf = if rest.is_empty() { - node.clone() - } else { - node.lock().leaf(&rest) - }; - let attach = attach_source(&ctx, &leaf, &source, route.clone(), may_take_over); - (leaf, attach) - } - }; - - let (state, broadcast, id) = match attach { - Attach::Ready(state, broadcast, id) => (state, broadcast, id), - Attach::Parked(incumbent) => { - tracing::debug!( - broadcast = %full, - "path already live with a different publisher; parking this source until it ends", - ); - // Wait for the incumbent front to close, or for our own route to - // change: a new route observation earns another takeover attempt, and - // our source closing means giving up. - let update = kio::wait(|waiter| { - if let Poll::Ready(update) = source.poll_route_changed(waiter) { - return Poll::Ready(Some(update)); - } - // Ready on either the closed flag or the channel itself dying; - // both mean the incumbent is gone. - match incumbent.poll(waiter, |s| if s.closed { Poll::Ready(()) } else { Poll::Pending }) { - Poll::Ready(_) => Poll::Ready(None), - Poll::Pending => Poll::Pending, - } - }) - .await; - match update { - // Our route moved; recompute the guard and retry with it. - Some(Ok(update)) => { - sync_announce(&mut announce, update.announce, &ingress); - // Only a new publisher is content the winner has not beaten. - // Plain equality, matching the detach check below: an - // UNKNOWN-to-UNKNOWN repricing from a legacy peer proves no - // new identity, so it must not re-arm either. - if update.hops.iter().next().copied() != route.hops.iter().next().copied() { - may_take_over = true; - } - route = update; - } - // The source closed while parked; it was never visible. - Some(Err(_)) => return, - // The incumbent is gone; retry, creating a fresh front. - None => {} - } - continue 'attach; - } - }; - let publisher = route.hops.iter().next().copied(); + let _ = timers; - loop { - let update = kio::wait(|waiter| { - // A takeover closes this front without touching its still-live source. - // Observe that first, ahead of any simultaneous route update: a new - // first hop would otherwise re-arm `may_take_over` and win the path - // straight back, which is the eviction loop the flag exists to stop. - // `Err` here is the state channel dying, which also means displaced. - if state - .poll_ref(waiter, |s| if s.closed { Poll::Ready(()) } else { Poll::Pending }) - .is_ready() - { - return Poll::Ready(None); - } - source.poll_route_changed(waiter).map(Some) - }) - .await; - match update { - None => { - // The winner owns the path now. Stand by behind it, holding the - // ingress announce guard, until it leaves or our route moves again. - may_take_over = false; - continue 'attach; - } - Some(Ok(update)) => { - let announced = update.announce; - // A different first hop is new content: this source can no - // longer feed the front it attached to. Detach and re-attach. - // - // Plain equality, not `same_identity`: within one source - // handle the session layer already guarantees continuity (it - // replaces the handle when identity breaks, UNKNOWN restarts - // included), so this only catches a caller moving a live - // handle to a new publisher. An UNKNOWN-to-UNKNOWN metadata - // update (a legacy peer repricing) must not detach. - if update.hops.iter().next().copied() != publisher { - detach_source(&state, &broadcast, &leaf, id, &timers); - sync_announce(&mut announce, announced, &ingress); - // A new publisher, so this is content no front has beaten yet. A - // sibling source may still hold the old front open, making the - // re-attach a replacement rather than a create. - may_take_over = true; - route = update; - continue 'attach; - } - { - let carrying = broadcast.demand().is_used(); - let Ok(mut s) = state.write() else { return }; - let Some(entry) = s.routes.iter_mut().find(|r| r.id == id) else { - return; - }; - if entry.route == update { - continue; - } - entry.route = update; - s.reselect(carrying, timers.now()); - } - // Toggle the ingress announce guard on a live/offline transition. - sync_announce(&mut announce, announced, &ingress); - sync_front(&state, &broadcast, &leaf); - } - Some(Err(_)) => { - // The source ended, deliberately or not: detach it. If it was the - // last one the front closes with it. - detach_source(&state, &broadcast, &leaf, id, &timers); - return; - } - } - } - } -} + kio::wait(|waiter| source.poll_closed(waiter).map(Ok::<(), Error>)) + .await + .ok(); -/// The outcome of [`attach_source`]. -enum Attach { - /// The source joined (or created) the front at its path, yielding the shared - /// source table, the spliced broadcast, and the source's table id. - Ready(kio::Producer, broadcast::Producer, u64), - /// The path's live front belongs to a different original publisher and this - /// source may not take it: either the source is offline (so it would rank below - /// every route the front holds), it already spent its takeover attempt on this - /// route and lost, or its chain leads back through a peer the front is already - /// exposed to, making it a reflection rather than rival content. The caller - /// parks on the returned table until the front closes. - Parked(kio::Producer), + // The source ended, deliberately or not: detach it. If it was the last one + // the front closes with it. + detach_source(&state, &broadcast, &leaf, id); } /// Everything about a source's attach that does not change between attempts. @@ -2325,70 +1892,35 @@ struct AttachContext<'a> { rest: &'a PathOwned, /// Driver submission handle, for queueing a fresh front's task. tasks: &'a Tasks, - /// The driver's clock, for stamping reselects and threading into fronts. + /// The driver's clock, threaded into fronts for the track idle linger. timers: &'a TimersSlot, } -/// Whether two hop entries prove the same endpoint. -/// -/// [`Hop::UNKNOWN`] identifies nothing: it is what a peer that declared no -/// identity, or that does not speak the hops extension at all, contributes as a -/// hop. Two such entries never match. As first hops, splicing the sources they -/// name would cut one publisher's subscribers over to an unrelated publisher's -/// content; as last hops, two anonymous relays would pass for one relay -/// reconnecting and skip the handover safeguards. Every other id compares -/// normally, including `None` for a locally produced broadcast with no hops. -fn same_identity(a: Option, b: Option) -> bool { - if a == Some(Hop::UNKNOWN) || b == Some(Hop::UNKNOWN) { - return false; - } - a == b -} - /// Attach a source to the broadcast at `leaf`, creating (and publishing) the /// broadcast if none is live. One lock acquisition covers the whole /// join-or-create decision, so concurrent attaches cannot race each other. /// -/// Joining requires the same content identity (first hop). A source whose -/// original publisher differs takes the path over instead: the incumbent front -/// closes and a fresh one is created below, so consumers observe an unannounce -/// followed by an announce. That mirrors the session layer's rule that a restart -/// with a different first hop is a replacement, never a standby, and it is what -/// keeps a reconnect from waiting on the transport to retire the session it -/// replaced. -/// -/// Taking over requires announcing, which keeps the rule consistent with -/// [`route_order`]: an offline source ranks below every announced route, so it -/// waits ([`Attach::Parked`]) rather than unannouncing a live broadcast and -/// cutting its subscribers for content nobody has advertised. It also requires a -/// chain that does not lead back through a peer this front is already exposed to -/// (see [`FrontState::taints_a_reader`]): such a source is our own broadcast -/// reflected by a peer that cannot detect the loop itself, and letting it evict the -/// front is how a publish direction ends up withdrawing its own announce. -/// -/// `may_take_over` is the caller's third gate: [`run_source`] clears it once this -/// source has been displaced, so a route that already lost the path stands by -/// instead of winning it straight back. Only a new publisher re-arms it, since a -/// repricing carries no content the winner has not already beaten. +/// A later source joins the live front and immediately becomes the active one +/// (newest wins), so a publisher re-creating a path over a fresh handle takes +/// over without waiting for the old handle to be torn down; tracks re-splice at +/// the first missing group. A front whose sources have all closed is replaced by +/// a fresh broadcast instead, so new content is never spliced into subscribers +/// of a broadcast that is over. fn attach_source( ctx: &AttachContext, leaf: &Lock, source: &broadcast::Consumer, - route: broadcast::Route, - may_take_over: bool, -) -> Attach { - let publisher = route.hops.iter().next().copied(); +) -> (kio::Producer, broadcast::Producer, u64) { let mut leaf_guard = leaf.lock(); // Join the live broadcast if the leaf already has one. A closed one (torn // down, awaiting teardown, or evicted just below) is replaced instead. if let Some(existing) = &leaf_guard.broadcast { let mut joined = None; - let carrying = existing.broadcast.demand().is_used(); if let Ok(mut s) = existing.state.write() && !s.closed { - if !s.routes.is_empty() && s.routes.iter().all(|r| r.source.is_closing()) { + if !s.sources.is_empty() && s.sources.iter().all(|entry| entry.source.is_closing()) { // Every attached source has already closed; only the driver's // detach sweep is outstanding. Splicing requires overlapping // *live* sources, so joining now would splice new content into @@ -2396,89 +1928,45 @@ fn attach_source( // create a fresh one below; its own task finishes the teardown, // finding the leaf slot already taken. s.closed = true; - } else if same_identity(s.publisher, publisher) { - let id = s.next_route; - s.next_route += 1; - s.routes.push(FrontRoute { + } else { + let id = s.next_source; + s.next_source += 1; + s.sources.push(FrontSource { id, - route: route.clone(), source: source.clone(), }); - // A pre-run attach cannot stamp a hold against a clock that has not - // been installed yet. `run_front` reselects the complete table on its - // first poll and starts any hold on the driver's clock. - if let Some(now) = ctx.timers.try_now() { - s.reselect(carrying, now); - } + s.reselect(); joined = Some(id); - } else if !may_take_over || !route.announce || s.taints_a_reader(&route) { - return Attach::Parked(existing.state.clone()); - } else { - // New content at a live path: the newest publisher wins it. Closing - // the incumbent here (rather than letting the newcomer wait it out) - // is what makes a reconnect immediate, and routing the takeover - // through the replacement path below keeps the guarantee that - // unrelated content is never spliced into live subscribers. The - // incumbent's own task observes the flag and finishes its teardown, - // finding the leaf slot already taken. - s.closed = true; - tracing::warn!(broadcast = %ctx.full, "replacing a live broadcast from a different publisher"); } } if let Some(id) = joined { let state = existing.state.clone(); let broadcast = existing.broadcast.clone(); - drop(leaf_guard); - sync_front(&state, &broadcast, leaf); - return Attach::Ready(state, broadcast, id); + return (state, broadcast, id); } } // First source: create the broadcast and publish it into the tree. - let announce = route.announce; let broadcast = broadcast::Producer::new_spliced(broadcast::Info { origin: ctx.origin.clone(), path: ctx.full.clone(), }); - let _ = broadcast.clone().set_route(route.clone()); let state = kio::Producer::new(FrontState { - pending: None, - path: ctx.full.clone(), - self_hop: ctx.origin.id, - publisher, - next_route: 1, - excluded: HashMap::new(), - excluded_changed: false, - routes: vec![FrontRoute { + next_source: 1, + sources: vec![FrontSource { id: 0, - route, source: source.clone(), }], active: Some(0), closed: false, }); - // Replacing a stale (closed) entry counts as an unannounce, so consumers - // observe the replacement rather than a silent swap; its own teardown task - // then finds the slot already taken and leaves it alone. - if let Some(stale) = leaf_guard.broadcast.take() - && stale.announced - { - leaf_guard.notify.lock().unannounce(&stale.path); - } - let entry = OriginBroadcast { - path: ctx.full.clone(), + // A stale (closed) entry is replaced; its own teardown task then finds the + // slot already taken and leaves it alone. + leaf_guard.broadcast = Some(OriginBroadcast { broadcast: broadcast.clone(), state: state.clone(), - announced: announce, - }; - if entry.announced { - leaf_guard - .notify - .lock() - .announce(ctx.full, &broadcast.consume(), &state); - } - leaf_guard.broadcast = Some(entry); + }); drop(leaf_guard); ctx.tasks.push(run_front( @@ -2490,7 +1978,7 @@ fn attach_source( ctx.timers.clone(), )); - Attach::Ready(state, broadcast, 0) + (state, broadcast, 0) } /// Owns a front's lifecycle: dispatches each requested track to a serve task @@ -2505,26 +1993,9 @@ async fn run_front( ) { enum Step { Serve(Arc, super::resume::Producer), - /// A held-down adoption came due, or the exclusion table changed: - /// re-run the selection on current costs and taints. - Reselect, Closed, } - // Resolving the slot here is safe: an async body runs only when first - // polled, all polling goes through the driver, and `Driver::run` installs - // the timers before the driver can poll anything. - let timers = slot.get(); - let mut deadline = crate::runtime::Deadline::new(&timers); - - // Sources may attach synchronously before `Driver::run` installs its clock. - // Start any resulting handover only now, on the same clock that will arm it. - let carrying = broadcast.demand().is_used(); - if let Ok(mut s) = state.write() { - s.reselect(carrying, timers.now()); - } - sync_front(&state, &broadcast, &node); - loop { let step = { kio::wait(|waiter| { @@ -2532,28 +2003,15 @@ async fn run_front( return Poll::Ready(Step::Serve(name, resume)); } // The close is set synchronously by the detach that empties the - // table or by a takeover; this task only finishes the teardown. - // An exclusion change rides the same poll: the guards cannot - // reselect under their own locks, so this task does it for them. - match state.poll(waiter, |s| match s.closed || s.excluded_changed { + // table; this task only finishes the teardown. `Err` is the + // channel itself dying, which also ends the front. + match state.poll_ref(waiter, |s| match s.closed { true => Poll::Ready(()), false => Poll::Pending, }) { - // `Err` is the channel itself dying, which also ends the front. - Poll::Ready(Ok(s)) if !s.closed => return Poll::Ready(Step::Reselect), - Poll::Ready(_) => return Poll::Ready(Step::Closed), - Poll::Pending => {} + Poll::Ready(_) => Poll::Ready(Step::Closed), + Poll::Pending => Poll::Pending, } - - // Re-armed on every poll rather than once per turn: a source task - // arms the hold under the state lock, and that write wakes this - // closure without leaving the wait. Setting the instant it already - // holds is a no-op, so the countdown is not restarted. - deadline.set({ - let s = state.read(); - s.pending.and_then(|(_, since)| s.hold_deadline(since)) - }); - deadline.poll(waiter).map(|_| Step::Reselect) }) .await }; @@ -2564,19 +2022,6 @@ async fn run_front( // front closes. tasks.push(serve_track(state.clone(), name, resume, slot.clone())); } - Step::Reselect => { - // The costs or taints behind the table may have changed while - // the table itself did not: re-run the selection so a due hold - // either applies now or is dropped as no longer wanted, and a - // fresh taint moves the front off a route it can no longer - // serve from. - let carrying = broadcast.demand().is_used(); - if let Ok(mut s) = state.write() { - s.excluded_changed = false; - s.reselect(carrying, timers.now()); - } - sync_front(&state, &broadcast, &node); - } Step::Closed => break, } } @@ -2662,9 +2107,9 @@ async fn serve_track( // (a reconnect) deserves the seamless splice. { let s = state.read(); - refused.retain(|id| s.routes.iter().any(|r| r.id == *id)); - dead.retain(|id| s.routes.iter().any(|r| r.id == *id)); - let exhausted = !s.routes.is_empty() + refused.retain(|id| s.sources.iter().any(|r| r.id == *id)); + dead.retain(|id| s.sources.iter().any(|r| r.id == *id)); + let exhausted = !s.sources.is_empty() && s.serve_route(|id| refused.contains(&id) || dead.contains(&id)) .is_none(); if exhausted && dead.is_empty() { @@ -2702,7 +2147,7 @@ async fn serve_track( // which retires the refusals collected against it. Splicing waits // for a reader. match state.poll(waiter, |s| { - let gone = serving_id.is_some_and(|id| !s.routes.iter().any(|r| r.id == id)); + let gone = serving_id.is_some_and(|id| !s.sources.iter().any(|r| r.id == id)); if s.closed || (used && (gone || matches!(s.serve_route(skip), Some(next) if Some(next) != serving_id))) { @@ -2719,7 +2164,7 @@ async fn serve_track( return Poll::Ready(Step::NoRoute); }; let source = guard - .routes + .sources .iter() .find(|r| r.id == next) .expect("servable source in table") @@ -2779,7 +2224,7 @@ async fn serve_track( { let closing = state .read() - .routes + .sources .iter() .find(|r| r.id == id) .is_some_and(|r| r.source.is_closing()); @@ -2900,22 +2345,30 @@ async fn serve_track( } } -/// Shared fallback request queue for an origin. +/// The origin's shared state: the route table, the announce cursors observing +/// it, and the fallback request queue. /// -/// Lives off to the side of the announce tree because dynamically served broadcasts -/// are never announced. Carried in a [`kio::Shared`], so consumers enqueue and handlers -/// drain under one lock. Mirrors the fetch state of the track model. +/// Carried in a [`kio::Shared`], so producers, consumers, and handlers work +/// under one lock. Local broadcasts live in the tree ([`OriginNode`]) instead; +/// this holds everything advertised or served on demand. #[derive(Default)] -struct OriginDynamicState { - // Result channels for pending requests, keyed by absolute path so concurrent - // `request_broadcast` calls for the same path coalesce onto one channel. - requests: Requests>, +struct OriginState { + // The announced routes, in announcement order. Scans are linear: the table + // holds one entry per live advertisement, not one per broadcast consumer. + routes: Vec, + next_route: u64, - // Broadcasts a handler has already served, kept weakly so a repeat request for the - // same path resolves to a shared clone instead of re-invoking the handler (which would - // open a duplicate upstream subscription). Weak so a served broadcast still closes once - // its real consumers drop. The cache reclaims closed entries incrementally on insert, so a - // long-lived origin serving many distinct one-shot paths stays bounded by the live count. + // The registered announce cursors, each with its own coalescing buffer. + cursors: HashMap, + + // Fallback request queue: `request_broadcast` calls that no local broadcast + // or served route resolves, drained by `Dynamic` handlers. + fallback: Requests>, + + // Broadcasts a fallback handler has already served, kept weakly so a repeat + // request for the same path resolves to a shared clone instead of re-invoking + // the handler. Weak so a served broadcast still closes once its real + // consumers drop. served: WeakCache, // Set when the origin's driver dropped: new requests fail with `Closed` @@ -2923,6 +2376,122 @@ struct OriginDynamicState { closed: bool, } +impl OriginState { + /// Re-deliver the best route at every presented prefix `prefix` maps to, on + /// every cursor. Called after an entry covering `prefix` was added, updated, + /// or removed. + fn sync_route(&mut self, prefix: &Path) { + // Split borrows: the recompute reads `routes` while mutating a cursor. + let routes = &self.routes; + for cursor in self.cursors.values_mut() { + for presented in cursor.presented(prefix) { + Self::sync_cursor(routes, cursor, &presented); + } + } + } + + /// Recompute the best visible route presenting at `presented` (absolute) for + /// one cursor and deliver the change, if any. + fn sync_cursor(routes: &[RouteEntry], cursor: &mut TableCursor, presented: &PathOwned) { + // Mirror `best_server`: among entries presenting here, the most specific + // prefix wins outright, so the metadata a cursor advertises matches what + // a request through it actually resolves. Entries at shorter prefixes + // only present here when clamped to the cursor's scope. + let candidates: Vec<&RouteEntry> = routes + .iter() + .filter(|entry| cursor.visible(entry)) + .filter(|entry| cursor.presented(&entry.prefix.as_path()).contains(presented)) + .collect(); + let most = candidates.iter().map(|entry| entry.prefix.len()).max(); + let best = most.and_then(|most| { + candidates + .into_iter() + .filter(|entry| entry.prefix.len() == most) + .min_by_key(|entry| route_order(&presented.as_path(), entry)) + }); + + let relative = presented + .strip_prefix(&cursor.root) + .expect("presented prefix outside the cursor root") + .to_owned(); + + match best { + Some(entry) => { + let meta = (entry.hops.clone(), entry.cost); + let served = entry.server.is_some(); + match cursor + .current + .insert(presented.clone(), (entry.id, meta.clone(), served)) + { + // Unchanged metadata and servability: nothing the consumer could + // act on, even if the winning entry itself changed (a reconnect + // under an identical route is invisible, which is the point). A + // servability flip is delivered: a request that failed Unroutable + // under an advertise-only route retries on the update, and hiding + // it would park that waiter forever. + Some((_, prev, prev_served)) if prev == meta && prev_served == served => {} + _ => { + if let Ok(mut state) = cursor.state.write() { + state.apply_announce(relative, meta); + } + } + } + } + None => { + if let Some((_, last, _)) = cursor.current.remove(presented) + && let Ok(mut state) = cursor.state.write() + { + state.apply_unannounce(relative, last); + } + } + } + } + + /// Register a cursor and replay the current best route per presented prefix. + fn register_cursor(&mut self, id: ConsumerId, mut cursor: TableCursor) { + let routes = &self.routes; + let mut presented: Vec = Vec::new(); + for entry in routes { + for p in cursor.presented(&entry.prefix.as_path()) { + if !presented.contains(&p) { + presented.push(p); + } + } + } + for p in &presented { + Self::sync_cursor(routes, &mut cursor, p); + } + self.cursors.insert(id, cursor); + } + + /// The queue behind the best served route covering `path` (absolute) for a + /// requester excluding `exclude`. + /// + /// The most specific covering prefix wins outright, so a narrow advertise-only + /// announcement shadows a broad served one: requests under it fall through to + /// the fallback handler instead of being routed around it. Among routes at the + /// winning prefix, the cheapest served one is picked by [`route_order`]. + fn best_server(&self, path: &Path, exclude: Option) -> Option> { + let candidates: Vec<&RouteEntry> = self + .routes + .iter() + .filter(|entry| path.has_prefix(&entry.prefix)) + .filter(|entry| match exclude { + Some(peer) if peer != Hop::UNKNOWN => !entry.hops.contains(&peer), + _ => true, + }) + .collect(); + + // Covering prefixes of one path form a chain, so the longest is unique. + let most = candidates.iter().map(|entry| entry.prefix.len()).max()?; + candidates + .into_iter() + .filter(|entry| entry.prefix.len() == most && entry.server.is_some()) + .min_by_key(|entry| route_order(path, entry)) + .and_then(|entry| entry.server.clone()) + } +} + /// One-shot result of a dynamic broadcast request. /// /// Stays `None` until a handler [`accept`](Request::accept)s (yielding the served @@ -2947,7 +2516,7 @@ struct PendingBroadcast { pub struct Dynamic { hop: Hop, root: PathOwned, - state: kio::Shared, + state: kio::Shared, } impl Clone for Dynamic { @@ -2955,7 +2524,7 @@ impl Clone for Dynamic { // Mirror `new`: count each live handle. Without this, dropping a clone would // decrement past `new`'s increment and prematurely flip the handler count to // zero, making future `request_broadcast` calls return `Unroutable`. - self.state.lock().requests.add_handler(); + self.state.lock().fallback.add_handler(); Self { hop: self.hop, @@ -2966,8 +2535,8 @@ impl Clone for Dynamic { } impl Dynamic { - fn new(hop: Hop, root: PathOwned, state: kio::Shared) -> Self { - state.lock().requests.add_handler(); + fn new(hop: Hop, root: PathOwned, state: kio::Shared) -> Self { + state.lock().fallback.add_handler(); Self { hop, root, state } } @@ -2983,7 +2552,7 @@ impl Dynamic { /// no request will ever arrive again, so handler loops should end. pub fn poll_requested_broadcast(&mut self, waiter: &kio::Waiter) -> Poll> { let mut state = ready!(self.state.poll(waiter, |state| { - if state.closed || state.requests.has_queued() { + if state.closed || state.fallback.has_queued() { Poll::Ready(()) } else { Poll::Pending @@ -2995,17 +2564,17 @@ impl Dynamic { return Poll::Ready(Err(Error::Closed)); } - let path = state.requests.pop().expect("predicate guaranteed a request"); + let path = state.fallback.pop().expect("predicate guaranteed a request"); // The popped request stays pending, so a repeat request in the window between // hand-off and accept coalesces onto it instead of re-invoking the handler. The // producer is a shared clone; `Request::{accept, reject, drop}` removes the // entry. This mirrors how `poll_requested_track` keeps a served track // discoverable via the weak cache across the same window. - let producer = state.requests.get(&path).expect("popped key must be pending").clone(); + let producer = state.fallback.get(&path).expect("popped key must be pending").clone(); Poll::Ready(Ok(Request { path, producer, - state: self.state.clone(), + home: RequestHome::Fallback(self.state.clone()), })) } @@ -3026,18 +2595,107 @@ impl Drop for Dynamic { // Decrement and reject under one lock, so a `request_broadcast` that saw a // live handler through the same lock can't slip a request past the rejection. let mut state = self.state.lock(); - if state.requests.remove_handler() { + if state.fallback.remove_handler() { // No handlers left to pop queued requests; drop them, closing their result // channels so awaiting requesters resolve to `Unroutable`. A request already // handed to a handler stays, resolved by its `Request` instead. - state.requests.drain_queued(); + state.fallback.drain_queued(); + } + } +} + +/// Where a [`Request`] came from: the origin's fallback queue, or one served +/// route's queue. Both hold the same request bookkeeping under their own lock. +enum RequestHome { + Fallback(kio::Shared), + Route(kio::Shared), +} + +impl RequestHome { + /// Resolve the pending request: cache an accepted broadcast for repeat + /// requests, remove the queue entry, and wake the requesters. + /// + /// Resolved while the home's lock is held, so this linearizes with the + /// teardown: either the teardown ran first (the `closed` check returns, its + /// rejection stands) or this write lands first and the teardown finds the + /// entry already gone. The home lock is released before the channel guard + /// drops, so the requester wakes outside it: an inline executor re-entering + /// `request_broadcast` from the wake must not find the non-reentrant lock + /// still held. + fn resolve( + &self, + path: &PathOwned, + producer: &kio::Producer, + result: Result, + ) { + match self { + Self::Fallback(shared) => { + let mut state = shared.lock(); + if state.closed { + return; + } + let OriginState { fallback, served, .. } = &mut *state; + let resolved = Self::settle(fallback, served, path, producer, result); + if let Ok(mut pending) = producer.write() { + pending.resolved.get_or_insert(resolved); + drop(state); + } + } + Self::Route(shared) => { + let mut state = shared.lock(); + if state.closed { + return; + } + let ServeState { requests, served, .. } = &mut *state; + let resolved = Self::settle(requests, served, path, producer, result); + if let Ok(mut pending) = producer.write() { + pending.resolved.get_or_insert(resolved); + drop(state); + } + } + } + } + + /// Move an accepted broadcast into the weak `served` cache (deduping onto a + /// live entry served concurrently) and remove the queue entry. + fn settle( + requests: &mut Requests>, + served: &mut WeakCache, + path: &PathOwned, + producer: &kio::Producer, + result: Result, + ) -> Result { + let resolved = match result { + Ok(broadcast) => { + // If a live broadcast was already served for this path while we were + // fetching upstream, dedup onto it and drop ours rather than replace + // a good entry with a duplicate subscription. + let existing = served.insert(path.clone(), broadcast.weak()); + Ok(existing.map(|weak| weak.consume()).unwrap_or(broadcast)) + } + Err(err) => Err(err), + }; + requests.remove_if(path, |p| p.same_channel(producer)); + resolved + } + + /// Drop the still-pending entry, if it is still ours. + fn forget(&self, path: &PathOwned, producer: &kio::Producer) { + match self { + Self::Fallback(shared) => { + shared.lock().fallback.remove_if(path, |p| p.same_channel(producer)); + } + Self::Route(shared) => { + shared.lock().requests.remove_if(path, |p| p.same_channel(producer)); + } } } } -/// A pending request for a broadcast that was not announced. +/// A pending request for a broadcast to be served on demand. /// -/// Yielded by [`Dynamic::requested_broadcast`]. The requester is awaiting inside +/// Yielded by [`Dynamic::requested_broadcast`] (the origin's fallback) and by a +/// served route's queue. The requester is awaiting inside /// [`Consumer::request_broadcast`]; [`accept`](Self::accept) resolves it with a live /// broadcast (which the handler keeps producing into) and [`reject`](Self::reject) resolves /// it with an error. Dropping the request without either rejects it. @@ -3049,8 +2707,9 @@ pub struct Request { // this wakes them with the outcome. producer: kio::Producer, - // Shared dynamic state, so `accept` can cache the served broadcast for repeat requests. - state: kio::Shared, + // The queue this request came from, so `accept` can cache the served + // broadcast for repeat requests. + home: RequestHome, } impl Request { @@ -3062,59 +2721,17 @@ impl Request { /// Accept the request, resolving every awaiting requester with `broadcast`. /// /// The caller keeps producing into `broadcast` (e.g. a relay proxying tracks from - /// upstream); the requesters receive a consumer for it. The broadcast is *not* - /// announced. + /// upstream); the requesters receive a consumer for it. Repeat requests for the + /// path share the served broadcast for as long as it stays live. pub fn accept(self, broadcast: impl Consume) { let broadcast = broadcast.consume(); - - // Move the entry out of the in-flight queue and into the weak `served` cache, so repeat - // requests for this path share the same broadcast instead of asking the handler to serve - // (and subscribe upstream) again. Re-check under the lock: if a live broadcast was already - // served for this path while we were fetching upstream, dedup onto it and drop ours rather - // than replace a good entry with a duplicate subscription. - { - let mut state = self.state.lock(); - // The origin tore down and already rejected this request; keep the - // served cache untouched so nothing outlives the teardown. - if state.closed { - return; - } - let existing = state.served.insert(self.path.clone(), broadcast.weak()); - state - .requests - .remove_if(&self.path, |producer| producer.same_channel(&self.producer)); - let resolved = existing.map(|weak| weak.consume()).unwrap_or(broadcast); - - // Resolved while the state lock is still held, so this linearizes - // with the driver's teardown: either the teardown ran first and the - // closed check above returned, or this write lands first and the - // teardown finds the entry already gone. The state lock is released - // before the channel guard drops, so the requester wakes outside it: - // an inline executor re-entering `request_broadcast` from the wake - // must not find this non-reentrant lock still held. - if let Ok(mut pending) = self.producer.write() { - pending.resolved.get_or_insert(Ok(resolved)); - drop(state); - } - } + self.home.resolve(&self.path, &self.producer, Ok(broadcast)); // `self.producer` drops here, closing the channel; the value is still observable. } /// Reject the request, resolving every awaiting requester with `err`. pub fn reject(self, err: Error) { - let mut state = self.state.lock(); - // Already rejected by the origin's teardown. - if state.closed { - return; - } - state - .requests - .remove_if(&self.path, |producer| producer.same_channel(&self.producer)); - // Written under the state lock, woken outside it, matching `accept`. - if let Ok(mut pending) = self.producer.write() { - pending.resolved.get_or_insert(Err(err)); - drop(state); - } + self.home.resolve(&self.path, &self.producer, Err(err)); } } @@ -3127,10 +2744,7 @@ impl Drop for Request { // The identity guard matters: `accept`/`reject` already removed our entry and released // the lock before we run, so a concurrent request for the same path may have registered // a *new* one here. Removing unconditionally would clobber it, stranding its requesters. - self.state - .lock() - .requests - .remove_if(&self.path, |producer| producer.same_channel(&self.producer)); + self.home.forget(&self.path, &self.producer); } } @@ -3174,6 +2788,18 @@ impl Requesting { Self::new(RequestState::Pending(consumer)) } + /// Whether the request was handed to a serving route or fallback handler, + /// 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, @@ -3251,7 +2877,7 @@ impl Consume for Producer { self.info, self.root.clone(), self.nodes.clone(), - self.dynamic.clone(), + self.shared.clone(), stats::Session::default(), ) } @@ -3288,11 +2914,11 @@ impl Consume for track::Consumer { } } -/// Cheap read handle over an origin's broadcast tree. +/// Cheap read handle over an origin's broadcast tree and route table. /// -/// Clones share the underlying tree state without allocating any per-cursor -/// resources. To actually receive announce / unannounce events, call -/// [`Self::announced`] to obtain an [`AnnounceConsumer`]. +/// Clones share the underlying state without allocating any per-cursor +/// resources. To receive route announcements, call [`Self::announced`]; to +/// resolve a path into a broadcast, call [`Self::request_broadcast`]. #[derive(Clone)] pub struct Consumer { // Identity of the origin this consumer was derived from. @@ -3302,18 +2928,18 @@ pub struct Consumer { // A prefix that is automatically stripped from all paths. root: PathOwned, - // Shared fallback request queue, fed to any `Dynamic` handler on the - // producer side. Used only by `request_broadcast`; announced lookups ignore it. - dynamic: kio::Shared, + // The origin's shared state: the route table, announce cursors, and the + // fallback request queue. + shared: kio::Shared, // Egress stats context. Broadcasts handed out through this consumer (and any // handle derived from them) are attributed to it (reads counted on the // publisher/egress side). Empty (no-op) unless a session tagged this handle. stats: stats::Session, - // Data-plane split horizon: broadcasts resolved through this handle are - // served from a source whose hop chain excludes this origin (the requesting - // peer). `None` (the default) serves from the active source as usual. + // Split horizon: routes whose hop chain contains this peer are invisible to + // `announced` and skipped by `request_broadcast`, so a peer is never served + // (or advertised) its own content back. `None` (the default) filters nothing. exclude: Option, } @@ -3330,23 +2956,23 @@ impl Consumer { info: Hop, root: PathOwned, nodes: OriginNodes, - dynamic: kio::Shared, + shared: kio::Shared, stats: stats::Session, ) -> Self { Self { info, nodes, root, - dynamic, + shared, stats, exclude: None, } } - /// A clone that never serves the given peer its own data: broadcasts resolve - /// to a source whose hop chain excludes `peer`, matching what the announce - /// loop advertises to them. Sessions apply this once they learn the peer's - /// Hop ID. + /// A clone that never serves the given peer its own data: routes whose hop + /// chain contains `peer` are invisible and never resolved from, matching what + /// the announce loop advertises to them. Sessions apply this once they learn + /// the peer's origin id. pub(crate) fn excluding(mut self, peer: Hop) -> Self { self.exclude = Some(peer); self @@ -3361,7 +2987,7 @@ impl Consumer { } /// A clone of this consumer with its stats context cleared, so an internal - /// lookup stream (e.g. [`Self::announced_broadcast`]) doesn't drive the egress + /// lookup stream (e.g. [`Self::routed`]) doesn't drive the egress /// announce guards; the caller re-attributes the result itself. fn untagged(&self) -> Self { Self { @@ -3370,7 +2996,7 @@ impl Consumer { } } - /// A view with this consumer's identity and root but no broadcasts: + /// A view with this consumer's identity and root but no scope: /// [`announced`](Self::announced) yields nothing. Used to answer a peer's /// announce-interest for a prefix outside our scope by announcing nothing, /// rather than tearing the stream down. @@ -3379,97 +3005,138 @@ impl Consumer { info: self.info, nodes: OriginNodes { nodes: Vec::new() }, root: self.root.clone(), - dynamic: self.dynamic.clone(), + shared: self.shared.clone(), stats: self.stats.clone(), exclude: self.exclude, } } - /// Subscribe to announce / unannounce events for this consumer's subtree. + /// Subscribe to route announcements for this consumer's scope. /// - /// Allocates a per-cursor coalescing buffer, registers it with each root - /// in this consumer's scope, and replays the currently active broadcast - /// set as initial announcements. Drop the returned [`AnnounceConsumer`] - /// to unregister. + /// Allocates a per-cursor coalescing buffer and replays the currently + /// announced routes as initial updates. A route announced above the scope is + /// clamped to it. Drop the returned [`AnnounceConsumer`] to unregister. pub fn announced(&self) -> AnnounceConsumer { AnnounceConsumer::new( self.root.clone(), - self.nodes.clone(), + self.allowed_absolute(), self.stats.clone(), self.exclude, - &self.dynamic, + &self.shared, ) } + /// The absolute prefixes this handle is scoped to. + fn allowed_absolute(&self) -> Vec { + self.nodes + .nodes + .iter() + .map(|(allowed, _)| self.root.join(allowed).to_owned()) + .collect() + } + /// Returns a cheap duplicate of this read handle. pub fn consume(&self) -> Self { self.clone() } - /// Internal synchronous lookup: how the broadcast at `path` resolves for this - /// consumer, telling "announced but every route loops back through you" apart - /// from "nothing here". - /// - /// Races announcement gossip (a freshly-connected consumer sees `Missing` even when - /// the broadcast is about to arrive), so it is not public. [`Self::request_broadcast`] - /// is the public lookup: it builds on this for the announced case, then falls back to - /// a dynamic handler. [`Self::announced_broadcast`] waits for a future announcement. - fn resolve(&self, path: impl AsPath) -> Resolved { + /// Internal synchronous lookup: the local broadcast at `path`, if any. + fn resolve(&self, path: impl AsPath) -> Option { let path = path.as_path(); - let Some((root, rest)) = self.nodes.get(&path) else { - return Resolved::Missing; - }; + let (root, rest) = self.nodes.get(&path)?; let state = root.lock(); - state.resolve_broadcast(&rest, self.exclude) + state.resolve_broadcast(&rest) } - /// [`Self::resolve`] reduced to "can I read it": the peek the tests assert on. + /// [`Self::resolve`] as the peek the tests assert on. #[cfg(test)] pub(crate) fn get_broadcast(&self, path: impl AsPath) -> Option { - match self.resolve(path) { - Resolved::Found(broadcast) => Some(broadcast), - Resolved::Excluded | Resolved::Missing => None, - } + self.resolve(path) } - /// Block until a broadcast with the given path is announced and return it. + /// Block until an announced route covers `path`, and return it. /// - /// Returns `None` if the path is outside this consumer's allowed prefixes or if the consumer - /// is closed before the broadcast is announced. The returned broadcast may itself be closed - /// later. Subscribers should watch [`broadcast::Consumer::closed`] to react to that. + /// Covering means the route's prefix is a (segment-wise) prefix of `path`, + /// including the exact path itself. Returns `None` if the path is outside this + /// consumer's scope or the consumer is closed first. /// - /// Use this whenever you know the exact path you want and cannot guarantee its - /// announcement has already arrived, which includes every path you resolve right after - /// connecting: [`Self::request_broadcast`] answers on the spot, so asking it first - /// races the announcement and reports a live broadcast as unroutable. - pub async fn announced_broadcast(&self, path: impl AsPath) -> Option { + /// Use this before [`Self::request_broadcast`] whenever the announcement may + /// not have arrived yet, which includes every path you resolve right after + /// connecting: `request_broadcast` answers on the spot, so asking it first + /// races the announcement and reports a covered path as unroutable. + pub async fn routed(&self, path: impl AsPath) -> Option { let path = path.as_path(); - // Scope a fresh consumer down to this path so we only wake up for relevant announcements. + // Scope a fresh consumer down to this path: any covering route then clamps + // to exactly the path, so we only wake for relevant announcements. let consumer = self.scope(std::slice::from_ref(&path))?; - // `scope` keeps narrower permissions intact: if we ask for `foo` on a consumer limited - // to `foo/specific`, `scope` returns a consumer scoped to `foo/specific`. No - // announcement at the exact path `foo` can ever arrive. Bail rather than loop forever. + // `scope` keeps narrower permissions intact: if we ask for `foo` on a + // consumer limited to `foo/specific`, no route can ever clamp to exactly + // `foo`. Bail rather than loop forever. if !consumer.allowed().any(|allowed| path.has_prefix(allowed)) { return None; } - // Use an untagged stream: this is a lookup, not egress announce forwarding, so - // it must not drive the announce guards. The matched result is attributed - // with the egress scope instead. + // Use an untagged stream: this is a lookup, not egress announce + // forwarding, so it must not drive the announce guards. let mut announced = consumer.untagged().announced(); - let scope = self.stats.egress(self.root.join(&path).to_owned()); loop { - let OriginAnnounce { - path: announced_path, - broadcast, - } = announced.next().await?; - // `scope` narrows by prefix, but we only want an exact-path match. - if announced_path.as_path() == path - && let Some(broadcast) = broadcast - { - return Some(broadcast.with_stats(scope)); + let update = announced.next().await?; + if update.active && update.prefix.as_path() == path { + return Some(update.route); + } + } + } + + /// Block until `path` resolves to a broadcast: [`Self::routed`], then + /// [`Self::request_broadcast`], retried when the two race. + /// + /// The wait and the resolution are separate steps, so the covering route can + /// retract between them (failover churn), and a route can cover the path while + /// nothing serves it yet (an advertise-only announce racing its handler). This + /// rides out the churn by retrying whenever the path's coverage changes, which + /// is what makes it the right call for resolving a path right after + /// connecting. Returns [`Error::Unauthorized`] for a path outside this + /// consumer's scope, [`Error::Closed`] once the origin closes, and any other + /// resolution failure as-is. + pub async fn routed_broadcast(&self, path: impl AsPath) -> Result { + let path = path.as_path(); + + // Watch the path's coverage for the retry wake: scoped so it only wakes + // for covering routes, untagged because this is a lookup, not egress + // announce forwarding. + let scoped = self.scope(std::slice::from_ref(&path)).ok_or(Error::Unauthorized)?; + // `scope` keeps narrower permissions intact: if the whole path is not + // reachable, no route can ever cover it, so bail rather than loop forever. + if !scoped.allowed().any(|allowed| path.has_prefix(allowed)) { + return Err(Error::Unauthorized); + } + let mut announced = scoped.untagged().announced(); + loop { + if self.routed(&path).await.is_none() { + return Err(Error::Closed); + } + let request = self.request_broadcast(&path); + // A queued request and an instant verdict fail differently. A request + // that queued and then failed `Unroutable` was killed by its serving + // route retracting, and an identical standby swaps in without any + // announce update, so retry through the already-updated table + // immediately; each such retry consumed a real retraction, so this + // cannot spin. An instant `Unroutable` means nothing serves the path + // right now, and only a coverage change fixes that: park on the + // announce stream (it replays the current coverage first, so at most + // one extra attempt runs before this genuinely blocks). + let queued = request.is_queued(); + match request.await { + Ok(broadcast) => return Ok(broadcast), + Err(Error::Unroutable) if queued => {} + Err(Error::Unroutable) => { + if announced.next().await.is_none() { + return Err(Error::Closed); + } + } + Err(err) => return Err(err), } } } @@ -3485,34 +3152,36 @@ impl Consumer { info: self.info, root: self.root.clone(), nodes: self.nodes.select(&prefixes)?, - dynamic: self.dynamic.clone(), + shared: self.shared.clone(), stats: self.stats.clone(), exclude: self.exclude, }) } - /// Get a broadcast by exact path, falling back to a dynamic request when none is reachable. + /// Resolve a broadcast by exact path. /// - /// Returns a [`kio::Pending`] future (resolved synchronously for an existing broadcast, - /// otherwise once a handler serves it), mirroring [`track::Consumer::fetch_group`](track::Consumer::fetch_group). - /// The lookup order is: an existing broadcast reachable by exact path resolves - /// immediately, whether announced or not; otherwise, if an [`Dynamic`] handler is live (see - /// [`Producer::dynamic`]), a fallback request is registered and the future resolves - /// when the handler [`accept`](Request::accept)s it (or errors if it - /// [`reject`](Request::reject)s or every handler drops). Concurrent requests for - /// the same unannounced path coalesce onto one handler request, and once served the - /// broadcast is cached weakly so *later* requests for that path also share it (rather - /// than re-invoking the handler and opening a duplicate upstream subscription) for as - /// long as it stays live; a closed one is re-served on the next request. + /// Returns a [`kio::Pending`] future (resolved synchronously where possible), + /// mirroring [`track::Consumer::fetch_group`](track::Consumer::fetch_group). + /// The lookup order: /// - /// The returned future resolves to [`Error::Unroutable`] when no broadcast is reachable and no - /// dynamic handler exists. A request that is registered while a handler is live but then loses - /// every handler before being served also resolves to [`Error::Unroutable`]. Unlike an announced - /// broadcast, a dynamically served one is never visible to [`Self::announced`]. + /// 1. A local broadcast at the exact path ([`Producer::create_broadcast`]), + /// announced or not, resolves immediately. + /// 2. Otherwise the best announced route covering the path (most specific + /// prefix first, then cheapest) serves it on demand: sessions materialize + /// the path from the peer that announced the route. Concurrent requests + /// for the same path coalesce, and the served broadcast is shared for as + /// long as it stays live; a closed one is re-served on the next request. + /// 3. Otherwise a live [`Dynamic`] handler (see [`Producer::dynamic`]) + /// receives the request as a fallback. + /// + /// The returned future resolves to [`Error::Unroutable`] when none of those + /// exist. 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. pub fn request_broadcast(&self, path: impl AsPath) -> kio::Pending { let path = path.as_path(); - // Key requests by absolute path so a scoped/rooted consumer and the handler + // Key requests by absolute path so scoped/rooted consumers and handlers // (which may have a different root) agree on the same entry, and so the egress // counters resolve against the same broadcast the ingress side wrote. let absolute = self.root.join(&path).to_owned(); @@ -3522,30 +3191,61 @@ impl Consumer { // catalog it reads may reference. let requested = path.to_owned(); - // Prefer a live announcement when one is present; the dynamic queue is only a - // fallback for a path we hold nothing for. A broadcast we do hold but cannot - // serve this requester is unroutable, not missing: a handler resolves paths - // with no route chain to check, so falling through would let it route around - // the split horizon and rebuild the loop. - match self.resolve(&path) { - Resolved::Found(broadcast) => { - let resolved = Requesting::ready(broadcast).with_path(requested).with_stats(scope); - return kio::Pending::new(resolved); - } - Resolved::Excluded => return kio::Pending::new(Requesting::failed(Error::Unroutable)), - Resolved::Missing => {} + // A local broadcast at the exact path wins. + if let Some(broadcast) = self.resolve(&path) { + let resolved = Requesting::ready(broadcast).with_path(requested).with_stats(scope); + return kio::Pending::new(resolved); } - let mut state = self.dynamic.lock(); + // Routes only cover paths within this consumer's scope; the fallback + // handler is deliberately unscoped, matching the dynamic behavior. + let in_scope = self.nodes.get(&path).is_some(); + + let mut state = self.shared.lock(); - // The origin's driver dropped: no handler will ever serve this. + // The origin's driver dropped: nothing will ever serve this. if state.closed { return kio::Pending::new(Requesting::failed(Error::Closed)); } - // Reuse a still-live broadcast a handler already served for this path, so repeat - // requests share one upstream subscription. A closed entry is stale; `get` drops it - // and returns `None`, so we fall through and re-serve below. + if in_scope && let Some(server) = state.best_server(&absolute.as_path(), self.exclude) { + // Two sequential locks, never nested: the entry's queue has its own. + drop(state); + let mut serve = server.lock(); + if !serve.closed { + // Reuse a still-live broadcast already served for this path, so repeat + // requests share one upstream subscription. + if let Some(weak) = serve.served.get(&absolute) { + let resolved = Requesting::ready(weak.consume()).with_path(requested).with_stats(scope); + return kio::Pending::new(resolved); + } + + // Coalesce onto a pending request for the same path; otherwise + // register a new one. + let consumer = if let Some(producer) = serve.requests.join(&absolute) { + producer.consume() + } else { + let producer = kio::Producer::::default(); + let consumer = producer.consume(); + if serve.requests.insert(absolute, producer).is_err() { + return kio::Pending::new(Requesting::failed(Error::Unroutable)); + } + consumer + }; + return kio::Pending::new(Requesting::pending(consumer).with_path(requested).with_stats(scope)); + } + + // The route was retracted between the lookup and its lock; fall + // through to the fallback handler. + drop(serve); + state = self.shared.lock(); + if state.closed { + return kio::Pending::new(Requesting::failed(Error::Closed)); + } + } + + // Reuse a still-live broadcast a fallback handler already served for this + // path. if let Some(weak) = state.served.get(&absolute) { let resolved = Requesting::ready(weak.consume()).with_path(requested).with_stats(scope); return kio::Pending::new(resolved); @@ -3553,12 +3253,12 @@ impl Consumer { // Coalesce onto a pending request for the same path; otherwise register a new // one, unless there is no handler alive to serve it. - let consumer = if let Some(producer) = state.requests.join(&absolute) { + let consumer = if let Some(producer) = state.fallback.join(&absolute) { producer.consume() } else { let producer = kio::Producer::::default(); let consumer = producer.consume(); - if state.requests.insert(absolute, producer).is_err() { + if state.fallback.insert(absolute, producer).is_err() { return kio::Pending::new(Requesting::failed(Error::Unroutable)); } consumer @@ -3578,7 +3278,7 @@ impl Consumer { info: self.info, root: self.root.join(&prefix).to_owned(), nodes: self.nodes.root(&prefix)?, - dynamic: self.dynamic.clone(), + shared: self.shared.clone(), stats: self.stats.clone(), exclude: self.exclude, }) @@ -3601,66 +3301,25 @@ impl Consumer { } } -/// Handle to the announcement stream for a subtree. -/// -/// Symmetric counterpart of [`AnnounceConsumer`]. Cheap to clone; call -/// [`Self::consume`] to obtain an [`AnnounceConsumer`] that receives events. -#[derive(Clone)] -pub struct AnnounceProducer { - nodes: OriginNodes, - root: PathOwned, - // Carried for its `closed` flag, so a cursor created after the origin's - // driver dropped is born ended rather than parking forever. - dynamic: kio::Shared, -} - -impl AnnounceProducer { - fn new(root: PathOwned, nodes: OriginNodes, dynamic: kio::Shared) -> Self { - Self { nodes, root, dynamic } - } - - /// Subscribe to announce / unannounce events for this subtree. - /// - /// Allocates a per-cursor coalescing buffer and replays the currently active broadcast set - /// as initial announcements. Drop the returned [`AnnounceConsumer`] to - /// unregister. - pub fn consume(&self) -> AnnounceConsumer { - // Untagged: `AnnounceProducer` is used for internal announce plumbing, not - // egress attribution (which flows through `origin::Consumer::announced`). - AnnounceConsumer::new( - self.root.clone(), - self.nodes.clone(), - stats::Session::default(), - None, - &self.dynamic, - ) - } - - /// Returns the prefix that is automatically stripped from announced paths. - pub fn root(&self) -> &Path<'_> { - &self.root - } -} - -/// Receives announce / unannounce events for a subtree. +/// Receives route announcements for a scope. /// -/// Created by [`Consumer::announced`] or [`AnnounceProducer::consume`]. +/// Created by [`Consumer::announced`]. /// Drop to unregister. pub struct AnnounceConsumer { id: ConsumerId, - nodes: OriginNodes, + shared: kio::Shared, root: PathOwned, // Pending updates queued for this cursor. Coalesced so a slow consumer - // can't accumulate redundant announce/unannounce pairs. + // can't accumulate redundant announce/retract pairs. state: kio::Producer, // Egress stats context (empty for an untagged stream). Announce events drive the - // per-broadcast announce guards below and tag the broadcasts handed out. + // per-prefix announce guards below. stats: stats::Session, - // Live egress announce guards, keyed by absolute broadcast path. An announce - // opens one (bumping `announced` + `announced_bytes`); the matching unannounce + // Live egress announce guards, keyed by absolute prefix. An announce + // opens one (bumping `announced` + `announced_bytes`); the matching retraction // drops it (bumping `announced_closed` + `announced_bytes`). guards: HashMap, } @@ -3668,35 +3327,38 @@ pub struct AnnounceConsumer { impl AnnounceConsumer { fn new( root: PathOwned, - nodes: OriginNodes, + allowed: Vec, stats: stats::Session, exclude: Option, - dynamic: &kio::Shared, + shared: &kio::Shared, ) -> Self { let state = kio::Producer::::default(); let id = ConsumerId::new(); - for (_, node) in &nodes.nodes { - let notify = AnnounceConsumerNotify { - root: root.clone(), - state: state.clone(), - exclude, - }; - node.lock().consume(id, notify); - } - - // Checked after registering: either the teardown's cursor walk saw the - // registration, or this check sees the closed flag the teardown set - // before walking. Either way a cursor on a dead origin is born ended. - if dynamic.read().closed - && let Ok(mut state) = state.write() { - state.ended = true; + let mut table = shared.lock(); + if table.closed { + // A cursor on a dead origin is born ended. + if let Ok(mut state) = state.write() { + state.ended = true; + } + } else { + table.register_cursor( + id, + TableCursor { + root: root.clone(), + allowed, + exclude, + state: state.clone(), + current: HashMap::new(), + }, + ); + } } Self { id, - nodes, + shared: shared.clone(), root, state, stats, @@ -3704,49 +3366,34 @@ impl AnnounceConsumer { } } - /// Stamp the broadcast for one update and drive the egress announce guards. - /// - /// An announce stamps the yielded broadcast with the path it was announced at (see - /// [`broadcast::Info::path`]) plus the egress scope, and opens a guard keyed by the - /// absolute path; an unannounce drops the guard. The stamped path is the - /// cursor-relative one, so a catalog served by the broadcast resolves its relative - /// references against exactly the subtree this cursor may name. - fn hand_out(&mut self, update: OriginAnnounce) -> OriginAnnounce { - let OriginAnnounce { path, broadcast } = update; - let absolute = self.root.join(&path).to_owned(); - match broadcast { - Some(broadcast) => { - let scope = self.stats.egress(&absolute); - self.guards.entry(absolute).or_insert_with(|| scope.announce()); - let broadcast = broadcast.with_path(path.clone()).with_stats(scope); - OriginAnnounce { - path, - broadcast: Some(broadcast), - } - } - None => { - self.guards.remove(&absolute); - OriginAnnounce { path, broadcast: None } - } + /// Drive the egress announce guards for one update. + fn hand_out(&mut self, update: AnnounceUpdate) -> AnnounceUpdate { + let absolute = self.root.join(update.prefix.as_path()).to_owned(); + if update.active { + let scope = self.stats.egress(&absolute); + self.guards.entry(absolute).or_insert_with(|| scope.announce()); + } else { + self.guards.remove(&absolute); } + update } - /// Returns the next (un)announced broadcast and its path relative to this - /// cursor's root. + /// Returns the next route announcement or retraction, its prefix relative to + /// this cursor's root. /// - /// The broadcast will only be announced if it was previously unannounced. - /// The same path won't be announced/unannounced twice in a row; instead it - /// toggles. Returns None if the cursor is closed. - pub async fn next(&mut self) -> Option { + /// A retraction is only delivered for a previously announced prefix, and a + /// repeated announcement for the same prefix is a metadata update. Returns + /// None if the cursor is closed. + pub async fn next(&mut self) -> Option { kio::wait(|waiter| self.poll_next(waiter)).await } - /// Poll for the next (un)announced broadcast, without blocking. + /// Poll for the next update, without blocking. /// /// Returns `Poll::Ready(Some(_))` for an update, `Poll::Ready(None)` if the /// cursor is closed, or `Poll::Pending` after registering `waiter` to be /// notified when the next update arrives. - pub fn poll_next(&mut self, waiter: &kio::Waiter) -> Poll> { + pub fn poll_next(&mut self, waiter: &kio::Waiter) -> Poll> { let update = { let mut state = match ready!(self.state.poll(waiter, |state| { if state.pending.is_empty() && !state.ended { @@ -3772,11 +3419,11 @@ impl AnnounceConsumer { Poll::Ready(Some(self.hand_out(update))) } - /// Returns the next (un)announced broadcast without blocking. + /// Returns the next update without blocking. /// /// Returns None if there is no update available; NOT because the cursor is closed. /// Use [`Self::is_closed`] to check if the cursor is closed. - pub fn try_next(&mut self) -> Option { + pub fn try_next(&mut self) -> Option { let update = self.state.write().ok()?.take()?; Some(self.hand_out(update)) } @@ -3800,8 +3447,45 @@ impl AnnounceConsumer { impl Drop for AnnounceConsumer { fn drop(&mut self) { - for (_, root) in &self.nodes.nodes { - root.lock().unconsume(self.id); + self.shared.lock().cursors.remove(&self.id); + } +} + +#[cfg(test)] +use futures::FutureExt; + +#[cfg(test)] +#[allow(missing_docs)] // test-only assertion helpers +impl AnnounceConsumer { + /// The next update must be an active route at `expected`; returns it. + pub fn assert_next_active(&mut self, expected: impl AsPath) -> Route { + let expected = expected.as_path(); + let update = self.next().now_or_never().expect("next blocked").expect("no next"); + assert_eq!(update.prefix.as_path(), expected, "wrong prefix"); + assert!(update.active, "should be an active route"); + update.route + } + + /// The `try_next` counterpart of [`Self::assert_next_active`]. + pub fn assert_try_next_active(&mut self, expected: impl AsPath) -> Route { + let expected = expected.as_path(); + let update = self.try_next().expect("no next"); + assert_eq!(update.prefix.as_path(), expected, "wrong prefix"); + assert!(update.active, "should be an active route"); + update.route + } + + /// The next update must be a retraction at `expected`. + pub fn assert_next_ended(&mut self, expected: impl AsPath) { + let expected = expected.as_path(); + let update = self.next().now_or_never().expect("next blocked").expect("no next"); + assert_eq!(update.prefix.as_path(), expected, "wrong prefix"); + assert!(!update.active, "should be a retraction"); + } + + pub fn assert_next_wait(&mut self) { + if let Some(res) = self.next().now_or_never() { + panic!("next should block: got {:?}", res.map(|u| u.prefix)); } } } @@ -3837,5364 +3521,585 @@ impl ProduceTest for Hop { } #[cfg(test)] -use futures::FutureExt; +mod tests { + use super::*; + use futures::FutureExt; -#[cfg(test)] -#[allow(missing_docs)] // test-only assertion helpers -impl AnnounceConsumer { - pub fn assert_next(&mut self, expected: impl AsPath, broadcast: &broadcast::Consumer) { - let expected = expected.as_path(); - let announce = self.next().now_or_never().expect("next blocked").expect("no next"); - assert_eq!(announce.path, expected, "wrong path"); - let announced = announce.broadcast.expect("should be an active announce"); - assert!(announced.is_clone(broadcast), "should be the same broadcast"); + fn origin(id: u64) -> Hop { + Hop::new(id).unwrap() } - /// An announce for `expected`, without asserting which broadcast backs it - /// (the origin owns the announced broadcast, not the publisher). Returns the - /// announced consumer. - pub fn assert_next_some(&mut self, expected: impl AsPath) -> broadcast::Consumer { - let expected = expected.as_path(); - let announce = self.next().now_or_never().expect("next blocked").expect("no next"); - assert_eq!(announce.path, expected, "wrong path"); - announce.broadcast.expect("should be an active announce") + fn hops(ids: &[u64]) -> Hops { + let mut list = Hops::new(); + for id in ids { + list.push(origin(*id)).unwrap(); + } + list } - pub fn assert_try_next(&mut self, expected: impl AsPath, broadcast: &broadcast::Consumer) { - let expected = expected.as_path(); - let announce = self.try_next().expect("no next"); - assert_eq!(announce.path, expected, "wrong path"); - let announced = announce.broadcast.expect("should be an active announce"); - assert!(announced.is_clone(broadcast), "should be the same broadcast"); + /// Yield to the driver until `check` passes, bounded so a bug fails instead + /// of hanging. + async fn settle(mut check: impl FnMut() -> bool) { + for _ in 0..100 { + if check() { + return; + } + tokio::task::yield_now().await; + } + panic!("condition never settled"); } - /// The `try_next` counterpart of [`Self::assert_next_some`]. - pub fn assert_try_next_some(&mut self, expected: impl AsPath) -> broadcast::Consumer { - let expected = expected.as_path(); - let announce = self.try_next().expect("no next"); - assert_eq!(announce.path, expected, "wrong path"); - announce.broadcast.expect("should be an active announce") - } + #[tokio::test] + async fn announce_and_retract() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let mut announced = consumer.announced(); + announced.assert_next_wait(); - pub fn assert_next_none(&mut self, expected: impl AsPath) { - let expected = expected.as_path(); - let announce = self.next().now_or_never().expect("next blocked").expect("no next"); - assert_eq!(announce.path, expected, "wrong path"); - assert!(announce.broadcast.is_none(), "should be unannounced"); - } + let announcement = producer.announce("room/alice", Route::default()).unwrap(); + let route = announced.assert_next_active("room/alice"); + assert!(route.hops.is_empty()); + assert_eq!(route.cost, Cost::default()); + announced.assert_next_wait(); - pub fn assert_next_wait(&mut self) { - if let Some(res) = self.next().now_or_never() { - panic!("next should block: got {:?}", res.map(|a| a.path)); - } + drop(announcement); + announced.assert_next_ended("room/alice"); + announced.assert_next_wait(); } - /* - pub fn assert_next_closed(&mut self) { - assert!( - self.next().now_or_never().expect("next blocked").is_none(), - "next should be closed" - ); + #[tokio::test] + async fn announce_replays_to_late_cursor() { + let producer = origin(1).produce(); + let _a = producer.announce("room/alice", Route::default()).unwrap(); + let _b = producer.announce("room/bob", Route::default()).unwrap(); + + let mut announced = producer.consume().announced(); + // BTreeMap order: lexicographic by prefix. + announced.assert_next_active("room/alice"); + announced.assert_next_active("room/bob"); + announced.assert_next_wait(); } - */ -} - -#[cfg(test)] -mod tests { - use crate::coding::Decode; - use crate::group; - use super::*; - use crate::track::Position; - - /// An announced direct route. - fn announce() -> broadcast::Route { - broadcast::Route::new().with_announce(true) - } - - /// The first origin whose handover key for `name` sits above (`true`) or below - /// (`false`) the peer's, so tests exercising the carrying gate are - /// deterministic instead of hinging on a random id winning a hash comparison. - /// Starts searching above the small ids the tests use in hop chains, so the - /// result never collides with a hop (a looping chain trips a debug_assert). - fn origin_keyed(name: &str, peer: Hop, above: bool) -> Hop { - let name = Path::new(name); - let peer_key = fnv_key(&name, [peer]); - (100u64..) - .map(|id| Hop::new(id).unwrap()) - .find(|origin| (fnv_key(&name, [*origin]) > peer_key) == above) - .unwrap() - } - - /// A front table for reselect tests: routes get ids in order, the first is - /// the incumbent. - fn front_state(self_hop: Hop, routes: Vec) -> FrontState { - let source = broadcast::Info::new().produce().consume(); - FrontState { - path: Path::new("test").to_owned(), - self_hop, - publisher: routes.first().and_then(|r| r.hops.iter().next().copied()), - next_route: routes.len() as u64, - excluded: HashMap::new(), - excluded_changed: false, - routes: routes - .into_iter() - .enumerate() - .map(|(id, route)| FrontRoute { - id: id as u64, - route, - source: source.clone(), - }) - .collect(), - active: Some(0), - closed: false, - pending: None, - } - } + #[tokio::test] + async fn announce_clamps_to_producer_scope() { + let producer = origin(1).produce(); + let scoped = producer.scope(&[Path::new("room")]).unwrap(); - /// What the sibling links in these tests cost, so a warm sibling always looks - /// cheaper than the `upstream_route(10)` incumbent on warm cost alone. The gate - /// then turns on the cold rank, which is what the tests are about. - const SIBLING_LINK: u64 = 1; + // A broad claim through a narrow scope advertises only the intersection. + let _a = scoped.announce("", Route::default()).unwrap(); + let mut announced = producer.consume().announced(); + announced.assert_next_active("room"); - /// A route as a warm relay would announce it: warm cost discounted to zero with - /// `cold` still flowing, charged `link` on arrival. `hops` is the chain it - /// advertised, which ends at the announcing relay; 0 is an anonymous hop. - fn warm_route(hops: &[u64], cold: u64, link: u64) -> broadcast::Route { - let hops = hops - .iter() - .map(|id| Hop::new(*id).unwrap_or(Hop::UNKNOWN)) - .collect::>(); - let advertised = broadcast::Cost { warm: 0, cold }; - let mut route = announce() - .with_hops(Hops::try_from(hops).unwrap()) - .with_cost(advertised.charged(link)); - route.advertised = advertised; - route + // Disjoint prefixes cannot be claimed at all. + assert!(matches!( + scoped.announce("other", Route::default()), + Err(Error::Unauthorized) + )); } - /// A route as a relay that is *not* carrying announces it: its accumulated cost - /// forwarded undiscounted, so it is a plain forwarder rather than a warm sibling - /// and never trips the adoption hold-down. - fn forwarder_route(hops: Hops, cost: u64) -> broadcast::Route { - let advertised = broadcast::Cost::new(cost); - let mut route = announce().with_hops(hops).with_cost(advertised); - route.advertised = advertised; - route - } + #[tokio::test] + async fn cursor_clamps_above_its_scope() { + let producer = origin(1).produce(); + let _a = producer.announce("", Route::default()).unwrap(); - /// A warm relay one hop past the publisher, on the standard test link. - fn sibling_route(peer: Hop, cold: u64) -> broadcast::Route { - warm_route(&[90, peer.id()], cold, SIBLING_LINK) + let consumer = producer.consume().scope(&[Path::new("room")]).unwrap(); + let mut announced = consumer.announced(); + announced.assert_next_active("room"); } - /// A route as the upstream announces it: priced, one hop. - fn upstream_route(cost: u64) -> broadcast::Route { - let hops = Hops::try_from(vec![Hop::new(90).unwrap()]).unwrap(); - announce().with_hops(hops).with_cost(cost) + #[tokio::test] + async fn cursor_root_strips_prefix() { + let producer = origin(1).produce(); + let _a = producer.announce("room/alice", Route::default()).unwrap(); + + let consumer = producer.consume().with_root("room").unwrap(); + let mut announced = consumer.announced(); + announced.assert_next_active("alice"); } - /// Equally-rooted relays (the same cold cost) fall through to the hash: while - /// carrying, a warm peer that hashes above us must not displace the incumbent, - /// while the same table re-parents freely once idle, or when the peer hashes - /// below us. - #[test] - fn test_carrying_gate_keys() { - let peer = Hop::new(3).unwrap(); + #[tokio::test] + async fn best_route_wins_and_fails_over() { + let producer = origin(1).produce(); + let mut announced = producer.consume().announced(); - // We lose the key comparison: stay put while carrying, migrate when idle. - let mut lost = front_state( - origin_keyed("test", peer, false), - vec![upstream_route(10), sibling_route(peer, 10)], - ); - lost.reselect_now(true); - assert_eq!( - lost.active, - Some(0), - "carrying front re-parented onto a higher-keyed peer" - ); - lost.reselect_now(false); - assert_eq!(lost.active, Some(1), "idle front must take the cheaper route"); + let expensive = producer + .announce("room", Route::default().with_hops(hops(&[10])).with_cost(5)) + .unwrap(); + let route = announced.assert_next_active("room"); + assert_eq!(route.cost, Cost::new(5)); - // We win the key comparison: re-parent even while carrying. - let mut won = front_state( - origin_keyed("test", peer, true), - vec![upstream_route(10), sibling_route(peer, 10)], - ); - won.reselect_now(true); - assert_eq!(won.active, Some(1), "carrying front must follow a lower-keyed peer"); - } + // A cheaper route for the same prefix takes over in place. + let cheap = producer + .announce("room", Route::default().with_hops(hops(&[20])).with_cost(1)) + .unwrap(); + let route = announced.assert_next_active("room"); + assert_eq!(route.cost, Cost::new(1)); - /// The gate's reconnect exemption needs a declared identity too: an anonymous - /// warm sibling is not "the relay we already serve from" just because the - /// incumbent's relay is anonymous as well. The rank then decides on the - /// declared ids, so two fully anonymous sides tie and neither moves (the - /// cluster draft's "equal Hop IDs cannot be ordered"). - #[test] - fn test_carrying_gate_anonymous_is_not_a_reconnect() { - let anon_hops = || Hops::try_from(vec![Hop::new(90).unwrap(), Hop::UNKNOWN]).unwrap(); - let incumbent = || forwarder_route(anon_hops(), 10); - let candidate = || warm_route(&[90, 0], 10, SIBLING_LINK); - - // Equal cold roots fall through to the hash of the declared ids, ours - // against the candidate's 0. Keyed to lose, we must stay put. - let mut state = front_state( - origin_keyed("test", Hop::UNKNOWN, false), - vec![incumbent(), candidate()], - ); - state.reselect_now(true); - assert_eq!( - state.active, - Some(0), - "an anonymous sibling must take the rank, not the reconnect exemption" - ); + // Losing the winner falls back to the survivor, still in place. + drop(cheap); + let route = announced.assert_next_active("room"); + assert_eq!(route.cost, Cost::new(5)); - // Both sides anonymous: the ranks tie exactly, and a tie never moves. - let mut state = front_state(Hop::UNKNOWN, vec![incumbent(), candidate()]); - state.reselect_now(true); - assert_eq!(state.active, Some(0), "two anonymous relays cannot be ordered"); - } - - /// The hold-down exists for this: three carrying relays in a ring, each holding - /// a stale, cheaper cold cost from the next one while its own upstream has just - /// worsened. Every one of them prefers its neighbour, so acting at once would - /// leave the broadcast with no source at all. - /// - /// The gate cannot catch it, because each relay is comparing a cost the peer - /// *reported* against its own current one, and all three reports are in flight. - /// Holding the adoption is what buys time for them to land. - #[test] - fn test_handover_hold_blocks_the_stale_ring() { - let ids = [1u64, 2, 3]; - let now = crate::model::clock::now(); - - let moved: Vec = (0..3) - .map(|i| { - let next = ids[(i + 1) % 3]; - let mut view = front_state( - Hop::new(ids[i]).unwrap(), - // Our own upstream has worsened to cold 10; the advertisement we - // still hold from the next relay says cold 1. - vec![upstream_route(10), warm_route(&[90, next], 1, 1)], - ); - view.reselect(true, now); - view.active == Some(1) - }) - .collect(); - - assert!( - !moved.iter().all(|m| *m), - "all three relays adopted at once, leaving no source: {moved:?}" - ); - assert!( - moved.iter().all(|m| !*m), - "the hold must defer every adoption, not just some" - ); - } - - /// The same ring, built out of relays forwarding their accumulated cost rather - /// than warm copies advertising zero. The handover gate never inspects these at - /// all, so the hold is the only thing standing between them and a cycle. - #[test] - fn test_handover_hold_blocks_a_forwarder_ring() { - let ids = [1u64, 2, 3]; - let now = crate::model::clock::now(); - - let moved: Vec = (0..3) - .map(|i| { - let next = Hop::new(ids[(i + 1) % 3]).unwrap(); - let hops = Hops::try_from(vec![Hop::new(90).unwrap(), next]).unwrap(); - let mut view = front_state( - Hop::new(ids[i]).unwrap(), - vec![upstream_route(10), forwarder_route(hops, 1)], - ); - view.reselect(true, now); - view.active == Some(1) - }) - .collect(); - - assert!( - moved.iter().all(|m| !*m), - "every adoption in the ring must be held: {moved:?}" - ); - } - - /// The hold defers the adoption; it does not cancel it. Once the deadline has - /// passed and the candidate is still preferred, the handover happens. - #[test] - fn test_handover_hold_expires() { - let peer = Hop::new(3).unwrap(); - let start = crate::model::clock::now(); - let mut state = front_state( - origin_keyed("test", peer, false), - vec![upstream_route(10), sibling_route(peer, 4)], - ); - - let deadline = state.reselect(true, start).expect("the hold must report a deadline"); - assert_eq!(state.active, Some(0), "the adoption must not apply immediately"); - assert!( - deadline >= start.checked_add(HANDOVER_HOLD).unwrap() - && deadline < start.checked_add(HANDOVER_HOLD + HANDOVER_HOLD / 2).unwrap(), - "the spread must sit above the floor and below half again" - ); - - // Re-running inside the window keeps waiting from the original start, so - // unrelated table churn cannot postpone the handover indefinitely. - let mid = start.checked_add(HANDOVER_HOLD / 2).unwrap(); - assert_eq!(state.reselect(true, mid), Some(deadline), "the deadline must not move"); - assert_eq!( - state.active, - Some(0), - "the hold must survive a re-run inside the window" - ); - - assert_eq!( - state.reselect(true, deadline), - None, - "an applied hold clears the deadline" - ); - assert_eq!(state.active, Some(1), "the handover must happen once the hold expires"); - } - - /// The spread is fixed per relay and broadcast, so a relay picks the same - /// deadline every time rather than re-rolling it and drifting. - #[test] - fn test_handover_hold_spread_is_stable() { - let peer = Hop::new(3).unwrap(); - let now = crate::model::clock::now(); - let build = || { - front_state( - origin_keyed("test", peer, false), - vec![upstream_route(10), sibling_route(peer, 4)], - ) - }; - assert_eq!(build().hold_deadline(now), build().hold_deadline(now)); - - // Different relays land on different instants, which is the point. - let a = front_state(Hop::new(11).unwrap(), vec![upstream_route(10)]); - let b = front_state(Hop::new(12).unwrap(), vec![upstream_route(10)]); - assert_ne!(a.hold_deadline(now), b.hold_deadline(now)); - } - - /// A drain is held like any other move. It reads like an emergency, but a GOAWAY - /// keeps serving for many seconds, so the wait costs optimality rather than - /// availability, and a fleet draining together is precisely when several relays - /// re-parent at once off prices that have not landed yet. - #[test] - fn test_handover_hold_covers_a_drain() { - let peer = Hop::new(3).unwrap(); - let now = crate::model::clock::now(); - let mut state = front_state( - origin_keyed("test", peer, false), - vec![upstream_route(broadcast::DRAIN_COST), sibling_route(peer, 4)], - ); - - assert!(state.reselect(true, now).is_some(), "a drain must still arm the hold"); - assert_eq!(state.active, Some(0), "leaving a drain must not apply yet"); - - // If the drain becomes a death the route leaves the table, and the - // lost-incumbent exemption applies at once: the wait is bounded by the - // session it is waiting on. - state.routes.retain(|r| r.id != 0); - assert_eq!(state.reselect(true, now), None); - assert_eq!(state.active, Some(1), "a drain that dies must fail over immediately"); - } - - /// The hold covers re-parenting onto anything reached through a session. Only - /// moves that cannot close a loop, and repairs that must not wait, are exempt. - #[test] - fn test_handover_hold_ignores_moves_that_cannot_cycle() { - let peer = Hop::new(3).unwrap(); - let now = crate::model::clock::now(); - let keyed = || origin_keyed("test", peer, false); - - // A local publish reaches no session, so nothing can depend on us through it. - let mut state = front_state(keyed(), vec![upstream_route(10), announce()]); - assert_eq!(state.reselect(true, now), None); - assert_eq!(state.active, Some(1), "a local publish must be immediate"); - - // A fresh session from the relay we already depend on is not a new edge, so - // it cannot close a loop the current route does not already close. - let mut state = front_state(keyed(), vec![sibling_route(peer, 4), sibling_route(peer, 4)]); - assert_eq!(state.reselect(true, now), None); - assert_eq!(state.active, Some(1), "a reconnect must be immediate"); - - // Losing the incumbent entirely: never held, or the front strands itself. - let mut state = front_state(keyed(), vec![upstream_route(10), sibling_route(peer, 4)]); - state.routes.retain(|r| r.id != 0); - assert_eq!(state.reselect(true, now), None); - assert_eq!(state.active, Some(1), "a lost incumbent must be replaced immediately"); - } - - /// An incumbent that stopped announcing is a repair target, not one end of a - /// mutual adoption. Holding the move would keep the unannounced route first - /// in `routes_snapshot`, retracting the whole path for the hold window while - /// a live route sits in the table. - #[test] - fn test_handover_hold_exempts_an_unannounced_incumbent() { - let peer = Hop::new(3).unwrap(); - let now = crate::model::clock::now(); - let offline = upstream_route(10).with_announce(false); - let mut state = front_state(origin_keyed("test", peer, false), vec![offline, sibling_route(peer, 4)]); - - assert_eq!( - state.reselect(true, now), - None, - "leaving an offline incumbent must not wait" - ); - assert_eq!(state.active, Some(1), "the live route must take over immediately"); - } - - /// An anonymous relay identifies nothing (lite: "a Hop ID of 0 never matches - /// anything"), so a move between two anonymous last hops is never "that - /// session reconnecting": it is held like any other re-parent. - #[test] - fn test_handover_hold_covers_anonymous_relays() { - let now = crate::model::clock::now(); - let anon = |cold: u64| warm_route(&[90, 0], cold, SIBLING_LINK); - let mut state = front_state(Hop::new(7).unwrap(), vec![anon(10), anon(1)]); - - assert!( - state.reselect(true, now).is_some(), - "two anonymous relays must be held, not exempted as a reconnect" - ); - assert_eq!(state.active, Some(0), "the re-parent must not apply yet"); - } - - /// The hold's clock belongs to the relay being adopted. A candidate from a - /// different relay must age its own hold: inheriting one that already - /// expired against an earlier candidate would apply the newcomer with no - /// hold at all, and two relays could cross-adopt through exactly that gap. - #[test] - fn test_handover_hold_is_keyed_to_the_target() { - let start = crate::model::clock::now(); - let relay_b = Hops::try_from(vec![Hop::new(90).unwrap(), Hop::new(3).unwrap()]).unwrap(); - let relay_c = Hops::try_from(vec![Hop::new(90).unwrap(), Hop::new(4).unwrap()]).unwrap(); - - let mut state = front_state( - Hop::new(7).unwrap(), - vec![upstream_route(10), forwarder_route(relay_b, 5)], - ); - let deadline = state.reselect(true, start).expect("the hold must arm"); - assert_eq!(state.active, Some(0)); - - // B reconnects under a fresh route id: the same relay, so the clock - // keeps running rather than restarting on every session. - let source = state.routes[1].source.clone(); - let route = state.routes[1].route.clone(); - state.routes.remove(1); - state.routes.push(FrontRoute { - id: 2, - route, - source: source.clone(), - }); - let mid = start.checked_add(HANDOVER_HOLD / 2).unwrap(); - assert_eq!( - state.reselect(true, mid), - Some(deadline), - "a reconnect must continue the same hold" - ); - - // C shows up after B's deadline passed: a different relay, so it starts - // its own hold instead of landing instantly on B's expired one. - let late = deadline.checked_add(HANDOVER_HOLD).unwrap(); - state.routes.push(FrontRoute { - id: 3, - route: forwarder_route(relay_c, 1), - source, - }); - let renewed = state.reselect(true, late).expect("a new target must arm a new hold"); - assert!(renewed > late, "the newcomer must wait out its own hold"); - assert_eq!(state.active, Some(0), "the newcomer must not be adopted unheld"); - - // The renewed hold still expires: the move happens, just held. - assert_eq!(state.reselect(true, renewed), None); - assert_eq!(state.active, Some(3)); - } - - /// Demand is deliberately not part of the hold. An idle front still records the - /// choice, nothing re-runs the selection when demand arrives, and `serve_route` - /// then dispatches down it, so a selection made while idle is a cycle that - /// starts later rather than one that cannot happen. - #[test] - fn test_handover_hold_covers_an_idle_front() { - let peer = Hop::new(3).unwrap(); - let now = crate::model::clock::now(); - let mut state = front_state( - origin_keyed("test", peer, false), - vec![upstream_route(10), sibling_route(peer, 4)], - ); - - assert!(state.reselect(false, now).is_some(), "an idle front must still hold"); - assert_eq!(state.active, Some(0), "the idle re-parent must not apply yet"); - } - - /// Hop count cannot stand in for provenance: a peer that does not speak the - /// cluster extension is announced as a single hop however deep the chain behind - /// it really is (see `ietf::subscriber::session_route`), so a one-hop target is - /// not necessarily a publisher that never re-parents. - #[test] - fn test_handover_hold_covers_an_opaque_one_hop_peer() { - let peer = Hop::new(3).unwrap(); - let now = crate::model::clock::now(); - let opaque = announce() - .with_hops(Hops::try_from(vec![peer]).unwrap()) - .with_cost(broadcast::Cost::UNKNOWN.charged(1)); - let mut state = front_state(origin_keyed("test", peer, false), vec![upstream_route(10), opaque]); - - assert!( - state.reselect(true, now).is_some(), - "an opaque one-hop peer must be held" - ); - assert_eq!(state.active, Some(0), "the re-parent must not apply yet"); - } - - /// Neither the gate nor the hold may keep an incumbent that flows through a peer - /// reading this front. `serve_route` refuses to serve from such a route, so - /// retaining it as `active` would leave `routes_snapshot` advertising (and - /// discounting) a chain the front does not actually serve from. Advertising one - /// path while dispatching down another is what lets a subscription cycle past - /// the hop-chain check, since the chain a peer inspects is no longer the chain - /// its bytes take. - #[test] - fn test_a_tainted_incumbent_is_never_retained() { - let reader = Hop::new(5).unwrap(); - let clean_peer = Hop::new(3).unwrap(); - let now = crate::model::clock::now(); - - // The incumbent runs through the reader and is cheaply rooted, so we outrank - // the clean alternative and would otherwise both veto and hold the move. - let mut state = front_state( - origin_keyed("test", clean_peer, false), - vec![ - warm_route(&[90, reader.id()], 1, 1), - warm_route(&[90, clean_peer.id()], 4, 1), - ], - ); - state.excluded.insert(reader, 1); - - assert_eq!(state.best_route(), Some(1), "the clean route must win selection"); - assert_eq!( - state.reselect(true, now), - None, - "a tainted incumbent must not arm the hold" - ); - assert_eq!(state.active, Some(1), "the tainted incumbent must not be retained"); - assert_eq!( - state.serve_route(|_| false), - state.active, - "what we serve from and what we advertise as serving must agree" - ); - assert_eq!( - state.routes_snapshot().first().map(|r| r.hops.clone()), - state - .routes - .iter() - .find(|r| Some(r.id) == state.active) - .map(|r| r.route.hops.clone()), - "the advertised serving chain must be the active one" - ); - } - - /// The taint steer may pick only among routes that serve: a clean offline - /// standby must not beat an announced route, or the steer retracts the path - /// and drops the very advertisement whose guard created the taint. - #[test] - fn test_taint_steer_keeps_the_announcement() { - let reader = Hop::new(5).unwrap(); - let mut state = front_state( - Hop::new(7).unwrap(), - vec![ - warm_route(&[90, reader.id()], 1, 1), - upstream_route(10).with_announce(false), - ], - ); - state.excluded.insert(reader, 1); - assert_eq!( - state.best_route(), - Some(0), - "an offline standby must not win the advert" - ); - - // Per-track dispatch still tries the clean standby first, so the reader - // is not handed its own bytes while the standby can serve; a track it - // refuses falls back through the skip set, the documented last resort. - assert_eq!( - state.serve_route(|_| false), - Some(1), - "a track must try the clean standby first" - ); - assert_eq!( - state.serve_route(|id| id == 1), - Some(0), - "a track the standby refuses falls back to the tainted route" - ); - - // An announced clean route wins the advert too. - state.routes[1].route = upstream_route(10); - assert_eq!( - state.best_route(), - Some(1), - "an announced clean route must win the steer" - ); - } - - /// The simultaneous-activation race: two relays that each pulled the same - /// broadcast independently see each other's zero-cost route. Exactly one of - /// them re-parents; the other keeps its upstream, so the broadcast is never - /// left without a source. - #[test] - fn test_carrying_gate_symmetric_race() { - let a = Hop::new(1).unwrap(); - let b = Hop::new(2).unwrap(); - - let mut a_view = front_state(a, vec![upstream_route(10), sibling_route(b, 10)]); - let mut b_view = front_state(b, vec![upstream_route(10), sibling_route(a, 10)]); - a_view.reselect_now(true); - b_view.reselect_now(true); - - let a_moved = a_view.active == Some(1); - let b_moved = b_view.active == Some(1); - assert!( - a_moved != b_moved, - "exactly one side must re-parent (a: {a_moved}, b: {b_moved})" - ); - } - - /// The asymmetric case the cold cost exists for. Two relays both carry the - /// broadcast, so both advertise a zero warm cost and the hash would decide at - /// random. The peer's upstream is genuinely cheaper than ours, so it must - /// become the aggregation point either way the hash falls. - #[test] - fn test_carrying_gate_follows_the_cheaper_root() { - let peer = Hop::new(3).unwrap(); - - for above in [false, true] { - let mut state = front_state( - origin_keyed("test", peer, above), - vec![upstream_route(10), sibling_route(peer, 4)], - ); - state.reselect_now(true); - assert_eq!( - state.active, - Some(1), - "a cheaper-rooted warm peer must win the hash comparison too (above: {above})" - ); - } - } - - /// The converse, which is what stops the aggregation tree from inverting: a - /// warm peer rooted further from the publisher than we are never attracts us, - /// however the hash falls. It is the peer that has to come to us. - #[test] - fn test_carrying_gate_rejects_the_pricier_root() { - let peer = Hop::new(3).unwrap(); - - for above in [false, true] { - let mut state = front_state( - origin_keyed("test", peer, above), - vec![upstream_route(4), sibling_route(peer, 10)], - ); - state.reselect_now(true); - assert_eq!( - state.active, - Some(0), - "a pricier-rooted warm peer must never displace us (above: {above})" - ); - } - } - - /// Adoption strictly descends the rank, which is what forbids a cycle: taking a - /// parent charges this link onto our own cold cost, so afterwards we advertise - /// strictly above the relay we adopted and can never attract it back. - #[test] - fn test_carrying_gate_descends() { - let peer = Hop::new(3).unwrap(); - let mut state = front_state( - origin_keyed("test", peer, false), - vec![upstream_route(10), sibling_route(peer, 4)], - ); - state.reselect_now(true); - - let adopted = state.routes.iter().find(|r| Some(r.id) == state.active).unwrap(); - assert_eq!( - adopted.route.cost.cold, - 4 + SIBLING_LINK, - "our cold cost must include the link to the parent we adopted" - ); - assert!( - adopted.route.cost.cold > adopted.route.advertised.cold, - "a relay must always rank above the parent it adopted" - ); - } - - /// Losing the parent reverts to our own cold upstream rather than stranding the - /// front on a route that no longer exists. - #[test] - fn test_carrying_gate_reverts_when_the_parent_goes() { - let peer = Hop::new(3).unwrap(); - let mut state = front_state( - origin_keyed("test", peer, false), - vec![upstream_route(10), sibling_route(peer, 4)], - ); - state.reselect_now(true); - assert_eq!(state.active, Some(1)); - - state.routes.retain(|route| route.id != 1); - state.reselect_now(true); - assert_eq!(state.active, Some(0), "the cold upstream was not restored"); - } - - /// A peer whose wire cannot express a cold cost (pre-lite-06, or the MoQ Cluster - /// extension) advertises [`broadcast::Cost::UNKNOWN`]. Two such peers tie there - /// and fall through to the hash, which is exactly how they behaved before cold - /// cost existed. - #[test] - fn test_carrying_gate_unknown_cold_falls_back_to_the_hash() { - let a = Hop::new(1).unwrap(); - let b = Hop::new(2).unwrap(); - let unknown = broadcast::Cost::UNKNOWN.cold; - - let mut a_view = front_state(a, vec![upstream_route(unknown), sibling_route(b, unknown)]); - let mut b_view = front_state(b, vec![upstream_route(unknown), sibling_route(a, unknown)]); - a_view.reselect_now(true); - b_view.reselect_now(true); - - assert_ne!( - a_view.active == Some(1), - b_view.active == Some(1), - "unknown-cold peers must still elect exactly one root" - ); - } - - /// An unknown cold cost must rank last, not read as the publisher's own zero. - /// A peer on a wire that cannot express one would otherwise outrank every relay - /// that can, and a mixed-version mesh would drag its aggregation point onto the - /// peer that told us the least. - #[test] - fn test_carrying_gate_unknown_cold_ranks_last() { - let peer = Hop::new(3).unwrap(); - let unknown = broadcast::Cost::UNKNOWN.cold; - - for above in [false, true] { - let mut state = front_state( - origin_keyed("test", peer, above), - vec![upstream_route(4), sibling_route(peer, unknown)], - ); - state.reselect_now(true); - assert_eq!( - state.active, - Some(0), - "an unknown cold path must not outrank a known one (above: {above})" - ); - } - } - - /// Warm cost stays the primary metric, but where it ties the cold cost breaks - /// the tie before hop count. - /// - /// The two tie-breaks answer the same question, "how far away is this content", - /// and the cold cost answers it in the operator's own prices while hop count - /// only counts relays. Putting the priced answer first is what stops an - /// expensive two-link path from outranking a cheap three-link one. - #[test] - fn test_equal_warm_cost_prefers_the_cheaper_root() { - // Two warm relays, each one link away, so the warm comparison ties. The one - // rooted nearer the publisher advertises the *longer* chain, since it sits - // deeper in an aggregation tree, which is exactly the case hop count reads - // backwards: a chain is only a guess at how far the content is, and the cold - // cost is that same distance actually priced. - let shallow = warm_route(&[90, 4], 5, 1); - let deep = warm_route(&[90, 91, 3], 1, 1); - assert_eq!( - shallow.cost.warm, deep.cost.warm, - "the candidates must tie on warm cost" - ); - assert!( - shallow.hops.len() < deep.hops.len(), - "hop count must favor the wrong one" - ); - - let mut state = front_state(Hop::new(7).unwrap(), vec![shallow, deep]); - state.reselect_now(true); - assert_eq!(state.active, Some(1), "hop count bypassed the cheaper-rooted warm copy"); - } - - /// The gate is scoped to warm siblings: a cheaper route via a relay that is - /// not itself carrying (advertised nonzero), or directly from the original - /// publisher (single-hop chain), is taken immediately even while carrying - /// and even when we would lose the key comparison. - #[test] - fn test_carrying_switches_to_benign_routes() { - let peer = Hop::new(3).unwrap(); - let lost = origin_keyed("test", peer, false); - - // A cheaper forwarder path: the relay advertised its accumulated cost. - let mut forwarder = sibling_route(peer, 10).with_cost(4); - forwarder.advertised = broadcast::Cost::new(4); - let mut state = front_state(lost, vec![upstream_route(10), forwarder]); - state.reselect_now(true); - assert_eq!( - state.active, - Some(1), - "a cheaper forwarder path must win while carrying" - ); - - // Directly from the original publisher: single-hop chain, advertised zero. - let direct = announce().with_hops(Hops::try_from(vec![peer]).unwrap()); - let mut state = front_state(lost, vec![upstream_route(10), direct]); - state.reselect_now(true); - assert_eq!( - state.active, - Some(1), - "a direct publisher route must win while carrying" - ); - - // The peer's session reconnecting: same chain, same cost, so the gate's - // strictly-cheaper test does not apply and recency decides. Loosening that - // test to `<=` would hold a carrying front on the dead session until the - // transport timed it out, which is the whole point of the recency order. - let mut state = front_state(lost, vec![sibling_route(peer, 10), sibling_route(peer, 10)]); - state.reselect_now(true); - assert_eq!( - state.active, - Some(1), - "a reconnect on an identical chain must win while carrying" - ); - } - - /// The gate only protects an announced incumbent: one that lost its announce - /// (the upstream retracted) is displaced regardless of the key comparison. - #[test] - fn test_carrying_gate_ignores_unannounced_incumbent() { - let peer = Hop::new(3).unwrap(); - let unannounced = upstream_route(10).with_announce(false); - let mut state = front_state( - origin_keyed("test", peer, false), - vec![unannounced, sibling_route(peer, 10)], - ); - state.reselect_now(true); - assert_eq!( - state.active, - Some(1), - "an unannounced incumbent must always be displaced" - ); - } - - /// A route arriving through a peer the front is already exposed to is our own - /// broadcast reflected back, whatever its chain claims, so it must not evict the - /// front. This is the shape a relay with no hop ids produces when both directions - /// of a sync target point at it. - #[test] - fn test_reflection_through_an_exposed_peer_cannot_take_over() { - let peer = Hop::new(42).unwrap(); - let upstream = Hops::try_from(vec![Hop::new(7).unwrap()]).unwrap(); - let reflected = announce().with_hops(Hops::try_from(vec![peer]).unwrap()); - - let mut state = front_state(Hop::new(1).unwrap(), vec![announce().with_hops(upstream)]); - - // Nobody is exposed yet: a different publisher is free to take the path. - assert!(!state.taints_a_reader(&reflected)); - - // Advertising the path to `peer` registers them, and the same route is now - // recognizable as a reflection. - *state.excluded.entry(peer).or_default() += 1; - assert!(state.taints_a_reader(&reflected)); - } - - /// The exposure is what discriminates, not the shape of the chain: an unrelated - /// publisher reaching us through some *other* peer still takes the path over. - #[test] - fn test_rival_publisher_through_another_peer_still_takes_over() { - let peer = Hop::new(42).unwrap(); - let elsewhere = Hop::new(43).unwrap(); - let upstream = Hops::try_from(vec![Hop::new(7).unwrap()]).unwrap(); - let rival = announce().with_hops(Hops::try_from(vec![Hop::UNKNOWN, elsewhere]).unwrap()); - - let mut state = front_state(Hop::new(1).unwrap(), vec![announce().with_hops(upstream)]); - *state.excluded.entry(peer).or_default() += 1; - - assert!(!state.taints_a_reader(&rival), "only the peer we feed is a reflection"); - } - - /// A peer that carries no hop ids hides its depth: everything behind it collapses - /// into one entry, so its route understates its true length and wins the cost - /// comparison against a longer-looking but genuinely shorter path. Pricing the - /// opaque link (`Client::with_cost`) is what restores the intended order. - #[test] - fn test_opaque_peer_understates_its_depth() { - let us = Hop::new(1).unwrap(); - - // Our own upstream, honestly described: two hops, charged per link. - let direct = || { - announce() - .with_hops(Hops::try_from(vec![Hop::new(7).unwrap(), Hop::new(8).unwrap()]).unwrap()) - .with_cost(2) - }; - // The same content reached through an opaque relay, which is actually further - // away but advertises no chain at all, so it lands as one unpriced hop. - let opaque = |cost| { - announce() - .with_hops(Hops::try_from(vec![Hop::new(42).unwrap()]).unwrap()) - .with_cost(cost) - }; - - // Unpriced, the opaque route wins on cost even though it is the longer path. - let mut state = front_state(us, vec![direct(), opaque(1)]); - state.reselect_now(false); - assert_eq!( - state.active, - Some(1), - "an unpriced opaque link out-ranks a shorter real path" - ); - - // Priced to reflect what it hides, the real path wins again. - let mut state = front_state(us, vec![direct(), opaque(16)]); - state.reselect_now(false); - assert_eq!( - state.active, - Some(0), - "pricing the opaque link restores the intended order" - ); - } - - /// Let the spawned origin tasks (source watchers, front dispatch) run. The - /// tests pause tokio time, so this advances the clock instantly. - /// Wait out a held re-parent (see [`HANDOVER_HOLD`]) and let the front task's - /// deadline fire, for tests whose subject is which route wins rather than when. - async fn settle_handover() { - tokio::time::advance(HANDOVER_HOLD * 2).await; - settle().await; - } - - async fn settle() { - tokio::time::sleep(tokio::time::Duration::from_millis(1)).await; - } - - /// Serve one requested track from a source like a session would: wait for the - /// origin to dispatch it, then accept with default info. - async fn accept_track(dynamic: &mut broadcast::Dynamic, name: &str) -> track::Producer { - let request = tokio::time::timeout(Duration::from_secs(1), dynamic.requested_track()) - .await - .expect("timed out waiting for a track request") - .expect("source closed"); - assert_eq!(request.name(), name, "unexpected track dispatched"); - request.accept(None) - } - - /// Serve `count` requested tracks, keyed by name. Dispatch order across - /// tracks is not guaranteed, which [`accept_track`]'s exact-name assert - /// cannot express. - async fn accept_tracks(dynamic: &mut broadcast::Dynamic, count: usize) -> HashMap { - let mut accepted = HashMap::new(); - for _ in 0..count { - let request = tokio::time::timeout(Duration::from_secs(1), dynamic.requested_track()) - .await - .expect("timed out waiting for a track request") - .expect("source closed"); - let name = request.name().to_string(); - accepted.insert(name, request.accept(None)); - } - accepted - } - - /// Tagging both origin handles with one context attributes the full model path: - /// ingress writes on the subscriber side, egress reads on the publisher side, - /// each counter landing exactly once (the model-layer silent-zero guard). - #[tokio::test] - async fn test_stats_tagged_end_to_end() { - use crate::Timestamp; - use crate::stats::{Config, Registry, Tier}; - use bytes::Bytes; - - tokio::time::pause(); - - let registry = Registry::new(Config::new()); - let ctx = registry.tier(Tier::default()).session("acme"); - - let origin = Hop::random().produce(); - let ingress = origin.clone().with_stats(ctx.clone()); - let egress = origin.consume().with_stats(ctx.clone()); - - // Egress announce stream: this is the tagged stream that drives the egress - // announce guard. - let mut announced = egress.announced(); - - // Ingress publishes an announced broadcast. - let source = ingress.create_broadcast("demo", announce()).unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - settle().await; - - // Egress observes the announce and gets the tagged broadcast. - let update = announced.next().await.unwrap(); - assert_eq!(update.path.as_str(), "demo"); - let broadcast = update.broadcast.unwrap(); - - // Egress subscribes; the ingress side serves the track on demand. - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer = accept_track(&mut dynamic, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - - // Ingress writes one group with two 5-byte frames. - let mut group = producer.append_group().unwrap(); - group - .write_frame(Timestamp::ZERO, Bytes::from_static(b"hello")) - .unwrap(); - group - .write_frame(Timestamp::ZERO, Bytes::from_static(b"world")) - .unwrap(); - group.finish().unwrap(); - - // Egress reads the group and both frames. - let mut group_c = sub.recv_group().await.unwrap().unwrap(); - let mut frames = 0; - while let Some(frame) = group_c.read_frame().await.unwrap() { - assert_eq!(frame.payload.len(), 5); - frames += 1; - } - assert_eq!(frames, 2); - settle().await; - - let report = registry.report(); - let entry = report - .traffic - .iter() - .find(|e| e.path.as_str() == "demo") - .expect("demo tracked"); - let path_len = "demo".len() as u64; - - // Egress (publisher side): reads out of the model. - let egress = &entry.publisher; - assert_eq!(egress.announced, 1, "one egress announce"); - assert_eq!(egress.announced_bytes, path_len); - assert_eq!(egress.subscriptions, 1, "one egress subscription"); - assert_eq!(egress.broadcasts, 1, "one viewer"); - assert_eq!(egress.groups, 1); - assert_eq!(egress.frames, 2); - assert_eq!(egress.bytes, 10); - assert_eq!(egress.fetches, 0); - - // Ingress (subscriber side): writes into the model. - let ingress = &entry.subscriber; - assert_eq!(ingress.announced, 1, "one ingress announce"); - assert_eq!(ingress.announced_bytes, path_len); - assert_eq!(ingress.subscriptions, 1, "one ingress track"); - assert_eq!(ingress.broadcasts, 0, "ingress has no viewer refcount"); - assert_eq!(ingress.groups, 1); - assert_eq!(ingress.frames, 2); - assert_eq!(ingress.bytes, 10); - - // A fetch bumps only `fetches` on the egress side, plus the delivered group. - let fetched = broadcast.track("video").unwrap().fetch_group(0, None).await.unwrap(); - let _ = fetched; - settle().await; - let report = registry.report(); - let entry = report.traffic.iter().find(|e| e.path.as_str() == "demo").unwrap(); - assert_eq!(entry.publisher.fetches, 1, "one fetch"); - assert_eq!(entry.publisher.subscriptions, 1, "fetch does not bump subscriptions"); - assert_eq!(entry.publisher.broadcasts, 1, "fetch does not bump the viewer refcount"); - // `fetches` is egress-only for the same structural reason as `broadcasts`: - // only a `track::Consumer` can fetch, and the ingress scope never reaches one - // (`broadcast::Producer::consume` hands out an untagged consumer). - assert_eq!(entry.subscriber.fetches, 0, "ingress cannot fetch"); - } - - /// A group the drift budget skips is counted, not silently dropped: without a - /// counter a skip is indistinguishable from loss, and `groups` alone would just - /// quietly under-report. - #[tokio::test] - async fn test_stats_counts_stale_skips() { - use crate::Timestamp; - use crate::stats::{Config, Registry, Tier}; - use bytes::Bytes; - - tokio::time::pause(); - - let registry = Registry::new(Config::new()); - let ctx = registry.tier(Tier::default()).session("acme"); - - let origin = Hop::random().produce(); - let ingress = origin.clone().with_stats(ctx.clone()); - let egress = origin.consume().with_stats(ctx.clone()); - - let mut announced = egress.announced(); - let source = ingress.create_broadcast("demo", announce()).unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - settle().await; - - let broadcast = announced.next().await.unwrap().broadcast.unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer = accept_track(&mut dynamic, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - - // Three seconds of media, delivered as a burst before the subscriber reads. - for second in 0..3 { - let mut group = producer.append_group().unwrap(); - group - .write_frame( - Timestamp::from_millis(second * 1000).unwrap(), - Bytes::from_static(b"hi"), - ) - .unwrap(); - group.finish().unwrap(); - } - - // The default REAL_TIME budget takes the live edge and writes the other two off. - let group = sub.recv_group().await.unwrap().unwrap(); - assert_eq!(group.sequence, 2); - settle().await; - - let report = registry.report(); - let entry = report.traffic.iter().find(|e| e.path.as_str() == "demo").unwrap(); - assert_eq!(entry.publisher.stale.groups, 2, "two groups skipped on the way out"); - assert_eq!(entry.publisher.stale.frames, 2); - assert_eq!(entry.publisher.stale.bytes, 4); - assert_eq!(entry.publisher.stale.datagrams, 0); - assert_eq!(entry.publisher.groups, 1, "only the live edge was delivered"); - assert_eq!(entry.subscriber.stale.groups, 0, "ingress wrote all three"); - assert_eq!(entry.subscriber.groups, 3); - } - - /// Expiry after handoff writes off only the unread tail. The group itself and - /// the frame already returned stay solely in the delivered counters, and a - /// cloned cursor cannot report the same tail again. - #[tokio::test] - async fn test_stats_handed_out_expiry_counts_the_unread_tail_once() { - use crate::Timestamp; - use crate::stats::{Config, Registry, Tier}; - use bytes::Bytes; - - tokio::time::pause(); - - let registry = Registry::new(Config::new()); - let ctx = registry.tier(Tier::default()).session("acme"); - - let origin = Hop::random().produce(); - let ingress = origin.clone().with_stats(ctx.clone()); - let egress = origin.consume().with_stats(ctx.clone()); - - let mut announced = egress.announced(); - let source = ingress.create_broadcast("demo", announce()).unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - settle().await; - - let broadcast = announced.next().await.unwrap().broadcast.unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer = accept_track(&mut dynamic, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - - // A frame whose payload is still in flight: the readers drain what has landed - // and then park on the rest, which is the stall the drift budget bounds. A - // group whose frames are all in hand is drained instead, so it would never - // reach expiry here. - let mut group = producer.append_group().unwrap(); - let mut writing = group - .create_frame(crate::frame::Info { - timestamp: Timestamp::ZERO, - size: 4, - }) - .unwrap(); - writing.write(Bytes::from_static(b"aa")).unwrap(); - - let mut reading = sub.recv_group().await.unwrap().expect("first group"); - let mut clone = reading.clone(); - let mut first = reading.next_frame().await.unwrap().expect("first frame"); - let mut second = clone.next_frame().await.unwrap().expect("cloned frame"); - assert_eq!(first.read_chunk().await.unwrap(), Some(Bytes::from_static(b"aa"))); - assert_eq!(second.read_chunk().await.unwrap(), Some(Bytes::from_static(b"aa"))); - - let mut edge = producer.append_group().unwrap(); - edge.write_frame(Timestamp::from_millis(1000).unwrap(), Bytes::from_static(b"edge")) - .unwrap(); - edge.finish().unwrap(); - - assert!(matches!(first.read_chunk().await, Err(crate::Error::Old))); - assert!(matches!(second.read_chunk().await, Err(crate::Error::Old))); - - let report = registry.report(); - let entry = report.traffic.iter().find(|e| e.path.as_str() == "demo").unwrap(); - assert_eq!(entry.publisher.groups, 1, "the handed-out group was delivered"); - assert_eq!(entry.publisher.stale.groups, 0, "the group is not counted twice"); - assert_eq!(entry.publisher.stale.frames, 0, "no whole frame went unread"); - assert_eq!( - entry.publisher.stale.bytes, 2, - "the undelivered half of the payload is stale, counted by one reader only" - ); - } - - /// Datagrams bypass the group/frame handles entirely, so they're metered at the - /// producer (ingress write) and the subscriber (egress read). Each one counts as - /// the single-frame group it stands in for, plus the `datagrams` breakout. - #[tokio::test] - async fn test_stats_datagrams_counted_both_sides() { - use crate::Timestamp; - use crate::stats::{Config, Registry, Tier}; - - tokio::time::pause(); - - let registry = Registry::new(Config::new()); - let ctx = registry.tier(Tier::default()).session("acme"); - - let origin = Hop::random().produce(); - let ingress = origin.clone().with_stats(ctx.clone()); - let egress = origin.consume().with_stats(ctx.clone()); - - let mut announced = egress.announced(); - let source = ingress.create_broadcast("demo", announce()).unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - settle().await; - - let broadcast = announced.next().await.unwrap().broadcast.unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer = accept_track(&mut dynamic, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - - producer.append_datagram(Timestamp::ZERO, &b"hello"[..]).unwrap(); - let datagram = sub.recv_datagram().await.unwrap().expect("datagram"); - assert_eq!(&datagram.payload[..], b"hello"); - settle().await; - - let report = registry.report(); - let entry = report - .traffic - .iter() - .find(|e| e.path.as_str() == "demo") - .expect("demo tracked"); - - for (side, traffic) in [("egress", &entry.publisher), ("ingress", &entry.subscriber)] { - assert_eq!(traffic.datagrams, 1, "{side}: one datagram"); - assert_eq!(traffic.groups, 1, "{side}: counted as its single-frame group"); - assert_eq!(traffic.frames, 1, "{side}: one frame"); - assert_eq!(traffic.bytes, 5, "{side}: payload counted once"); - } - } - - #[test] - fn origin_rejects_reserved_ids() { - assert!(Hop::new(0).is_err()); - assert!(Hop::new(1u64 << 62).is_err()); - assert_eq!(Hop::new(1).unwrap().id(), 1); - - let mut zero = [0u8].as_slice(); - assert_eq!( - Hop::decode(&mut zero, crate::lite::Version::Lite05).unwrap(), - Hop::UNKNOWN - ); - } - - #[test] - fn origin_list_push_fails_at_limit() { - let mut list = Hops::new(); - for _ in 0..MAX_HOPS { - list.push(Hop::random()).unwrap(); - } - assert_eq!(list.len(), MAX_HOPS); - assert_eq!(list.push(Hop::random()), Err(InvalidHop::TooMany)); - } - - /// A chain that revisits a hop looped, and every receiver of one must close the - /// session over it. Refusing it here is what keeps that unbuildable rather than a - /// rule each place that constructs a chain has to remember. - #[test] - fn origin_list_push_rejects_a_repeat() { - let seven = Hop::new(7).unwrap(); - let mut list = Hops::new(); - list.push(seven).unwrap(); - list.push(Hop::new(9).unwrap()).unwrap(); - - assert_eq!(list.push(seven), Err(InvalidHop::Duplicate)); - assert_eq!(list.len(), 2, "a refused push must not grow the chain"); - - // 0 identifies nothing, so two unknown hops are two hops, not a loop. - list.push(Hop::UNKNOWN).unwrap(); - list.push(Hop::UNKNOWN).unwrap(); - assert_eq!(list.len(), 4); - } - - #[test] - fn origin_list_replace_first() { - let mut list = Hops::new(); - for _ in 0..3 { - list.push(Hop::UNKNOWN).unwrap(); - } - - // Rewrites only the first placeholder, keeping the length the same. - assert!(list.replace_first(Hop::UNKNOWN, Hop::new(7).unwrap()).unwrap()); - assert_eq!(list.as_slice(), &[Hop::new(7).unwrap(), Hop::UNKNOWN, Hop::UNKNOWN]); - - // No match leaves the list untouched. - assert!(!list.replace_first(Hop::new(99).unwrap(), Hop::new(8).unwrap()).unwrap()); - assert_eq!(list.len(), 3); - - // Writing in an id the chain already carries would name it twice, which is the - // loop `push` refuses; the rewrite has to refuse it for the same reason. - assert_eq!( - list.replace_first(Hop::UNKNOWN, Hop::new(7).unwrap()), - Err(InvalidHop::Duplicate) - ); - - // A target that is not there changes nothing, so it cannot duplicate anything, - // however many times the replacement already appears. - assert_eq!( - list.replace_first(Hop::new(99).unwrap(), Hop::new(7).unwrap()), - Ok(false) - ); - - // Overwriting a slot with what it already holds is a no-op, not a duplicate: the - // entry being replaced is not a second occurrence of itself. - assert_eq!(list.replace_first(Hop::new(7).unwrap(), Hop::new(7).unwrap()), Ok(true)); - assert_eq!(list.as_slice(), &[Hop::new(7).unwrap(), Hop::UNKNOWN, Hop::UNKNOWN]); - } - - #[test] - fn origin_list_try_from_vec_enforces_limit() { - let under: Vec = (0..MAX_HOPS).map(|_| Hop::random()).collect(); - assert!(Hops::try_from(under).is_ok()); - - let over: Vec = (0..MAX_HOPS + 1).map(|_| Hop::random()).collect(); - assert_eq!(Hops::try_from(over), Err(InvalidHop::TooMany)); - - // The other wire rule, on the path that skips `push` entirely. - let seven = Hop::new(7).unwrap(); - assert_eq!( - Hops::try_from(vec![seven, Hop::new(9).unwrap(), seven]), - Err(InvalidHop::Duplicate) - ); - assert!(Hops::try_from(vec![Hop::UNKNOWN, seven, Hop::UNKNOWN]).is_ok()); - } - - /// Exact lookups and eligible announcements land synchronously in - /// `create_broadcast`: no runtime, no driver poll. - #[test] - fn test_create_visible_without_driver() { - let (origin, _driver) = Producer::new(Info::new(Hop::random())); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let _source = origin.create_broadcast("cam", announce()).unwrap(); - - assert!(consumer.get_broadcast("cam").is_some()); - announced.assert_try_next_some("cam"); - } - - /// Route changes and track dispatch are lifecycle work: nothing moves until - /// the driver is polled, and polling catches the origin up. - #[tokio::test] - async fn test_lifecycle_requires_driver() { - tokio::time::pause(); - - let (origin, driver) = Producer::new(Info::new(Hop::random())); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let mut source = origin.create_broadcast("cam", announce()).unwrap(); - let mut dynamic = source.dynamic(); - announced.assert_try_next_some("cam"); - - // Take the route offline and ask for a track. Both are driver work. - source.set_route(broadcast::Route::new()).unwrap(); - let broadcast = consumer.get_broadcast("cam").unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - settle().await; - assert!(announced.try_next().is_none(), "unannounce needs the driver"); - dynamic.assert_no_request(); - - // Run the driver: the unannounce lands and the track dispatches. - web_async::spawn(driver.run(crate::runtime::tokio_test::Tokio::<()>::new())); - settle().await; - announced.assert_next_none("cam"); - let _producer = accept_track(&mut dynamic, "video").await; - drop(subscribing); - } - - /// A handover discovered before the driver runs starts aging only after the - /// driver's clock is installed. An already-advanced virtual runtime must not - /// interpret a stamp from another clock as an expired hold. - #[test] - fn test_pre_run_handover_uses_driver_clock() { - let (origin, driver) = Producer::new(Info::new(Hop::new(7).unwrap())); - let consumer = origin.consume(); - let publisher = Hop::new(90).unwrap(); - let peer = Hop::new(3).unwrap(); - let incumbent_hops = Hops::try_from(vec![publisher]).unwrap(); - let candidate_hops = Hops::try_from(vec![publisher, peer]).unwrap(); - - let _incumbent = origin - .create_broadcast("cam", announce().with_hops(incumbent_hops.clone()).with_cost(10)) - .unwrap(); - let _candidate = origin - .create_broadcast("cam", forwarder_route(candidate_hops.clone(), 1)) - .unwrap(); - let watch = consumer.get_broadcast("cam").unwrap(); - assert_eq!(watch.route().hops, incumbent_hops); - - let timers = crate::runtime::Test::::new(); - timers.advance(HANDOVER_HOLD * 4); - let mut run = driver.run(timers.clone()); - let _ = run.poll(&kio::Waiter::noop()); - assert_eq!( - watch.route().hops, - incumbent_hops, - "installing an advanced clock must not expire a pre-run handover" - ); - - timers.advance(HANDOVER_HOLD * 2); - let _ = run.poll(&kio::Waiter::noop()); - assert_eq!( - watch.route().hops, - candidate_hops, - "the hold must expire on the driver clock" - ); - } - - /// Dropping the driver tears the origin down: fronts abort with `Dropped`, - /// pending dynamic requests are rejected, unannounces are delivered before - /// cursors end, and later mutations fail with `Closed`. - #[tokio::test] - async fn test_driver_drop_tears_down() { - tokio::time::pause(); - - let (origin, driver) = Producer::new(Info::new(Hop::random())); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let _source = origin.create_broadcast("cam", announce()).unwrap(); - announced.assert_try_next_some("cam"); - let broadcast = consumer.get_broadcast("cam").unwrap(); - - // A dynamic request no handler serves before the teardown. - let handler = origin.dynamic(); - let pending = consumer.request_broadcast("missing"); - - drop(driver); - - // The front aborted with Dropped and left the tree. - assert!(matches!(broadcast.closed().now_or_never(), Some(Error::Dropped))); - assert!(consumer.get_broadcast("cam").is_none()); - - // The cursor still delivers the unannounce, then ends. - let update = announced.try_next().expect("the final unannounce"); - assert_eq!(update.path.as_path(), Path::new("cam")); - assert!(update.broadcast.is_none()); - assert!(announced.next().now_or_never().expect("cursor ends").is_none()); - assert!(announced.is_closed()); - - // The pending request was rejected, and everything later fails fast. - assert!(matches!(pending.await, Err(Error::Dropped))); - assert!( - matches!(origin.create_broadcast("late", announce()), Err(Error::Closed)), - "a mutation after the driver dropped", - ); - assert!(matches!(consumer.request_broadcast("late").await, Err(Error::Closed))); - let mut handler = handler; - assert!(matches!( - handler.requested_broadcast().now_or_never(), - Some(Err(Error::Closed)) - )); - let mut late = consumer.announced(); - assert!(late.next().now_or_never().expect("born ended").is_none()); - } - - /// A dynamic request already handed to a handler is still rejected by the - /// teardown, and the handler resolving late cannot overturn the rejection. - #[tokio::test] - async fn test_driver_drop_rejects_handed_out_requests() { - tokio::time::pause(); - - let (origin, driver) = Producer::new(Info::new(Hop::random())); - let consumer = origin.consume(); - let mut handler = origin.dynamic(); - - let pending = consumer.request_broadcast("vod"); - let request = handler.requested_broadcast().await.unwrap(); - - drop(driver); - - // The handler answers after the teardown: first write wins, so the - // requester still observes the rejection. - request.accept(broadcast::Info::new().produce()); - assert!(matches!(pending.await, Err(Error::Dropped))); - } - - /// The driver holds no producer clone: once every producer drops and the - /// remaining lifecycle work drains, it finishes on its own. - #[tokio::test] - async fn test_driver_finishes_when_drained() { - tokio::time::pause(); - - let (origin, driver) = Producer::new(Info::new(Hop::random())); - let driver = tokio::spawn(driver.run(crate::runtime::tokio_test::Tokio::<()>::new())); - - let mut source = origin.create_broadcast("cam", announce()).unwrap(); - settle().await; - - // Producers still alive: the driver keeps running. - assert!(!driver.is_finished()); - - source.finish(); - drop(origin); - settle().await; - assert!(driver.is_finished(), "producers dropped and work drained"); - } - - /// A create over a path whose every source already closed replaces the dying - /// front instead of joining it, even before the driver runs its detach. The - /// alternative splices unrelated content into subscribers of a broadcast - /// that is over. - #[tokio::test] - async fn test_create_after_dead_source_is_fresh() { - tokio::time::pause(); - - let (origin, _driver) = Producer::new(Info::new(Hop::random())); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let old = origin.create_broadcast("cam", announce()).unwrap(); - announced.assert_try_next_some("cam"); - let old_front = consumer.get_broadcast("cam").unwrap(); - - // The publisher goes away and reconnects before the driver ever polls. - drop(old); - let _new = origin.create_broadcast("cam", announce()).unwrap(); - - // A replacement, not a splice: unannounce then announce, and the fresh - // front is a different broadcast. - let update = announced.try_next().expect("the unannounce"); - assert!(update.broadcast.is_none()); - let new_front = announced.assert_try_next_some("cam"); - assert!(!new_front.is_clone(&old_front)); - } - - #[tokio::test] - async fn test_announce() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - - let mut consumer1 = origin.consume().announced(); - consumer1.assert_next_wait(); - - // Publish the first broadcast; it becomes visible asynchronously. - let mut broadcast1 = origin.create_broadcast("test1", announce()).unwrap(); - settle().await; - - consumer1.assert_next_some("test1"); - consumer1.assert_next_wait(); - - // Make a new consumer that should get the existing broadcast. - // But we don't consume it yet. - let mut consumer2 = origin.consume().announced(); - - // Publish the second broadcast. - let mut broadcast2 = origin.create_broadcast("test2", announce()).unwrap(); - settle().await; - - consumer1.assert_next_some("test2"); - consumer1.assert_next_wait(); - - consumer2.assert_next_some("test1"); - consumer2.assert_next_some("test2"); - consumer2.assert_next_wait(); - - // Finish the first broadcast: a graceful end unannounces immediately. - broadcast1.finish(); - settle().await; - - // All consumers should get a None now. - consumer1.assert_next_none("test1"); - consumer2.assert_next_none("test1"); - consumer1.assert_next_wait(); - consumer2.assert_next_wait(); - - // And a new consumer only gets the last broadcast. - let mut consumer3 = origin.consume().announced(); - consumer3.assert_next_some("test2"); - consumer3.assert_next_wait(); - - broadcast2.finish(); - settle().await; - - consumer1.assert_next_none("test2"); - consumer2.assert_next_none("test2"); - consumer3.assert_next_none("test2"); - } - - /// Multiple sources created at one path feed a single origin-owned broadcast: - /// one announce, no churn as sources come and go, and an unannounce only when - /// the last source leaves. - #[tokio::test] - async fn test_duplicate() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let mut broadcast1 = origin.create_broadcast("test", announce()).unwrap(); - let mut broadcast2 = origin.create_broadcast("test", announce()).unwrap(); - let mut broadcast3 = origin.create_broadcast("test", announce()).unwrap(); - settle().await; - assert!(consumer.get_broadcast("test").is_some()); - - announced.assert_next_some("test"); - announced.assert_next_wait(); - - // A standby source finishing changes nothing. - broadcast2.finish(); - settle().await; - assert!(consumer.get_broadcast("test").is_some()); - announced.assert_next_wait(); - - // The active source finishing hands over to a survivor, invisibly. - broadcast1.finish(); - settle().await; - assert!(consumer.get_broadcast("test").is_some()); - announced.assert_next_wait(); - - // The last source finishing unannounces and removes the broadcast. - broadcast3.finish(); - settle().await; - assert!(consumer.get_broadcast("test").is_none()); - - announced.assert_next_none("test"); - announced.assert_next_wait(); - } - - /// A source dying mid-serve fails over: the track re-splices from the standby - /// source and resumes exactly at the first missing group. - #[tokio::test] - async fn test_route_failover() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - // Both routes share the first hop (the original publisher): only - // interchangeable content may join as a standby. - let hops_a = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let hops_b = Hops::try_from(vec![Hop::new(1).unwrap(), Hop::new(3).unwrap()]).unwrap(); - - // The first source announces the broadcast. - let source_a = origin.create_broadcast("test", announce().with_hops(hops_a)).unwrap(); - let mut dynamic_a = source_a.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - announced.assert_next_some("test"); - - // A second (longer) source joins silently as a standby. - let source_b = origin.create_broadcast("test", announce().with_hops(hops_b)).unwrap(); - let mut dynamic_b = source_b.dynamic(); - settle().await; - settle().await; - announced.assert_next_wait(); - - // Subscribing dispatches the track to the best source (A). - let subscribing = broadcast - .track("video") - .unwrap() - .subscribe(track::Subscription::default().with_max_age(Duration::from_secs(5))); - let mut producer = accept_track(&mut dynamic_a, "video").await; - settle().await; - dynamic_b.assert_no_request(); - - let mut sub = subscribing.await.unwrap(); - // Demand registers as the subscriber polls; a fresh segment carries no - // boundary, so the demand is the subscriber's own. - sub.assert_no_group(); - assert_eq!(producer.subscription().unwrap().start, None); - - producer.append_group().unwrap(); - producer.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 0); - assert_eq!(sub.assert_group().sequence, 1); - - // Source A dies (session loss): the track re-splices from B and nothing - // is announced. - // abort() consumes the producer, so this both aborts and drops it. - producer.abort(Error::Dropped).unwrap(); - source_a.abort(Error::Dropped).unwrap(); - drop(dynamic_a); - settle().await; - announced.assert_next_wait(); - - // The new copy resumes one past the spliced groups: its demand starts at - // the boundary, and groups the old source already delivered are filtered. - let mut producer = accept_track(&mut dynamic_b, "video").await; - settle().await; - sub.assert_no_group(); - assert_eq!(producer.subscription().unwrap().start, Some(Position::group(2))); - producer.create_group(group::Info { sequence: 1 }).unwrap(); - producer.create_group(group::Info { sequence: 2 }).unwrap(); - assert_eq!(sub.assert_group().sequence, 2, "groups below the boundary are filtered"); - sub.assert_not_closed(); - } - - /// Failover restores *every* subscribed track, not just one. A single-track - /// takeover leaves a partial recovery indistinguishable from a whole one: - /// the subscriber survives and keeps reading, but a track that is never - /// re-dispatched to the standby stalls silently. Real broadcasts are - /// multi-track (an MPEG-TS feed carries video, audio and data together), so - /// each track's boundary has to be computed and served independently. - #[tokio::test] - async fn test_route_failover_restores_every_track() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - // Both routes share the first hop: interchangeable content. - let hops_a = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let hops_b = Hops::try_from(vec![Hop::new(1).unwrap(), Hop::new(3).unwrap()]).unwrap(); - - let source_a = origin.create_broadcast("test", announce().with_hops(hops_a)).unwrap(); - let mut dynamic_a = source_a.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - - // The standby joins silently. - let source_b = origin.create_broadcast("test", announce().with_hops(hops_b)).unwrap(); - let mut dynamic_b = source_b.dynamic(); - settle().await; - settle().await; - - // Deliberately unequal group counts, so every track's resume boundary is a - // different number. Equal counts would let a boundary computed per - // broadcast rather than per track pass unnoticed. - const TRACKS: [(&str, u64); 3] = [("video", 3), ("audio", 1), ("data", 2)]; - - let subscribing: Vec<_> = TRACKS - .iter() - .map(|(name, _)| broadcast.track(name).unwrap().subscribe(None)) - .collect(); - let mut producers_a = accept_tracks(&mut dynamic_a, TRACKS.len()).await; - settle().await; - - let mut subs = Vec::new(); - for ((name, groups), subscribing) in TRACKS.iter().zip(subscribing) { - let mut sub = subscribing.await.unwrap(); - let producer = producers_a - .get_mut(*name) - .unwrap_or_else(|| panic!("{name} was never dispatched")); - for expected in 0..*groups { - producer.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, expected, "{name} did not start"); - } - subs.push((*name, *groups, sub)); - } - - // Source A dies mid-stream. - for (_, producer) in producers_a.drain() { - producer.abort(Error::Dropped).unwrap(); - } - source_a.abort(Error::Dropped).unwrap(); - drop(dynamic_a); - settle().await; - - // The standby must be asked for all of them, and each must resume at its - // own boundary. - let mut producers_b = accept_tracks(&mut dynamic_b, TRACKS.len()).await; - settle().await; - - // Demand registers as each subscriber polls, so poll them all before - // reading the boundaries back. - for (_, _, sub) in subs.iter_mut() { - sub.assert_no_group(); - } - settle().await; - - for (name, groups, sub) in subs.iter_mut() { - let producer = producers_b - .get_mut(*name) - .unwrap_or_else(|| panic!("{name} was never re-dispatched to the standby")); - let start = producer - .subscription() - .unwrap_or_else(|| panic!("{name} resumed without a subscription")) - .start - .unwrap_or_else(|| panic!("{name} resumed without a boundary")); - assert_eq!( - start, - Position::group(*groups), - "{name} resumed at another track's boundary instead of its own" - ); - let boundary = start.group; - - // A group below the boundary is filtered out; one at it is delivered. - producer.create_group(group::Info { sequence: boundary - 1 }).unwrap(); - producer.create_group(group::Info { sequence: boundary }).unwrap(); - assert_eq!(sub.assert_group().sequence, boundary, "{name} did not resume"); - sub.assert_not_closed(); - } - } - - /// `route_changed` yields the current route first, then each change; equal - /// updates coalesce, and the watch errors once every producer is gone. - #[tokio::test] - async fn test_broadcast_route_watch() { - let mut producer = broadcast::Info::new().produce(); - let mut consumer = producer.consume(); - - // Initial value: the default route. - assert_eq!(consumer.route_changed().await.unwrap(), broadcast::Route::default()); - - // An equal update is a no-op. - producer.set_route(broadcast::Route::default()).unwrap(); - assert!(consumer.route_changed().now_or_never().is_none()); - - let mut hops = Hops::new(); - hops.push(Hop::new(7).unwrap()).unwrap(); - let route = broadcast::Route::new().with_hops(hops).with_cost(3); - producer.set_route(route.clone()).unwrap(); - assert_eq!(consumer.route_changed().await.unwrap(), route); - - // A fresh consumer sees the current value immediately. - let mut fresh = producer.consume(); - assert_eq!(fresh.route_changed().await.unwrap(), route); - - drop(producer); - assert!(matches!(consumer.route_changed().await.unwrap_err(), Error::Dropped)); - } - - /// A cost update that flips the winning source hands live tracks over at a - /// group boundary and re-advertises the broadcast's route, without announce - /// churn. - #[tokio::test] - async fn test_route_cost_update() { - tokio::time::pause(); - - // The takeover happens while a subscriber is live (carrying), so the local - // origin must win the handover key comparison against B's announcing hop - // (origin 3); a random id would flake on the hash. - let origin = Info::new(origin_keyed("test", Hop::new(3).unwrap(), true)).produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - // Both routes share the first hop (the original publisher): only - // interchangeable content may join as a standby. - let hops_a = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let hops_b = Hops::try_from(vec![Hop::new(1).unwrap(), Hop::new(3).unwrap()]).unwrap(); - - // A (shorter chain) wins at equal cost. - let mut source_a = origin - .create_broadcast("test", announce().with_hops(hops_a.clone())) - .unwrap(); - let mut dynamic_a = source_a.dynamic(); - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - announced.assert_next_some("test"); - - let mut watch = broadcast.clone(); - assert_eq!(watch.route_changed().await.unwrap().hops, hops_a); - - let mut source_b = origin - .create_broadcast("test", forwarder_route(hops_b.clone(), 1)) - .unwrap(); - let mut dynamic_b = source_b.dynamic(); - settle().await; - assert!( - watch.route_changed().now_or_never().is_none(), - "a losing standby must not change the advertised route" - ); - - // Dispatch the track to A and deliver a group. - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer = accept_track(&mut dynamic_a, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - producer.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 0); - - // A's cost rises above B's: B takes over at the boundary and the - // broadcast re-advertises B's route. No announce events. - source_a - .set_route(announce().with_hops(hops_a.clone()).with_cost(10)) - .unwrap(); - settle().await; - - // Re-parenting onto another relay while serving is held down first: the - // advert follows A's new cost, but the front is still served by A. Only the - // front task's deadline wakes it out of that, which is what the advance - // exercises. - assert_eq!(watch.route().hops, hops_a, "the handover must wait out the hold"); - tokio::time::advance(HANDOVER_HOLD * 2).await; - settle().await; - assert_eq!(watch.route().hops, hops_b, "the hold must expire into the handover"); - announced.assert_next_wait(); - - let mut producer_b = accept_track(&mut dynamic_b, "video").await; - settle().await; - // Demand registers as the subscriber polls; the new segment starts at the - // splice boundary. - sub.assert_no_group(); - assert_eq!(producer_b.subscription().unwrap().start, Some(Position::group(1))); - producer_b.create_group(group::Info { sequence: 1 }).unwrap(); - assert_eq!(sub.assert_group().sequence, 1); - sub.assert_not_closed(); - - // The active source updating its own metadata re-advertises in place. - source_b - .set_route(announce().with_hops(hops_b.clone()).with_cost(5)) - .unwrap(); - settle().await; - let advertised = watch.route_changed().await.unwrap(); - assert_eq!(advertised.hops, hops_b); - assert_eq!(advertised.cost, broadcast::Cost::new(5)); - announced.assert_next_wait(); - } - - /// A track completed for good must survive later source churn: it is never - /// re-dispatched, and late subscribers still see a clean end. - #[tokio::test] - async fn test_completed_track_survives_route_churn() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - // Shared first hop, so B is a standby rather than a parked replacement. - let hops_a = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let hops_b = Hops::try_from(vec![Hop::new(1).unwrap(), Hop::new(3).unwrap()]).unwrap(); - - let source_a = origin.create_broadcast("test", announce().with_hops(hops_a)).unwrap(); - let mut dynamic_a = source_a.dynamic(); - settle().await; - let source_b = origin.create_broadcast("test", announce().with_hops(hops_b)).unwrap(); - let mut dynamic_b = source_b.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - - // Serve the track via A and end it for good. - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer = accept_track(&mut dynamic_a, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - producer.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 0); - producer.finish().unwrap(); - drop(producer); - settle().await; - sub.assert_closed(); - - // A detaching must not re-dispatch the finished track to B. - source_a.abort(Error::Dropped).unwrap(); - drop(dynamic_a); - settle().await; - dynamic_b.assert_no_request(); - - // A late subscriber sees the same clean end, not an abort. - let mut late = broadcast.track("video").unwrap().subscribe(None).await.unwrap(); - late.assert_closed(); - } - - /// A source rejecting a track ends the logical track immediately, with the - /// source's own error: which tracks a broadcast carries is the publisher's - /// contract, so there is no sweep of other routes and no retry budget. - #[tokio::test] - async fn test_refused_track_aborts_instantly() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let hops = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let source = origin.create_broadcast("test", announce().with_hops(hops)).unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let request = dynamic.requested_track().await.unwrap(); - request.reject(Error::NotFound); - settle().await; - - // One refusal is the verdict; the source is never re-asked. - assert!(matches!(subscribing.await, Err(Error::NotFound))); - dynamic.assert_no_request(); - } - - /// A rejection only rules its source out of the track, so a better route - /// taking over while the original source's info request is pending (and the - /// stale source rejecting at the same moment) rides the handover instead of - /// aborting the subscription. - #[tokio::test] - async fn test_stale_rejection_does_not_abort_a_handover() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let publisher = Hop::new(1).unwrap(); - let peer = Hop::new(5).unwrap(); - let via_peer = Hops::try_from(vec![publisher, peer]).unwrap(); - let local = Hops::try_from(vec![publisher]).unwrap(); - - // The only route: dispatch parks on its pending info request. - let source_remote = origin - .create_broadcast("test", announce().with_hops(via_peer).with_cost(2)) - .unwrap(); - let mut dynamic_remote = source_remote.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let request_remote = dynamic_remote.requested_track().await.unwrap(); - - // A better route attaches (taking dispatch) while the old source's - // request is still pending; the old source rejects in the same window. - let source_local = origin.create_broadcast("test", announce().with_hops(local)).unwrap(); - let mut dynamic_local = source_local.dynamic(); - request_remote.reject(Error::NotFound); - settle().await; - - // The subscription rides the handover onto the new route. - let mut producer_local = accept_track(&mut dynamic_local, "video").await; - settle().await; - let mut sub = subscribing - .await - .expect("the handover must win over the stale rejection"); - producer_local.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 0); - sub.assert_not_closed(); - } - - /// A better source attaching mid-subscription takes the track over at an - /// explicit group boundary: the old copy's demand is capped, the new copy - /// starts at the boundary, and the subscriber reads a seamless sequence. - #[tokio::test] - async fn test_route_handover() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - // Shared first hop, so the short route joins as an interchangeable source. - let hops_long = Hops::try_from(vec![Hop::new(1).unwrap(), Hop::new(3).unwrap()]).unwrap(); - let hops_short = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - - let source_a = origin - .create_broadcast("test", announce().with_hops(hops_long)) - .unwrap(); - let mut dynamic_a = source_a.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - announced.assert_next_some("test"); - - let subscribing = broadcast - .track("video") - .unwrap() - .subscribe(track::Subscription::default().with_max_age(Duration::from_secs(5))); - let mut producer_a = accept_track(&mut dynamic_a, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - producer_a.append_group().unwrap(); - producer_a.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 0); - assert_eq!(sub.assert_group().sequence, 1); - - // A strictly shorter source attaches: the live track is handed over with - // no announce churn. - let source_b = origin - .create_broadcast("test", announce().with_hops(hops_short)) - .unwrap(); - let mut dynamic_b = source_b.dynamic(); - settle().await; - settle().await; - announced.assert_next_wait(); - - let mut producer_b = accept_track(&mut dynamic_b, "video").await; - settle().await; - - // The old copy's demand is capped at the boundary; the new copy's starts - // there. Both propagate as the subscriber polls. - sub.assert_no_group(); - assert_eq!(producer_a.subscription().unwrap().end, Some(Position::group(2))); - assert_eq!(producer_b.subscription().unwrap().start, Some(Position::group(2))); - - // The old copy racing past its cap is filtered; the new copy serves on. - producer_a.create_group(group::Info { sequence: 2 }).unwrap(); - producer_b.create_group(group::Info { sequence: 2 }).unwrap(); - producer_b.create_group(group::Info { sequence: 3 }).unwrap(); - assert_eq!(sub.assert_group().sequence, 2); - assert_eq!(sub.assert_group().sequence, 3); - sub.assert_no_group(); - sub.assert_not_closed(); - } - - /// A graceful detach (deliberate unannounce) closes immediately: the - /// unannounce propagates promptly and a re-create is a fresh broadcast. - #[tokio::test(start_paused = true)] - async fn test_route_unannounce_immediate() { - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let hops = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let mut source = origin - .create_broadcast("test", announce().with_hops(hops.clone())) - .unwrap(); - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - announced.assert_next_some("test"); - - // The peer deliberately unannounced: no reconnect window, the broadcast is - // gone as soon as the teardown task observes the close. - source.finish(); - settle().await; - announced.assert_next_none("test"); - - // A re-create at the same path is a brand-new broadcast. - let _source = origin.create_broadcast("test", announce().with_hops(hops)).unwrap(); - settle().await; - let fresh = consumer.request_broadcast("test").await.unwrap(); - announced.assert_next_some("test"); - assert!( - !fresh.is_clone(&broadcast), - "re-create must not splice the old broadcast" - ); - } - - /// A dying source (a session drop, not a deliberate unannounce) closes the - /// broadcast just as promptly as a graceful one: no reconnect window, the - /// tracks abort, and a re-create is a fresh broadcast rather than a splice. - /// The application decides how to react to the loss; the origin never hides - /// it behind a stale route. - #[tokio::test(start_paused = true)] - async fn test_route_detach_immediate() { - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let hops = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let source = origin - .create_broadcast("test", announce().with_hops(hops.clone())) - .unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - announced.assert_next_some("test"); - - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let producer = accept_track(&mut dynamic, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - - // The session dies without unannouncing. - drop(producer); - source.abort(Error::Dropped).unwrap(); - drop(dynamic); - - settle().await; - announced.assert_next_none("test"); - sub.assert_error(); - - // A reconnecting session gets a brand-new broadcast, not a splice into - // the old one. - let _source = origin.create_broadcast("test", announce().with_hops(hops)).unwrap(); - settle().await; - settle().await; - let fresh = consumer.request_broadcast("test").await.unwrap(); - announced.assert_next_some("test"); - assert!( - !fresh.is_clone(&broadcast), - "re-create must not splice the old broadcast" - ); - } - - /// A track nobody reads keeps the source's copy for [`TRACK_IDLE_LINGER`], then - /// releases it. Crucially, the release must not immediately re-splice: the same - /// demand signal gates both directions, so an idle track settles instead of - /// re-requesting the track (and its info) every linger. - #[tokio::test(start_paused = true)] - async fn test_idle_track_releases_without_respinning() { - let origin = Info::new(Hop::random()).produce(); - let consumer = origin.consume(); - - let hops = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let source = origin.create_broadcast("test", announce().with_hops(hops)).unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let producer = accept_track(&mut dynamic, "video").await; - settle().await; - let sub = subscribing.await.unwrap(); - - // The reader leaves, but the copy stays warm inside the window so a viewer - // coming back (or a follow-up fetch) reuses it. - drop(sub); - tokio::time::sleep(TRACK_IDLE_LINGER / 2).await; - settle().await; - assert!( - producer.poll_unused(&kio::Waiter::noop()).is_pending(), - "the copy must stay spliced inside the linger", - ); - - // Past the window the segment is released, so the serving session sees its - // copy go unused and can drop it (along with the track info). - tokio::time::sleep(TRACK_IDLE_LINGER).await; - settle().await; - assert!( - producer.poll_unused(&kio::Waiter::noop()).is_ready(), - "an idle copy must be released after the linger", - ); - - // The anti-spin property: the release must not re-arm the splice. Ungated, - // the loop re-attaches the copy immediately and drops it again every linger, - // re-requesting the track (and its info) from the session each time it dies. - for _ in 0..3 { - tokio::time::sleep(TRACK_IDLE_LINGER).await; - settle().await; - assert!( - producer.poll_unused(&kio::Waiter::noop()).is_ready(), - "an unread copy must stay released, not be re-spliced", - ); - } - assert!( - dynamic.requested_track().now_or_never().is_none(), - "an unread track must not be re-requested", - ); - drop(producer); - - // A returning reader re-splices: the origin asks the source for a fresh copy. - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer = accept_track(&mut dynamic, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - producer.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 0); - } - - /// Back-to-back fetches reuse the source's copy: only the first asks the source - /// for the track, so a fetch-driven consumer (HLS pulling segment after segment) - /// doesn't re-request the track, and its `TRACK_INFO`, for every group. - #[tokio::test(start_paused = true)] - async fn test_back_to_back_fetches_reuse_the_track() { - let origin = Info::new(Hop::random()).produce(); - let consumer = origin.consume(); - - let hops = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let source = origin.create_broadcast("test", announce().with_hops(hops)).unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - - // The first fetch has to ask the source for the track. - let fetching = broadcast.track("video").unwrap().fetch_group(0, None); - let mut producer = accept_track(&mut dynamic, "video").await; - producer.append_group().unwrap().finish().unwrap(); - settle().await; - let first = fetching.await.expect("first fetch"); - drop(first); - - // A second fetch inside the linger reuses the copy already spliced in. - settle().await; - let fetching = broadcast.track("video").unwrap().fetch_group(0, None); - settle().await; - assert!( - dynamic.requested_track().now_or_never().is_none(), - "a fetch inside the linger must reuse the track, not re-request it", - ); - drop(fetching.await.expect("second fetch")); - - // Once the fetches stop, the copy is released like any other idle track. - tokio::time::sleep(TRACK_IDLE_LINGER * 2).await; - settle().await; - assert!( - producer.poll_unused(&kio::Waiter::noop()).is_ready(), - "the copy must be released once the fetches stop", - ); - drop(producer); - - // And a later fetch re-requests it: `accept_track` times out if it doesn't. - settle().await; - let fetching = broadcast.track("video").unwrap().fetch_group(0, None); - let mut producer = accept_track(&mut dynamic, "video").await; - producer.append_group().unwrap().finish().unwrap(); - settle().await; - fetching.await.expect("fetch after the linger"); - } - - /// A non-live broadcast is reachable by exact path but never announced; - /// toggling `live` announces and unannounces without touching the broadcast. - #[tokio::test] - async fn test_announce_toggle() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let mut source = origin.create_broadcast("test", broadcast::Route::new()).unwrap(); - settle().await; - - // Routable but not announced. - announced.assert_next_wait(); - let broadcast = consumer - .get_broadcast("test") - .expect("offline broadcast is still routable"); - assert!(!broadcast.route().announce); - - // request_broadcast resolves the offline broadcast too. - let requested = consumer.request_broadcast("test").await.unwrap(); - assert!(requested.is_clone(&broadcast)); - - // Going live announces. - source.set_route(announce()).unwrap(); - settle().await; - let face = announced.assert_next_some("test"); - assert!(face.is_clone(&broadcast)); - - // A fresh consumer replays only announced broadcasts. - let mut fresh = origin.consume().announced(); - fresh.assert_next_some("test"); - fresh.assert_next_wait(); - - // Going offline unannounces but stays routable. - source.set_route(broadcast::Route::new()).unwrap(); - settle().await; - announced.assert_next_none("test"); - assert!(consumer.get_broadcast("test").is_some()); - let mut fresh = origin.consume().announced(); - fresh.assert_next_wait(); - - source.finish(); - settle().await; - assert!(consumer.get_broadcast("test").is_none()); - } - - /// An announced source outranks a cheaper offline one, so the broadcast - /// stays announced and serves from it. - #[tokio::test] - async fn test_announce_beats_offline() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - // An unannounced source with the best cost. - let _offline = origin.create_broadcast("test", broadcast::Route::new()).unwrap(); - settle().await; - announced.assert_next_wait(); - - // An announced source with a worse cost still wins: the path announces - // and advertises its route. - let mut announced_source = origin.create_broadcast("test", announce().with_cost(10)).unwrap(); - settle().await; - announced.assert_next_some("test"); - let face = consumer.get_broadcast("test").unwrap(); - assert!(face.route().announce); - assert_eq!(face.route().cost, broadcast::Cost::new(10)); - - // The announced source leaving falls back to the offline one: the path - // unannounces but stays routable. - announced_source.finish(); - settle().await; - announced.assert_next_none("test"); - assert!(consumer.get_broadcast("test").is_some()); - } - - /// A better source attaching does not churn announces: the broadcast identity - /// is origin-owned, so the swap is invisible to consumers. - #[tokio::test] - async fn test_better_source_no_churn() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let mut announced = origin.consume().announced(); - - // `a` carries two hops; `b` reaches the same publisher in one, so `b` - // wins dispatch when it joins. - let hops_a = Hops::try_from(vec![Hop::new(1).unwrap(), Hop::new(3).unwrap()]).unwrap(); - let hops_b = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let _a = origin.create_broadcast("test", announce().with_hops(hops_a)).unwrap(); - settle().await; - let face = announced.assert_next_some("test"); - - let _b = origin - .create_broadcast("test", announce().with_hops(hops_b.clone())) - .unwrap(); - settle().await; - settle_handover().await; - announced.assert_next_wait(); - let current = origin.consume().get_broadcast("test").unwrap(); - assert!(current.is_clone(&face), "the broadcast identity must not change"); - // The face now advertises the winning (shorter) route. - assert_eq!(current.route().hops, hops_b); - } - - /// A second source with a different original publisher (first hop) is new - /// content, not a standby: it must not splice into the incumbent's - /// subscribers. It takes the path over immediately, as a real unannounce + - /// announce, rather than waiting out an incumbent whose session may only be - /// alive because the transport has not timed it out yet. - #[tokio::test] - async fn test_publisher_mismatch_replaces() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let hops_a = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let hops_b = Hops::try_from(vec![Hop::new(2).unwrap()]).unwrap(); - - let mut source_a = origin - .create_broadcast("test", announce().with_hops(hops_a.clone())) - .unwrap(); - settle().await; - let face_a = announced.assert_next_some("test"); - - // A different publisher at the same path: the newcomer wins it now, while - // the incumbent is still attached and still believes it is publishing. - let _source_b = origin - .create_broadcast("test", announce().with_hops(hops_b.clone())) - .unwrap(); - settle().await; - settle().await; - announced.assert_next_none("test"); - let face_b = announced.assert_next_some("test"); - assert!(!face_b.is_clone(&face_a), "a replacement, never a splice"); - assert_eq!(consumer.get_broadcast("test").unwrap().route().hops, hops_b); - // The displaced front is torn down, not merely unpublished: leaving it - // running would strand its subscribers and its source watchers on a face - // nothing can reach. - assert!(face_a.is_closed(), "the displaced front must close"); - - // The displaced incumbent ending is invisible: it no longer owns the path. - source_a.finish(); - settle().await; - settle().await; - announced.assert_next_wait(); - assert_eq!(consumer.get_broadcast("test").unwrap().route().hops, hops_b); - } - - /// A displaced live publisher stands by rather than fighting for the path back, - /// then reclaims it once its replacement leaves. - #[tokio::test] - async fn test_displaced_publisher_reclaims_path_when_replacement_leaves() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let hops_a = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let hops_b = Hops::try_from(vec![Hop::new(2).unwrap()]).unwrap(); - - // A announces and is live. - let mut source_a = origin - .create_broadcast("test", announce().with_hops(hops_a.clone())) - .unwrap(); - settle().await; - announced.assert_next_some("test"); - - // A different publisher announces the same path, displacing A even though - // A's session is still open. - let mut source_b = origin.create_broadcast("test", announce().with_hops(hops_b)).unwrap(); - settle().await; - settle().await; - announced.assert_next_none("test"); - announced.assert_next_some("test"); - // Exactly one handover: A stands by on its unchanged route instead of - // taking the path straight back, which would trade announces forever. - announced.assert_next_wait(); - - // B disconnects. A is still an open, live broadcast producer. - source_b.finish(); - settle().await; - settle().await; - - assert!( - consumer.get_broadcast("test").is_some(), - "the still-live publisher A should reclaim the path once its replacement leaves" - ); - let recovered = consumer.request_broadcast("test").await.unwrap(); - assert_eq!(recovered.route().hops, hops_a); - - announced.assert_next_none("test"); - announced.assert_next_some("test"); - announced.assert_next_wait(); - - source_a.finish(); - } - - /// A source that was displaced and later reclaimed the path must still be able - /// to take the path over when its own route moves to a new publisher, even - /// though a sibling source keeps the old front alive. - #[tokio::test] - async fn test_reclaimed_publisher_can_still_replace_itself() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let hops_a = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let hops_b = Hops::try_from(vec![Hop::new(2).unwrap()]).unwrap(); - let hops_c = Hops::try_from(vec![Hop::new(3).unwrap()]).unwrap(); - - // Two sources sharing a publisher splice into one front. - let mut source_a1 = origin - .create_broadcast("test", announce().with_hops(hops_a.clone())) - .unwrap(); - let mut source_a2 = origin - .create_broadcast("test", announce().with_hops(hops_a.clone())) - .unwrap(); - settle().await; - settle().await; - assert_eq!(consumer.get_broadcast("test").unwrap().route().hops, hops_a); - - // A different publisher takes the path; both A sources stand by behind it. - let mut source_b = origin.create_broadcast("test", announce().with_hops(hops_b)).unwrap(); - settle().await; - settle().await; - - // B leaves and the A sources reclaim the path, having spent their attempt. - source_b.finish(); - settle().await; - settle().await; - assert_eq!(consumer.get_broadcast("test").unwrap().route().hops, hops_a); - - // A1 now moves to a new publisher, which is a fresh route observation. Its - // sibling A2 keeps the old front open, so this attach is a replacement, and - // a publisher swap is always a replacement rather than a standby. - source_a1.set_route(announce().with_hops(hops_c.clone())).unwrap(); - settle().await; - settle().await; - assert_eq!( - consumer.get_broadcast("test").unwrap().route().hops, - hops_c, - "the new publisher must take the path over, not stand by behind the old front" - ); - - source_a1.finish(); - source_a2.finish(); - } - - /// A repricing is not new content: a standby source must not use a cost-only - /// route update to evict the live front it already lost to. - #[tokio::test] - async fn test_repricing_does_not_earn_a_takeover() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let hops_a = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let hops_b = Hops::try_from(vec![Hop::new(2).unwrap()]).unwrap(); - - let mut source_a = origin - .create_broadcast("test", announce().with_hops(hops_a.clone()).with_cost(5)) - .unwrap(); - settle().await; - announced.assert_next_some("test"); - - // B displaces A; A stands by. - let mut source_b = origin - .create_broadcast("test", announce().with_hops(hops_b.clone())) - .unwrap(); - settle().await; - settle().await; - announced.assert_next_none("test"); - announced.assert_next_some("test"); - announced.assert_next_wait(); - - // A's peer re-announces it at a new cost. Same publisher, same content: - // nothing about this says A should own the path again. - source_a - .set_route(announce().with_hops(hops_a.clone()).with_cost(9)) - .unwrap(); - settle().await; - settle().await; - assert_eq!( - consumer.get_broadcast("test").unwrap().route().hops, - hops_b, - "a repricing must not take the path back from the live front" - ); - announced.assert_next_wait(); - - source_a.finish(); - source_b.finish(); - } - - /// A publisher reconnecting under the same identity attaches as a second - /// route with an identical hop chain and cost. The new session is the one - /// actually carrying frames, so it must win selection immediately rather than - /// waiting for the transport to retire the old one. - #[tokio::test] - async fn test_reconnect_wins_over_stale_route() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let publisher = Hop::new(1).unwrap(); - let hops = Hops::try_from(vec![publisher]).unwrap(); - - // The original session, still attached: its QUIC connection has not been - // declared dead yet. - let stale = origin - .create_broadcast("test", announce().with_hops(hops.clone())) - .unwrap(); - let mut stale_dynamic = stale.dynamic(); - settle().await; - - // The same publisher reconnecting over a fresh session. - let fresh = origin - .create_broadcast("test", announce().with_hops(hops.clone())) - .unwrap(); - let mut fresh_dynamic = fresh.dynamic(); - settle().await; - settle().await; - - // Track requests dispatch to the reconnect, not the corpse. - let broadcast = consumer.request_broadcast("test").await.unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - settle().await; - let _producer = accept_track(&mut fresh_dynamic, "video").await; - settle().await; - subscribing.await.unwrap(); - stale_dynamic.assert_no_request(); - } - - /// The same reconnect, but arriving while a subscription is already spliced - /// onto the stale route: the live track must re-splice onto the new session - /// rather than ride the dead one until the transport gives up. The gate - /// [`FrontState::reselect`] applies while carrying is pinned separately, in - /// [`test_carrying_switches_to_benign_routes`]. - #[tokio::test] - async fn test_carrying_reconnect_switches_immediately() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let hops = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - - let stale = origin - .create_broadcast("test", announce().with_hops(hops.clone())) - .unwrap(); - let mut stale_dynamic = stale.dynamic(); - settle().await; - - // A live subscription riding the original session. - let broadcast = consumer.request_broadcast("test").await.unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - settle().await; - let _stale_producer = accept_track(&mut stale_dynamic, "video").await; - settle().await; - // Held: the splice only follows the active route while the track is read. - let _subscription = subscribing.await.unwrap(); - - // The reconnect arrives with the front already carrying. - let fresh = origin - .create_broadcast("test", announce().with_hops(hops.clone())) - .unwrap(); - let mut fresh_dynamic = fresh.dynamic(); - settle().await; - settle().await; - - // The carrying front re-splices onto the reconnect rather than waiting for - // the stale session to die. - let _fresh_producer = accept_track(&mut fresh_dynamic, "video").await; - } - - /// Taking the path over is scoped to a newcomer that would actually outrank - /// the incumbent. An offline source (a cache, or an on-demand handler) is - /// ranked below every announced route, so arriving under a different - /// publisher must not unannounce a live broadcast and cut its subscribers. - /// - /// The tail of this test covers the park's *exit*: the parked source has to - /// wake and attach once the incumbent ends. Nothing else drives that wait, so - /// without this a lost wakeup would strand the source invisibly forever - /// rather than failing anything. - #[tokio::test] - async fn test_offline_mismatch_never_evicts_a_live_front() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let hops_live = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let hops_cache = Hops::try_from(vec![Hop::new(2).unwrap()]).unwrap(); - - let mut live = origin - .create_broadcast("test", announce().with_hops(hops_live.clone())) - .unwrap(); - let mut live_dynamic = live.dynamic(); - settle().await; - let face = announced.assert_next_some("test"); - - // A subscriber riding the live broadcast, which the eviction would cut. - let broadcast = consumer.request_broadcast("test").await.unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - settle().await; - let _producer = accept_track(&mut live_dynamic, "video").await; - settle().await; - subscribing.await.unwrap(); - - // An offline source for different content at the same path: it stays - // invisible rather than displacing the live one. - let cache = origin - .create_broadcast("test", broadcast::Route::new().with_hops(hops_cache.clone())) - .unwrap(); - settle().await; - settle().await; - announced.assert_next_wait(); - assert!(!face.is_closed(), "the live front must survive"); - assert_eq!(consumer.get_broadcast("test").unwrap().route().hops, hops_live); - - // The incumbent ending hands the path to the parked source, which is the - // only thing that ever wakes that wait. - live.finish(); - settle().await; - settle().await; - announced.assert_next_none("test"); - let taken = consumer - .get_broadcast("test") - .expect("the parked source must take over"); - assert_eq!(taken.route().hops, hops_cache); - // Offline, so it holds the path without being advertised. - announced.assert_next_wait(); - drop(cache); - } - - /// A subscription from a peer the active chain flows through is served from - /// the best clean source directly (data-plane split horizon), while every - /// other consumer keeps the shared spliced broadcast fed by the active - /// source. The two selections match what the announce loop advertises, so - /// the data plane keeps the control plane's promise. - #[tokio::test] - async fn test_dispatch_excludes_requester() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let peer = Hop::new(5).unwrap(); - let publisher = Hop::new(1).unwrap(); - // The route through the peer is cheaper, so it is the active source. - let tainted = Hops::try_from(vec![publisher, peer]).unwrap(); - let clean = Hops::try_from(vec![publisher]).unwrap(); - - let source_a = origin.create_broadcast("test", announce().with_hops(tainted)).unwrap(); - let mut dynamic_a = source_a.dynamic(); - settle().await; - let source_b = origin - .create_broadcast("test", announce().with_hops(clean).with_cost(5)) - .unwrap(); - let mut dynamic_b = source_b.dynamic(); - settle().await; - settle().await; - - // An ordinary consumer rides the shared front, dispatched to the active - // (peer-tainted) source. - let shared = consumer.request_broadcast("test").await.unwrap(); - let subscribing = shared.track("video").unwrap().subscribe(None); - let _producer_a = accept_track(&mut dynamic_a, "video").await; - settle().await; - subscribing.await.unwrap(); - - // The peer is pinned to the clean source. Crucially, nothing reaches the - // via-peer source: a track request on it is what a session would forward - // upstream as a SUBSCRIBE, and forwarding this one would send the peer's - // own subscription back to them. - let scoped = consumer.clone().excluding(peer); - let pinned = scoped.request_broadcast("test").await.unwrap(); - let subscribing = pinned.track("video").unwrap().subscribe(None); - let _producer_b = accept_track(&mut dynamic_b, "video").await; - settle().await; - subscribing.await.unwrap(); - dynamic_a.assert_no_request(); - } - - /// A peer starting to read is itself the event that taints routes: the - /// exclusion guard registers when the front is advertised to them, and - /// nothing else may churn for a long time afterwards. The registration must - /// re-run selection on its own, moving the front (and what it advertises) - /// off a route that now flows through a reader; the release must re-run it - /// too, freeing the better route again. - #[tokio::test] - async fn test_reader_taint_triggers_reselect() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let publisher = Hop::new(1).unwrap(); - let peer = Hop::new(5).unwrap(); - let via_peer = Hops::try_from(vec![publisher, peer]).unwrap(); - let clean = Hops::try_from(vec![publisher]).unwrap(); - - // The via-peer route is cheaper, so it is the active source. - let _source_a = origin - .create_broadcast("test", announce().with_hops(via_peer.clone())) - .unwrap(); - settle().await; - let _source_b = origin - .create_broadcast("test", announce().with_hops(clean.clone()).with_cost(5)) - .unwrap(); - settle().await; - settle().await; - - let mut broadcast = consumer.request_broadcast("test").await.unwrap(); - assert_eq!(broadcast.route_changed().await.unwrap().hops, via_peer); - - // The peer opens its announce stream: advertising the path to them is - // what registers the exclusion, and that alone must move the front. - let scoped = consumer.clone().excluding(peer); - let mut announced = scoped.announced(); - let reading = announced.assert_next_some("test"); - settle().await; - settle().await; - assert_eq!( - broadcast - .route_changed() - .now_or_never() - .expect("registering a reader must reselect the front off the tainted route") - .unwrap() - .hops, - clean - ); - - // The reader leaving releases the taint, and the release must re-run - // selection too: the cheaper route comes back, held like any re-parent. - drop(reading); - drop(announced); - // The release reselect arms the hold; then wait it out. - settle().await; - settle_handover().await; - assert_eq!( - broadcast - .route_changed() - .now_or_never() - .expect("releasing the last reader must reselect the front") - .unwrap() - .hops, - via_peer - ); - } - - /// The steer away from a tainted route must never cost the front its - /// announcement. The only clean route here is an offline standby; moving onto - /// it would retract the path, dropping the advertisement whose guard created - /// the taint, and then re-announce with the taint gone, forever. - #[tokio::test] - async fn test_reader_taint_does_not_retract_the_announcement() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let publisher = Hop::new(1).unwrap(); - let peer = Hop::new(5).unwrap(); - let via_peer = Hops::try_from(vec![publisher, peer]).unwrap(); - let clean = Hops::try_from(vec![publisher]).unwrap(); - - let source_a = origin - .create_broadcast("test", announce().with_hops(via_peer.clone())) - .unwrap(); - let mut dynamic_a = source_a.dynamic(); - settle().await; - // The clean alternative is an offline standby: joinable, never announced. - let source_b = origin - .create_broadcast("test", broadcast::Route::new().with_hops(clean).with_cost(5)) - .unwrap(); - let mut dynamic_b = source_b.dynamic(); - settle().await; - settle().await; - - let mut broadcast = consumer.request_broadcast("test").await.unwrap(); - assert_eq!(broadcast.route_changed().await.unwrap().hops, via_peer); - - // Advertising to the peer registers the exclusion, tainting the active - // route. With no announced alternative, the front must stay put and the - // announcement must hold steady. - let scoped = consumer.clone().excluding(peer); - let mut announced = scoped.announced(); - let _reading = announced.assert_next_some("test"); - settle().await; - settle().await; - assert!( - broadcast.route_changed().now_or_never().is_none(), - "the front must not steer onto an offline standby" - ); - announced.assert_next_wait(); - - // Data still avoids the reader: a track on the shared front dispatches - // to the clean standby, not the tainted advertised route. - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let _producer_b = accept_track(&mut dynamic_b, "video").await; - settle().await; - subscribing.await.unwrap(); - dynamic_a.assert_no_request(); - } - - /// Two publishers that never declared an identity both arrive with a first - /// hop of UNKNOWN. They are unrelated content, so the second MUST replace the - /// first rather than joining it as an interchangeable standby: splicing them - /// would cut one publisher's subscribers over to the other's stream. - #[tokio::test] - async fn test_unknown_publishers_do_not_splice() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let unknown_a = Hops::try_from(vec![Hop::UNKNOWN]).unwrap(); - let unknown_b = Hops::try_from(vec![Hop::UNKNOWN]).unwrap(); - - let mut source_a = origin - .create_broadcast("test", announce().with_hops(unknown_a.clone())) - .unwrap(); - settle().await; - settle().await; - announced.assert_next_some("test"); - - // Same first hop by value, but it identifies nothing, so this is a - // replacement: the path is unannounced and re-announced rather than - // silently gaining a standby. - let source_b = origin - .create_broadcast("test", announce().with_hops(unknown_b)) - .unwrap(); - settle().await; - settle().await; - announced.assert_next_none("test"); - let live = announced.assert_next_some("test"); - - // Repricing the displaced UNKNOWN source is still not evidence of a new - // publisher. It remains parked behind the replacement. - source_a - .set_route(announce().with_hops(unknown_a).with_cost(9)) - .unwrap(); - settle().await; - settle().await; - assert!( - consumer.get_broadcast("test").unwrap().is_clone(&live), - "UNKNOWN-to-UNKNOWN repricing must not replace the live front" - ); - announced.assert_next_wait(); - - drop(source_a); - drop(source_b); - } - - /// The same two sources under a real shared publisher id do splice, which is - /// what keeps the rule above about UNKNOWN rather than about hop chains. - #[tokio::test] - async fn test_known_publishers_still_splice() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let publisher = Hop::new(1).unwrap(); - let hops_a = Hops::try_from(vec![publisher]).unwrap(); - let hops_b = Hops::try_from(vec![publisher, Hop::new(3).unwrap()]).unwrap(); - - let source_a = origin.create_broadcast("test", announce().with_hops(hops_a)).unwrap(); - settle().await; - settle().await; - announced.assert_next_some("test"); - - // Shares the publisher, so it joins silently as a standby: no churn. - let source_b = origin.create_broadcast("test", announce().with_hops(hops_b)).unwrap(); - settle().await; - settle().await; - announced.assert_next_wait(); - - drop(source_a); - drop(source_b); - } - - /// A local standby with the same original publisher joining a front that is - /// carrying the broadcast from a peer must splice the live subscription onto - /// the new source, never tear it down (#2473, e2e finding 2). Redundant - /// publishers sharing an Hop ID MUST produce the same tracks, so the - /// splice resumes seamlessly at the group boundary. - #[tokio::test] - async fn test_standby_join_splices_live_subscriber() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let publisher = Hop::new(1).unwrap(); - let peer = Hop::new(5).unwrap(); - let via_peer = Hops::try_from(vec![publisher, peer]).unwrap(); - let local = Hops::try_from(vec![publisher]).unwrap(); - - // Carrying via the peer, with a live subscriber mid-stream. - let source_remote = origin - .create_broadcast("test", announce().with_hops(via_peer).with_cost(2)) - .unwrap(); - let mut dynamic_remote = source_remote.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer_remote = accept_track(&mut dynamic_remote, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - producer_remote.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 0); - - // The local standby joins with the same first hop and a cheaper route: - // it wins dispatch and the live track re-splices at the boundary. - let source_local = origin.create_broadcast("test", announce().with_hops(local)).unwrap(); - let mut dynamic_local = source_local.dynamic(); - settle().await; - let mut producer_local = accept_track(&mut dynamic_local, "video").await; - settle().await; - sub.assert_no_group(); - assert_eq!(producer_local.subscription().unwrap().start, Some(Position::group(1))); - producer_local.create_group(group::Info { sequence: 1 }).unwrap(); - assert_eq!(sub.assert_group().sequence, 1); - sub.assert_not_closed(); - } - - /// Reselect is decided per track, so a standby carrying only some of the - /// broadcast's tracks splices the ones it has and leaves the rest on the - /// incumbent. This is the divergent-layout case for a 1+1 pair: two sources - /// that are meant to be interchangeable but do not agree on the track list - /// must degrade to a per-track split rather than taking the whole broadcast - /// with them. - #[tokio::test] - async fn test_standby_with_a_partial_track_list_splits_per_track() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let publisher = Hop::new(1).unwrap(); - let peer = Hop::new(5).unwrap(); - let via_peer = Hops::try_from(vec![publisher, peer]).unwrap(); - let local = Hops::try_from(vec![publisher]).unwrap(); - - // The incumbent carries both tracks, with live subscribers mid-stream. - let source_remote = origin - .create_broadcast("test", announce().with_hops(via_peer).with_cost(2)) - .unwrap(); - let mut dynamic_remote = source_remote.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - - let subscribing_video = broadcast.track("video").unwrap().subscribe(None); - let subscribing_audio = broadcast.track("audio").unwrap().subscribe(None); - let mut producers_remote = accept_tracks(&mut dynamic_remote, 2).await; - settle().await; - - let mut sub_video = subscribing_video.await.unwrap(); - let mut sub_audio = subscribing_audio.await.unwrap(); - for name in ["video", "audio"] { - producers_remote.get_mut(name).unwrap().append_group().unwrap(); - } - assert_eq!(sub_video.assert_group().sequence, 0); - assert_eq!(sub_audio.assert_group().sequence, 0); - - // The cheaper standby joins and wins dispatch, but only has "video". - let source_local = origin.create_broadcast("test", announce().with_hops(local)).unwrap(); - let mut dynamic_local = source_local.dynamic(); - settle().await; - - let mut producer_local = None; - for _ in 0..2 { - let request = tokio::time::timeout(Duration::from_secs(1), dynamic_local.requested_track()) - .await - .expect("timed out waiting for a track request") - .expect("source closed"); - match request.name() { - "video" => producer_local = Some(request.accept(None)), - "audio" => request.reject(Error::NotFound), - other => panic!("unexpected track dispatched: {other}"), - } - } - settle().await; - let mut producer_local = producer_local.expect("the standby was never asked for video"); - - // Video re-splices onto the standby at the boundary. - sub_video.assert_no_group(); - assert_eq!(producer_local.subscription().unwrap().start, Some(Position::group(1))); - producer_local.create_group(group::Info { sequence: 1 }).unwrap(); - assert_eq!( - sub_video.assert_group().sequence, - 1, - "video did not move to the standby" - ); - - // Audio is untouched: the refusal costs the incumbent nothing. - producers_remote.get_mut("audio").unwrap().append_group().unwrap(); - assert_eq!( - sub_audio.assert_group().sequence, - 1, - "audio did not stay on the incumbent" - ); - sub_video.assert_not_closed(); - sub_audio.assert_not_closed(); - } - - /// A standby that wins dispatch before creating a track must not kill a - /// subscription the incumbent is serving: its refusal only rules it out of - /// this track, and the incumbent keeps delivering. The refusal is still - /// never retried: once the incumbent goes away every remaining source has - /// refused, so the subscription aborts and the consumer's next request asks - /// afresh. - #[tokio::test] - async fn test_standby_missing_track_keeps_incumbent() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let publisher = Hop::new(1).unwrap(); - let peer = Hop::new(5).unwrap(); - let via_peer = Hops::try_from(vec![publisher, peer]).unwrap(); - let local = Hops::try_from(vec![publisher]).unwrap(); - - // Carrying via the peer, with a live subscriber mid-stream. - let source_remote = origin - .create_broadcast("test", announce().with_hops(via_peer).with_cost(2)) - .unwrap(); - let mut dynamic_remote = source_remote.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - let subscribing = broadcast.track("audio").unwrap().subscribe(None); - let mut producer_remote = accept_track(&mut dynamic_remote, "audio").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - producer_remote.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 0); - - // The standby joins and wins dispatch, but has not created "audio" yet. - // Its refusal must cost the incumbent nothing. - let source_local = origin.create_broadcast("test", announce().with_hops(local)).unwrap(); - let mut dynamic_local = source_local.dynamic(); - settle().await; - let request = dynamic_local.requested_track().await.unwrap(); - assert_eq!(request.name(), "audio"); - request.reject(Error::NotFound); - settle().await; - - // Still spliced to the incumbent, still delivering. - producer_remote.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 1); - sub.assert_not_closed(); - - // The incumbent leaving exhausts the table (the standby's refusal is - // never retried): the subscription aborts. - source_remote.abort(Error::Dropped).unwrap(); - settle().await; - settle().await; - sub.assert_closed(); - dynamic_local.assert_no_request(); - - // A fresh consumer request asks the standby anew, which has the track now. - let retry = broadcast.track("audio").unwrap().subscribe(None); - let mut producer_local = accept_track(&mut dynamic_local, "audio").await; - settle().await; - let mut sub = retry.await.expect("a fresh request must reach the standby"); - producer_local.create_group(group::Info { sequence: 2 }).unwrap(); - assert_eq!(sub.assert_group().sequence, 2); - } - - /// A refused track aborts, but the verdict is not cached: it belongs to the - /// request that received it, so a later request re-asks the source. Otherwise - /// one early request for a track the publisher had not created yet leaves the - /// name dead for the life of the front. - #[tokio::test] - async fn test_unservable_track_retried_by_a_later_request() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let source = origin.create_broadcast("test", announce()).unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - - // Nothing serves it: the refusal aborts the track with the source's error. - let subscribing = broadcast.track("audio").unwrap().subscribe(None); - let request = dynamic.requested_track().await.unwrap(); - request.reject(Error::NotFound); - settle().await; - assert!(matches!(subscribing.await, Err(Error::NotFound))); - - // The publisher has the track now; a fresh request must reach it. - let retry = broadcast.track("audio").unwrap().subscribe(None); - let mut producer = accept_track(&mut dynamic, "audio").await; - settle().await; - let mut sub = retry.await.expect("a fresh request must reach the source"); - producer.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 0); - } - - /// A copy that dies before delivering anything is a refusal, not a failover: - /// a source whose track keeps dying right after acceptance must not - /// re-splice forever. With every attached source refused, the track aborts - /// with the copy's error, and the verdict belongs to that request: a fresh - /// consumer request asks again. - #[tokio::test] - async fn test_track_dying_without_progress_aborts() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let hops = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let source = origin.create_broadcast("test", announce().with_hops(hops)).unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let producer = accept_track(&mut dynamic, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - - // The copy dies without delivering a single group, from a source that is - // alive and well: that's its answer for the track, not a failover. - drop(producer); - settle().await; - sub.assert_closed(); - dynamic.assert_no_request(); - - // A fresh request asks the (still attached) source anew. - let retry = broadcast.track("video").unwrap().subscribe(None); - let mut producer = accept_track(&mut dynamic, "video").await; - settle().await; - let mut sub = retry.await.expect("a fresh request must reach the source"); - producer.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 0); - } - - /// A copy that delivered and later died is a failover even when unrelated - /// wakes happened between its last group and its death: progress is tracked - /// per splice, so a demand edge must not launder it into a zero-progress - /// refusal that aborts the only route. - #[tokio::test] - async fn test_delivered_copy_death_survives_unrelated_wakes() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let hops = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let source = origin.create_broadcast("test", announce().with_hops(hops)).unwrap(); - let mut dynamic = source.dynamic(); - settle().await; - settle().await; - let broadcast = consumer.request_broadcast("test").await.unwrap(); - - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer = accept_track(&mut dynamic, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - producer.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 0); - - // Unrelated demand-edge wakes after the copy's last group: the reader - // leaves and a new one arrives. - drop(sub); - settle().await; - let resubscribing = broadcast.track("video").unwrap().subscribe(None); - settle().await; - let mut sub = resubscribing.await.unwrap(); - assert_eq!(sub.assert_group().sequence, 0, "cached group re-served"); - - // The copy then dies having delivered: failover, so the source is - // re-asked and the subscription resumes. - drop(producer); - let mut producer = accept_track(&mut dynamic, "video").await; - settle().await; - producer.create_group(group::Info { sequence: 1 }).unwrap(); - assert_eq!(sub.assert_group().sequence, 1); - sub.assert_not_closed(); - } - - /// The front picks a source per track and re-picks on failover, so a route - /// tainted for a peer is one the front may serve them from even when the - /// active route is clean. Sharing the front therefore has to check the whole - /// table, not just the active route: here the clean route is active but cannot - /// carry the track, and the fallback is the peer's own route. - #[tokio::test] - async fn test_per_track_fallback_respects_exclusion() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let publisher = Hop::new(1).unwrap(); - let peer = Hop::new(5).unwrap(); - let via_peer = Hops::try_from(vec![publisher, peer]).unwrap(); - let local = Hops::try_from(vec![publisher]).unwrap(); - - // The route through the peer has the track. - let source_tainted = origin - .create_broadcast("test", announce().with_hops(via_peer).with_cost(2)) - .unwrap(); - let mut dynamic_tainted = source_tainted.dynamic(); - settle().await; - settle().await; - - // The clean route is cheaper, so it is active, but its publisher has not - // created the track yet. - let source_clean = origin.create_broadcast("test", announce().with_hops(local)).unwrap(); - let mut dynamic_clean = source_clean.dynamic(); - settle().await; - - let scoped = consumer.clone().excluding(peer); - let broadcast = scoped.request_broadcast("test").await.unwrap(); - let _subscribing = broadcast.track("video").unwrap().subscribe(None); - settle().await; - - // The peer is pinned to the clean source, so the fallback the front would - // take for everyone else is not reachable from their subscription: the - // refusal aborts the track rather than asking the tainted route. - let request = dynamic_clean.requested_track().await.unwrap(); - request.reject(Error::NotFound); - settle().await; - dynamic_tainted.assert_no_request(); - } - - /// The same guarantee under failover: the peer resolves while a clean route is - /// active, then that route dies. Its subscription must not migrate onto the - /// route that flows back through it. - #[tokio::test] - async fn test_exclusion_survives_failover_onto_a_tainted_route() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let publisher = Hop::new(1).unwrap(); - let peer = Hop::new(5).unwrap(); - let via_peer = Hops::try_from(vec![publisher, peer]).unwrap(); - let local = Hops::try_from(vec![publisher]).unwrap(); - - let source_tainted = origin - .create_broadcast("test", announce().with_hops(via_peer).with_cost(2)) - .unwrap(); - let mut dynamic_tainted = source_tainted.dynamic(); - settle().await; - settle().await; - let source_clean = origin.create_broadcast("test", announce().with_hops(local)).unwrap(); - let mut dynamic_clean = source_clean.dynamic(); - settle().await; - - let scoped = consumer.clone().excluding(peer); - let broadcast = scoped.request_broadcast("test").await.unwrap(); - let _subscribing = broadcast.track("video").unwrap().subscribe(None); - let _clean = accept_track(&mut dynamic_clean, "video").await; - settle().await; - - // The clean route dies, so the front's only remaining route is the peer's. - source_clean.abort(Error::Dropped).unwrap(); - settle().await; - settle().await; - dynamic_tainted.assert_no_request(); - - // A fresh request now has nowhere clean to go, and says so rather than - // silently serving the peer their own route. - assert!(matches!(scoped.request_broadcast("test").await, Err(Error::Unroutable))); - } - - /// The resolve-time check only proves the table is clean for a peer at that - /// instant. A route through them attaching *afterwards* must not be adopted - /// underneath their live subscription: they hold the shared front, so the front - /// stays off that route while a clean one remains. - #[tokio::test] - async fn test_exclusion_holds_when_a_tainted_route_attaches_later() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let publisher = Hop::new(1).unwrap(); - let peer = Hop::new(5).unwrap(); - let local = Hops::try_from(vec![publisher]).unwrap(); - let via_peer = Hops::try_from(vec![publisher, peer]).unwrap(); - - // Only a clean route exists, so the peer legitimately gets the shared front. - // Priced above the route that arrives later, so the front genuinely prefers - // that one and staying put is the guard's doing, not the tie-break's. - let source_clean = origin - .create_broadcast("test", announce().with_hops(local).with_cost(5)) - .unwrap(); - let mut dynamic_clean = source_clean.dynamic(); - settle().await; - settle().await; - let scoped = consumer.clone().excluding(peer); - let broadcast = scoped.request_broadcast("test").await.unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer_clean = accept_track(&mut dynamic_clean, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - producer_clean.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 0); - - // A cheaper route back through the peer attaches. Without the registration - // the front would re-splice onto it and hand the peer its own bytes. - // `advertised` non-zero says the announcing relay is not itself carrying, which - // keeps the simultaneous-activation handover gate (whose key comparison is - // hash-random) out of this test: the front takes the cheaper route outright - // unless the exclusion stops it. - let mut tainted = announce().with_hops(via_peer.clone()).with_cost(0); - tainted.advertised = broadcast::Cost::new(1); - let mut source_tainted = origin.create_broadcast("test", tainted).unwrap(); - let mut dynamic_tainted = source_tainted.dynamic(); - settle().await; - settle().await; - dynamic_tainted.assert_no_request(); - producer_clean.append_group().unwrap(); - assert_eq!(sub.assert_group().sequence, 1); - sub.assert_not_closed(); - - // The registration ends with the last handle. The next table change is free - // to take the cheaper route, which is what proves it was released. - drop(sub); - drop(broadcast); - drop(scoped); - settle().await; - let mut bumped = announce().with_hops(via_peer).with_cost(1); - bumped.advertised = broadcast::Cost::new(1); - source_tainted.set_route(bumped).unwrap(); - settle().await; - settle_handover().await; - let plain = consumer.request_broadcast("test").await.unwrap(); - let _plain_track = plain.track("video").unwrap().subscribe(None); - settle().await; - settle().await; - assert!( - dynamic_tainted.requested_track().now_or_never().is_some(), - "the front must be free to use the route again once the peer is gone" - ); - } - - /// An announced path every route of which loops through the requester is - /// unroutable, not missing: the dynamic handler resolves paths with no route - /// chain to check, so consulting it would route around the split horizon. - #[tokio::test] - async fn test_excluded_path_never_reaches_the_dynamic_handler() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut dynamic = origin.dynamic(); - - let peer = Hop::new(5).unwrap(); - let tainted = Hops::try_from(vec![Hop::new(1).unwrap(), peer]).unwrap(); - let _source = origin.create_broadcast("test", announce().with_hops(tainted)).unwrap(); - settle().await; - settle().await; - - let scoped = consumer.clone().excluding(peer); - assert!(matches!(scoped.request_broadcast("test").await, Err(Error::Unroutable))); - assert!( - dynamic.requested_broadcast().now_or_never().is_none(), - "the dynamic handler was asked to route around the exclusion" - ); - - // An unannounced path still reaches the handler, exclusion or not. - let _pending = scoped.request_broadcast("other"); - settle().await; - assert!( - dynamic.requested_broadcast().now_or_never().is_some(), - "a genuinely missing path must still fall back" - ); - } - - /// A dynamic handler may serve a broadcast that was never created at the requested - /// path, so the requester's handle is named by what it asked for rather than by - /// whatever the producer was stamped with. A standalone broadcast (path `""`) served - /// at `a/pub` would otherwise be its own root, and a legal `../source` reference in - /// its catalog would read as escaping. - #[tokio::test] - async fn test_dynamic_broadcast_named_by_the_requested_path() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let mut dynamic = origin.dynamic(); - - // A standalone broadcast, with no origin and no path of its own. - let mut standalone = broadcast::Info::new().produce(); - let _track = standalone.create_track("catalog.json", None).unwrap(); - assert_eq!(standalone.info().path.as_str(), ""); - - let requesting = origin.consume().request_broadcast("a/pub"); - settle().await; - dynamic - .requested_broadcast() - .await - .expect("handler should be asked for the path") - .accept(&standalone); - - let broadcast = requesting.await.expect("the handler served it"); - assert_eq!(broadcast.info().path.as_str(), "a/pub"); - // The stamp reaches the tracks, which is what a catalog reader resolves against. - let track = broadcast.track("catalog.json").unwrap(); - assert_eq!(track.broadcast().path.as_str(), "a/pub"); - assert_eq!(track.subscribe(None).await.unwrap().broadcast().path.as_str(), "a/pub"); - - // A repeat request shares the served broadcast and is named the same way. - let cached = origin.consume().request_broadcast("a/pub").await.unwrap(); - assert_eq!(cached.info().path.as_str(), "a/pub"); - - // The handler's own handle keeps the broadcast's own (empty) name. - assert_eq!(standalone.consume().info().path.as_str(), ""); - } - - /// A rooted cursor names a broadcast relative to its own root, both when it requests - /// one by path and when it observes an announce. That is the only name it can - /// resolve against, so a catalog reference is bounds-checked against exactly the - /// subtree the cursor may reach rather than the origin's wider root. - #[tokio::test] - async fn test_rooted_cursor_names_broadcasts_relatively() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let _source = origin.create_broadcast("a/pub", announce()).unwrap(); - settle().await; - settle().await; - - // The origin stamps the absolute path at creation. - let absolute = origin.consume().request_broadcast("a/pub").await.unwrap(); - assert_eq!(absolute.info().path.as_str(), "a/pub"); - - let rooted = origin.consume().with_root("a").unwrap(); - assert_eq!( - rooted.request_broadcast("pub").await.unwrap().info().path.as_str(), - "pub" - ); - - let update = rooted.announced().next().await.unwrap(); - assert_eq!(update.path.as_str(), "pub"); - assert_eq!(update.broadcast.unwrap().info().path.as_str(), "pub"); - } - - /// When every route flows through the requester, the path is unroutable for - /// them: serving it would hand them their own bytes back. - #[tokio::test] - async fn test_dispatch_all_tainted_unroutable() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - - let peer = Hop::new(5).unwrap(); - let tainted = Hops::try_from(vec![Hop::new(1).unwrap(), peer]).unwrap(); - let _source = origin.create_broadcast("test", announce().with_hops(tainted)).unwrap(); - settle().await; - settle().await; - - let scoped = consumer.clone().excluding(peer); - match scoped.request_broadcast("test").await { - Err(Error::Unroutable) => {} - Err(err) => panic!("expected Unroutable, got {err:?}"), - Ok(_) => panic!("expected Unroutable, got a broadcast"), - } - - // Everyone else still resolves the shared front. - consumer.request_broadcast("test").await.unwrap(); - } - - #[tokio::test] - async fn test_duplicate_reverse() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - - let mut broadcast1 = origin.create_broadcast("test", announce()).unwrap(); - let mut broadcast2 = origin.create_broadcast("test", announce()).unwrap(); - settle().await; - assert!(origin.consume().get_broadcast("test").is_some()); - - // This is harder, finishing the newer source first. - broadcast2.finish(); - settle().await; - assert!(origin.consume().get_broadcast("test").is_some()); - - broadcast1.finish(); - settle().await; - assert!(origin.consume().get_broadcast("test").is_none()); - } - - #[tokio::test] - async fn test_deterministic_tiebreak() { - tokio::time::pause(); - - fn hops(ids: &[u64]) -> Hops { - Hops::try_from(ids.iter().copied().map(|id| Hop::new(id).unwrap()).collect::>()).unwrap() - } - - // Resolve the advertised route for "test" after creating both sources in - // the given order. - async fn winner(first: &[u64], second: &[u64]) -> Hops { - let origin = Hop::random().produce(); - // Equal-cost forwarders: the ordering is what this test is about, so neither - // route is a warm sibling and the adoption hold-down never applies. - let _a = origin - .create_broadcast("test", forwarder_route(hops(first), 1)) - .unwrap(); - let _b = origin - .create_broadcast("test", forwarder_route(hops(second), 1)) - .unwrap(); - settle().await; - settle_handover().await; - origin.consume().get_broadcast("test").unwrap().route().hops - } - - // Two routes with equal hop counts but distinct chains (sharing the first - // hop, so both may attach). The winner is decided by the deterministic - // key, not arrival order, so both publish orders converge. - let forward = winner(&[5, 20], &[5, 40]).await; - let reverse = winner(&[5, 40], &[5, 20]).await; - assert_eq!(forward, reverse, "tie-break must not depend on publish order"); - - // A strictly shorter chain always wins regardless of the hash. - assert_eq!(winner(&[5, 20], &[5]).await.len(), 1); - assert_eq!(winner(&[5], &[5, 20]).await.len(), 1); - } - - // A previous mpsc-based implementation could only deliver the first 127 broadcasts - // instantly via `assert_next` (which uses `now_or_never`). The kio-backed - // implementation polls synchronously and can deliver all of them without yielding. - // Names are zero-padded so lexicographic delivery order matches the loop index. - #[tokio::test] - async fn test_many_announces() { - let origin = Hop::random().produce(); - - let mut consumer = origin.consume().announced(); - // Held for the duration: a dropped source unannounces immediately. - let mut broadcasts = Vec::new(); - for i in 0..256 { - broadcasts.push(origin.create_broadcast(format!("test{i:03}"), announce()).unwrap()); - settle().await; - } - - for i in 0..256 { - consumer.assert_next_some(format!("test{i:03}")); - } - consumer.assert_next_wait(); - } - - #[tokio::test] - async fn test_many_announces_try() { - let origin = Hop::random().produce(); - - let mut consumer = origin.consume().announced(); - // Held for the duration: a dropped source unannounces immediately. - let mut broadcasts = Vec::new(); - for i in 0..256 { - broadcasts.push(origin.create_broadcast(format!("test{i:03}"), announce()).unwrap()); - settle().await; - } - - for i in 0..256 { - consumer.assert_try_next_some(format!("test{i:03}")); - } - } - - #[tokio::test] - async fn test_with_root_basic() { - let origin = Hop::random().produce(); - - // Create a producer with root "/foo" - let foo_producer = origin.with_root("foo").expect("should create root"); - assert_eq!(foo_producer.root().as_str(), "foo"); - - let mut consumer = origin.consume().announced(); - - // When publishing to "bar/baz", it should actually publish to "foo/bar/baz" - let _broadcast = foo_producer - .create_broadcast("bar/baz", announce()) - .expect("publish allowed"); - settle().await; - // The original consumer should see the full path - consumer.assert_next_some("foo/bar/baz"); - - // A consumer created from the rooted producer should see the stripped path - let mut foo_consumer = foo_producer.consume().announced(); - foo_consumer.assert_next_some("bar/baz"); - } - - #[tokio::test] - async fn test_with_root_nested() { - let origin = Hop::random().produce(); - - // Create nested roots - let foo_producer = origin.with_root("foo").expect("should create foo root"); - let foo_bar_producer = foo_producer.with_root("bar").expect("should create bar root"); - assert_eq!(foo_bar_producer.root().as_str(), "foo/bar"); - - let mut consumer = origin.consume().announced(); - - // Publishing to "baz" should actually publish to "foo/bar/baz" - let _broadcast = foo_bar_producer - .create_broadcast("baz", announce()) - .expect("publish allowed"); - settle().await; - // The original consumer sees the full path - consumer.assert_next_some("foo/bar/baz"); - - // Consumer from foo_bar_producer sees just "baz" - let mut foo_bar_consumer = foo_bar_producer.consume().announced(); - foo_bar_consumer.assert_next_some("baz"); - } - - #[tokio::test] - async fn test_publish_scope_allows() { - let origin = Hop::random().produce(); - - // Create a producer that can only publish to "allowed" paths - let limited_producer = origin - .scope(&["allowed/path1".into(), "allowed/path2".into()]) - .expect("should create limited producer"); - - // Should be able to publish to allowed paths - let _broadcast = limited_producer - .create_broadcast("allowed/path1", announce()) - .expect("publish allowed"); - let _keep2 = limited_producer - .create_broadcast("allowed/path1/nested", announce()) - .expect("publish allowed"); - let _keep3 = limited_producer - .create_broadcast("allowed/path2", announce()) - .expect("publish allowed"); - settle().await; - - // Should not be able to publish to disallowed paths - assert!(limited_producer.create_broadcast("notallowed", announce()).is_err()); - assert!(limited_producer.create_broadcast("allowed", announce()).is_err()); // Parent of allowed path - assert!(limited_producer.create_broadcast("other/path", announce()).is_err()); - } - - #[tokio::test] - async fn test_publish_max_parts() { - let origin = Hop::random().produce(); - - let at_limit = (0..Path::MAX_PARTS) - .map(|i| i.to_string()) - .collect::>() - .join("/"); - let _broadcast = origin - .create_broadcast(at_limit.as_str(), announce()) - .expect("publish allowed"); - settle().await; - - let too_deep = format!("{at_limit}/extra"); - assert!(origin.create_broadcast(too_deep.as_str(), announce()).is_err()); - - // The root counts toward the limit; a joined path past 32 parts is rejected. - let rooted = origin.with_root("root").expect("wildcard allows any root"); - assert!(rooted.create_broadcast(at_limit.as_str(), announce()).is_err()); - } - - #[tokio::test] - async fn test_publish_scope_empty() { - let origin = Hop::random().produce(); - - // Creating a producer with no allowed paths should return None - assert!(origin.scope(&[]).is_none()); - } - - #[tokio::test] - async fn test_consume_scope_filters() { - let origin = Hop::random().produce(); - - let mut consumer = origin.consume().announced(); - - // Publish to different paths - let _broadcast1 = origin.create_broadcast("allowed", announce()).unwrap(); - let _broadcast2 = origin.create_broadcast("allowed/nested", announce()).unwrap(); - let _broadcast3 = origin.create_broadcast("notallowed", announce()).unwrap(); - settle().await; - - // Create a consumer that only sees "allowed" paths - let mut limited_consumer = origin - .consume() - .scope(&["allowed".into()]) - .expect("should create limited consumer") - .announced(); - - // Should only receive broadcasts under "allowed" - limited_consumer.assert_next_some("allowed"); - limited_consumer.assert_next_some("allowed/nested"); - limited_consumer.assert_next_wait(); // Should not see "notallowed" - - // Unscoped consumer should see all - consumer.assert_next_some("allowed"); - consumer.assert_next_some("allowed/nested"); - consumer.assert_next_some("notallowed"); - } - - #[tokio::test] - async fn test_consume_scope_multiple_prefixes() { - let origin = Hop::random().produce(); - - let _broadcast1 = origin.create_broadcast("foo/test", announce()).unwrap(); - let _broadcast2 = origin.create_broadcast("bar/test", announce()).unwrap(); - let _broadcast3 = origin.create_broadcast("baz/test", announce()).unwrap(); - settle().await; - - // Consumer that only sees "foo" and "bar" paths - let mut limited_consumer = origin - .consume() - .scope(&["foo".into(), "bar".into()]) - .expect("should create limited consumer") - .announced(); - - // Order depends on PathPrefixes canonical sort (lexicographic for same length) - limited_consumer.assert_next_some("bar/test"); - limited_consumer.assert_next_some("foo/test"); - limited_consumer.assert_next_wait(); // Should not see "baz/test" - } - - #[tokio::test] - async fn test_with_root_and_publish_scope() { - let origin = Hop::random().produce(); - - // User connects to /foo root - let foo_producer = origin.with_root("foo").expect("should create foo root"); - - // Limit them to publish only to "bar" and "goop/pee" within /foo - let limited_producer = foo_producer - .scope(&["bar".into(), "goop/pee".into()]) - .expect("should create limited producer"); - - let mut consumer = origin.consume().announced(); - - // Should be able to publish to foo/bar and foo/goop/pee (but user sees as bar and goop/pee) - let _broadcast = limited_producer - .create_broadcast("bar", announce()) - .expect("publish allowed"); - let _keep2 = limited_producer - .create_broadcast("bar/nested", announce()) - .expect("publish allowed"); - let _keep3 = limited_producer - .create_broadcast("goop/pee", announce()) - .expect("publish allowed"); - let _keep4 = limited_producer - .create_broadcast("goop/pee/nested", announce()) - .expect("publish allowed"); - settle().await; - - // Should not be able to publish outside allowed paths - assert!(limited_producer.create_broadcast("baz", announce()).is_err()); - assert!(limited_producer.create_broadcast("goop", announce()).is_err()); // Parent of allowed - assert!(limited_producer.create_broadcast("goop/other", announce()).is_err()); - - // Original consumer sees full paths - consumer.assert_next_some("foo/bar"); - consumer.assert_next_some("foo/bar/nested"); - consumer.assert_next_some("foo/goop/pee"); - consumer.assert_next_some("foo/goop/pee/nested"); - } - - #[tokio::test] - async fn test_with_root_and_consume_scope() { - let origin = Hop::random().produce(); - - // Publish broadcasts - let _broadcast1 = origin.create_broadcast("foo/bar/test", announce()).unwrap(); - let _broadcast2 = origin.create_broadcast("foo/goop/pee/test", announce()).unwrap(); - let _broadcast3 = origin.create_broadcast("foo/other/test", announce()).unwrap(); - settle().await; - - // User connects to /foo root - let foo_producer = origin.with_root("foo").expect("should create foo root"); - - // Create consumer limited to "bar" and "goop/pee" within /foo - let mut limited_consumer = foo_producer - .consume() - .scope(&["bar".into(), "goop/pee".into()]) - .expect("should create limited consumer") - .announced(); - - // Should only see allowed paths (without foo prefix) - limited_consumer.assert_next_some("bar/test"); - limited_consumer.assert_next_some("goop/pee/test"); - limited_consumer.assert_next_wait(); // Should not see "other/test" - } - - #[tokio::test] - async fn test_with_root_unauthorized() { - let origin = Hop::random().produce(); - - // First limit the producer to specific paths - let limited_producer = origin - .scope(&["allowed".into()]) - .expect("should create limited producer"); - - // Trying to create a root outside allowed paths should fail - assert!(limited_producer.with_root("notallowed").is_none()); - - // But creating a root within allowed paths should work - let allowed_root = limited_producer - .with_root("allowed") - .expect("should create allowed root"); - assert_eq!(allowed_root.root().as_str(), "allowed"); - } - - #[tokio::test] - async fn test_wildcard_permission() { - let origin = Hop::random().produce(); - - // Producer with root access (empty string means wildcard) - let root_producer = origin.clone(); - - // Should be able to publish anywhere - let _broadcast = root_producer - .create_broadcast("any/path", announce()) - .expect("publish allowed"); - let _keep2 = root_producer - .create_broadcast("other/path", announce()) - .expect("publish allowed"); - settle().await; - - // Can create any root - let foo_producer = root_producer.with_root("foo").expect("should create any root"); - assert_eq!(foo_producer.root().as_str(), "foo"); - } - - #[tokio::test] - async fn test_consume_broadcast_with_permissions() { - let origin = Hop::random().produce(); - - let _broadcast1 = origin.create_broadcast("allowed/test", announce()).unwrap(); - let _broadcast2 = origin.create_broadcast("notallowed/test", announce()).unwrap(); - settle().await; - - // Create limited consumer - let limited_consumer = origin - .consume() - .scope(&["allowed".into()]) - .expect("should create limited consumer"); - - // Should be able to get allowed broadcast - let result = limited_consumer.get_broadcast("allowed/test"); - assert!(result.is_some()); - assert!( - result - .unwrap() - .is_clone(&origin.consume().get_broadcast("allowed/test").unwrap()) - ); - - // Should not be able to get disallowed broadcast - assert!(limited_consumer.get_broadcast("notallowed/test").is_none()); - - // Original consumer can get both - let consumer = origin.consume(); - assert!(consumer.get_broadcast("allowed/test").is_some()); - assert!(consumer.get_broadcast("notallowed/test").is_some()); - } - - #[tokio::test] - async fn test_nested_paths_with_permissions() { - let origin = Hop::random().produce(); - - // Create producer limited to "a/b/c" - let limited_producer = origin.scope(&["a/b/c".into()]).expect("should create limited producer"); - - // Should be able to publish to exact path and nested paths - let _broadcast = limited_producer - .create_broadcast("a/b/c", announce()) - .expect("publish allowed"); - let _keep2 = limited_producer - .create_broadcast("a/b/c/d", announce()) - .expect("publish allowed"); - let _keep3 = limited_producer - .create_broadcast("a/b/c/d/e", announce()) - .expect("publish allowed"); - settle().await; - - // Should not be able to publish to parent or sibling paths - assert!(limited_producer.create_broadcast("a", announce()).is_err()); - assert!(limited_producer.create_broadcast("a/b", announce()).is_err()); - assert!(limited_producer.create_broadcast("a/b/other", announce()).is_err()); - } - - #[tokio::test] - async fn test_multiple_consumers_with_different_permissions() { - let origin = Hop::random().produce(); - - // Publish to different paths - let _broadcast1 = origin.create_broadcast("foo/test", announce()).unwrap(); - let _broadcast2 = origin.create_broadcast("bar/test", announce()).unwrap(); - let _broadcast3 = origin.create_broadcast("baz/test", announce()).unwrap(); - settle().await; - - // Create consumers with different permissions - let mut foo_consumer = origin - .consume() - .scope(&["foo".into()]) - .expect("should create foo consumer") - .announced(); - - let mut bar_consumer = origin - .consume() - .scope(&["bar".into()]) - .expect("should create bar consumer") - .announced(); - - let mut foobar_consumer = origin - .consume() - .scope(&["foo".into(), "bar".into()]) - .expect("should create foobar consumer") - .announced(); - - // Each consumer should only see their allowed paths - foo_consumer.assert_next_some("foo/test"); - foo_consumer.assert_next_wait(); - - bar_consumer.assert_next_some("bar/test"); - bar_consumer.assert_next_wait(); - - foobar_consumer.assert_next_some("bar/test"); - foobar_consumer.assert_next_some("foo/test"); - foobar_consumer.assert_next_wait(); - } - - #[tokio::test] - async fn test_select_with_empty_prefix() { - let origin = Hop::random().produce(); - - // User with root "demo" allowed to subscribe to "worm-node" and "foobar" - let demo_producer = origin.with_root("demo").expect("should create demo root"); - let limited_producer = demo_producer - .scope(&["worm-node".into(), "foobar".into()]) - .expect("should create limited producer"); - - // Publish some broadcasts - let _broadcast1 = limited_producer - .create_broadcast("worm-node/test", announce()) - .expect("publish allowed"); - let _broadcast2 = limited_producer - .create_broadcast("foobar/test", announce()) - .expect("publish allowed"); - settle().await; - - // scope with empty prefix should keep the exact same "worm-node" and "foobar" nodes - let mut consumer = limited_producer - .consume() - .scope(&["".into()]) - .expect("should create consumer with empty prefix") - .announced(); - - // Should see both broadcasts (order depends on PathPrefixes sort) - let a1 = consumer.try_next().expect("expected first announcement"); - let a2 = consumer.try_next().expect("expected second announcement"); - consumer.assert_next_wait(); - - let mut paths: Vec<_> = [&a1, &a2].iter().map(|a| a.path.to_string()).collect(); - paths.sort(); - assert_eq!(paths, ["foobar/test", "worm-node/test"]); - } - - #[tokio::test] - async fn test_select_narrowing_scope() { - let origin = Hop::random().produce(); - - // User with root "demo" allowed to subscribe to "worm-node" and "foobar" - let demo_producer = origin.with_root("demo").expect("should create demo root"); - let limited_producer = demo_producer - .scope(&["worm-node".into(), "foobar".into()]) - .expect("should create limited producer"); - - // Publish broadcasts at different levels - let _broadcast1 = limited_producer - .create_broadcast("worm-node", announce()) - .expect("publish allowed"); - let _broadcast2 = limited_producer - .create_broadcast("worm-node/foo", announce()) - .expect("publish allowed"); - let _broadcast3 = limited_producer - .create_broadcast("foobar/bar", announce()) - .expect("publish allowed"); - settle().await; - - // Test 1: scope("worm-node") should result in a single "" node with contents of "worm-node" ONLY - let mut worm_consumer = limited_producer - .consume() - .scope(&["worm-node".into()]) - .expect("should create worm-node consumer") - .announced(); - - // Should see worm-node content with paths stripped to "" - worm_consumer.assert_next_some("worm-node"); - worm_consumer.assert_next_some("worm-node/foo"); - worm_consumer.assert_next_wait(); // Should NOT see foobar content - - // Test 2: scope("worm-node/foo") should result in a "" node with contents of "worm-node/foo" - let mut foo_consumer = limited_producer - .consume() - .scope(&["worm-node/foo".into()]) - .expect("should create worm-node/foo consumer") - .announced(); - - foo_consumer.assert_next_some("worm-node/foo"); - foo_consumer.assert_next_wait(); // Should NOT see other content + // Losing the last retracts. + drop(expensive); + announced.assert_next_ended("room"); } #[tokio::test] - async fn test_select_multiple_roots_with_empty_prefix() { - let origin = Hop::random().produce(); - - // Producer with multiple allowed roots - let limited_producer = origin - .scope(&["app1".into(), "app2".into(), "shared".into()]) - .expect("should create limited producer"); - - // Publish to each root - let _broadcast1 = limited_producer - .create_broadcast("app1/data", announce()) - .expect("publish allowed"); - let _broadcast2 = limited_producer - .create_broadcast("app2/config", announce()) - .expect("publish allowed"); - let _broadcast3 = limited_producer - .create_broadcast("shared/resource", announce()) - .expect("publish allowed"); - settle().await; - - // scope with empty prefix should maintain all roots - let mut consumer = limited_producer - .consume() - .scope(&["".into()]) - .expect("should create consumer with empty prefix") - .announced(); + async fn identical_reannounce_is_invisible() { + let producer = origin(1).produce(); + let mut announced = producer.consume().announced(); - // Should see all broadcasts from all roots - consumer.assert_next_some("app1/data"); - consumer.assert_next_some("app2/config"); - consumer.assert_next_some("shared/resource"); - consumer.assert_next_wait(); - } + let old = producer + .announce("room", Route::default().with_hops(hops(&[10]))) + .unwrap(); + let first = announced.assert_next_active("room"); + assert_eq!(first.hops.as_slice(), hops(&[10]).as_slice()); + + // An identical route from a fresh announcement (a reconnect) changes + // nothing a consumer could act on, so nothing is delivered; new requests + // still prefer the newest entry. + let _new = producer + .announce("room", Route::default().with_hops(hops(&[10]))) + .unwrap(); + announced.assert_next_wait(); - #[tokio::test] - async fn test_publish_scope_with_empty_prefix() { - let origin = Hop::random().produce(); - - // Producer with specific allowed paths - let limited_producer = origin - .scope(&["services/api".into(), "services/web".into()]) - .expect("should create limited producer"); - - // scope with empty prefix should keep the same restrictions - let same_producer = limited_producer - .scope(&["".into()]) - .expect("should create producer with empty prefix"); - - // Should still have the same publishing restrictions - let _broadcast = same_producer - .create_broadcast("services/api", announce()) - .expect("publish allowed"); - let _keep2 = same_producer - .create_broadcast("services/web", announce()) - .expect("publish allowed"); - assert!(same_producer.create_broadcast("services/db", announce()).is_err()); - assert!(same_producer.create_broadcast("other", announce()).is_err()); + // Retracting the stale twin leaves the fresh one standing, still quietly. + drop(old); + announced.assert_next_wait(); } #[tokio::test] - async fn test_select_narrowing_to_deeper_path() { - let origin = Hop::random().produce(); - - // Producer with broad permission - let limited_producer = origin.scope(&["org".into()]).expect("should create limited producer"); - - // Publish at various depths - let _broadcast1 = limited_producer - .create_broadcast("org/team1/project1", announce()) - .expect("publish allowed"); - let _broadcast2 = limited_producer - .create_broadcast("org/team1/project2", announce()) - .expect("publish allowed"); - let _broadcast3 = limited_producer - .create_broadcast("org/team2/project1", announce()) - .expect("publish allowed"); - settle().await; - - // Narrow down to team2 only - let mut team2_consumer = limited_producer - .consume() - .scope(&["org/team2".into()]) - .expect("should create team2 consumer") - .announced(); - - team2_consumer.assert_next_some("org/team2/project1"); - team2_consumer.assert_next_wait(); // Should NOT see team1 content + async fn exclude_hides_routes_through_the_peer() { + let producer = origin(1).produce(); + let _a = producer + .announce("room", Route::default().with_hops(hops(&[7]))) + .unwrap(); - // Further narrow down to team1/project1 - let mut project1_consumer = limited_producer - .consume() - .scope(&["org/team1/project1".into()]) - .expect("should create project1 consumer") - .announced(); + let mut hidden = producer.consume().excluding(origin(7)).announced(); + hidden.assert_next_wait(); - // Should only see project1 content at root - project1_consumer.assert_next_some("org/team1/project1"); - project1_consumer.assert_next_wait(); + let mut visible = producer.consume().excluding(origin(8)).announced(); + visible.assert_next_active("room"); } #[tokio::test] - async fn test_select_with_non_matching_prefix() { - let origin = Hop::random().produce(); - - // Producer with specific allowed paths - let limited_producer = origin - .scope(&["allowed/path".into()]) - .expect("should create limited producer"); + async fn update_reprices_in_place() { + let producer = origin(1).produce(); + let mut announced = producer.consume().announced(); - // Trying to scope with a completely different prefix should return None - assert!(limited_producer.consume().scope(&["different/path".into()]).is_none()); + let announcement = producer.announce("room", Route::default()).unwrap(); + announced.assert_next_active("room"); - // Similarly for scope - assert!(limited_producer.scope(&["other/path".into()]).is_none()); + announcement.update(Route::default().with_cost(9)).unwrap(); + let route = announced.assert_next_active("room"); + assert_eq!(route.cost, Cost::new(9)); } - // Regression test for https://github.com/moq-dev/moq/issues/910 - // with_root panics when String has trailing slash (AsPath for String skips normalization) #[tokio::test] - async fn test_with_root_trailing_slash_consumer() { - let origin = Hop::random().produce(); - - // Use an owned String so the trailing slash is NOT normalized away. - let prefix = "some_prefix/".to_string(); - let mut consumer = origin.consume().with_root(prefix).unwrap().announced(); - - let _b = origin.create_broadcast("some_prefix/test", announce()).unwrap(); - settle().await; - consumer.assert_next_some("test"); + async fn retract_after_undelivered_reprice_still_delivered() { + let producer = origin(1).produce(); + let mut announced = producer.consume().announced(); + + let announcement = producer.announce("room", Route::default()).unwrap(); + announced.assert_next_active("room"); + + // Reprice, then retract before the consumer observes the reprice: the + // pending metadata update must not cancel the retraction the delivered + // announce still owes. + announcement.update(Route::default().with_cost(9)).unwrap(); + drop(announcement); + announced.assert_next_ended("room"); + announced.assert_next_wait(); } - // Same issue but for the producer side of with_root #[tokio::test] - async fn test_with_root_trailing_slash_producer() { - let origin = Hop::random().produce(); - - // Use an owned String so the trailing slash is NOT normalized away. - let prefix = "some_prefix/".to_string(); - let rooted = origin.with_root(prefix).unwrap(); - - let _b = rooted.create_broadcast("test", announce()).unwrap(); - settle().await; - - let mut consumer = rooted.consume().announced(); - consumer.assert_next_some("test"); + async fn scoped_cursor_advertises_most_specific_covering_route() { + let producer = origin(1).produce(); + // Broad and cheap; narrow and expensive. Both clamp to a cursor rooted + // below them, and the narrow one is what a request there resolves. + let _broad = producer.announce("room", Route::default().with_cost(1)).unwrap(); + let _narrow = producer.announce("room/alice", Route::default().with_cost(9)).unwrap(); + + let consumer = producer.consume().with_root("room/alice").unwrap(); + let mut announced = consumer.announced(); + let route = announced.assert_next_active(""); + assert_eq!(route.cost, Cost::new(9)); + announced.assert_next_wait(); } - // Verify unannounce also doesn't panic with trailing slash #[tokio::test] - async fn test_with_root_trailing_slash_unannounce() { - tokio::time::pause(); + async fn routed_broadcast_resolves_once_announced() { + let producer = origin(1).produce(); + let consumer = producer.consume(); - let origin = Hop::random().produce(); + // Asking before anything is announced parks instead of failing Unroutable. + let mut resolving = Box::pin(consumer.routed_broadcast("room/alice")); + assert!((&mut resolving).now_or_never().is_none()); - let prefix = "some_prefix/".to_string(); - let mut consumer = origin.consume().with_root(prefix).unwrap().announced(); - - let mut b = origin.create_broadcast("some_prefix/test", announce()).unwrap(); - settle().await; - consumer.assert_next_some("test"); - - // Finish the broadcast to trigger an immediate unannounce. - b.finish(); - settle().await; - - // unannounce also calls strip_prefix(&self.root).unwrap() - consumer.assert_next_none("test"); + let broadcast = producer.create_broadcast("room/alice").unwrap(); + let _announcement = producer.announce("room/alice", Route::default()).unwrap(); + let resolved = resolving + .now_or_never() + .expect("resolves once announced") + .expect("resolves"); + assert_eq!(resolved.info().path.as_str(), "room/alice"); + drop(broadcast); } #[tokio::test] - async fn test_select_maintains_access_with_wider_prefix() { - let origin = Hop::random().produce(); - - // Setup: user with root "demo" allowed to subscribe to specific paths - let demo_producer = origin.with_root("demo").expect("should create demo root"); - let user_producer = demo_producer - .scope(&["worm-node".into(), "foobar".into()]) - .expect("should create user producer"); - - // Publish some data - let _broadcast1 = user_producer - .create_broadcast("worm-node/data", announce()) - .expect("publish allowed"); - let _broadcast2 = user_producer - .create_broadcast("foobar", announce()) - .expect("publish allowed"); - settle().await; - - // Key test: scope with "" should maintain access to allowed roots - let mut consumer = user_producer - .consume() - .scope(&["".into()]) - .expect("scope with empty prefix should not fail when user has specific permissions") - .announced(); - - // Should still receive broadcasts from allowed paths (order not guaranteed) - let a1 = consumer.try_next().expect("expected first announcement"); - let a2 = consumer.try_next().expect("expected second announcement"); - consumer.assert_next_wait(); - - let mut paths: Vec<_> = [&a1, &a2].iter().map(|a| a.path.to_string()).collect(); - paths.sort(); - assert_eq!(paths, ["foobar", "worm-node/data"]); + async fn local_broadcast_resolves_by_exact_path() { + let producer = origin(1).produce(); + let consumer = producer.consume(); - // Also test that we can still narrow the scope - let mut narrow_consumer = user_producer - .consume() - .scope(&["worm-node".into()]) - .expect("should be able to narrow scope to worm-node") - .announced(); + let broadcast = producer.create_broadcast("room/alice").unwrap(); + let resolved = consumer + .request_broadcast("room/alice") + .now_or_never() + .expect("local lookup is synchronous") + .expect("resolves"); + assert_eq!(resolved.info().path.as_str(), "room/alice"); + drop(broadcast); - narrow_consumer.assert_next_some("worm-node/data"); - narrow_consumer.assert_next_wait(); // Should not see foobar + // Nothing covers an unknown path and no handler exists. + let err = consumer + .request_broadcast("room/bob") + .now_or_never() + .expect("unroutable is synchronous") + .err() + .unwrap(); + assert!(matches!(err, Error::Unroutable)); } #[tokio::test] - async fn test_duplicate_prefixes_deduped() { - let origin = Hop::random().produce(); - - // scope with duplicate prefixes should work (deduped internally) - let producer = origin - .scope(&["demo".into(), "demo".into()]) - .expect("should create producer"); - - let _broadcast = producer - .create_broadcast("demo/stream", announce()) - .expect("publish allowed"); - settle().await; - - let mut consumer = producer.consume().announced(); - consumer.assert_next_some("demo/stream"); - consumer.assert_next_wait(); + async fn local_broadcast_is_not_announced() { + let producer = origin(1).produce(); + let mut announced = producer.consume().announced(); + let _broadcast = producer.create_broadcast("room/alice").unwrap(); + announced.assert_next_wait(); } #[tokio::test] - async fn test_overlapping_prefixes_deduped() { - let origin = Hop::random().produce(); - - // "demo" and "demo/foo". "demo/foo" is redundant, only "demo" should remain - let producer = origin - .scope(&["demo".into(), "demo/foo".into()]) - .expect("should create producer"); + async fn served_route_materializes_on_demand() { + let producer = origin(1).produce(); + let consumer = producer.consume(); - // Can still publish under "demo/bar" since "demo" covers everything - let _broadcast = producer - .create_broadcast("demo/bar/stream", announce()) - .expect("publish allowed"); - settle().await; - - let mut consumer = producer.consume().announced(); - consumer.assert_next_some("demo/bar/stream"); - consumer.assert_next_wait(); - } + let (_announcement, mut server) = producer.announce_served("room", Route::default()).unwrap(); - #[tokio::test] - async fn test_overlapping_prefixes_no_duplicate_announcements() { - let origin = Hop::random().produce(); + let pending = consumer.request_broadcast("room/alice"); + let request = match server.poll_requested_broadcast(&kio::Waiter::noop()) { + Poll::Ready(Ok(request)) => request, + _ => panic!("expected a queued request"), + }; + assert_eq!(request.path().as_str(), "room/alice"); - // Both "demo" and "demo/foo" are requested. Should only have one node - let producer = origin - .scope(&["demo".into(), "demo/foo".into()]) - .expect("should create producer"); + let source = broadcast::Info::new().produce(); + request.accept(&source); - let _broadcast = producer - .create_broadcast("demo/foo/stream", announce()) - .expect("publish allowed"); - settle().await; + let resolved = pending.now_or_never().expect("accepted").expect("resolves"); + // The handle is named by what the requester asked for. + assert_eq!(resolved.info().path.as_str(), "room/alice"); - let mut consumer = producer.consume().announced(); - // Should only get ONE announcement (not two from overlapping nodes) - consumer.assert_next_some("demo/foo/stream"); - consumer.assert_next_wait(); + // A repeat request shares the served broadcast instead of re-asking. + let again = consumer + .request_broadcast("room/alice") + .now_or_never() + .expect("cached") + .expect("resolves"); + assert!(again.is_clone(&resolved)); } #[tokio::test] - async fn test_allowed_returns_deduped_prefixes() { - let origin = Hop::random().produce(); - - let producer = origin - .scope(&["demo".into(), "demo/foo".into(), "anon".into()]) - .expect("should create producer"); + async fn served_requests_coalesce() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let (_announcement, mut server) = producer.announce_served("room", Route::default()).unwrap(); - let allowed: Vec<_> = producer.allowed().collect(); - assert_eq!(allowed.len(), 2, "demo/foo should be subsumed by demo"); - } + let first = consumer.request_broadcast("room/alice"); + let second = consumer.request_broadcast("room/alice"); - #[tokio::test] - async fn test_announced_broadcast_already_announced() { - let origin = Hop::random().produce(); + let request = match server.poll_requested_broadcast(&kio::Waiter::noop()) { + Poll::Ready(Ok(request)) => request, + _ => panic!("expected a queued request"), + }; + // Only one request reaches the server. + assert!(server.poll_requested_broadcast(&kio::Waiter::noop()).is_pending()); - let _broadcast = origin.create_broadcast("test", announce()).unwrap(); - settle().await; + let source = broadcast::Info::new().produce(); + request.accept(&source); - let consumer = origin.consume(); - let result = consumer.announced_broadcast("test").await.expect("should find it"); - assert!(result.is_clone(&consumer.get_broadcast("test").unwrap())); + let first = first.now_or_never().expect("accepted").expect("resolves"); + let second = second.now_or_never().expect("accepted").expect("resolves"); + assert!(first.is_clone(&second)); } #[tokio::test] - async fn test_announced_broadcast_delayed() { - tokio::time::pause(); - - let origin = Hop::random().produce(); + async fn retract_rejects_pending_requests() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let (announcement, server) = producer.announce_served("room", Route::default()).unwrap(); - let consumer = origin.consume(); + let pending = consumer.request_broadcast("room/alice"); + drop(announcement); + drop(server); - // Start waiting before it's announced. - let wait = tokio::spawn({ - let consumer = consumer.clone(); - async move { consumer.announced_broadcast("test").await } - }); - - // Give the spawned task a chance to subscribe. - tokio::task::yield_now().await; + let err = pending.now_or_never().expect("rejected").err().unwrap(); + assert!(matches!(err, Error::Unroutable)); - let _broadcast = origin.create_broadcast("test", announce()).unwrap(); - settle().await; - - let result = wait.await.unwrap().expect("should find it"); - assert!(result.is_clone(&consumer.get_broadcast("test").unwrap())); + // With the route gone, later requests are unroutable immediately. + let err = consumer + .request_broadcast("room/alice") + .now_or_never() + .expect("unroutable") + .err() + .unwrap(); + assert!(matches!(err, Error::Unroutable)); } #[tokio::test] - async fn test_announced_broadcast_ignores_unrelated_paths() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - - let consumer = origin.consume(); - - let wait = tokio::spawn({ - let consumer = consumer.clone(); - async move { consumer.announced_broadcast("target").await } - }); - - tokio::task::yield_now().await; - - // Publish an unrelated broadcast first. announced_broadcast should skip it. - let _other = origin.create_broadcast("other", announce()).unwrap(); - settle().await; - tokio::task::yield_now().await; - assert!(!wait.is_finished(), "must not resolve on unrelated path"); + async fn routed_broadcast_survives_serving_route_retraction() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + + // Three identical routes, oldest first: the newest identical route wins + // requests, and swapping between them emits no announce update. + let (_standby, mut standby_server) = producer.announce_served("room", Route::default()).unwrap(); + let (second, second_server) = producer.announce_served("room", Route::default()).unwrap(); + let (incumbent, incumbent_server) = producer.announce_served("room", Route::default()).unwrap(); + + let mut resolving = Box::pin(consumer.routed_broadcast("room/alice")); + assert!((&mut resolving).now_or_never().is_none()); + + // Each incumbent dies with the request still queued on it: the request + // fails Unroutable, and the resolve must retry through the next standby + // instead of parking on an announce update that never comes. Two + // retractions in a row, so the announce stream's initial coverage replay + // cannot paper over the missing retry. + drop(incumbent); + drop(incumbent_server); + assert!((&mut resolving).now_or_never().is_none()); + drop(second); + drop(second_server); + assert!((&mut resolving).now_or_never().is_none()); + + let request = match standby_server.poll_requested_broadcast(&kio::Waiter::noop()) { + Poll::Ready(Ok(request)) => request, + _ => panic!("expected the retry to queue on the standby"), + }; + let source = broadcast::Info::new().produce(); + request.accept(&source); - let _target = origin.create_broadcast("target", announce()).unwrap(); - settle().await; - let result = wait.await.unwrap().expect("should find target"); - assert!(result.is_clone(&consumer.get_broadcast("target").unwrap())); + let resolved = resolving + .now_or_never() + .expect("resolves via the standby") + .expect("resolves"); + assert_eq!(resolved.info().path.as_str(), "room/alice"); } #[tokio::test] - async fn test_announced_broadcast_skips_nested_paths() { - tokio::time::pause(); - - let origin = Hop::random().produce(); - - let consumer = origin.consume(); - - let wait = tokio::spawn({ - let consumer = consumer.clone(); - async move { consumer.announced_broadcast("foo").await } - }); - - tokio::task::yield_now().await; + async fn split_horizon_skips_routes_through_the_requester() { + let producer = origin(1).produce(); + let (_announcement, _server) = producer + .announce_served("room", Route::default().with_hops(hops(&[7]))) + .unwrap(); - // "foo/bar" is under the prefix scope, but it's not the exact path. Skip it. - let _nested = origin.create_broadcast("foo/bar", announce()).unwrap(); - settle().await; - tokio::task::yield_now().await; - assert!(!wait.is_finished(), "must not resolve on a nested path"); + // The requester's own bytes must not be served back to it. + let excluded = producer.consume().excluding(origin(7)); + let err = excluded + .request_broadcast("room/alice") + .now_or_never() + .expect("unroutable") + .err() + .unwrap(); + assert!(matches!(err, Error::Unroutable)); - let _exact = origin.create_broadcast("foo", announce()).unwrap(); - settle().await; - let result = wait.await.unwrap().expect("should find foo exactly"); - assert!(result.is_clone(&consumer.get_broadcast("foo").unwrap())); + // A clean requester resolves through the route (the request queues). + let clean = producer.consume().excluding(origin(8)); + let pending = clean.request_broadcast("room/alice"); + assert!(pending.now_or_never().is_none()); } #[tokio::test] - async fn test_announced_broadcast_disallowed() { - let origin = Hop::random().produce(); - let limited = origin - .consume() - .scope(&["allowed".into()]) - .expect("should create limited"); - - // Path is outside allowed prefixes. Should return None immediately. - assert!(limited.announced_broadcast("notallowed").await.is_none()); - } + async fn most_specific_prefix_shadows() { + let producer = origin(1).produce(); + let consumer = producer.consume(); - #[tokio::test] - async fn test_announced_broadcast_scope_too_narrow() { - // Consumer's scope is narrower than the requested path: asking for `foo` on a consumer - // limited to `foo/specific` can never resolve. Must return None, not loop forever. - let origin = Hop::random().produce(); - let limited = origin - .consume() - .scope(&["foo/specific".into()]) - .expect("should create limited"); + let (_broad, mut broad_server) = producer.announce_served("", Route::default()).unwrap(); + // A narrow advertise-only claim: requests under it must NOT route to the + // broad server; they fall through to the (absent) fallback handler. + let _narrow = producer.announce(".dash", Route::default()).unwrap(); - // now_or_never so we fail fast instead of hanging if the guard regresses. - let result = limited - .announced_broadcast("foo") + let err = consumer + .request_broadcast(".dash/pid") .now_or_never() - .expect("must not block"); - assert!(result.is_none()); - } - - // Coalescing tests: a slow cursor that doesn't drain between updates - // should observe a bounded number of deliveries. - - #[tokio::test] - async fn test_coalesce_announce_then_unannounce() { - // announce + unannounce that the cursor hasn't observed yet collapses to nothing. - tokio::time::pause(); - - let origin = Hop::random().produce(); - let mut announced = origin.consume().announced(); - - let mut broadcast = origin.create_broadcast("test", announce()).unwrap(); - settle().await; - broadcast.finish(); - - settle().await; - - announced.assert_next_wait(); - } + .expect("unroutable") + .err() + .unwrap(); + assert!(matches!(err, Error::Unroutable)); - #[tokio::test] - async fn test_coalesce_announce_unannounce_announce() { - // announce, unannounce, announce that the cursor hasn't drained collapses - // to a single Announce of the latest broadcast. - tokio::time::pause(); - - let origin = Hop::random().produce(); - let mut announced = origin.consume().announced(); - - let mut broadcast1 = origin.create_broadcast("test", announce()).unwrap(); - settle().await; - broadcast1.finish(); - settle().await; - let _broadcast2 = origin.create_broadcast("test", announce()).unwrap(); - settle().await; - - announced.assert_next_some("test"); - announced.assert_next_wait(); + // Everything else still routes to the broad server. + let _pending = consumer.request_broadcast("room/alice"); + assert!(broad_server.poll_requested_broadcast(&kio::Waiter::noop()).is_ready()); } #[tokio::test] - async fn test_coalesce_unannounce_announce_preserved() { - // unannounce followed by announce of a different broadcast must be preserved - // as two deliveries so the cursor learns the origin changed. - tokio::time::pause(); - - let origin = Hop::random().produce(); - let mut broadcast1 = origin.create_broadcast("test", announce()).unwrap(); - settle().await; - - let mut announced = origin.consume().announced(); - announced.assert_next_some("test"); - - // Finish, then publish a fresh broadcast at the same path. - broadcast1.finish(); - settle().await; - - let _broadcast2 = origin.create_broadcast("test", announce()).unwrap(); - settle().await; + async fn dynamic_fallback_serves_uncovered_paths() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let mut dynamic = producer.dynamic(); + + let pending = consumer.request_broadcast("anything/at/all"); + let request = match dynamic.poll_requested_broadcast(&kio::Waiter::noop()) { + Poll::Ready(Ok(request)) => request, + _ => panic!("expected a queued request"), + }; + assert_eq!(request.path().as_str(), "anything/at/all"); - // The cursor must see the unannounce before the new announce. - announced.assert_next_none("test"); - announced.assert_next_some("test"); - announced.assert_next_wait(); + let source = broadcast::Info::new().produce(); + request.accept(&source); + let resolved = pending.now_or_never().expect("accepted").expect("resolves"); + assert_eq!(resolved.info().path.as_str(), "anything/at/all"); } #[tokio::test] - async fn test_coalesce_unannounce_announce_unannounce() { - // unannounce + announce + unannounce collapses to a single unannounce: the - // embedded announce was never observed. - tokio::time::pause(); - - let origin = Hop::random().produce(); - let mut broadcast1 = origin.create_broadcast("test", announce()).unwrap(); - settle().await; + async fn routed_waits_for_coverage() { + let producer = origin(1).produce(); + let consumer = producer.consume(); - let mut announced = origin.consume().announced(); - announced.assert_next_some("test"); + let mut fut = consumer.routed("room/alice").boxed(); + assert!((&mut fut).now_or_never().is_none()); - broadcast1.finish(); - settle().await; + // A covering prefix resolves the wait, clamped to the requested path. + let _a = producer.announce("room", Route::default().with_cost(3)).unwrap(); + let route = fut.now_or_never().expect("covered").expect("routed"); + assert_eq!(route.cost, Cost::new(3)); - let mut broadcast2 = origin.create_broadcast("test", announce()).unwrap(); - settle().await; - broadcast2.finish(); - settle().await; - - announced.assert_next_none("test"); - announced.assert_next_wait(); + // Already covered: resolves immediately. + consumer + .routed("room/alice/cam") + .now_or_never() + .expect("covered") + .expect("routed"); } #[tokio::test] - async fn test_coalesce_churn_bounded() { - // A churn loop on a single path should keep the pending set bounded. - // Backup promotion during cleanup can leave the cursor with zero or one - // pending update for "test" depending on the order tasks run; we only - // require that churn doesn't accumulate across iterations. - tokio::time::pause(); - - let origin = Hop::random().produce(); - let mut announced = origin.consume().announced(); - - for _ in 0..1000 { - let mut broadcast = origin.create_broadcast("test", announce()).unwrap(); - settle().await; - broadcast.finish(); - } - settle().await; + async fn routed_ignores_deeper_routes() { + let producer = origin(1).produce(); + let consumer = producer.consume(); - let mut collected = Vec::new(); - while let Some(update) = announced.try_next() { - collected.push(update); - } - assert!( - collected.len() <= 1, - "expected at most one pending update, got {}", - collected.len() - ); - assert!( - collected.iter().all(|a| a.path == Path::new("test")), - "unexpected path in pending updates", - ); + // A deeper route does not cover the shorter path. + let _deep = producer.announce("room/alice/cam", Route::default()).unwrap(); + let mut fut = consumer.routed("room/alice").boxed(); + assert!((&mut fut).now_or_never().is_none()); + + let _exact = producer.announce("room/alice", Route::default()).unwrap(); + fut.now_or_never().expect("covered").expect("routed"); } - // Consumer should be cheap to clone: cloning must NOT drain any - // other cursor's announce channel. A freshly-built AnnounceConsumer - // still receives the active backlog. #[tokio::test] - async fn test_consumer_clone_is_side_effect_free() { - let origin = Hop::random().produce(); - - let _broadcast1 = origin.create_broadcast("test1", announce()).unwrap(); - let _broadcast2 = origin.create_broadcast("test2", announce()).unwrap(); - settle().await; - - let consumer = origin.consume(); + async fn teardown_ends_everything() { + let (producer, driver) = Producer::new(Info::new(origin(1))); + let consumer = producer.consume(); + let _announcement = producer.announce("room", Route::default()).unwrap(); let mut announced = consumer.announced(); + announced.assert_next_active("room"); - // Cloning the Consumer many times and looking up broadcasts - // must not consume any events from the existing cursor. - for _ in 0..16 { - let cloned = consumer.clone(); - assert!(cloned.get_broadcast("test1").is_some()); - assert!(cloned.get_broadcast("test2").is_some()); - } + let (_a2, _server) = producer.announce_served("served", Route::default()).unwrap(); + let pending = consumer.request_broadcast("served/path"); - // The original cursor still sees both announcements in their - // natural order, undisturbed by the clones above. - let a1 = announced.try_next().expect("first announcement"); - let a2 = announced.try_next().expect("second announcement"); - announced.assert_next_wait(); + drop(driver); - let mut paths: Vec<_> = [&a1, &a2].iter().map(|a| a.path.to_string()).collect(); - paths.sort(); - assert_eq!(paths, ["test1", "test2"]); + // The cursor observes the end (after draining pending updates). + announced.assert_next_active("served"); + assert!(announced.next().now_or_never().expect("ended").is_none()); - // A freshly-built AnnounceConsumer still receives the active backlog. - let mut fresh = consumer.announced(); - let b1 = fresh.try_next().expect("backlog: first"); - let b2 = fresh.try_next().expect("backlog: second"); - fresh.assert_next_wait(); + // Pending requests reject; new work refuses. + assert!(pending.now_or_never().expect("rejected").is_err()); + assert!(matches!(producer.announce("x", Route::default()), Err(Error::Closed))); + assert!(matches!(producer.create_broadcast("x"), Err(Error::Closed))); + let err = consumer + .request_broadcast("y") + .now_or_never() + .expect("closed") + .err() + .unwrap(); + assert!(matches!(err, Error::Closed)); - let mut paths: Vec<_> = [&b1, &b2].iter().map(|a| a.path.to_string()).collect(); - paths.sort(); - assert_eq!(paths, ["test1", "test2"]); + // A cursor born after the teardown is born ended. + let mut late = consumer.announced(); + assert!(late.next().now_or_never().expect("ended").is_none()); } - // With no Dynamic handler, an unannounced path resolves to Unroutable. #[tokio::test] - async fn dynamic_request_unroutable_without_handler() { - let origin = Hop::random().produce(); - let consumer = origin.consume(); - assert!(matches!( - consumer.request_broadcast("missing").await, - Err(Error::Unroutable) - )); - } - - // A dynamically served broadcast resolves the requester and serves tracks, but is - // never announced. - #[tokio::test(start_paused = true)] - async fn dynamic_request_served_not_announced() { - let origin = Hop::random().produce(); - let mut dynamic = origin.dynamic(); - let consumer = origin.consume(); - - // A separate announce cursor must never observe the dynamic broadcast. - let mut announced = origin.consume().announced(); - announced.assert_next_wait(); - - let served = broadcast::Info::new().produce(); - // Request a path that nobody announced; the future stays pending until served. - // Registration happens up front, so the handler sees the request immediately. - let request_fut = consumer.request_broadcast("fallback"); - - // The handler serves it with a live broadcast it keeps producing into. - let mut served_dynamic = served.dynamic(); - - let request = dynamic.requested_broadcast().await.unwrap(); - assert_eq!(request.path(), &Path::new("fallback")); - request.accept(&served); - - let broadcast = request_fut.await.unwrap(); - assert!(broadcast.is_clone(&served.consume())); + async fn local_sources_splice_newest_first() { + let producer = origin(1).produce(); + let consumer = producer.consume(); - // The served broadcast is live: a track subscription resolves via its handler. - let track_fut = broadcast.track("video").unwrap().subscribe(None); - let mut producer = served_dynamic.requested_track().await.unwrap().accept(None); - let mut track = track_fut.await.unwrap(); - producer.append_group().unwrap(); - track.assert_group(); - - // Still nothing announced. - announced.assert_next_wait(); - } - - // Concurrent requests for the same queued path coalesce onto one handler request. - #[tokio::test(start_paused = true)] - async fn dynamic_request_coalesces() { - let origin = Hop::random().produce(); - let mut dynamic = origin.dynamic(); - let consumer = origin.consume(); - - // Both register before the handler drains either. - let f1 = consumer.request_broadcast("dup"); - let f2 = consumer.request_broadcast("dup"); - - // Exactly one request reaches the handler. - let request = dynamic.requested_broadcast().await.unwrap(); - assert_eq!(request.path(), &Path::new("dup")); - assert!( - dynamic.requested_broadcast().now_or_never().is_none(), - "a coalesced request must not be served twice" - ); - - // Accepting resolves both awaiting requesters with the same broadcast. - let served = broadcast::Info::new().produce(); - request.accept(&served); - assert!(f1.await.unwrap().is_clone(&served.consume())); - assert!(f2.await.unwrap().is_clone(&served.consume())); - } - - // A repeat request for an already-served, still-live path shares the same broadcast - // instead of asking the handler again (no duplicate upstream subscription). - #[tokio::test(start_paused = true)] - async fn dynamic_request_dedups_served() { - let origin = Hop::random().produce(); - let mut dynamic = origin.dynamic(); - let consumer = origin.consume(); - - let request_fut = consumer.request_broadcast("fallback"); - let request = dynamic.requested_broadcast().await.unwrap(); - let served = broadcast::Info::new().produce(); - request.accept(&served); - let first = request_fut.await.unwrap(); - assert!(first.is_clone(&served.consume())); - - // The repeat resolves immediately to the same broadcast... - let second = consumer.request_broadcast("fallback").await.unwrap(); - assert!(second.is_clone(&served.consume())); - - // ...and the handler never sees a second request. - assert!( - dynamic.requested_broadcast().now_or_never().is_none(), - "a still-live served broadcast must not be re-requested from the handler" - ); - } - - // Once a served broadcast closes, its cache entry is stale, so the next request re-serves. - #[tokio::test(start_paused = true)] - async fn dynamic_request_reserves_after_close() { - let origin = Hop::random().produce(); - let mut dynamic = origin.dynamic(); - let consumer = origin.consume(); - - let request_fut = consumer.request_broadcast("fallback"); - let request = dynamic.requested_broadcast().await.unwrap(); - let served = broadcast::Info::new().produce(); - request.accept(&served); - request_fut.await.unwrap(); - - // Close the first served broadcast; the weak cache entry goes stale. - drop(served); - - // A fresh request must reach the handler again and resolve to the new broadcast. - let request_fut = consumer.request_broadcast("fallback"); - let request = dynamic.requested_broadcast().await.unwrap(); - assert_eq!(request.path(), &Path::new("fallback")); - let served = broadcast::Info::new().produce(); - request.accept(&served); - assert!(request_fut.await.unwrap().is_clone(&served.consume())); - } - - // Serving many distinct one-shot paths that each close must not grow the `served` cache - // unboundedly: the amortized GC on `accept` reclaims the stale entries left by closed ones. - #[tokio::test(start_paused = true)] - async fn dynamic_request_served_cache_bounded() { - let origin = Hop::random().produce(); - let mut dynamic = origin.dynamic(); - let consumer = origin.consume(); - - for i in 0..100 { - let path = format!("one-shot/{i}"); - let request_fut = consumer.request_broadcast(&path); - let request = dynamic.requested_broadcast().await.unwrap(); - let served = broadcast::Info::new().produce(); - request.accept(&served); - request_fut.await.unwrap(); - // Close the served broadcast; its cache entry is now stale. - drop(served); - } - - // The GC keeps the map bounded by the live count (zero here) plus a small probe window, - // rather than one entry per distinct path. - assert!( - origin.dynamic.read().served.len() <= 4, - "stale served entries must be reclaimed, not accumulate per distinct path: {}", - origin.dynamic.read().served.len() - ); - } - - // A repeat request in the window after the handler picks one up but before it accepts - // coalesces onto the in-flight request instead of queuing a duplicate. - #[tokio::test(start_paused = true)] - async fn dynamic_request_coalesces_after_handoff() { - let origin = Hop::random().produce(); - let mut dynamic = origin.dynamic(); - let consumer = origin.consume(); - - let f1 = consumer.request_broadcast("fallback"); - // Handler drains the request but has not accepted yet. - let request = dynamic.requested_broadcast().await.unwrap(); - - // A second request in this window must not queue another handler request. - let f2 = consumer.request_broadcast("fallback"); - assert!( - dynamic.requested_broadcast().now_or_never().is_none(), - "a repeat request during hand-off must coalesce, not re-queue" - ); - - // Accepting resolves both awaiting requesters with the same broadcast. - let served = broadcast::Info::new().produce(); - request.accept(&served); - assert!(f1.await.unwrap().is_clone(&served.consume())); - assert!(f2.await.unwrap().is_clone(&served.consume())); - } - - // Dropping a handed-off request without accept/reject rejects every coalesced requester. - #[tokio::test(start_paused = true)] - async fn dynamic_request_dropped_after_handoff() { - let origin = Hop::random().produce(); - let mut dynamic = origin.dynamic(); - let consumer = origin.consume(); - - let f1 = consumer.request_broadcast("fallback"); - let request = dynamic.requested_broadcast().await.unwrap(); - let f2 = consumer.request_broadcast("fallback"); - - // Abandon it; both requesters resolve to Unroutable instead of hanging. - drop(request); - assert!(matches!(f1.await, Err(Error::Unroutable))); - assert!(matches!(f2.await, Err(Error::Unroutable))); - } - - // Rejecting a request resolves the requester with the error. - #[tokio::test(start_paused = true)] - async fn dynamic_request_rejected() { - let origin = Hop::random().produce(); - let mut dynamic = origin.dynamic(); - let consumer = origin.consume(); - - let request_fut = consumer.request_broadcast("fallback"); - - let request = dynamic.requested_broadcast().await.unwrap(); - request.reject(Error::Cancel); - - assert!(matches!(request_fut.await, Err(Error::Cancel))); - } - - // After a rejected hand-off, a fresh request for the same path reaches the handler again: - // the rejected `Request`'s removal + `Drop` leave the request queue consistent - // (a stale/clobbered entry would strand this request or panic the handler). - #[tokio::test(start_paused = true)] - async fn dynamic_request_rerequest_after_reject() { - let origin = Hop::random().produce(); - let mut dynamic = origin.dynamic(); - let consumer = origin.consume(); - - let f1 = consumer.request_broadcast("fallback"); - dynamic.requested_broadcast().await.unwrap().reject(Error::Unroutable); - assert!(matches!(f1.await, Err(Error::Unroutable))); - - let served = broadcast::Info::new().produce(); - // A fresh request re-reaches the handler and can be served. - let f2 = consumer.request_broadcast("fallback"); - let request = dynamic.requested_broadcast().await.unwrap(); - assert_eq!(request.path(), &Path::new("fallback")); - request.accept(&served); - assert!(f2.await.unwrap().is_clone(&served.consume())); - } - - // Dropping the last handler resolves queued requests with an error and reverts to - // resolving Unroutable. - #[tokio::test(start_paused = true)] - async fn dynamic_request_handler_dropped() { - let origin = Hop::random().produce(); - let dynamic = origin.dynamic(); - let consumer = origin.consume(); - - let request_fut = consumer.request_broadcast("fallback"); - drop(dynamic); - assert!(matches!(request_fut.await, Err(Error::Unroutable))); - - // With no handler left, a fresh request resolves Unroutable. - assert!(matches!( - consumer.request_broadcast("again").await, - Err(Error::Unroutable) - )); - } - - // `accept` is decoupled from the dynamic count: once a handler has picked a request up, - // it can still serve it even if every handler (including itself) drops first, flipping the - // count to zero. The in-flight request must not be rejected as `Unroutable`. - #[tokio::test(start_paused = true)] - async fn dynamic_request_accept_after_handler_dropped() { - let origin = Hop::random().produce(); - let mut dynamic = origin.dynamic(); - let consumer = origin.consume(); - - let request_fut = consumer.request_broadcast("fallback"); - - // The handler picks the request up, then every handler drops (count -> 0). - let request = dynamic.requested_broadcast().await.unwrap(); - drop(dynamic); - - let served = broadcast::Info::new().produce(); - // Accept still resolves the awaiting requester with the served broadcast. - request.accept(&served); - assert!(request_fut.await.unwrap().is_clone(&served.consume())); - } - - // A published broadcast wins over the dynamic fallback; no request is queued. - #[tokio::test(start_paused = true)] - async fn dynamic_request_prefers_announced() { - let origin = Hop::random().produce(); - let mut dynamic = origin.dynamic(); - let consumer = origin.consume(); - - let _broadcast = origin.create_broadcast("live", announce()).unwrap(); - settle().await; - - let got = consumer.request_broadcast("live").await.unwrap(); - assert!( - got.is_clone(&consumer.get_broadcast("live").unwrap()), - "should return the published broadcast" - ); - assert!( - dynamic.requested_broadcast().now_or_never().is_none(), - "a published path must not queue a fallback request" - ); - } - - // Cloning a handler and dropping the clone must not flip the count to zero. - #[tokio::test(start_paused = true)] - async fn dynamic_clone_keeps_alive() { - let origin = Hop::random().produce(); - let dynamic = origin.dynamic(); - let consumer = origin.consume(); - - drop(dynamic.clone()); - - // The original handle is still live, so the request registers (stays pending) - // instead of resolving Unroutable. - let request_fut = consumer.request_broadcast("fallback"); - assert!( - request_fut.now_or_never().is_none(), - "request should stay pending until served" - ); - } - - /// A draining route has to lose to every ordinary one. Cost is only the second - /// term of the ordering, so a draining route that ties on cost would fall - /// through to hop count, the hash, and recency, which is how a dying - /// connection could otherwise stay primary. - /// - /// Every comparison here gives the draining route the highest id, so it is also - /// the most recently attached. That is the case that matters since recency - /// became a tie-break: a reconnect is supposed to take over immediately, but - /// not when the newcomer is the one going away. - #[test] - fn drain_cost_sorts_last() { - let name = Path::new("drainer"); - let source = broadcast::Info::new().produce().consume(); - let front = |id: u64, route: broadcast::Route| FrontRoute { - id, - route, - source: source.clone(), - }; + let mut first = producer.create_broadcast("room/alice").unwrap(); + let resolved = consumer + .request_broadcast("room/alice") + .now_or_never() + .expect("resolves") + .expect("resolves"); - let draining = front(9, announce().with_cost(broadcast::DRAIN_COST)); + // A second source at the same path joins the same front. + let mut second = producer.create_broadcast("room/alice").unwrap(); + let again = consumer + .request_broadcast("room/alice") + .now_or_never() + .expect("resolves") + .expect("resolves"); + assert!(again.is_clone(&resolved)); - assert!(route_order(&name, &draining) > route_order(&name, &front(0, announce()))); - assert!(route_order(&name, &draining) > route_order(&name, &front(0, announce().with_cost(1000)))); + // Losing one source keeps the front alive; losing both closes it. + first.finish(); + settle(|| consumer.get_broadcast("room/alice").is_some()).await; + second.finish(); + settle(|| consumer.get_broadcast("room/alice").is_none()).await; - // Two hops beats one when the cheaper one is draining: the longer path is - // still the one that will still be there. - let hops = Hops::try_from(vec![Hop::new(1).unwrap(), Hop::new(2).unwrap()]).unwrap(); - let long = front(0, announce().with_hops(hops).with_cost(1)); - assert!(route_order(&name, &draining) > route_order(&name, &long)); + // The path is free again for a fresh broadcast. + let _third = producer.create_broadcast("room/alice").unwrap(); + assert!(consumer.get_broadcast("room/alice").is_some()); } - /// The whole point of the mechanism: with two sources for one broadcast, - /// draining the winner moves the origin onto the other one, and a broadcast - /// with nowhere else to go keeps being served by the draining route. - #[tokio::test(start_paused = true)] - async fn drain_migrates_best_route() { - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let mut announced = consumer.announced(); - - let path = PathOwned::from("drainer"); - - // Two paths to the same content, so they share a first hop: a differing one - // would be a different publisher, and the front would park it as new content - // instead of attaching it as an alternate route. - let publisher = Hop::new(1).unwrap(); - let hops_a = Hops::try_from(vec![publisher, Hop::new(2).unwrap()]).unwrap(); - let hops_b = Hops::try_from(vec![publisher, Hop::new(3).unwrap()]).unwrap(); - - // The source that will drain, and the pricier live fallback. - let source_a = origin.create_broadcast(&path, announce().with_hops(hops_a)).unwrap(); - settle().await; - announced.assert_next_some("drainer"); + #[tokio::test] + async fn multiple_scopes_present_a_broad_route_at_each() { + let producer = origin(1).produce(); + let _a = producer.announce("", Route::default()).unwrap(); - let _source_b = origin - .create_broadcast(&path, announce().with_hops(hops_b).with_cost(10)) + let consumer = producer + .consume() + .scope(&[Path::new("alpha"), Path::new("beta")]) .unwrap(); - settle().await; - - let mut broadcast = consumer.get_broadcast("drainer").unwrap(); - assert_eq!( - broadcast.route().cost, - broadcast::Cost::default(), - "the cheaper source serves first" - ); - - // What the subscriber does when its peer sends a GOAWAY. - let mut draining = source_a.dynamic(); - draining.drain(); - settle().await; - - // A GOAWAY keeps serving for many seconds, so the migration waits out the - // re-parent hold like any other move rather than racing off stale prices. - settle_handover().await; - let migrated = broadcast.route_changed().await.unwrap(); - assert_eq!( - migrated.cost, - broadcast::Cost::new(10), - "draining must hand over to the live source" - ); - assert_ne!( - migrated.cost, - broadcast::Cost::DRAIN, - "the draining source must not stay active" - ); - } - - /// A draining route is deprioritized, not withdrawn: while it is the only path - /// to the content it keeps serving, which is what makes the handover window - /// worth having. - #[tokio::test(start_paused = true)] - async fn drain_still_serves_when_it_is_the_only_route() { - let origin = Hop::random().produce(); - let consumer = origin.consume(); let mut announced = consumer.announced(); - - let path = PathOwned::from("lonely"); - let hops = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let source = origin.create_broadcast(&path, announce().with_hops(hops)).unwrap(); - settle().await; - announced.assert_next_some("lonely"); - - let mut draining = source.dynamic(); - draining.drain(); - settle().await; - - let broadcast = consumer.get_broadcast("lonely").expect("the path stays routable"); - assert_eq!(broadcast.route().cost, broadcast::Cost::DRAIN); - } - - /// Run `scenario` on its own thread with a current_thread runtime and fail - /// if it does not complete within `secs`. A `serve_track` task that spins - /// inside a single poll (the livelock class this guards against) never - /// yields, so the runtime wedges and the scenario cannot finish; a timeout - /// here IS the detection, not flakiness. - fn wedge_watchdog(name: &str, secs: u64, scenario: F) - where - F: std::future::Future + Send + 'static, - { - let (done_tx, done_rx) = std::sync::mpsc::channel::<()>(); - let handle = std::thread::spawn(move || { - let rt = ::tokio::runtime::Builder::new_current_thread() - .enable_time() - .build() - .unwrap(); - rt.block_on(scenario); - let _ = done_tx.send(()); - }); - match done_rx.recv_timeout(Duration::from_secs(secs)) { - Ok(()) => { - let _ = handle.join(); - } - Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => { - // The scenario thread panicked before sending: surface it. - let err = handle.join().unwrap_err(); - std::panic::resume_unwind(err); - } - Err(std::sync::mpsc::RecvTimeoutError::Timeout) => { - panic!("{name}: scenario wedged; a task is spinning inside a single poll") - } - } + announced.assert_next_active("alpha"); + announced.assert_next_active("beta"); + announced.assert_next_wait(); } - /// A closing route that is still `active` (its watcher has not detached it - /// yet) must not be re-dispatched after a successful takeover from a - /// healthy standby. If the takeover re-admits the corpse, serve_track - /// cycles splice(corpse) -> splice(healthy) -> takeover -> splice(corpse) - /// with no await: a livelock inside one task poll that also starves the - /// watcher whose detach would end it. - /// - /// The setup makes every step of the cycle synchronous: the healthy source - /// holds a live producer (so a re-splice needs no handler roundtrip), and - /// the corpse is aborted while its track request is still pending (so - /// serve_track, a value waiter, wakes before the corpse's closed-watcher - /// and observes the corpse still attached). + /// Charging a link accumulates onto both halves, saturating rather than wrapping + /// so a bogus peer sorts last, not first. The ceiling is the largest cost a + /// varint can carry, so whatever a peer advertises, the sum we forward still + /// encodes. #[test] - fn test_active_corpse_does_not_livelock_takeover() { - wedge_watchdog("active-corpse", 20, async { - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let hops = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - - // The healthy source: accepts the track and keeps the producer - // alive, so a later re-splice resolves synchronously from cache. - let source_a = origin - .create_broadcast("test", announce().with_hops(hops.clone())) - .unwrap(); - let mut dynamic_a = source_a.dynamic(); - settle().await; - settle().await; - - let broadcast = consumer.request_broadcast("test").await.unwrap(); - let subscribing = broadcast.track("video").unwrap().subscribe(None); - let mut producer_a = accept_track(&mut dynamic_a, "video").await; - settle().await; - let mut sub = subscribing.await.unwrap(); - producer_a.append_group().unwrap(); - sub.assert_group(); - - // A newer same-cost source attaches: recency wins the tie, so it - // becomes `active` and the serve task asks it for the track. Leave - // the request unanswered. - let source_b = origin - .create_broadcast("test", announce().with_hops(hops.clone())) - .unwrap(); - let dynamic_b = source_b.dynamic(); - settle().await; - - // Kill it with the request still pending: a corpse that is still - // attached and still `active`. Dropping the handler first queues the - // serve task's request-failure wake ahead of the corpse watcher's - // closed-wake, so the serve task observes the corpse before the - // watcher can detach it - the fleet-wedge ordering. It must fail - // over to the healthy cached copy and park there instead of - // re-dispatching the corpse. - drop(dynamic_b); - source_b.abort(Error::Dropped).unwrap(); - settle().await; - - // Progress through the healthy source proves the serve task parked - // instead of spinning. - producer_a.append_group().unwrap(); - sub.assert_group(); - sub.assert_not_closed(); - }); - } + fn cost_charge_saturates() { + assert_eq!(Cost { warm: 4, cold: 6 }.charged(5), Cost { warm: 9, cold: 11 }); + assert_eq!(Cost::new(u64::MAX).charged(10), Cost::new(MAX_COST)); - /// Randomized source/subscriber churn over one path: sources attach with - /// per-track behaviors (refuse, serve-then-abort, serve-and-hold, finish), - /// detach by abort or plain drop, and subscribers come and go. A wedge net - /// for the livelock class the test above pins down. The LCG makes each - /// seed's action sequence repeatable, but task interleaving still varies - /// per run, so treat a wedge here as real and shrink it with the seed as a - /// starting point rather than expecting an identical replay. - #[test] - fn test_route_churn_never_wedges() { - for seed in 1..=8u64 { - wedge_watchdog(&format!("churn seed {seed}"), 30, churn_scenario(seed)); - } + // An unknown cold path stays unknown however many links it crosses, so it + // can never accumulate its way into outranking a path we actually know. + assert_eq!(Cost::UNKNOWN.charged(3).cold, MAX_COST); } - async fn churn_scenario(seed: u64) { - // LCG: deterministic sequence per seed. - let mut rng = seed.wrapping_mul(6364136223846793005).wrapping_add(1442695040888963407); - let mut next = move || { - rng = rng.wrapping_mul(6364136223846793005).wrapping_add(1442695040888963407); - rng >> 33 - }; - - let origin = Hop::random().produce(); - let consumer = origin.consume(); - let names: Vec> = (0..8).map(|i| Arc::from(format!("t{i}"))).collect(); - - let mut subs: Vec = Vec::new(); - let mut pending_subs: Vec> = Vec::new(); - - struct Source { - producer: Option, - server: ::tokio::task::JoinHandle<()>, - } - let mut sources: Vec = Vec::new(); - - for step in 0..400u64 { - match next() % 10 { - // Attach a source whose handler randomly refuses / serves-then- - // aborts / serves-and-holds / finishes each track request. - 0 | 1 => { - if sources.len() >= 3 { - continue; - } - let hops = Hops::try_from(vec![Hop::new(1).unwrap()]).unwrap(); - let route = announce().with_hops(hops).with_cost(next() % 4); - let Ok(source) = origin.create_broadcast("test", route) else { - continue; - }; - let mut dynamic = source.dynamic(); - let behavior = next(); - let server = ::tokio::spawn(async move { - let mut round = 0u64; - let mut kept: Vec = Vec::new(); - while let Ok(request) = dynamic.requested_track().await { - round += 1; - match (behavior >> (round % 16)) % 4 { - 0 => drop(request), // refuse - 1 => { - let mut producer = request.accept(None); - let _ = producer.create_group(group::Info { sequence: round }); - let _ = producer.abort(Error::Dropped); - } - 2 => { - let mut producer = request.accept(None); - let _ = producer.create_group(group::Info { sequence: round }); - kept.push(producer); - } - _ => { - let mut producer = request.accept(None); - let _ = producer.finish(); - } - } - } - }); - sources.push(Source { - producer: Some(source), - server, - }); - } - // Detach a source, by abort or plain drop. - 2 | 3 => { - if sources.is_empty() { - continue; - } - let i = (next() as usize) % sources.len(); - let mut source = sources.swap_remove(i); - if next() % 2 == 0 - && let Some(producer) = source.producer.take() - { - let _ = producer.abort(Error::Dropped); - } - source.server.abort(); - } - // Subscribe to a random track. - 4..=6 => { - if subs.len() + pending_subs.len() >= 24 { - continue; - } - let Some(broadcast) = consumer.get_broadcast("test") else { - continue; - }; - let name = &names[(next() as usize) % names.len()]; - if let Ok(track) = broadcast.track(name.as_ref()) { - pending_subs.push(track.subscribe(None)); - } - } - // Drop a random subscriber. - 7 => { - if subs.is_empty() { - continue; - } - let i = (next() as usize) % subs.len(); - subs.swap_remove(i); - } - // Drain: resolve pending subscriptions and read groups. - _ => { - for sub in pending_subs.drain(..) { - match ::tokio::time::timeout(Duration::from_millis(5), sub).await { - Ok(Ok(sub)) => subs.push(sub), - Ok(Err(_)) => {} - // Still pending: dropping unsubscribes. - Err(_) => {} - } - } - for sub in subs.iter_mut() { - while let Some(Ok(Some(_))) = sub.recv_group().now_or_never() {} - } - } - } - if step % 16 == 0 { - settle().await; - } - // Vary task interleaving per seed. - for _ in 0..(next() % 3) { - ::tokio::task::yield_now().await; - } - } + /// A draining cost still has to fit the wire, since the route keeps being + /// announced downstream while it drains. + #[test] + fn drain_cost_is_encodable() { + use crate::coding::Encode; - for source in sources { - source.server.abort(); - } - settle().await; + let mut buf = Vec::new(); + Cost::DRAIN + .encode(&mut buf, crate::lite::Version::Lite06Wip) + .expect("a draining route is still forwarded, so its cost must encode"); } } diff --git a/rs/moq-net/src/runtime.rs b/rs/moq-net/src/runtime.rs index 199ec2b22a6..a96e5505d00 100644 --- a/rs/moq-net/src/runtime.rs +++ b/rs/moq-net/src/runtime.rs @@ -214,16 +214,6 @@ impl TimersSlot { pub(crate) fn get(&self) -> AnyTimers { self.0.get().expect("origin driver is not running").clone() } - - /// The installed timers' clock, if the driver is running. - pub(crate) fn try_now(&self) -> Option { - self.0.get().map(Timers::now) - } - - /// The installed timers' clock. - pub(crate) fn now(&self) -> Instant { - self.try_now().expect("origin driver is not running") - } } /// A wall-clock deadline: the ergonomic layer over [`Timer`]. diff --git a/rs/moq-net/src/server.rs b/rs/moq-net/src/server.rs index 5802b74d209..b71f54a1a26 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -1128,21 +1128,13 @@ mod tests { let mut echoed_hops = crate::Hops::new(); echoed_hops.push(assigned).unwrap(); let _echoed = origin - .create_broadcast( - "echoed-route", - crate::broadcast::Route::new() - .with_hops(echoed_hops) - .with_announce(true), - ) + .announce("echoed-route", crate::origin::Route::default().with_hops(echoed_hops)) .unwrap(); let mut local_hops = crate::Hops::new(); local_hops.push(other).unwrap(); let _local = origin - .create_broadcast( - "local-route", - crate::broadcast::Route::new().with_hops(local_hops).with_announce(true), - ) + .announce("local-route", crate::origin::Route::default().with_hops(local_hops)) .unwrap(); let session = request.ok().await.unwrap(); diff --git a/rs/moq-net/tests/goaway.rs b/rs/moq-net/tests/goaway.rs index 99dce75e8b3..642b9bf2801 100644 --- a/rs/moq-net/tests/goaway.rs +++ b/rs/moq-net/tests/goaway.rs @@ -318,9 +318,10 @@ async fn goaway_gates_new_subscribes_moq_lite_04() { // Server publishes a broadcast with one live track. let pub_origin = produce_origin(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) - .expect("create broadcast"); + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce = pub_origin + .announce("test", moq_net::origin::Route::default()) + .expect("announce"); let mut track = broadcast.create_track("video", None).expect("create track"); // A second track with content ready, so the gated subscribe below would // deliver immediately if it reached the wire. @@ -340,11 +341,9 @@ async fn goaway_gates_new_subscribes_moq_lite_04() { let MockPair { client, server } = connect_mock(opts).await; // Subscribe BEFORE the GOAWAY and receive a first group. - let bc = sub_origin - .consume() - .announced_broadcast("test") - .await - .expect("broadcast announced"); + let sub = sub_origin.consume(); + sub.routed("test").await.expect("route announced"); + let bc = sub.request_broadcast("test").await.expect("broadcast resolves"); let mut existing = bc.track("video").unwrap().subscribe(None).await.expect("subscribe"); let mut group = track.append_group().expect("append group"); @@ -418,9 +417,10 @@ async fn goaway_gates_new_subscribes_moq_lite_04() { async fn goaway_drains_routes(version: Version) { tokio::time::timeout(TEST_TIMEOUT, async { let pub_origin = produce_origin(Hop::random()); - let _broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) - .expect("create broadcast"); + let _broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce = pub_origin + .announce("test", moq_net::origin::Route::default()) + .expect("announce"); let sub_origin = produce_origin(Hop::random()); @@ -429,14 +429,11 @@ async fn goaway_drains_routes(version: Version) { opts.client_subscribe = Some(sub_origin.clone()); let MockPair { client, server } = connect_mock(opts).await; - let mut announced = sub_origin - .consume() - .announced_broadcast("test") - .await - .expect("broadcast announced"); + let sub = sub_origin.consume(); + let route = sub.routed("test").await.expect("route announced"); assert_ne!( - announced.route().cost, - moq_net::broadcast::Cost::DRAIN, + route.cost, + moq_net::origin::Cost::DRAIN, "a healthy route must not start out draining" ); @@ -444,11 +441,15 @@ async fn goaway_drains_routes(version: Version) { client.draining().recv().await.expect("goaway"); // Nothing else is sent on the announce stream, so this only resolves if the - // subscriber acted on the GOAWAY rather than on another message. + // subscriber acted on the GOAWAY rather than on another message. The drain + // re-prices the route in place, which arrives as another active update. + let mut announced = sub.announced(); loop { - let route = announced.route_changed().await.expect("route"); - if route.cost == moq_net::broadcast::Cost::DRAIN { - assert!(route.announce, "a draining route stays announced"); + let update = announced.next().await.expect("update"); + if update.active + && update.prefix.as_path().as_str() == "test" + && update.route.cost == moq_net::origin::Cost::DRAIN + { break; } } diff --git a/rs/moq-relay/src/cluster.rs b/rs/moq-relay/src/cluster.rs index 944baf66a97..65fa1b79598 100644 --- a/rs/moq-relay/src/cluster.rs +++ b/rs/moq-relay/src/cluster.rs @@ -599,7 +599,7 @@ struct Work { /// /// Local sessions and remote cluster connections all publish into the same /// origin. Loop prevention and route preference come from the hop list carried -/// on each broadcast's route (see [`moq_net::broadcast::Route`]). +/// on each announced route (see [`moq_net::origin::Route`]). /// /// Construct with [`Cluster::new`], then attach a QUIC client and (optionally) /// a [`stats::Registry`](moq_net::stats::Registry) with the `with_*` builder @@ -991,13 +991,14 @@ impl Cluster { // Held in scope so the registration stays announced until `run` exits. // Discovery is paired with it: a gossip-only relay (passive rendezvous) has // nothing to discover, so we only run it when we also have an outbound peer. - let self_registration: Option = if gossip { + // A pure route: the path itself is the advertisement, no broadcast behind it. + let self_registration: Option = if gossip { // Checked above: gossip requires `node`. let node = node.as_deref().expect("gossip requires --cluster-node"); let path = Path::new(MESH_PREFIX).join(node); - let broadcast = self + let announcement = self .origin - .create_broadcast(&path, moq_net::broadcast::Route::new().with_announce(true)) + .announce(&path, moq_net::origin::Route::default()) .expect(".internal/origins is within the relay origin's root"); tracing::info!(%node, %path, "advertising cluster node URL"); @@ -1012,7 +1013,7 @@ impl Cluster { }); } - Some(broadcast) + Some(announcement) } else { None }; @@ -1034,11 +1035,8 @@ impl Cluster { } } - // Deliberate shutdown: finish the registration rather than dropping it, so - // there is no dropped-without-finish warning. - if let Some(mut registration) = self_registration { - registration.finish(); - } + // Deliberate shutdown: dropping the registration retracts the route. + drop(self_registration); Ok(()) } @@ -1067,7 +1065,8 @@ impl Cluster { loop { tokio::select! { ann = announced.next() => { - let Some(moq_net::announce::Update { path: relative, broadcast }) = ann else { return; }; + let Some(update) = ann else { return; }; + let relative = update.prefix.as_path(); // The address to dial, which keeps its query: `run_remote` reads // `?cost=` and `?jwt=` off it. The key is only its identity. let peer = advertised_node_url(relative.as_str()); @@ -1084,8 +1083,8 @@ impl Cluster { continue; } let advertisement = relative.as_str().to_owned(); - match broadcast { - Some(_) => { + match update.active { + true => { let target = live.announce(advertisement, target); let mut spawn = |target: DialTarget| { tracing::info!(peer = %target.key, "discovered cluster peer; dialing"); @@ -1096,7 +1095,7 @@ impl Cluster { tracing::debug!(peer = %key, "reannounce within sweep window; keeping dial"); } } - None => match live.unannounce(&advertisement, &target.key) { + false => match live.unannounce(&advertisement, &target.key) { GossipUpdate::Current(target) => { let mut spawn = |target: DialTarget| { tracing::info!(peer = %target.key, "cluster peer advertisement changed; redialing"); @@ -1642,25 +1641,23 @@ mod tests { let cluster = cluster.with_stats(stats); let path = moq_net::Path::new(".stats").join("node").join("test"); - let broadcast = tokio::time::timeout( - std::time::Duration::from_secs(5), - cluster.origin.consume().announced_broadcast(&path), - ) - .await - .expect("stats broadcast announced within 5s") - .expect("stats broadcast present"); + let consumer = cluster.origin.consume(); + tokio::time::timeout(std::time::Duration::from_secs(5), consumer.routed(&path)) + .await + .expect("stats broadcast announced within 5s") + .expect("stats broadcast present"); + let broadcast = consumer + .request_broadcast(&path) + .await + .expect("stats broadcast resolves"); // Several publish intervals (1s each by default) after the handle went out // of scope, the task is still running and its broadcast still open. The // re-check is bounded: without the keepalive the broadcast is gone and - // `announced_broadcast` waits forever, which must read as a failure rather + // `routed` waits forever, which must read as a failure rather // than a hung test. tokio::time::sleep(std::time::Duration::from_millis(2500)).await; - let still_live = tokio::time::timeout( - std::time::Duration::from_secs(2), - cluster.origin.consume().announced_broadcast(&path), - ) - .await; + let still_live = tokio::time::timeout(std::time::Duration::from_secs(2), consumer.routed(&path)).await; assert!( matches!(still_live, Ok(Some(_))), "stats broadcast unannounced after the producer handle was dropped: \ @@ -2147,11 +2144,13 @@ mod tests { // Give the runtime a moment to execute the synchronous setup work. tokio::time::sleep(tokio::time::Duration::from_millis(10)).await; - // The self-registration broadcast must be visible on the origin. - let moq_net::announce::Update { path, broadcast } = - watcher.try_next().expect("self-registration must be published"); - assert_eq!(path.as_str(), ".internal/origins/rendezvous.example.com:4443"); - assert!(broadcast.is_some()); + // The self-registration route must be visible on the origin. + let update = watcher.try_next().expect("self-registration must be published"); + assert_eq!( + update.prefix.as_path().as_str(), + ".internal/origins/rendezvous.example.com:4443" + ); + assert!(update.active); // run() must NOT have returned: dropping the broadcast (via run returning) // would unannounce the registration immediately. Use a short timeout to diff --git a/rs/moq-relay/src/internal.rs b/rs/moq-relay/src/internal.rs index e80b569ef61..46522cd29a8 100644 --- a/rs/moq-relay/src/internal.rs +++ b/rs/moq-relay/src/internal.rs @@ -210,9 +210,9 @@ async fn serve_metrics(State(state): State) -> Response { /// Cluster nodes currently visible through gossip or a direct outbound dial. /// -/// Inbound connections appear only after their SETUP Hop ID resolves to a -/// unique `.internal/origins` node advertisement. Sessions without a unique -/// match are omitted. +/// Inbound connections appear only after their SETUP origin identity resolves +/// to a unique `.internal/origins` node advertisement. Sessions without a +/// unique match are omitted. async fn serve_nodes(State(state): State) -> Json { Json(state.nodes.map(|nodes| nodes.snapshot()).unwrap_or_default()) } @@ -577,7 +577,7 @@ mod tests { #[tokio::test(start_paused = true)] async fn metrics_render_exposition() { use moq_net::stats::{Registry, Tier}; - use moq_net::{Hop, Timestamp, broadcast}; + use moq_net::{Hop, Timestamp}; let stats = Registry::new(Default::default()); @@ -587,18 +587,16 @@ mod tests { let pub_origin = moq_tokio::origin::spawn(Hop::random()); let egress = pub_origin.consume().with_stats(default_ctx.clone()); let mut announced = egress.announced(); - let mut pub_source = pub_origin - .create_broadcast("demo/x", broadcast::Route::announced()) - .unwrap(); + let mut pub_source = pub_origin.create_broadcast("demo/x").unwrap(); + let _announce_pub_source = pub_origin.announce("demo/x", Default::default()).unwrap(); let mut pub_track = pub_source.create_track("video", None).unwrap(); // Named-tier ingress: a tagged ingress producer writes, so subscriber // `bytes` advance on the regional tier. let regional_ctx = stats.tier(Tier::new("region/sjc")).session("peer"); let sub_origin = moq_tokio::origin::spawn(Hop::random()).with_stats(regional_ctx.clone()); - let mut sub_source = sub_origin - .create_broadcast("demo/x", broadcast::Route::announced()) - .unwrap(); + let mut sub_source = sub_origin.create_broadcast("demo/x").unwrap(); + let _announce_sub_source = sub_origin.announce("demo/x", Default::default()).unwrap(); let mut sub_track = sub_source.create_track("audio", None).unwrap(); tokio::time::sleep(std::time::Duration::from_millis(1)).await; @@ -606,7 +604,9 @@ mod tests { // Leave 46 bytes across two frames behind the live edge, then read 1234 // egress bytes out of the default-tier broadcast. - let bc = announced.next().await.unwrap().broadcast.unwrap(); + let update = announced.next().await.unwrap(); + assert!(update.active); + let bc = egress.request_broadcast(update.prefix.as_path()).await.unwrap(); let mut egress_sub = bc.track("video").unwrap().subscribe(None).await.unwrap(); { let mut group = pub_track.append_group().unwrap(); diff --git a/rs/moq-relay/src/nodes.rs b/rs/moq-relay/src/nodes.rs index 8646e5444cd..948c6ac303b 100644 --- a/rs/moq-relay/src/nodes.rs +++ b/rs/moq-relay/src/nodes.rs @@ -51,8 +51,8 @@ pub(crate) struct Snapshot { pub(crate) struct Node { /// Canonical URL advertised for the node. pub node: String, - /// The node's [`Hop`](moq_net::Hop) id from its announcement, when available. - pub hop_id: Option, + /// Hop identity from the node's announcement, when available. + pub origin_id: Option, /// Selected route for the node's internal advertisement. pub announced: Option, /// Established direct connections to this node. @@ -62,7 +62,7 @@ pub(crate) struct Node { /// The selected route for a node advertisement. #[derive(Debug, Serialize)] pub(crate) struct Announcement { - /// Hop ids in traversal order, oldest first. + /// Hop identities in traversal order, oldest first. pub hops: Vec, /// Number of hops in the selected route. pub hop_count: usize, @@ -95,7 +95,7 @@ pub(crate) enum Direction { } struct NodeBuilder { - hop_id: Option, + origin_id: Option, announced: Option, connections: Vec, } @@ -106,7 +106,7 @@ struct Announced { nodes: BTreeMap, /// Hop id to the single node advertising it, or `None` once more than one /// does and the id no longer identifies a peer. - hops: HashMap>, + origins: HashMap>, } /// Removes a live connection from the topology view when its session ends. @@ -169,20 +169,22 @@ impl Nodes { let mut scanned = Announced::default(); while let Some(update) = announced.try_next() { - // The origin delivers a re-announce as unannounce-then-announce, so an - // unannounce can land mid-drain. Skip it rather than end the scan, which + // A retraction can land mid-drain (a re-announce is a metadata update, + // not a retract-and-announce). Skip it rather than end the scan, which // would drop every node still queued behind it. - let Some(broadcast) = update.broadcast else { continue }; + if !update.active { + continue; + } - let key = canonical_announced_node(update.path.as_str()); - let route = broadcast.route(); - let hop_ids = route.hops.iter().map(|hop| hop.id()).collect::>(); + let key = canonical_announced_node(update.prefix.as_path().as_str()); + let route = update.route; + let hop_ids = route.hops.iter().map(|origin| origin.id()).collect::>(); // An advertisement with no hops never crossed a link, so it is our own. - let hop_id = hop_ids.first().copied().unwrap_or_else(|| self.origin.id()); + let origin_id = hop_ids.first().copied().unwrap_or_else(|| self.origin.id()); scanned - .hops - .entry(hop_id) + .origins + .entry(origin_id) .and_modify(|current| { if current.as_deref() != Some(&key) { *current = None; @@ -193,10 +195,10 @@ impl Nodes { scanned.nodes.insert( key, NodeBuilder { - hop_id: Some(hop_id.to_string()), + origin_id: Some(origin_id.to_string()), announced: Some(Announcement { hop_count: hop_ids.len(), - hops: hop_ids.into_iter().map(|hop| hop.to_string()).collect(), + hops: hop_ids.into_iter().map(|origin| origin.to_string()).collect(), cost: route.cost.warm, cold_cost: route.cost.cold, }), @@ -209,7 +211,7 @@ impl Nodes { } pub(crate) fn snapshot(&self) -> Snapshot { - let Announced { mut nodes, hops } = self.announced(); + let Announced { mut nodes, origins } = self.announced(); let connections = self .connections @@ -221,15 +223,15 @@ impl Nodes { for (&id, connection) in connections { let key = match &connection.target { ConnectionTarget::Node(node) => canonical_node(node), - ConnectionTarget::Hop(hop) => { - let Some(Some(node)) = hops.get(&hop.id()) else { + ConnectionTarget::Hop(origin) => { + let Some(Some(node)) = origins.get(&origin.id()) else { continue; }; node.clone() } }; let node = nodes.entry(key).or_insert_with(|| NodeBuilder { - hop_id: None, + origin_id: None, announced: None, connections: Vec::new(), }); @@ -244,7 +246,7 @@ impl Nodes { .into_iter() .map(|(key, node)| Node { node: key, - hop_id: node.hop_id, + origin_id: node.origin_id, announced: node.announced, connections: node.connections, }) @@ -275,14 +277,14 @@ fn canonical_announced_node(node: &str) -> String { #[cfg(test)] mod tests { use super::*; - use moq_net::{Hop, Hops, broadcast}; + use moq_net::{Hop, Hops}; async fn announced_node( origin: &moq_net::origin::Producer, node: &str, hops: &[u64], cost: u64, - ) -> broadcast::Producer { + ) -> moq_net::announce::Producer { let hops = Hops::try_from( hops.iter() .map(|id| Hop::new(*id).expect("valid test origin")) @@ -290,15 +292,11 @@ mod tests { ) .unwrap(); let path = moq_net::Path::new(MESH_PREFIX).join(node); - let broadcast = origin - .create_broadcast(&path, broadcast::Route::announced().with_hops(hops).with_cost(cost)) + let announcement = origin + .announce(&path, moq_net::origin::Route::default().with_hops(hops).with_cost(cost)) .unwrap(); - origin - .consume() - .announced_broadcast(&path) - .await - .expect("test node announced"); - broadcast + origin.consume().routed(&path).await.expect("test node announced"); + announcement } #[tokio::test] @@ -315,7 +313,7 @@ mod tests { assert_eq!(snapshot.nodes.len(), 1); let node = &snapshot.nodes[0]; assert_eq!(node.node, "https://relay-b.example/"); - assert_eq!(node.hop_id.as_deref(), Some("9007199254740993")); + assert_eq!(node.origin_id.as_deref(), Some("9007199254740993")); assert_eq!(node.announced.as_ref().unwrap().hops, vec!["9007199254740993"]); assert_eq!(node.announced.as_ref().unwrap().hop_count, 1); assert_eq!(node.announced.as_ref().unwrap().cost, 7); @@ -328,7 +326,7 @@ mod tests { serde_json::json!({ "nodes": [{ "node": "https://relay-b.example/", - "hop_id": "9007199254740993", + "origin_id": "9007199254740993", "announced": { "hops": ["9007199254740993"], "hop_count": 1, "cost": 7, "cold_cost": 7 }, "connections": [ { "id": 0, "direction": "outbound" }, @@ -376,7 +374,7 @@ mod tests { async fn scan_skips_an_unannounce_queued_ahead_of_another_node() { let origin = moq_tokio::origin::spawn(Hop::new(100).unwrap()); let nodes = Nodes::new(origin.clone()); - let mut first = announced_node(&origin, "https://relay-a.example/", &[200], 1).await; + let first = announced_node(&origin, "https://relay-a.example/", &[200], 1).await; let _second = announced_node(&origin, "https://relay-b.example/", &[300], 1).await; let consumer = origin.consume().with_root(MESH_PREFIX).expect("mesh prefix is in root"); @@ -386,13 +384,10 @@ mod tests { // bare unannounce ahead of relay-b's still-pending announce. let first_update = announced.try_next().expect("replayed announce"); assert_eq!( - canonical_announced_node(first_update.path.as_str()), + canonical_announced_node(first_update.prefix.as_path().as_str()), "https://relay-a.example/" ); - first.finish(); - // The origin retires a finished source on a spawned task; time is paused, so - // this advances the clock instantly. - tokio::time::sleep(std::time::Duration::from_millis(1)).await; + drop(first); let scanned = nodes.scan_announced(&mut announced); assert!( @@ -402,7 +397,7 @@ mod tests { } #[tokio::test] - async fn duplicate_hop_ids_do_not_resolve_inbound_connections() { + async fn duplicate_origin_ids_do_not_resolve_inbound_connections() { let origin = moq_tokio::origin::spawn(Hop::new(100).unwrap()); let nodes = Nodes::new(origin.clone()); let _first = announced_node(&origin, "https://relay-b.example/", &[200], 1).await; diff --git a/rs/moq-relay/src/web.rs b/rs/moq-relay/src/web.rs index 274deedac3f..2a3553d06ce 100644 --- a/rs/moq-relay/src/web.rs +++ b/rs/moq-relay/src/web.rs @@ -687,13 +687,9 @@ async fn serve_announced( let mut announced = origin.consume().announced(); let mut broadcasts = Vec::new(); - while let Some(moq_net::announce::Update { - path: suffix, - broadcast, - }) = announced.try_next() - { - if broadcast.is_some() { - broadcasts.push(suffix); + while let Some(update) = announced.try_next() { + if update.active { + broadcasts.push(update.prefix); } } @@ -744,13 +740,10 @@ async fn serve_fetch( let result = tokio::time::timeout_at(deadline, async { // NOTE: The auth token is already scoped to the broadcast. - // Block until the broadcast has been announced (within the fetch deadline) so + // Block until a route covers the broadcast (within the fetch deadline) so // freshly-connected subscribers don't get a spurious 404 before gossip arrives. - let broadcast = origin - .consume() - .announced_broadcast("") - .await - .ok_or(StatusCode::NOT_FOUND)?; + let consumer = origin.consume(); + let broadcast = consumer.routed_broadcast("").await.map_err(|_| StatusCode::NOT_FOUND)?; let group = match params.group { // "latest" needs a live subscription to learn the newest sequence, since a // fetch can only retrieve a sequence you already know. Once it's known, fetch diff --git a/rs/moq-relay/tests/auth_lifetime.rs b/rs/moq-relay/tests/auth_lifetime.rs index 520b0d792b6..3b0f1591ba0 100644 --- a/rs/moq-relay/tests/auth_lifetime.rs +++ b/rs/moq-relay/tests/auth_lifetime.rs @@ -176,8 +176,9 @@ fn room_url(scheme: &str, port: u16, key: &Key, claims: &moq_token::Claims) -> u /// round-trips. Returns both sessions so the caller can watch them close. async fn connect_and_round_trip(url: &url::Url) -> (moq_tokio::Connection, moq_tokio::Connection) { let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); let mut group = track.append_group().expect("append group"); @@ -199,7 +200,8 @@ async fn connect_and_round_trip(url: &url::Url) -> (moq_tokio::Connection, moq_t .expect("publisher connect failed"); let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let sub_session = tokio::time::timeout( TIMEOUT, client() @@ -212,12 +214,16 @@ async fn connect_and_round_trip(url: &url::Url) -> (moq_tokio::Connection, moq_t .expect("subscriber connect timeout") .expect("subscriber connect failed"); - let moq_net::announce::Update { path, broadcast: bc } = tokio::time::timeout(TIMEOUT, announcements.next()) + let update = tokio::time::timeout(TIMEOUT, announcements.next()) .await .expect("announcement timeout") .expect("origin closed"); - assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let bc = sub_consumer + .request_broadcast("test") + .await + .expect("announced broadcast resolves"); let mut track_sub = bc.track("video").unwrap().subscribe(None).await.expect("consume_track"); let mut group_sub = tokio::time::timeout(TIMEOUT, track_sub.recv_group()) diff --git a/rs/moq-relay/tests/cluster_unknown.rs b/rs/moq-relay/tests/cluster_unknown.rs index 098cad127c1..711d33f701e 100644 --- a/rs/moq-relay/tests/cluster_unknown.rs +++ b/rs/moq-relay/tests/cluster_unknown.rs @@ -67,6 +67,7 @@ fn client(version: Option) -> moq_tokio::Client { struct Publisher { _broadcast: moq_net::broadcast::Producer, + _announcement: moq_net::announce::Producer, _session: moq_tokio::Connection, streamer: tokio::task::AbortHandle, } @@ -83,9 +84,8 @@ impl Drop for Publisher { async fn publish_version(port: u16, version: &str) -> Publisher { let url: Url = format!("tcp://127.0.0.1:{port}").parse().expect("parse url"); let origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = origin - .create_broadcast(PATH, moq_net::broadcast::Route::new().with_announce(true)) - .expect("create broadcast"); + let mut broadcast = origin.create_broadcast(PATH).expect("create broadcast"); + let announcement = origin.announce(PATH, Default::default()).expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); // Stream like a real publisher: a fresh group every 100ms, so a subscriber @@ -117,6 +117,7 @@ async fn publish_version(port: u16, version: &str) -> Publisher { Publisher { _broadcast: broadcast, + _announcement: announcement, _session: session, streamer, } @@ -143,10 +144,14 @@ async fn read_first_frame(port: u16) -> Result, String> { // Wait for the announcement rather than asking the moment the session connects: // `request_broadcast` answers on the spot, so it would race the announcement that // makes the path routable. - let broadcast = tokio::time::timeout(TIMEOUT, consumer.announced_broadcast(PATH)) + tokio::time::timeout(TIMEOUT, consumer.routed(PATH)) .await - .map_err(|_| "announced_broadcast timed out".to_string())? + .map_err(|_| "routed timed out".to_string())? .ok_or_else(|| "origin closed before the broadcast was announced".to_string())?; + let broadcast = consumer + .request_broadcast(PATH) + .await + .map_err(|err| format!("broadcast unroutable: {err}"))?; // This verifies route propagation rather than real-time backlog skipping. Give // every hop enough tolerance for the next 100ms group to arrive while the @@ -189,7 +194,7 @@ async fn watch_announces(port: u16, window: Duration) -> Vec<(String, bool)> { let mut updates = Vec::new(); let deadline = tokio::time::Instant::now() + window; while let Ok(Some(update)) = tokio::time::timeout_at(deadline, announced.next()).await { - updates.push((update.path.as_str().to_string(), update.broadcast.is_some())); + updates.push((update.prefix.as_path().as_str().to_string(), update.active)); } updates } diff --git a/rs/moq-relay/tests/goaway_cluster.rs b/rs/moq-relay/tests/goaway_cluster.rs index d6cebd2108d..6901dbdc307 100644 --- a/rs/moq-relay/tests/goaway_cluster.rs +++ b/rs/moq-relay/tests/goaway_cluster.rs @@ -175,16 +175,19 @@ async fn wait_listening(port: u16) { } } -/// An upstream GOAWAY with a redirect migrates the cluster dial to the sibling -/// with no gap and no unannounce visible on the cluster origin. +/// An upstream GOAWAY with a redirect migrates the cluster dial to the sibling. +/// The draining session keeps serving through the handover window, and the path +/// never retracts on the cluster origin (route re-pricing and the sibling's +/// announce surface as metadata updates, not churn). async fn cluster_migrates_on_upstream_goaway_inner() { let _ = rustls::crypto::aws_lc_rs::default_provider().install_default(); tokio::time::timeout(TEST_TIMEOUT, async { // ── the shared "live" broadcast both siblings can serve ───────── let upstream_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = upstream_origin - .create_broadcast("cam", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = upstream_origin.create_broadcast("cam").expect("create broadcast"); + let _announce_broadcast = upstream_origin + .announce("cam", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); @@ -212,10 +215,11 @@ async fn cluster_migrates_on_upstream_goaway_inner() { // ── downstream consumer on the cluster origin ─────────────────── let consumer = cluster.origin.consume(); - let bc = consumer - .announced_broadcast("cam") + consumer + .routed("cam") .await .expect("broadcast announced through sibling A"); + let bc = consumer.request_broadcast("cam").await.expect("broadcast resolves"); let mut sub = bc .track("video") .expect("track handle") @@ -235,11 +239,12 @@ async fn cluster_migrates_on_upstream_goaway_inner() { b"g0"[..] ); - // Watch for unannounce during the swap: seamless migration must never - // unannounce the path. + // Watch for retraction during the swap: the migration must never + // unannounce the path (metadata updates are expected: the drain + // re-prices the old route and the sibling announces its own). let mut announcements = cluster.origin.consume().announced(); let first = announcements.next().await.expect("initial announce"); - assert_eq!(first.path.as_str(), "cam"); + assert_eq!(first.prefix.as_path().as_str(), "cam"); // ── sibling A drains with a redirect to sibling B ──────────────── session_a @@ -272,13 +277,16 @@ async fn cluster_migrates_on_upstream_goaway_inner() { // handover window at the latest). session_a.closed().await; - // No unannounce leaked to the origin during the whole swap: the next - // announce event (with a generous bound) must never arrive. - let churn = tokio::time::timeout(Duration::from_millis(500), announcements.next()).await; - assert!( - churn.is_err(), - "migration must not churn announces on the cluster origin" - ); + // No retraction leaked to the origin during the whole swap. Metadata + // updates (the drain re-pricing, the sibling's route) are expected and + // harmless; an inactive event means the path flapped. + loop { + match tokio::time::timeout(Duration::from_millis(500), announcements.next()).await { + Err(_) => break, + Ok(Some(update)) if update.active => continue, + Ok(event) => panic!("migration must not retract the path on the cluster origin: {event:?}"), + } + } cluster_run.abort(); }) @@ -359,19 +367,25 @@ async fn spawn_relay_with_upstream( /// SUBSCRIBER /// ``` /// -/// Proves that with the route/resume machinery: +/// Proves the failover contract across a GOAWAY: /// 1. Content flows TOP -> MID-A -> BOTTOM -> subscriber. /// 2. On MID-A's GOAWAY naming MID-B, BOTTOM reconnects there (positively /// gated: MID-B's first inbound connection can only be that reconnect). -/// 3. The subscriber sees contiguous, duplicate-free groups across the swap. -/// 4. No GOAWAY leaks to the subscriber's own session. +/// 3. The draining MID-A leg keeps serving through the handover window, so +/// every group published across the swap arrives exactly once. +/// 4. Once the old leg closes, the subscription through it ends (failover is +/// a resubscribe, not a transparent splice) and a fresh subscription +/// through MID-B carries the rest. +/// 5. No GOAWAY leaks to the subscriber's own session, and the path never +/// retracts under the subscriber. async fn cluster_diamond_goaway_seamless_failover_inner() { let _ = rustls::crypto::aws_lc_rs::default_provider().install_default(); // ── TOP: origin server serving the same broadcast to both mids ────── let top_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = top_origin - .create_broadcast("diamond", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = top_origin.create_broadcast("diamond").expect("create broadcast"); + let _announce_broadcast = top_origin + .announce("diamond", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); @@ -436,18 +450,19 @@ async fn cluster_diamond_goaway_seamless_failover_inner() { .await .expect("subscriber connect"); - // Watch announcements for the whole test: a seamless failover must never + // Watch announcements for the whole test: the failover must never // unannounce the broadcast under the subscriber. let mut announcements = sub_origin.consume().announced(); let first = within("broadcast announced through the MID-A leg", announcements.next()) .await .expect("origin closed before the announce"); - assert_eq!(first.path.as_str(), "diamond"); + assert_eq!(first.prefix.as_path().as_str(), "diamond"); - let bc = within( - "broadcast resolves on the subscriber origin", - sub_origin.consume().announced_broadcast("diamond"), - ) + let bc = within("broadcast resolves on the subscriber origin", async { + let consumer = sub_origin.consume(); + consumer.routed("diamond").await?; + consumer.request_broadcast("diamond").await.ok() + }) .await .expect("broadcast announced"); // The age budget is what makes the completeness check below meaningful: this test @@ -534,27 +549,60 @@ async fn cluster_diamond_goaway_seamless_failover_inner() { within("old session drains after the swap", session_bottom_on_a.closed()).await; // Cut MID-A off from TOP so it can never receive (let alone forward) new // groups. Anything delivered from here on MUST have flowed TOP -> MID-B -> - // BOTTOM, positively proving the new leg carries the subscription. + // BOTTOM, positively proving the new leg carries the resubscribe. drop(mid_a_upstream); - const POST_DRAIN_LAST: u64 = LAST_GROUP + 3; - for seq in (LAST_GROUP + 1)..=POST_DRAIN_LAST { - let mut g = track.append_group().expect("append group"); - for f in 0..FRAMES_PER_GROUP { - let payload = format!("diamond_g{seq}_f{f}"); - g.write_frame(moq_net::Timestamp::ZERO, payload.as_bytes()) - .expect("write frame"); + // The subscription was served through the MID-A leg, so its close ends it: + // failover is a resubscribe, not a transparent splice. Drain any groups + // still in flight, then observe the end. + within("old subscription ends with the drained leg", async { + while let Ok(Some(_)) = sub.recv_group().await {} + }) + .await; + + // Resubscribe on the same broadcast handle: the subscriber's session with + // BOTTOM is intact, and BOTTOM now resolves the track through MID-B. + drop(bc); + let bc = within("broadcast re-resolves after the failover", async { + let consumer = sub_origin.consume(); + consumer.request_broadcast("diamond").await.ok() + }) + .await + .expect("broadcast re-resolves"); + let mut sub = within( + "resubscribe after the failover", + bc.track("video") + .expect("track handle") + .subscribe(moq_net::track::Subscription::default().with_max_age(Duration::from_secs(60))), + ) + .await + .expect("resubscribe"); + + // A lite-05 subscription starts at the live edge (its Max Age is a staleness + // tolerance, not a replay request), so publish at a steady cadence and collect + // what lands once the fresh chain establishes. MID-A is severed, so any + // post-drain group can only have flowed TOP -> MID-B -> BOTTOM. + const POST_DRAIN_LAST: u64 = LAST_GROUP + 40; + let post_publisher = tokio::spawn(async move { + for seq in (LAST_GROUP + 1)..=POST_DRAIN_LAST { + let mut g = track.append_group().expect("append group"); + for f in 0..FRAMES_PER_GROUP { + let payload = format!("diamond_g{seq}_f{f}"); + g.write_frame(moq_net::Timestamp::ZERO, payload.as_bytes()) + .expect("write frame"); + } + g.finish().expect("finish"); + tokio::time::sleep(Duration::from_millis(50)).await; } - g.finish().expect("finish"); - } - for _ in (LAST_GROUP + 1)..=POST_DRAIN_LAST { - collect_group(&mut sub, &mut seen, FRAMES_PER_GROUP, "post-drain (MID-B leg only)").await; + }); + + // Three distinct post-drain groups, every frame verified, proves the new leg + // carries the subscription (the establish may still see the pre-swap edge). + let mut post = BTreeSet::new(); + while post.iter().filter(|seq| **seq > LAST_GROUP).count() < 3 { + collect_group(&mut sub, &mut post, FRAMES_PER_GROUP, "post-drain (MID-B leg only)").await; } - assert_eq!( - seen, - (0..=POST_DRAIN_LAST).collect::>(), - "the new leg alone must carry the rest, exactly once each" - ); + post_publisher.abort(); // ── no GOAWAY cascade to the downstream subscriber ─────────────────── assert!( @@ -573,9 +621,15 @@ async fn cluster_diamond_goaway_seamless_failover_inner() { "downstream subscriber received a GOAWAY (the relay should absorb it): {leaked:?}" ); - // ── announcement stability: the path never churned under the swap ──── - let churn = tokio::time::timeout(Duration::from_millis(500), announcements.next()).await; - assert!(churn.is_err(), "failover must not churn announces under the subscriber"); + // ── announcement stability: the path never retracted under the swap ── + // Metadata updates (route re-pricing, the new leg's hops) are expected. + loop { + match tokio::time::timeout(Duration::from_millis(500), announcements.next()).await { + Err(_) => break, + Ok(Some(update)) if update.active => continue, + Ok(event) => panic!("failover must not retract the path under the subscriber: {event:?}"), + } + } } /// Receive the next group, assert every frame's payload and the exact frame count @@ -617,14 +671,15 @@ async fn collect_group(sub: &mut moq_net::track::Subscriber, seen: &mut BTreeSet } /// An empty-URI GOAWAY ("reconnect to me") makes the cluster redial the same -/// endpoint. The upstream keeps its origin across the restart, so the rejoined -/// route resumes delivery. +/// endpoint. The subscription through the drained session ends with it, and a +/// resubscribe through the redialed session resumes delivery. async fn cluster_reconnects_on_empty_uri_goaway_inner() { let _ = rustls::crypto::aws_lc_rs::default_provider().install_default(); let upstream_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = upstream_origin - .create_broadcast("cam", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = upstream_origin.create_broadcast("cam").expect("create broadcast"); + let _announce_broadcast = upstream_origin + .announce("cam", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); @@ -648,10 +703,11 @@ async fn cluster_reconnects_on_empty_uri_goaway_inner() { .expect("accept channel closed"); // Downstream consumer sees group 0 through the first session. - let bc = within( - "broadcast announced", - cluster.origin.consume().announced_broadcast("cam"), - ) + let bc = within("broadcast announced", async { + let consumer = cluster.origin.consume(); + consumer.routed("cam").await?; + consumer.request_broadcast("cam").await.ok() + }) .await .expect("broadcast announced"); let mut sub = within("subscribe", async { @@ -688,17 +744,40 @@ async fn cluster_reconnects_on_empty_uri_goaway_inner() { within("old session drains", first_dial.closed()).await; - // Delivery continues on the redialed session (same origin, same publisher - // identity, so the rejoined route resumes at the boundary). + // The broadcast was materialized through the first session, so its close ends + // the subscription: failover is a resubscribe, not a transparent splice. + within("old subscription ends with the session", async { + while let Ok(Some(_)) = sub.recv_group().await {} + }) + .await; + + // Re-request through the redialed session's route and resubscribe. + let bc = within("broadcast resolves through the redial", async { + cluster.origin.consume().request_broadcast("cam").await.ok() + }) + .await + .expect("broadcast resolves"); + let mut sub = within("resubscribe", async { + bc.track("video").expect("track handle").subscribe(None).await + }) + .await + .expect("resubscribe"); + let mut g = track.append_group().expect("append group"); g.write_frame(moq_net::Timestamp::ZERO, b"empty_g1".as_ref()) .expect("write frame"); g.finish().expect("finish"); - let mut g1 = within("recv g1 after the redial", sub.recv_group()) - .await - .expect("recv") - .expect("track ended early"); - assert_eq!(g1.sequence, 1, "delivery must resume contiguously after the redial"); + // The fresh subscription may start at the retained group 0; skip up to g1. + let mut g1 = loop { + let g = within("recv g1 after the redial", sub.recv_group()) + .await + .expect("recv") + .expect("track ended early"); + if g.sequence >= 1 { + break g; + } + }; + assert_eq!(g1.sequence, 1, "the redialed session must deliver the new group"); assert_eq!( g1.read_frame().await.expect("read").expect("frame").payload[..], b"empty_g1"[..] diff --git a/rs/moq-relay/tests/runtime_uring.rs b/rs/moq-relay/tests/runtime_uring.rs index 5f3bd2fda89..d6604f1325a 100644 --- a/rs/moq-relay/tests/runtime_uring.rs +++ b/rs/moq-relay/tests/runtime_uring.rs @@ -136,9 +136,8 @@ async fn uring_workers_serve_webtransport_and_raw_quic() { let raw_url: url::Url = format!("moql://127.0.0.1:{port}/uring").parse().expect("parse url"); let origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) - .expect("create broadcast"); + let mut broadcast = origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = origin.announce("test", Default::default()).expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); let mut group = track.append_group().expect("append group"); group @@ -152,18 +151,23 @@ async fn uring_workers_serve_webtransport_and_raw_quic() { let mut subscribers = Vec::new(); for url in [&wt_url, &raw_url, &wt_url, &raw_url] { let origin = moq_tokio::origin::spawn(Hop::random()); - let announced = origin.consume().announced(); + let consumer = origin.consume(); + let announced = consumer.announced(); let connection = connect(client().with_subscriber(origin), url.clone()).await; - subscribers.push((connection, announced)); + subscribers.push((connection, consumer, announced)); } - for (index, (_connection, announced)) in subscribers.iter_mut().enumerate() { - let moq_net::announce::Update { path, broadcast } = tokio::time::timeout(TIMEOUT, announced.next()) + for (index, (_connection, consumer, announced)) in subscribers.iter_mut().enumerate() { + let update = tokio::time::timeout(TIMEOUT, announced.next()) .await .unwrap_or_else(|_| panic!("subscriber {index} announcement timeout")) .expect("origin closed"); - assert_eq!(path.as_str(), "test"); - let broadcast = broadcast.expect("expected announce, got unannounce"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let broadcast = tokio::time::timeout(TIMEOUT, consumer.request_broadcast("test")) + .await + .unwrap_or_else(|_| panic!("subscriber {index} request timeout")) + .expect("announced broadcast resolves"); let mut subscription = broadcast .track("video") @@ -294,9 +298,8 @@ async fn an_mtls_client_authenticates_without_a_token() { // connecting proves nothing. let url: url::Url = format!("moql://127.0.0.1:{port}/mtls").parse().expect("parse url"); let origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) - .expect("create broadcast"); + let mut broadcast = origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = origin.announce("test", Default::default()).expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); let mut group = track.append_group().expect("append group"); group @@ -306,18 +309,20 @@ async fn an_mtls_client_authenticates_without_a_token() { let publisher = connect(client().with_publisher(&origin), url.clone()).await; let subscriber_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announced = subscriber_origin.consume().announced(); + let consumer = subscriber_origin.consume(); + let mut announced = consumer.announced(); let subscriber = connect(client().with_subscriber(subscriber_origin), url).await; - let moq_net::announce::Update { - path, - broadcast: announced, - } = tokio::time::timeout(TIMEOUT, announced.next()) + let update = tokio::time::timeout(TIMEOUT, announced.next()) .await .expect("announcement timeout") .expect("origin closed"); - assert_eq!(path.as_str(), "test"); - let announced = announced.expect("expected announce, got unannounce"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let announced = tokio::time::timeout(TIMEOUT, consumer.request_broadcast("test")) + .await + .expect("request timeout") + .expect("announced broadcast resolves"); let mut subscription = announced .track("video") .unwrap() diff --git a/rs/moq-relay/tests/runtime_workers.rs b/rs/moq-relay/tests/runtime_workers.rs index 67b60f32d3a..308e99f6af5 100644 --- a/rs/moq-relay/tests/runtime_workers.rs +++ b/rs/moq-relay/tests/runtime_workers.rs @@ -111,9 +111,8 @@ async fn workers_serve_quic_and_share_one_origin() { // ── publisher ─────────────────────────────────────────────────── let origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) - .expect("create broadcast"); + let mut broadcast = origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = origin.announce("test", Default::default()).expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); let mut group = track.append_group().expect("append group"); group @@ -127,18 +126,23 @@ async fn workers_serve_quic_and_share_one_origin() { let mut subscribers = Vec::new(); for _ in 0..WORKERS { let origin = moq_tokio::origin::spawn(Hop::random()); - let announced = origin.consume().announced(); + let consumer = origin.consume(); + let announced = consumer.announced(); let connection = connect(client().with_subscriber(origin), url.clone()).await; - subscribers.push((connection, announced)); + subscribers.push((connection, consumer, announced)); } - for (index, (_connection, announced)) in subscribers.iter_mut().enumerate() { - let moq_net::announce::Update { path, broadcast } = tokio::time::timeout(TIMEOUT, announced.next()) + for (index, (_connection, consumer, announced)) in subscribers.iter_mut().enumerate() { + let update = tokio::time::timeout(TIMEOUT, announced.next()) .await .unwrap_or_else(|_| panic!("subscriber {index} announcement timeout")) .expect("origin closed"); - assert_eq!(path.as_str(), "test"); - let broadcast = broadcast.expect("expected announce, got unannounce"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let broadcast = tokio::time::timeout(TIMEOUT, consumer.request_broadcast("test")) + .await + .unwrap_or_else(|_| panic!("subscriber {index} request timeout")) + .expect("announced broadcast resolves"); let mut subscription = broadcast .track("video") diff --git a/rs/moq-relay/tests/smoke.rs b/rs/moq-relay/tests/smoke.rs index 1d712073d89..d2e83e248b3 100644 --- a/rs/moq-relay/tests/smoke.rs +++ b/rs/moq-relay/tests/smoke.rs @@ -177,8 +177,9 @@ async fn relay_websocket_round_trip_uses_newest_version() { // ── publisher ─────────────────────────────────────────────────── let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); let mut group = track.append_group().expect("append group"); @@ -200,7 +201,8 @@ async fn relay_websocket_round_trip_uses_newest_version() { // ── subscriber ────────────────────────────────────────────────── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let (_client, sub_connection) = tokio::time::timeout(TIMEOUT, connect_once(client().with_subscriber(sub_origin), url)) @@ -214,13 +216,18 @@ async fn relay_websocket_round_trip_uses_newest_version() { ); // ── data path ─────────────────────────────────────────────────── - let moq_net::announce::Update { path, broadcast: bc } = tokio::time::timeout(TIMEOUT, announcements.next()) + let update = tokio::time::timeout(TIMEOUT, announcements.next()) .await .expect("announcement timeout") .expect("origin closed"); + let path = update.prefix.as_path().to_owned(); + assert!(update.active, "expected announce, got retraction"); // Auth root for `/smoke` is "smoke"; the broadcast "test" announces underneath. assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + let bc = sub_consumer + .request_broadcast(&path) + .await + .expect("announced broadcast resolves"); let mut track_sub = bc.track("video").unwrap().subscribe(None).await.expect("consume_track"); let mut group_sub = tokio::time::timeout(TIMEOUT, track_sub.recv_group()) @@ -370,8 +377,9 @@ async fn relay_websocket_root_path_upgrades() { // ── publisher ─────────────────────────────────────────────────── let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); let mut group = track.append_group().expect("append group"); @@ -390,7 +398,8 @@ async fn relay_websocket_root_path_upgrades() { // ── subscriber ────────────────────────────────────────────────── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let (_client, sub_connection) = tokio::time::timeout(TIMEOUT, connect_once(client().with_subscriber(sub_origin), url)) .await @@ -400,12 +409,17 @@ async fn relay_websocket_root_path_upgrades() { // ── data path ─────────────────────────────────────────────────── // The root auth scope is the empty path, so the broadcast announces at its // own name with no prefix. - let moq_net::announce::Update { path, broadcast: bc } = tokio::time::timeout(TIMEOUT, announcements.next()) + let update = tokio::time::timeout(TIMEOUT, announcements.next()) .await .expect("announcement timeout") .expect("origin closed"); + let path = update.prefix.as_path().to_owned(); + assert!(update.active, "expected announce, got retraction"); assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + let bc = sub_consumer + .request_broadcast(&path) + .await + .expect("announced broadcast resolves"); let mut track_sub = bc.track("video").unwrap().subscribe(None).await.expect("consume_track"); let mut group_sub = tokio::time::timeout(TIMEOUT, track_sub.recv_group()) @@ -437,9 +451,8 @@ async fn two_publish_only_clients_coexist() { // ── two publish-only publishers, each serving a distinct broadcast ── let pub_a = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast_a = pub_a - .create_broadcast("alpha", moq_net::broadcast::Route::new().with_announce(true)) - .expect("create broadcast a"); + let mut broadcast_a = pub_a.create_broadcast("alpha").expect("create broadcast a"); + let _announce_broadcast_a = pub_a.announce("alpha", Default::default()).expect("create broadcast a"); let mut track_a = broadcast_a.create_track("video", None).expect("create track a"); track_a .append_group() @@ -448,9 +461,8 @@ async fn two_publish_only_clients_coexist() { .expect("write frame a"); let pub_b = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast_b = pub_b - .create_broadcast("beta", moq_net::broadcast::Route::new().with_announce(true)) - .expect("create broadcast b"); + let mut broadcast_b = pub_b.create_broadcast("beta").expect("create broadcast b"); + let _announce_broadcast_b = pub_b.announce("beta", Default::default()).expect("create broadcast b"); let mut track_b = broadcast_b.create_track("video", None).expect("create track b"); track_b .append_group() @@ -475,7 +487,8 @@ async fn two_publish_only_clients_coexist() { // ── one subscriber should see broadcasts from both publish-only clients ── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let (_client, sub_connection) = tokio::time::timeout(TIMEOUT, connect_once(client().with_subscriber(sub_origin), url)) .await @@ -484,12 +497,12 @@ async fn two_publish_only_clients_coexist() { let mut seen = std::collections::HashSet::new(); while seen.len() < 2 { - let moq_net::announce::Update { path, broadcast: bc } = tokio::time::timeout(TIMEOUT, announcements.next()) + let update = tokio::time::timeout(TIMEOUT, announcements.next()) .await .expect("announcement timeout") .expect("origin closed"); - if bc.is_some() { - seen.insert(path.as_str().to_owned()); + if update.active { + seen.insert(update.prefix.as_path().as_str().to_owned()); } } assert!( @@ -595,8 +608,9 @@ async fn internal_tcp_round_trip() { // ── publisher ─────────────────────────────────────────────────── let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); let mut group = track.append_group().expect("append group"); @@ -620,7 +634,8 @@ async fn internal_tcp_round_trip() { // ── subscriber ────────────────────────────────────────────────── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let (_client, sub_connection) = tokio::time::timeout(TIMEOUT, connect_once(client().with_subscriber(sub_origin), url)) .await @@ -630,12 +645,17 @@ async fn internal_tcp_round_trip() { // ── data path ─────────────────────────────────────────────────── // The internal listener grants the empty root, so the broadcast announces // at its own name with no path prefix. - let moq_net::announce::Update { path, broadcast: bc } = tokio::time::timeout(TIMEOUT, announcements.next()) + let update = tokio::time::timeout(TIMEOUT, announcements.next()) .await .expect("announcement timeout") .expect("origin closed"); + let path = update.prefix.as_path().to_owned(); + assert!(update.active, "expected announce, got retraction"); assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + let bc = sub_consumer + .request_broadcast(&path) + .await + .expect("announced broadcast resolves"); let mut track_sub = bc.track("video").unwrap().subscribe(None).await.expect("consume_track"); let mut group_sub = tokio::time::timeout(TIMEOUT, track_sub.recv_group()) @@ -708,8 +728,9 @@ async fn internal_unix_round_trip() { // ── publisher ─────────────────────────────────────────────────── let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); let mut group = track.append_group().expect("append group"); @@ -733,7 +754,8 @@ async fn internal_unix_round_trip() { // ── subscriber ────────────────────────────────────────────────── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let (_client, sub_connection) = tokio::time::timeout(TIMEOUT, connect_once(client().with_subscriber(sub_origin), url)) .await @@ -741,17 +763,21 @@ async fn internal_unix_round_trip() { .expect("subscriber connect failed"); // ── data path ─────────────────────────────────────────────────── - let moq_net::announce::Update { - path: announced_path, - broadcast: bc, - } = tokio::time::timeout(TIMEOUT, announcements.next()) + let update = tokio::time::timeout(TIMEOUT, announcements.next()) .await .expect("announcement timeout") .expect("origin closed"); - assert_eq!(announced_path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timeout") + .expect("announced broadcast resolves"); - let mut track_sub = bc.track("video").unwrap().subscribe(None).await.expect("consume_track"); + let mut track_sub = tokio::time::timeout(TIMEOUT, async { bc.track("video").unwrap().subscribe(None).await }) + .await + .expect("subscribe timeout") + .expect("consume_track"); let mut group_sub = tokio::time::timeout(TIMEOUT, track_sub.recv_group()) .await .expect("recv_group timeout") @@ -796,8 +822,9 @@ fn path_versions() -> Vec { /// to that root). async fn path_round_trip(version: moq_net::Version, pub_url: url::Url, sub_url: url::Url, broadcast: &str) -> String { let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut bc = pub_origin - .create_broadcast(broadcast, moq_net::broadcast::Route::new().with_announce(true)) + let mut bc = pub_origin.create_broadcast(broadcast).expect("create broadcast"); + let _announce_bc = pub_origin + .announce(broadcast, Default::default()) .expect("create broadcast"); let mut track = bc.create_track("video", None).expect("create track"); let mut group = track.append_group().expect("append group"); @@ -813,17 +840,19 @@ async fn path_round_trip(version: moq_net::Version, pub_url: url::Url, sub_url: .expect("publisher connect failed"); let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let sub_client = client_version(Some(version)).with_subscriber(sub_origin); let (_client, sub_connection) = tokio::time::timeout(TIMEOUT, connect_once(sub_client, sub_url)) .await .expect("subscriber connect timeout") .expect("subscriber connect failed"); - let moq_net::announce::Update { path, .. } = tokio::time::timeout(TIMEOUT, announcements.next()) + let update = tokio::time::timeout(TIMEOUT, announcements.next()) .await .expect("announcement timeout") .expect("origin closed"); + let path = update.prefix.as_path().to_owned(); drop(track); drop(bc); diff --git a/rs/moq-rtc/src/server/mod.rs b/rs/moq-rtc/src/server/mod.rs index 6255e0f9c27..01ba9f5212d 100644 --- a/rs/moq-rtc/src/server/mod.rs +++ b/rs/moq-rtc/src/server/mod.rs @@ -65,6 +65,9 @@ struct AcceptedSession { // WHIP only: a clone of the ingest broadcast, so a deliberate DELETE can // finish() it: a clean end instead of an abort error. broadcast: Option, + // WHIP only: the route advertising the broadcast; dropping it retracts. + // Held for the session's lifetime, released (retracting) when it ends. + _announcement: Option, } impl AcceptedSession { diff --git a/rs/moq-rtc/src/server/whep.rs b/rs/moq-rtc/src/server/whep.rs index 400b122a4ab..8aa6f44696f 100644 --- a/rs/moq-rtc/src/server/whep.rs +++ b/rs/moq-rtc/src/server/whep.rs @@ -158,6 +158,7 @@ pub async fn accept( cancel: Some(cancel), role: "whep server", broadcast: None, + _announcement: None, }, }) } diff --git a/rs/moq-rtc/src/server/whip.rs b/rs/moq-rtc/src/server/whip.rs index c9234277924..aeda8ffd183 100644 --- a/rs/moq-rtc/src/server/whip.rs +++ b/rs/moq-rtc/src/server/whip.rs @@ -94,13 +94,17 @@ pub async fn accept( offer: &str, ) -> Result { let offer = sdp::parse_offer(offer)?; + let broadcast = broadcast.as_path(); // Create the broadcast on the publish origin before negotiating, so a // fast subscriber doesn't see a 404 in the gap between the SDP answer // and the first RTP packet. let producer = publisher - .create_broadcast(broadcast, moq_net::broadcast::Route::new().with_announce(true)) + .create_broadcast(&broadcast) .map_err(|err| Error::Other(anyhow::anyhow!("failed to create broadcast: {err}")))?; + let announcement = publisher + .announce(&broadcast, moq_net::origin::Route::default()) + .map_err(|err| Error::Other(anyhow::anyhow!("failed to announce broadcast: {err}")))?; let handle = producer.clone(); let sink = Box::new(IngestSink::new(producer, server.config().max_age)?); @@ -137,6 +141,7 @@ pub async fn accept( cancel: Some(cancel), role: "whip server", broadcast: Some(handle), + _announcement: Some(announcement), }, }) } diff --git a/rs/moq-rtmp/src/dial.rs b/rs/moq-rtmp/src/dial.rs index a607633e502..41491395d8f 100644 --- a/rs/moq-rtmp/src/dial.rs +++ b/rs/moq-rtmp/src/dial.rs @@ -35,7 +35,7 @@ use crate::rml::sessions::{ use crate::rml::time::RtmpTimestamp; use bytes::Bytes; use moq_mux::container::flv::{Export as FlvExport, Import as FlvImport}; -use moq_net::{broadcast, origin}; +use moq_net::origin; use tokio::io::{AsyncReadExt, AsyncWriteExt}; use tokio::net::TcpStream; @@ -464,13 +464,18 @@ struct Publisher { // A clone of the importer's producer, so a deliberate end can finish() the // broadcast (prompt unannounce) even though the importer owns it. broadcast: moq_net::broadcast::Producer, + // The route advertising the path; dropping it retracts. + _announcement: moq_net::announce::Producer, } impl Publisher { fn new(origin: &origin::Producer, path: &str, max_age: Option) -> anyhow::Result { let mut broadcast = origin - .create_broadcast(path, broadcast::Route::new().with_announce(true)) + .create_broadcast(path) .map_err(|err| anyhow::anyhow!("broadcast '{path}' could not be published: {err}"))?; + let announcement = origin + .announce(path, moq_net::origin::Route::default()) + .map_err(|err| anyhow::anyhow!("broadcast '{path}' could not be announced: {err}"))?; let config = moq_mux::catalog::Config::default().with_max_age(max_age); let catalog = moq_mux::catalog::Producer::with_config(&mut broadcast, config)?; let handle = broadcast.clone(); @@ -481,6 +486,7 @@ impl Publisher { Ok(Self { importer, broadcast: handle, + _announcement: announcement, }) } @@ -536,9 +542,8 @@ mod tests { vframe.extend_from_slice(&[0, 0, 0, 5, 0x65, 0x88, 0x84, 0x21, 0x00]); let server_origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let mut broadcast = server_origin - .create_broadcast("live/cam0", broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut broadcast = server_origin.create_broadcast("live/cam0").unwrap(); + let _announcement = server_origin.announce("live/cam0", Default::default()).unwrap(); let catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); let mut importer = FlvImport::new(broadcast, catalog.reserve()); importer.decode(&flv::file_header()).unwrap(); @@ -568,10 +573,11 @@ mod tests { }); // The republished broadcast should show up in the client's origin. - let broadcast = tokio::time::timeout(Duration::from_secs(5), announced.announced_broadcast("pulled/cam0")) + tokio::time::timeout(Duration::from_secs(5), announced.routed("pulled/cam0")) .await .expect("client republish timed out") .expect("broadcast announced in client origin"); + let broadcast = announced.request_broadcast("pulled/cam0").await.unwrap(); // It should carry a hang catalog track (proof the FLV demux produced real // media on the far side): subscribe to it and read one catalog frame. diff --git a/rs/moq-rtmp/src/server.rs b/rs/moq-rtmp/src/server.rs index 8447833fc2b..95344e1fd40 100644 --- a/rs/moq-rtmp/src/server.rs +++ b/rs/moq-rtmp/src/server.rs @@ -43,7 +43,7 @@ use futures::stream::FuturesUnordered; use hang::catalog::{AudioCodec, VideoCodec}; use moq_mux::catalog::{CatalogFormat, Stream as CatalogStream}; use moq_mux::container::flv::{Export as FlvExport, Import as FlvImport}; -use moq_net::{broadcast, origin}; +use moq_net::origin; use socket2::{SockRef, TcpKeepalive}; use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt, ReadBuf}; use tokio::net::{TcpListener, TcpStream}; @@ -678,9 +678,9 @@ impl Play { tracing::debug!(peer = %self.peer, %path, "viewer disconnected before play started"); return Ok(()); } - broadcast = tokio::time::timeout(PLAY_RESOLVE_TIMEOUT, origin.announced_broadcast(&path)) => { - match broadcast { - Ok(broadcast) => broadcast, + resolved = tokio::time::timeout(PLAY_RESOLVE_TIMEOUT, origin.routed_broadcast(&path)) => { + match resolved { + Ok(resolved) => resolved, Err(_) => { tracing::debug!(peer = %self.peer, %path, "play broadcast resolve timed out"); return self.reject("stream not found").await; @@ -688,7 +688,7 @@ impl Play { } } }; - let Some(broadcast) = broadcast else { + let Ok(broadcast) = broadcast else { tracing::debug!(peer = %self.peer, %path, "play broadcast unavailable"); return self.reject("stream not found").await; }; @@ -1244,13 +1244,16 @@ struct Publisher { // A clone of the importer's producer, so a deliberate end can finish() the // broadcast (prompt unannounce) even though the importer owns it. broadcast: moq_net::broadcast::Producer, + // The route advertising the path; dropping it retracts. + _announcement: moq_net::announce::Producer, } impl Publisher { /// Open a broadcast at `path` and prime the importer with the FLV file /// header, so subsequent tags decode against an initialized demuxer. fn new(origin: &origin::Producer, path: &str, max_age: Option) -> anyhow::Result { - let mut broadcast = origin.create_broadcast(path, broadcast::Route::new().with_announce(true))?; + let mut broadcast = origin.create_broadcast(path)?; + let announcement = origin.announce(path, moq_net::origin::Route::default())?; let config = moq_mux::catalog::Config::default().with_max_age(max_age); let catalog = moq_mux::catalog::Producer::with_config(&mut broadcast, config)?; let handle = broadcast.clone(); @@ -1262,6 +1265,7 @@ impl Publisher { Ok(Self { importer, broadcast: handle, + _announcement: announcement, }) } @@ -1590,7 +1594,9 @@ mod tests { let mut publisher = Publisher::new(&origin, "live/cam0", Some(Duration::from_secs(3))).unwrap(); publisher.push(flv::TAG_VIDEO, 0, &vseq).unwrap(); - let broadcast = origin.consume().announced_broadcast("live/cam0").await.unwrap(); + let consumer = origin.consume(); + consumer.routed("live/cam0").await.unwrap(); + let broadcast = consumer.request_broadcast("live/cam0").await.unwrap(); let info = broadcast.track("0.flv-v").unwrap().info().await.unwrap(); assert_eq!(info.max_age, Duration::from_secs(3)); } @@ -1617,9 +1623,8 @@ mod tests { // Publish the broadcast at `live/cam0` by feeding synthetic FLV to the importer. let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let mut broadcast = origin - .create_broadcast("live/cam0", broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut broadcast = origin.create_broadcast("live/cam0").unwrap(); + let _announcement = origin.announce("live/cam0", Default::default()).unwrap(); let catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); let mut importer = FlvImport::new(broadcast, catalog.reserve()); importer.decode(&flv::file_header()).unwrap(); @@ -1666,9 +1671,8 @@ mod tests { const VP9_KEYFRAME_320X240: &[u8] = &[0x82, 0x49, 0x83, 0x42, 0x20, 0x13, 0xf0, 0x0e, 0xf0, 0x00]; let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let mut broadcast = origin - .create_broadcast("live/cam0", broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut broadcast = origin.create_broadcast("live/cam0").unwrap(); + let _announcement = origin.announce("live/cam0", Default::default()).unwrap(); let catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); let mut importer = FlvImport::new(broadcast, catalog.reserve()); importer.decode(&flv::file_header()).unwrap(); @@ -1789,9 +1793,8 @@ mod tests { let frames = multitrack_body(CODED_FRAMES, &[(0, nalu(0x88)), (1, nalu(0x99))]); let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let mut broadcast = origin - .create_broadcast("live/cam0", broadcast::Route::new().with_announce(true)) - .unwrap(); + let mut broadcast = origin.create_broadcast("live/cam0").unwrap(); + let _announcement = origin.announce("live/cam0", Default::default()).unwrap(); let catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); let mut importer = FlvImport::new(broadcast, catalog.reserve()); importer.decode(&flv::file_header()).unwrap(); diff --git a/rs/moq-srt/src/server.rs b/rs/moq-srt/src/server.rs index 77e622d5c52..d1c256838ae 100644 --- a/rs/moq-srt/src/server.rs +++ b/rs/moq-srt/src/server.rs @@ -389,7 +389,7 @@ pub(crate) async fn serve_subscribe( mut socket: SrtSocket, latency: Duration, ) -> Result<()> { - // Resolve the broadcast, but watch the socket while we wait: `announced_broadcast` + // Resolve the broadcast, but watch the socket while we wait: `routed` // parks forever for a stream that is never published, and nothing else polls the // socket during that wait, so without this a caller who requests a non-existent // stream (or hangs up before it starts) would leak this task and its socket. diff --git a/rs/moq-srt/src/ts.rs b/rs/moq-srt/src/ts.rs index 5b9de9e9053..528400c5ce4 100644 --- a/rs/moq-srt/src/ts.rs +++ b/rs/moq-srt/src/ts.rs @@ -11,7 +11,7 @@ use std::time::Duration; use bytes::Bytes; use moq_mux::container::{Frame, ts}; -use moq_net::{broadcast, origin}; +use moq_net::origin; use crate::Result; @@ -30,6 +30,8 @@ pub struct Publisher { // A clone of the importer's producer, so a deliberate end can finish() the // broadcast (prompt unannounce) even though the importer owns it. broadcast: moq_net::broadcast::Producer, + // The route advertising the path; dropping it retracts. + _announcement: moq_net::announce::Producer, } impl Publisher { @@ -39,7 +41,8 @@ impl Publisher { /// `max_age` is the retention declared on the media tracks the importer mints: how /// long relays keep a non-latest group fetchable, or `None` for hang's own default. pub fn new(origin: &origin::Producer, path: &str, max_age: Option) -> Result { - let mut broadcast = origin.create_broadcast(path, broadcast::Route::new().with_announce(true))?; + let mut broadcast = origin.create_broadcast(path)?; + let announcement = origin.announce(path, moq_net::origin::Route::default())?; let config = moq_mux::catalog::Config::default() .with_catalog(moq_mux::catalog::hang::Catalog::::default()) .with_max_age(max_age); @@ -51,6 +54,7 @@ impl Publisher { Ok(Self { importer, broadcast: handle, + _announcement: announcement, }) } @@ -107,7 +111,7 @@ impl Subscriber { // Confirm the broadcast is in scope and wait for it to be announced (out-of-scope / // origin-closed -> `None`). The export re-resolves it (and any referenced sibling // broadcast, via the catalog `broadcast` field) through the origin. - if origin.announced_broadcast(path).await.is_none() { + if origin.routed(path).await.is_none() { return Ok(None); } @@ -206,7 +210,9 @@ mod tests { ts.extend_from_slice(&psi_packet(0x0100, &pmt(0x0101))); publisher.feed(Bytes::from(ts)).unwrap(); - let broadcast = origin.consume().announced_broadcast("live/cam0").await.unwrap(); + let consumer = origin.consume(); + consumer.routed("live/cam0").await.unwrap(); + let broadcast = consumer.request_broadcast("live/cam0").await.unwrap(); let info = broadcast.track("0.avc3").unwrap().info().await.unwrap(); assert_eq!(info.max_age, Duration::from_secs(3)); } @@ -217,10 +223,12 @@ mod tests { let origin = produce_origin(); let mut publisher = Publisher::new(&origin, "ingest", None).unwrap(); - let broadcast = timeout(Duration::from_secs(5), origin.consume().announced_broadcast("ingest")) + let consumer = origin.consume(); + timeout(Duration::from_secs(5), consumer.routed("ingest")) .await .expect("announce timed out") .expect("the ingest broadcast is announced"); + let broadcast = consumer.request_broadcast("ingest").await.unwrap(); publisher.feed(bytes::Bytes::from_static(BBB5S)).unwrap(); diff --git a/rs/moq-stats/src/aggregate.rs b/rs/moq-stats/src/aggregate.rs index 5be98bd911b..aec974f5aed 100644 --- a/rs/moq-stats/src/aggregate.rs +++ b/rs/moq-stats/src/aggregate.rs @@ -6,6 +6,7 @@ //! cumulative counters into one merged frame per `(tier, role)`, so a downstream //! sees a project's whole live traffic as if it came from a single node. +use std::collections::hash_map::Entry; use std::collections::{BTreeMap, HashMap}; use std::task::Poll; @@ -102,7 +103,7 @@ impl Consumer { pub fn traffic(&self, tier: &Tier, role: Role) -> TrafficConsumer { let name = traffic_track(tier, role, self.config.compression); TrafficConsumer { - inner: Merged::new(self.origin.announced(), &self.config, name), + inner: Merged::new(self.origin.clone(), &self.config, name), } } @@ -110,7 +111,7 @@ impl Consumer { pub fn sessions(&self, tier: &Tier) -> SessionsConsumer { let name = sessions_track(tier, self.config.compression); SessionsConsumer { - inner: Merged::new(self.origin.announced(), &self.config, name), + inner: Merged::new(self.origin.clone(), &self.config, name), } } } @@ -163,6 +164,15 @@ impl Mergeable for Presence { /// 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, + }, /// Awaiting the subscription handshake. Subscribing(Pending), /// Reading frames. Boxed: the snapshot consumer dwarfs the other variants, @@ -177,11 +187,16 @@ enum Reader { /// merged view). struct Node { reader: Reader, + /// The announced path, relative to the announce cursor: what a re-resolve + /// after the reader ends requests again. + path: PathOwned, last: Option>, } /// Watches a group's node announces and folds one track across all of them. struct Merged { + /// Resolves announced node paths into broadcasts. + origin: origin::Consumer, announce: moq_net::announce::Consumer, prefix: PathOwned, depth: usize, @@ -193,9 +208,10 @@ struct Merged { } impl Merged { - fn new(announce: moq_net::announce::Consumer, config: &Config, name: String) -> Self { + fn new(origin: origin::Consumer, config: &Config, name: String) -> Self { Self { - announce, + announce: origin.announced(), + origin, prefix: config.prefix.clone(), depth: config.depth, name, @@ -223,8 +239,9 @@ impl Merged { // Advance each node's reader, collapsing any backlog to its latest frame. let config = &self.config; let name = self.name.as_str(); + let origin = &self.origin; for node in self.nodes.values_mut() { - changed |= advance(node, config, name, waiter); + changed |= advance(node, origin, config, name, waiter); } if changed { @@ -237,32 +254,42 @@ impl Merged { /// Apply one announce update to the node set. Returns whether the merged view /// changed (only a drop or a replacement of a node that had a value does). fn apply_announce(&mut self, update: moq_net::announce::Update) -> bool { - let moq_net::announce::Update { path, broadcast } = update; + let path = update.prefix.as_path().to_owned(); let absolute = self.announce.absolute(&path).to_owned(); - // Only fold node-category broadcasts; skip sibling categories a producer - // may publish under the same prefix. + // Only fold node-category routes; skip sibling categories a producer + // may publish under the same prefix. A route names a prefix, and node + // broadcasts are announced at their exact path by convention. if parse_node_path(&self.prefix, self.depth, &absolute).is_none() { return false; } - match broadcast { - Some(broadcast) => match broadcast.track(&self.name) { - Ok(track) => { - let node = Node { - reader: Reader::Subscribing(track.subscribe(None)), - last: None, - }; - // A replacement (failover) drops the old value until the new - // subscription catches up. - self.nodes.insert(absolute, node).is_some_and(|old| old.last.is_some()) + if update.active { + // A route update on a node already tracked (a reprice, or a takeover + // with different metadata) keeps the live reader: existing + // subscriptions survive a takeover, and the reader re-resolves through + // the current best route the moment it actually ends. Only an ended + // node re-arms here, since a fresh route is new evidence that a + // re-resolve could succeed. + match self.nodes.entry(absolute) { + Entry::Occupied(mut entry) => { + let node = entry.get_mut(); + if matches!(node.reader, Reader::Ended) { + node.reader = resolve(&self.origin, &node.path); + } + false } - Err(err) => { - tracing::debug!(?err, node = %absolute, name = %self.name, "stats: node missing track"); - self.nodes.remove(&absolute).is_some_and(|old| old.last.is_some()) + Entry::Vacant(entry) => { + entry.insert(Node { + reader: resolve(&self.origin, &path), + path, + last: None, + }); + false } - }, - None => self.nodes.remove(&absolute).is_some_and(|old| old.last.is_some()), + } + } else { + self.nodes.remove(&absolute).is_some_and(|old| old.last.is_some()) } } @@ -284,13 +311,42 @@ impl Merged { /// whether that node's contribution to the merged view changed. fn advance( node: &mut Node, + origin: &origin::Consumer, config: &moq_json::snapshot::ConsumerConfig, name: &str, waiter: &Waiter, ) -> bool { let mut changed = false; + // At most one re-resolve per call: a subscription that terminates + // synchronously twice in a row is done, not failing over. + let mut rearmed = false; loop { match &mut node.reader { + Reader::Resolving { pending, queued } => match pending.poll_ok(waiter) { + Poll::Ready(Ok(broadcast)) => match broadcast.track(name) { + Ok(track) => node.reader = Reader::Subscribing(track.subscribe(None)), + Err(err) => { + tracing::debug!(?err, name, "stats: node missing track"); + node.reader = Reader::Ended; + return changed; + } + }, + // 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); + } + Poll::Ready(Err(err)) => { + tracing::debug!(?err, name, "stats: node broadcast unresolvable"); + node.reader = Reader::Ended; + return changed; + } + Poll::Pending => return changed, + }, Reader::Subscribing(pending) => match pending.poll_ok(waiter) { Poll::Ready(Ok(subscriber)) => { node.reader = @@ -308,12 +364,28 @@ fn advance( node.last = Some(frame); changed = true; } - Poll::Ready(Ok(None)) => return terminate(node, changed), - Poll::Ready(Err(err)) => { - // One bad node must not tear down the whole merged view; drop - // just this node and keep folding the rest. - tracing::debug!(?err, name, "stats: node read error"); - return terminate(node, changed); + // The subscription ended: the serving session died (a failover to + // an identical route delivers no announce update) or the track + // finished. Drop the last frame so a stale gauge stops pinning + // the sum, then re-resolve through the current best route; an + // authoritative refusal on the way ends the node instead. + Poll::Ready(result @ (Ok(None) | Err(_))) => { + if let Err(err) = result { + // One bad node must not tear down the whole merged view; + // re-resolve just this node and keep folding the rest. + tracing::debug!(?err, name, "stats: node read error"); + } + changed |= node.last.take().is_some(); + if rearmed { + node.reader = Reader::Ended; + return changed; + } + rearmed = true; + // Drop the dead reader before re-requesting: our own handle is + // what keeps a dying served broadcast cached, and releasing it + // first lets the request materialize a fresh one. + node.reader = Reader::Ended; + node.reader = resolve(origin, &node.path); } Poll::Pending => return changed, }, @@ -322,14 +394,11 @@ fn advance( } } -/// Retire a node whose reader terminated: drop its last frame so it stops -/// contributing (a still-announced but unreadable node must not pin a stale -/// gauge into the sum) and mark it ended so it lingers only until it -/// unannounces. Returns whether the merged view changed. -fn terminate(node: &mut Node, changed: bool) -> bool { - let had_value = node.last.take().is_some(); - node.reader = Reader::Ended; - changed || had_value +/// Start resolving `path` (relative to the announce cursor) into a broadcast. +fn resolve(origin: &origin::Consumer, path: &PathOwned) -> Reader { + let pending = origin.request_broadcast(path); + let queued = pending.is_queued(); + Reader::Resolving { pending, queued } } #[cfg(test)] @@ -372,6 +441,7 @@ mod tests { #[allow(dead_code)] struct Feed { announced: announce::Consumer, + route: announce::Producer, source: broadcast::Producer, consumer: broadcast::Consumer, sub: track::Subscriber, @@ -387,17 +457,13 @@ mod tests { let egress = feed_origin.consume().with_stats(ctx.clone()); let mut announced = egress.announced(); - let mut source = feed_origin - .create_broadcast(path, broadcast::Route::announced()) - .expect("create_broadcast"); + let mut source = feed_origin.create_broadcast(path).expect("create_broadcast"); + let route = feed_origin.announce(path, origin::Route::default()).expect("announce"); let mut track = source.create_track("video", None).expect("create_track"); - // Let the origin's source watcher attach and announce. - tokio::time::sleep(Duration::from_millis(1)).await; - tokio::time::sleep(Duration::from_millis(1)).await; - - let announce::Update { broadcast, .. } = announced.next().await.expect("announce"); - let consumer = broadcast.expect("active"); + let update = announced.next().await.expect("announce"); + assert!(update.active); + let consumer = egress.request_broadcast(path).await.expect("resolve"); let mut sub = consumer.track("video").unwrap().subscribe(None).await.unwrap(); let mut group = track.append_group().unwrap(); @@ -408,6 +474,7 @@ mod tests { Feed { announced, + route, source, consumer, sub, diff --git a/rs/moq-stats/src/consume.rs b/rs/moq-stats/src/consume.rs index ccb81ddc639..579aeeb69c9 100644 --- a/rs/moq-stats/src/consume.rs +++ b/rs/moq-stats/src/consume.rs @@ -138,6 +138,7 @@ mod tests { track: track::Producer, sub: track::Subscriber, _announced: announce::Consumer, + _route: announce::Producer, _source: broadcast::Producer, _ctx: moq_net::stats::Session, } @@ -160,22 +161,20 @@ mod tests { let egress = feed_origin.consume().with_stats(ctx.clone()); let mut announced = egress.announced(); - let mut source = feed_origin - .create_broadcast(path, broadcast::Route::announced()) - .unwrap(); - let track = source.create_track("video", None).unwrap(); + let source = feed_origin.create_broadcast(path).unwrap(); + let route = feed_origin.announce(path, origin::Route::default()).unwrap(); + let track = source.clone().create_track("video", None).unwrap(); - tokio::time::sleep(Duration::from_millis(1)).await; - tokio::time::sleep(Duration::from_millis(1)).await; - - let announce::Update { broadcast, .. } = announced.next().await.expect("announce"); - let consumer = broadcast.expect("active"); + let update = announced.next().await.expect("announce"); + assert!(update.active); + let consumer = egress.request_broadcast(path).await.expect("resolve"); let sub = consumer.track("video").unwrap().subscribe(None).await.unwrap(); Feed { track, sub, _announced: announced, + _route: route, _source: source, _ctx: ctx, } @@ -184,8 +183,13 @@ mod tests { async fn announced(origin: &origin::Producer) -> moq_net::broadcast::Consumer { let mut consumer = origin.consume().announced(); tokio::time::advance(Duration::from_millis(1)).await; - let announce::Update { broadcast, .. } = consumer.next().await.expect("expected announce"); - broadcast.expect("active") + let update = consumer.next().await.expect("expected announce"); + assert!(update.active); + origin + .consume() + .request_broadcast(update.prefix.as_path()) + .await + .expect("resolve") } async fn drive_tick() { diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index 52ae012c8c2..4bab208115f 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -615,6 +615,8 @@ impl TrackFamily { /// One group stats broadcast and its change-detection state. struct GroupPublisher { broadcast: broadcast::Producer, + /// The route advertising this group's broadcast; dropping it retracts. + _announcement: moq_net::announce::Producer, /// Holds the broadcast's request queue open, so a subscriber asking for a /// tier track no drain has created yet parks (served next tick) instead of /// being rejected `NotFound` on the spot. @@ -633,13 +635,20 @@ struct GroupPublisher { impl GroupPublisher { fn create(origin: &origin::Producer, prefix: &Path, group: &Path, node: Option<&str>) -> Option { let advertised = advertised_path(prefix, group, node); - let mut broadcast = match origin.create_broadcast(&advertised, broadcast::Route::new().with_announce(true)) { + let mut broadcast = match origin.create_broadcast(&advertised) { Ok(broadcast) => broadcast, Err(err) => { tracing::warn!(advertised = %advertised, ?err, "stats: origin rejected stats broadcast"); return None; } }; + let announcement = match origin.announce(&advertised, origin::Route::default()) { + Ok(announcement) => announcement, + Err(err) => { + tracing::warn!(advertised = %advertised, ?err, "stats: origin rejected stats announce"); + return None; + } + }; tracing::debug!(advertised = %advertised, "stats: publishing broadcast"); let mut traffic = TrackFamily::new(); @@ -674,6 +683,7 @@ impl GroupPublisher { Some(Self { broadcast, + _announcement: announcement, dynamic, requested: HashSet::new(), traffic, @@ -911,6 +921,7 @@ mod tests { #[allow(dead_code)] struct Feed { announced: announce::Consumer, + route: announce::Producer, source: broadcast::Producer, consumer: broadcast::Consumer, sub: Option, @@ -936,18 +947,13 @@ mod tests { let egress = origin.consume().with_stats(ctx); let mut announced = egress.announced(); - let mut source = origin - .create_broadcast(path, broadcast::Route::announced()) - .expect("create_broadcast"); + let mut source = origin.create_broadcast(path).expect("create_broadcast"); + let route = origin.announce(path, origin::Route::default()).expect("announce"); let mut producer = source.create_track("video", None).expect("create_track"); - // Let the origin's source watcher attach and announce (paused time advances - // instantly and yields to the spawned tasks). - tokio::time::sleep(Duration::from_millis(1)).await; - tokio::time::sleep(Duration::from_millis(1)).await; - - let announce::Update { broadcast, .. } = announced.next().await.expect("announce"); - let consumer = broadcast.expect("active"); + let update = announced.next().await.expect("announce"); + assert!(update.active); + let consumer = egress.request_broadcast(path).await.expect("resolve"); let sub = if subscribe { let mut sub = consumer @@ -976,6 +982,7 @@ mod tests { Feed { announced, + route, source, consumer, sub, @@ -986,8 +993,14 @@ mod tests { async fn announced(origin: &origin::Producer) -> (String, moq_net::broadcast::Consumer) { let mut consumer = origin.consume().announced(); tokio::time::advance(Duration::from_millis(1)).await; - let announce::Update { path, broadcast } = consumer.next().await.expect("expected announce"); - (path.as_str().to_string(), broadcast.expect("active")) + let update = consumer.next().await.expect("expected announce"); + assert!(update.active); + let broadcast = origin + .consume() + .request_broadcast(update.prefix.as_path()) + .await + .expect("resolve"); + (update.prefix.as_path().as_str().to_string(), broadcast) } /// Advance past one publish interval so the task drains and writes frames. diff --git a/rs/moq-tokio/examples/chat.rs b/rs/moq-tokio/examples/chat.rs index 937ea656eac..3e00005f790 100644 --- a/rs/moq-tokio/examples/chat.rs +++ b/rs/moq-tokio/examples/chat.rs @@ -43,9 +43,10 @@ async fn run_broadcast(origin: moq_net::origin::Producer) -> anyhow::Result<()> // but in this example we'll only create one. The live route announces it. // NOTE: The path is empty because we're using the URL to scope the broadcast. // If you put "alice" here, it would be published as "anon/chat-example/alice". - let mut broadcast = origin - .create_broadcast("", moq_net::broadcast::Route::new().with_announce(true)) - .context("failed to create broadcast")?; + let mut broadcast = origin.create_broadcast("").context("failed to create broadcast")?; + let _announcement = origin + .announce("", Default::default()) + .context("failed to announce broadcast")?; // Create a track that we'll insert into the broadcast. // A track is a series of groups representing a live stream. diff --git a/rs/moq-tokio/examples/clock.rs b/rs/moq-tokio/examples/clock.rs index 7ba4a8ed9d3..c4fccc8c288 100644 --- a/rs/moq-tokio/examples/clock.rs +++ b/rs/moq-tokio/examples/clock.rs @@ -64,9 +64,12 @@ async fn main() -> anyhow::Result<()> { match config.role { Command::Publish => { let mut broadcast = origin - .create_broadcast(&config.broadcast, moq_net::broadcast::Route::new().with_announce(true)) + .create_broadcast(&config.broadcast) .context("failed to create broadcast")?; let track = broadcast.create_track(track, None)?; + let _announce_broadcast = origin + .announce(&config.broadcast, Default::default()) + .context("failed to announce broadcast")?; let clock = Publisher::new(track); let reconnect = client.with_publisher(&origin).connect(url); @@ -92,25 +95,27 @@ async fn main() -> anyhow::Result<()> { tracing::info!(broadcast = %config.broadcast, "waiting for broadcast to be online"); let path: moq_net::Path<'_> = config.broadcast.into(); - let mut origin = origin + let consumer = origin .scope(&[path]) .context("not allowed to consume broadcast")? - .consume() - .announced(); + .consume(); + let mut announced = consumer.announced(); let mut clock: Option = None; loop { tokio::select! { - Some(moq_net::announce::Update { path, broadcast }) = origin.next() => match broadcast { - Some(broadcast) => { + Some(update) = announced.next() => match update.active { + true => { + let path = update.prefix.as_path().to_owned(); tracing::info!(broadcast = %path, "broadcast is online, subscribing to track"); + let broadcast = consumer.request_broadcast(&path).await?; let track = broadcast .track(&track)?.subscribe(None).await?; clock = Some(Subscriber::new(track)); } - None => { - tracing::warn!(broadcast = %path, "broadcast is offline, waiting..."); + false => { + tracing::warn!(broadcast = %update.prefix, "broadcast is offline, waiting..."); } }, res = reconnect.closed() => return Ok(res?), diff --git a/rs/moq-tokio/src/origin.rs b/rs/moq-tokio/src/origin.rs index 33f688dc146..1fe28367e78 100644 --- a/rs/moq-tokio/src/origin.rs +++ b/rs/moq-tokio/src/origin.rs @@ -22,24 +22,24 @@ pub fn spawn(info: impl Into) -> moq_net::origin::Produce mod tests { use super::*; - /// The spawned driver runs the origin's lifecycle: an announced broadcast - /// reaches a consumer, and finishing it unannounces. + /// The spawned driver runs the origin's lifecycle: an announced route + /// reaches a consumer, and dropping the announcement retracts it. #[tokio::test] async fn spawn_drives_the_origin() { let origin = spawn(moq_net::origin::Info::new(moq_net::Hop::random())); let mut announced = origin.consume().announced(); - let mut broadcast = origin - .create_broadcast("cam", moq_net::broadcast::Route::new().with_announce(true)) - .expect("create broadcast"); + let mut broadcast = origin.create_broadcast("cam").expect("create broadcast"); + let announcement = origin.announce("cam", Default::default()).expect("create broadcast"); let update = announced.next().await.expect("announce"); - assert_eq!(update.path.as_str(), "cam"); - assert!(update.broadcast.is_some()); + assert_eq!(update.prefix.as_path().as_str(), "cam"); + assert!(update.active); broadcast.finish(); - let update = announced.next().await.expect("unannounce"); - assert!(update.broadcast.is_none()); + drop(announcement); + let update = announced.next().await.expect("retraction"); + assert!(!update.active); } /// Outside a runtime the spawn has nowhere to run the driver: it panics diff --git a/rs/moq-tokio/src/server.rs b/rs/moq-tokio/src/server.rs index 407eb3ac16f..f68738b9f9f 100644 --- a/rs/moq-tokio/src/server.rs +++ b/rs/moq-tokio/src/server.rs @@ -1478,9 +1478,8 @@ mod tests { let _ = std::fs::remove_file(&path); let origin = crate::origin::spawn(moq_net::Hop::random()); - let mut broadcast = origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) - .expect("create broadcast"); + let mut broadcast = origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = origin.announce("test", Default::default()).expect("announce broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); let mut group = track.append_group().expect("append group"); group @@ -1516,7 +1515,8 @@ mod tests { let url: Url = format!("unix://{}", path.display()).parse().expect("parse url"); let subscriber = crate::origin::spawn(moq_net::Hop::random()); - let mut announced = subscriber.consume().announced(); + let consumer = subscriber.consume(); + let mut announced = consumer.announced(); let client = crate::connect::Config::default() .init(Default::default()) .expect("client init") @@ -1532,8 +1532,9 @@ mod tests { .await .expect("announce timeout") .expect("origin closed"); - assert_eq!(update.path.as_str(), "test"); - let broadcast = update.broadcast.expect("expected an announce"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active); + let broadcast = consumer.request_broadcast("test").await.expect("resolve"); let mut track = broadcast .track("video") diff --git a/rs/moq-tokio/tests/backend.rs b/rs/moq-tokio/tests/backend.rs index 4bfc0b40183..3d4d690714b 100644 --- a/rs/moq-tokio/tests/backend.rs +++ b/rs/moq-tokio/tests/backend.rs @@ -4,7 +4,7 @@ //! Each test is gated with `#[cfg(feature = "...")]` so it only compiles when the //! corresponding backend is enabled. Running `cargo test --all-features` exercises all. -use moq_tokio::moq_net::{self, Hop}; +use moq_tokio::moq_net::Hop; use std::time::Duration; const TIMEOUT: Duration = Duration::from_secs(10); @@ -105,8 +105,9 @@ async fn connect_test(config: ConnectTest<'_>) { // ── publisher (server) ────────────────────────────────────────── let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast.create_track("video", None).expect("failed to create track"); @@ -129,7 +130,8 @@ async fn connect_test(config: ConnectTest<'_>) { // ── subscriber (client) ───────────────────────────────────────── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -171,14 +173,16 @@ async fn connect_test(config: ConnectTest<'_>) { .expect("client connect timed out") .expect("client connect failed"); - let moq_tokio::moq_net::announce::Update { path, broadcast: bc } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timed out") - .expect("origin closed"); - - assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timed out") + .expect("origin closed"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); let mut track_sub = bc .track("video") @@ -467,8 +471,9 @@ async fn iroh_connect() { // ── publisher (server) ────────────────────────────────────────── let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast.create_track("video", None).expect("failed to create track"); @@ -506,7 +511,8 @@ async fn iroh_connect() { // ── subscriber (client) ───────────────────────────────────────── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); // Create client iroh endpoint let mut client_iroh_config = EndpointConfig::default(); @@ -556,14 +562,16 @@ async fn iroh_connect() { .expect("client connect timed out") .expect("client connect failed"); - let moq_tokio::moq_net::announce::Update { path, broadcast: bc } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timed out") - .expect("origin closed"); - - assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timed out") + .expect("origin closed"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); let mut track_sub = bc .track("video") diff --git a/rs/moq-tokio/tests/broadcast.rs b/rs/moq-tokio/tests/broadcast.rs index 0093219f73e..706900f1732 100644 --- a/rs/moq-tokio/tests/broadcast.rs +++ b/rs/moq-tokio/tests/broadcast.rs @@ -24,8 +24,9 @@ async fn broadcast_test(scheme: &str, client_version: Option<&str>, server_versi // ── publisher (server) ────────────────────────────────────────── let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast.create_track("video", None).expect("failed to create track"); @@ -49,7 +50,8 @@ async fn broadcast_test(scheme: &str, client_version: Option<&str>, server_versi // ── subscriber (client) ───────────────────────────────────────── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -81,14 +83,17 @@ async fn broadcast_test(scheme: &str, client_version: Option<&str>, server_versi .expect("client connect failed"); // Wait for the broadcast announcement. - let moq_tokio::moq_net::announce::Update { path, broadcast: bc } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timed out") - .expect("origin closed"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timed out") + .expect("origin closed"); - assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); // Subscribe to the track. let mut track_sub = bc @@ -128,8 +133,9 @@ async fn lite05_timestamp_roundtrip(scheme: &str) { use moq_tokio::moq_net::{Timescale, Timestamp}; let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("failed to create broadcast"); // Track with an explicit microsecond timescale (the default is milliseconds). @@ -167,7 +173,8 @@ async fn lite05_timestamp_roundtrip(scheme: &str) { let addr = server.local_addr().expect("failed to get local addr"); let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -190,13 +197,16 @@ async fn lite05_timestamp_roundtrip(scheme: &str) { .expect("client connect timed out") .expect("client connect failed"); - let moq_tokio::moq_net::announce::Update { path, broadcast: bc } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timed out") - .expect("origin closed"); - assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timed out") + .expect("origin closed"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); let mut track_sub = bc .track("video") @@ -248,8 +258,9 @@ async fn lite05_fetch_roundtrip(scheme: &str) { use moq_tokio::moq_net::{Timescale, Timestamp}; let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast .create_track( @@ -285,7 +296,8 @@ async fn lite05_fetch_roundtrip(scheme: &str) { let addr = server.local_addr().expect("failed to get local addr"); let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -308,13 +320,16 @@ async fn lite05_fetch_roundtrip(scheme: &str) { .expect("client connect timed out") .expect("client connect failed"); - let moq_tokio::moq_net::announce::Update { path, broadcast: bc } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timed out") - .expect("origin closed"); - assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timed out") + .expect("origin closed"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); // Fetch group 0 directly, without subscribing. No live producer holds the group // on the client, so this issues a wire FETCH upstream. @@ -377,8 +392,9 @@ async fn lite05_fetch_during_subscribe(scheme: &str) { } let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast .create_track( @@ -410,7 +426,8 @@ async fn lite05_fetch_during_subscribe(scheme: &str) { let addr = server.local_addr().expect("failed to get local addr"); let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -433,13 +450,16 @@ async fn lite05_fetch_during_subscribe(scheme: &str) { .expect("client connect timed out") .expect("client connect failed"); - let moq_tokio::moq_net::announce::Update { path, broadcast: bc } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timed out") - .expect("origin closed"); - assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timed out") + .expect("origin closed"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); // Subscribe (starts at the latest group) and read the live group, which // establishes the upstream subscription and leaves it active. @@ -498,8 +518,9 @@ async fn broadcast_moq_lite_05_default_timescale() { use moq_tokio::moq_net::Timescale; let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); @@ -518,7 +539,8 @@ async fn broadcast_moq_lite_05_default_timescale() { let addr = server.local_addr().expect("local addr"); let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -541,12 +563,15 @@ async fn broadcast_moq_lite_05_default_timescale() { .expect("connect timeout") .expect("connect failed"); - let moq_tokio::moq_net::announce::Update { broadcast: bc, .. } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timeout") - .expect("origin closed"); - let bc = bc.expect("expected announce"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timeout") + .expect("origin closed"); + assert!(update.active, "expected announce"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast(update.prefix.as_path())) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); let mut track_sub = bc .track("video") @@ -595,8 +620,9 @@ async fn broadcast_moq_lite_06_announce_lifecycle() { let pub_origin = moq_tokio::origin::spawn(Hop::random()); // Announced before the client connects, so it rides the initial set. - let mut first = pub_origin - .create_broadcast("first", moq_net::broadcast::Route::new().with_announce(true)) + let mut first = pub_origin.create_broadcast("first").expect("create broadcast"); + let _announce_first = pub_origin + .announce("first", Default::default()) .expect("create broadcast"); let mut server_config = moq_tokio::listen::Config::default(); @@ -608,7 +634,8 @@ async fn broadcast_moq_lite_06_announce_lifecycle() { let addr = server.local_addr().expect("local addr"); let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -631,55 +658,60 @@ async fn broadcast_moq_lite_06_announce_lifecycle() { .expect("connect failed"); // The initial set: "first" was announced before the session existed. - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "first"); - assert!(broadcast.is_some(), "expected initial announce"); + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "first"); + assert!(update.active, "expected initial announce"); // A live announce after the initial set. - let mut second = pub_origin - .create_broadcast("second", moq_net::broadcast::Route::new().with_announce(true)) + let mut second = pub_origin.create_broadcast("second").expect("create broadcast"); + let announce_second = pub_origin + .announce("second", Default::default()) .expect("create broadcast"); - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "second"); - assert!(broadcast.is_some(), "expected live announce"); + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "second"); + assert!(update.active, "expected live announce"); - // Unannounce: retracted by announce id on the wire. A deliberate finish - // unannounces cleanly (a bare drop would read as a failure and log a warning). + // Unannounce: retracted by announce id on the wire. Dropping the announcement + // retracts the route; the broadcast's own end is independent. second.finish(); - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "second"); - assert!(broadcast.is_none(), "expected unannounce"); + drop(announce_second); + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "second"); + assert!(!update.active, "expected retraction"); // Re-announce the same path: a fresh announce assigning a fresh id. - let _second = pub_origin - .create_broadcast("second", moq_net::broadcast::Route::new().with_announce(true)) + let _second = pub_origin.create_broadcast("second").expect("create broadcast"); + let _announce_second = pub_origin + .announce("second", Default::default()) .expect("create broadcast"); - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "second"); - assert!(broadcast.is_some(), "expected re-announce"); - - // Replace the broadcast at "first": finish the original (retiring its announce - // id on the wire), then create a fresh broadcast at the same path (assigning a - // fresh id). Await the unannounce first so the re-create can't splice into the - // original's teardown. + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "second"); + assert!(update.active, "expected re-announce"); + + // Replace the route at "first": retract the original (retiring its announce + // id on the wire), then announce the same path again (assigning a fresh id). + // Await the retraction first so the events cannot coalesce away. first.finish(); - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "first"); - assert!(broadcast.is_none(), "expected the replaced unannounce"); - let _replacement = pub_origin - .create_broadcast("first", moq_net::broadcast::Route::new().with_announce(true)) + drop(_announce_first); + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "first"); + assert!(!update.active, "expected the replaced retraction"); + let _replacement = pub_origin.create_broadcast("first").expect("create replacement"); + let _announce_replacement = pub_origin + .announce("first", Default::default()) .expect("create replacement"); - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "first"); - assert!(broadcast.is_some(), "expected the replacement announce"); + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "first"); + assert!(update.active, "expected the replacement announce"); // A sentinel proves no stray event for "first" snuck in behind the replacement. - let _sentinel = pub_origin - .create_broadcast("sentinel", moq_net::broadcast::Route::new().with_announce(true)) + let _sentinel = pub_origin.create_broadcast("sentinel").expect("create broadcast"); + let _announce_sentinel = pub_origin + .announce("sentinel", Default::default()) .expect("create broadcast"); - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "sentinel"); - assert!(broadcast.is_some(), "expected sentinel announce"); + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "sentinel"); + assert!(update.active, "expected sentinel announce"); drop(connection); server_handle @@ -709,36 +741,28 @@ async fn read_payloads(sub: &mut moq_net::track::Subscriber, count: usize) -> Ve payloads } -/// A subscription migrates transparently between two publisher sessions. -/// -/// The client connects to two servers announcing the same broadcast path. The -/// preferred route (shorter hop chain) serves the track; when that session dies, -/// the same `track::Subscriber` keeps receiving groups from the standby session. -/// No unannounce is observed and nothing is resubscribed by the application. +/// A path stays routed across two publisher sessions announcing it. /// -/// The subscription is live-edge (`group_start: None`), and that means the same -/// thing on the standby as it did on the first route: tune in at the latest -/// group. The standby's older cached groups are not replayed. +/// The client connects to two servers announcing the same route. The preferred +/// (cheaper) route serves the track; when that session dies, the materialized +/// broadcast aborts and a fresh request resolves through the standby, without +/// the path ever being retracted. Routes claim capability, not content +/// identity, so the failover is an explicit re-request rather than a splice. #[tracing_test::traced_test] #[tokio::test] async fn broadcast_route_migration() { use moq_net::Timestamp; - // The original publisher's identity, shared by both routes: the first hop is - // the broadcast's content identity, so only same-first-hop routes are - // interchangeable enough to migrate across without a re-announce. let publisher = Hop::new(0x42).unwrap(); - // ── publisher A: the preferred route (shorter hop chain) ──────── + // ── publisher A: the preferred route (cheaper) ────────────────── let origin_a = moq_tokio::origin::spawn(Hop::random()); let mut hops_a = moq_net::Hops::new(); hops_a.push(publisher).unwrap(); - let mut broadcast_a = origin_a - .create_broadcast( - "test", - moq_net::broadcast::Route::new().with_hops(hops_a).with_announce(true), - ) - .expect("create broadcast"); + let mut broadcast_a = origin_a.create_broadcast("test").expect("create broadcast"); + let _announce_a = origin_a + .announce("test", moq_net::origin::Route::default().with_hops(hops_a).with_cost(1)) + .expect("announce"); let mut track_a = broadcast_a.create_track("video", None).expect("create track"); for sequence in 0..2u64 { let mut group = track_a @@ -755,12 +779,10 @@ async fn broadcast_route_migration() { let mut hops_b = moq_net::Hops::new(); hops_b.push(publisher).unwrap(); hops_b.push(Hop::new(0x1234).unwrap()).unwrap(); - let mut broadcast_b = origin_b - .create_broadcast( - "test", - moq_net::broadcast::Route::new().with_hops(hops_b).with_announce(true), - ) - .expect("create broadcast"); + let mut broadcast_b = origin_b.create_broadcast("test").expect("create broadcast"); + let _announce_b = origin_b + .announce("test", moq_net::origin::Route::default().with_hops(hops_b).with_cost(2)) + .expect("announce"); let mut track_b = broadcast_b.create_track("video", None).expect("create track"); // A clone to keep producing from the test body once the task owns the rest. let mut standby_track = track_b.clone(); @@ -810,7 +832,8 @@ async fn broadcast_route_migration() { // ── one subscriber origin fed by both sessions ─────────────────── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let connect = |port: u16, sub: moq_net::origin::Producer| { let mut config = moq_tokio::connect::Config::default(); @@ -827,39 +850,53 @@ async fn broadcast_route_migration() { let session_a = connect(addr_a.port(), sub_origin.clone()).await; let _session_b = connect(addr_b.port(), sub_origin.clone()).await; - // One broadcast, announced exactly once even though two sessions feed it. - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "test"); - let broadcast = broadcast.expect("expected announce"); + // One path, announced once even though two sessions route it (the cheaper + // route wins the advertisement). + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce"); - // Subscribe once, with a generous stale window so the continuation B already holds - // is served rather than aged out, and a floor at the live edge so that window is a - // tolerance rather than a request for A's backlog: the budget alone would resolve - // the start at a0. + // Resolve and subscribe: the cheaper route (A) serves the track. let subscription = moq_net::track::Subscription::default() .with_start(moq_net::track::Position::group(1)) .with_max_age(Duration::from_secs(10)); + let broadcast = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timeout") + .expect("routed broadcast resolves"); let mut sub = broadcast .track("video") .unwrap() - .subscribe(subscription) + .subscribe(subscription.clone()) .await .expect("subscribe failed"); - - // The preferred route (A) serves the track from the floor, so only A's newest - // group arrives. assert_eq!(read_payloads(&mut sub, 1).await, ["a1"]); - // Kill the serving session. The track migrates to B and the same subscriber keeps - // reading, resuming at the splice boundary: B holds the continuation of the same - // content, so group 2 is the next thing owed rather than something to skip. The - // catch-up is bounded by the boundary, and a consumer wanting only the live edge - // drops it on its own latency budget downstream. + // Kill the serving session. The materialized broadcast aborts; the next + // request resolves through the standby route and serves its content. drop(session_a); + tokio::time::timeout(TIMEOUT, async { while sub.recv_group().await.is_ok() {} }) + .await + .expect("the dead session's subscription should abort"); + + let mut sub = tokio::time::timeout(TIMEOUT, async { + loop { + // The dead session's entry may still be routable for an instant; keep + // re-requesting until the standby serves the subscription. + if let Ok(broadcast) = sub_consumer.request_broadcast("test").await + && let Ok(track) = broadcast.track("video") + && let Ok(sub) = track.subscribe(subscription.clone()).await + { + return sub; + } + tokio::time::sleep(Duration::from_millis(10)).await; + } + }) + .await + .expect("the standby route should serve a fresh subscription"); assert_eq!(read_payloads(&mut sub, 2).await, ["b2", "b3"]); - // The migrated subscription is live: what B produces from here on flows - // through the same subscriber handle. + // The new subscription is live: what B produces from here on flows through it. { let mut group = standby_track .create_group(moq_net::group::Info { sequence: 4 }) @@ -869,24 +906,22 @@ async fn broadcast_route_migration() { } assert_eq!(read_payloads(&mut sub, 1).await, ["b4"]); - // The application observed no unannounce or re-announce across the swap. - assert!( - announcements.try_next().is_none(), - "route migration must not emit announce events" - ); + // The path was never retracted across the swap: any events delivered are + // active metadata updates (the standby's chain taking over). + while let Some(update) = announcements.try_next() { + assert!(update.active, "failover must not retract the route"); + } handle_a.await.expect("server a panicked").expect("server a failed"); drop(_session_b); handle_b.await.expect("server b panicked").expect("server b failed"); } -/// A publisher-side route change re-advertises downstream as a restart. +/// A publisher-side route update re-advertises downstream as a restart. /// -/// The publisher updates its broadcast's route with a longer chain behind the -/// same first hop (the original publisher, as if an intermediate relay failed -/// over); the subscriber observes the new chain on the same broadcast handle -/// via `route_changed`, with zero announce events and an uninterrupted -/// subscription. +/// The publisher re-prices its announced route with a longer chain; the +/// subscriber observes the new chain as another active update for the same +/// prefix, with no retraction and an uninterrupted subscription. async fn route_reannounce_test(version: Option<&str>) { use moq_net::Timestamp; @@ -900,14 +935,10 @@ async fn route_reannounce_test(version: Option<&str>) { let publisher_hop = Hop::new(0x4444).unwrap(); let mut initial_hops = moq_net::Hops::new(); initial_hops.push(publisher_hop).unwrap(); - let mut producer = origin - .create_broadcast( - "test", - moq_net::broadcast::Route::new() - .with_hops(initial_hops) - .with_announce(true), - ) - .expect("create broadcast"); + let mut producer = origin.create_broadcast("test").expect("create broadcast"); + let announcement = origin + .announce("test", moq_net::origin::Route::default().with_hops(initial_hops)) + .expect("announce"); let mut track = producer.create_track("video", None).expect("create track"); { let mut group = track @@ -926,9 +957,6 @@ async fn route_reannounce_test(version: Option<&str>) { let mut server = server.listen().await.expect("failed to listen"); let addr = server.local_addr().expect("local addr"); - // A clone to re-advertise from the test body while the task owns the rest. - let mut route_producer = producer.clone(); - let handle = tokio::spawn(async move { let request = server.accept().await.expect("accept"); let session = request.with_publisher(&origin).ok().await?; @@ -939,7 +967,8 @@ async fn route_reannounce_test(version: Option<&str>) { // ── subscriber (client) ───────────────────────────────────────── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -953,17 +982,15 @@ async fn route_reannounce_test(version: Option<&str>) { .expect("connect timeout") .expect("connect failed"); - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "test"); - let broadcast = broadcast.expect("expected announce"); + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce"); + let initial = update.route; - // The initial route: a direct publish, so just the publisher session's hop. - let mut watch = broadcast.clone(); - let initial = tokio::time::timeout(TIMEOUT, watch.route_changed()) + let broadcast = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) .await - .expect("route timeout") - .expect("route dropped"); - + .expect("request timeout") + .expect("routed broadcast resolves"); let mut sub = broadcast .track("video") .unwrap() @@ -972,31 +999,24 @@ async fn route_reannounce_test(version: Option<&str>) { .expect("subscribe failed"); assert_eq!(read_payloads(&mut sub, 1).await, ["g0"]); - // The publisher re-advertises: the same original publisher, reached through - // a new intermediate relay. + // The publisher re-advertises: the same route, reached through a new + // intermediate relay. let mut hops = moq_net::Hops::new(); hops.push(publisher_hop).unwrap(); hops.push(Hop::new(0x5555).unwrap()).unwrap(); - route_producer - .set_route(moq_net::broadcast::Route::new().with_hops(hops).with_announce(true)) + announcement + .update(moq_net::origin::Route::default().with_hops(hops)) .expect("update route"); - // The subscriber sees the new chain on the same handle... - let updated = tokio::time::timeout(TIMEOUT, watch.route_changed()) - .await - .expect("route update timeout") - .expect("route dropped"); - assert_ne!(initial, updated, "route must change"); + // The subscriber sees the new chain as another active update for the prefix... + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "a restart must not retract the route"); + assert_ne!(initial.hops, update.route.hops, "route must change"); assert!( - updated.hops.iter().any(|h| h.id() == 0x5555), + update.route.hops.iter().any(|h| h.id() == 0x5555), "the new chain must carry the added hop" ); - - // ...with no announce churn, and the subscription keeps flowing. - assert!( - announcements.try_next().is_none(), - "a route change must not emit announce events" - ); { let mut group = track .create_group(moq_net::group::Info { sequence: 1 }) @@ -1024,124 +1044,6 @@ async fn broadcast_route_reannounce_lite_06() { route_reannounce_test(Some("moq-lite-06-wip")).await; } -/// A restart whose first hop changed replaces the broadcast outright. -/// -/// The chain's first hop identifies the original publisher; advertising a -/// different one means the path now carries different content, so the -/// subscriber observes a real Ended + Active (a fresh broadcast) instead of an -/// in-place route update. -async fn route_replaced_test(version: Option<&str>) { - use moq_net::Timestamp; - - let version: Option = version.map(|v| v.parse().expect("invalid version")); - - // ── publisher (server) ────────────────────────────────────────── - let origin = moq_tokio::origin::spawn(Hop::random()); - let mut hops_a = moq_net::Hops::new(); - hops_a.push(Hop::new(0x1111).unwrap()).unwrap(); - let mut producer = origin - .create_broadcast( - "test", - moq_net::broadcast::Route::new().with_hops(hops_a).with_announce(true), - ) - .expect("create broadcast"); - let mut track = producer.create_track("video", None).expect("create track"); - { - let mut group = track - .create_group(moq_net::group::Info { sequence: 0 }) - .expect("create group"); - group.write_frame(Timestamp::ZERO, b"g0".as_ref()).expect("write frame"); - group.finish().expect("finish group"); - } - let mut server_config = moq_tokio::listen::Config::default(); - server_config.bind = Some("[::]:0".to_string()); - server_config.tls.generate = vec!["localhost".into()]; - if let Some(v) = version { - server_config.version = vec![v]; - } - let server = server_config.init(Default::default()).expect("init server"); - let mut server = server.listen().await.expect("failed to listen"); - let addr = server.local_addr().expect("local addr"); - - let mut route_producer = producer.clone(); - - let handle = tokio::spawn(async move { - let request = server.accept().await.expect("accept"); - let session = request.with_publisher(&origin).ok().await?; - let _producer = producer; - let _ = session.closed().await; - Ok::<_, anyhow::Error>(()) - }); - - // ── subscriber (client) ───────────────────────────────────────── - let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); - - let mut client_config = moq_tokio::connect::Config::default(); - client_config.tls.insecure = Some(true); - if let Some(v) = version { - client_config.version = vec![v]; - } - let client = client_config.init(Default::default()).expect("init client"); - let url: url::Url = format!("moqt://localhost:{}", addr.port()).parse().unwrap(); - let (_client, connection) = tokio::time::timeout(TIMEOUT, connect_once(client.with_subscriber(sub_origin), url)) - .await - .expect("connect timeout") - .expect("connect failed"); - - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "test"); - let broadcast = broadcast.expect("expected announce"); - let mut sub = broadcast - .track("video") - .unwrap() - .subscribe(moq_net::track::Subscription::default().with_max_age(Duration::from_secs(10))) - .await - .expect("subscribe failed"); - assert_eq!(read_payloads(&mut sub, 1).await, ["g0"]); - - // A different first hop: a different original publisher took the path over. - let mut hops_b = moq_net::Hops::new(); - hops_b.push(Hop::new(0x2222).unwrap()).unwrap(); - route_producer - .set_route(moq_net::broadcast::Route::new().with_hops(hops_b).with_announce(true)) - .expect("update route"); - - // The subscriber observes the swap as a real unannounce + fresh announce. - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "test"); - assert!(broadcast.is_none(), "expected the old broadcast to end"); - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "test"); - let replacement = broadcast.expect("expected the replacement announce"); - - // The replacement is a fresh broadcast serving the same session's content. - let mut sub = replacement - .track("video") - .unwrap() - .subscribe(moq_net::track::Subscription::default().with_max_age(Duration::from_secs(10))) - .await - .expect("subscribe to the replacement failed"); - assert_eq!(read_payloads(&mut sub, 1).await, ["g0"]); - - drop(connection); - handle.await.expect("server panicked").expect("server failed"); -} - -/// Publisher replacement on the default version (lite-05: a duplicate ANNOUNCE). -#[tracing_test::traced_test] -#[tokio::test] -async fn broadcast_route_replaced() { - route_replaced_test(None).await; -} - -/// Publisher replacement on lite-06 (an explicit ANNOUNCE_RESTART by id). -#[tracing_test::traced_test] -#[tokio::test] -async fn broadcast_route_replaced_lite_06() { - route_replaced_test(Some("moq-lite-06-wip")).await; -} - // ── Raw QUIC (moqt://) – same version on both sides ───────────────── #[tracing_test::traced_test] @@ -1335,8 +1237,9 @@ async fn max_age_test(version: &str) -> Duration { // ── publisher (server) ────────────────────────────────────────── let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("create broadcast"); let info = moq_net::track::Info::default().with_max_age(MAX_AGE_PUBLISHED); let track = broadcast.create_track("video", info).expect("create track"); @@ -1363,7 +1266,8 @@ async fn max_age_test(version: &str) -> Duration { // tracks whose protocol can't carry the publisher's. let sub_origin = moq_tokio::origin::spawn(moq_net::origin::Info::new(Hop::random()).with_default_max_age(MAX_AGE_DEFAULT)); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -1384,9 +1288,13 @@ async fn max_age_test(version: &str) -> Duration { .expect("connect timeout") .expect("connect failed"); - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "test"); - let broadcast = broadcast.expect("expected announce"); + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce"); + let broadcast = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); let sub = broadcast .track("video") @@ -1615,8 +1523,9 @@ async fn broadcast_websocket() { // ── publisher (server) ────────────────────────────────────────── let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast.create_track("video", None).expect("failed to create track"); @@ -1644,7 +1553,8 @@ async fn broadcast_websocket() { // ── subscriber (client) ───────────────────────────────────────── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -1675,14 +1585,17 @@ async fn broadcast_websocket() { .expect("client connect failed"); // Wait for the broadcast announcement. - let moq_tokio::moq_net::announce::Update { path, broadcast: bc } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timed out") - .expect("origin closed"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timed out") + .expect("origin closed"); - assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); // Subscribe to the track. let mut track_sub = bc @@ -1727,8 +1640,9 @@ async fn broadcast_websocket_fallback() { // ── publisher (server) ────────────────────────────────────────── let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast.create_track("video", None).expect("failed to create track"); @@ -1756,7 +1670,8 @@ async fn broadcast_websocket_fallback() { // ── subscriber (client) ───────────────────────────────────────── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -1794,14 +1709,17 @@ async fn broadcast_websocket_fallback() { .expect("client connect failed"); // Wait for the broadcast announcement. - let moq_tokio::moq_net::announce::Update { path, broadcast: bc } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timed out") - .expect("origin closed"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timed out") + .expect("origin closed"); - assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); // Subscribe to the track. let mut track_sub = bc @@ -1850,8 +1768,9 @@ const NEWEST_LITE: &str = "moq-lite-05"; #[tokio::test] async fn broadcast_websocket_uses_newest_version() { let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast.create_track("video", None).expect("failed to create track"); let mut group = track.append_group().expect("failed to append group"); @@ -1921,8 +1840,9 @@ async fn broadcast_websocket_uses_newest_version() { #[tokio::test] async fn broadcast_race_quic_wins() { let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast.create_track("video", None).expect("failed to create track"); let mut group = track.append_group().expect("failed to append group"); @@ -2006,8 +1926,9 @@ async fn quic_driver_task_inherits_connection_span() { use tracing::Instrument; let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast.create_track("video", None).expect("failed to create track"); let mut group = track.append_group().expect("failed to append group"); @@ -2025,7 +1946,8 @@ async fn quic_driver_task_inherits_connection_span() { let addr = server.local_addr().expect("failed to get local addr"); let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -2056,12 +1978,15 @@ async fn quic_driver_task_inherits_connection_span() { .expect("client connect timed out") .expect("client connect failed"); - let moq_tokio::moq_net::announce::Update { broadcast: bc, .. } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timed out") - .expect("origin closed"); - let bc = bc.expect("expected announce, got unannounce"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timed out") + .expect("origin closed"); + assert!(update.active, "expected announce, got retraction"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast(update.prefix.as_path())) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); // Triggers `lite/publisher.rs`'s "subscribed started" log on the server, // from inside the driver task the runtime hands to `tokio::spawn`. @@ -2127,8 +2052,9 @@ async fn quic_driver_task_inherits_connection_span() { #[tokio::test] async fn resubscribe_keeps_flowing_moq_lite_03() { let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); @@ -2147,7 +2073,8 @@ async fn resubscribe_keeps_flowing_moq_lite_03() { let addr = server.local_addr().expect("server addr"); let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -2168,13 +2095,16 @@ async fn resubscribe_keeps_flowing_moq_lite_03() { .expect("connect timeout") .expect("connect failed"); - let moq_tokio::moq_net::announce::Update { path, broadcast: bc } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timeout") - .expect("origin closed"); - assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timeout") + .expect("origin closed"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); // First subscription: receive group 0. let mut sub1 = bc.track("video").unwrap().subscribe(None).await.expect("subscribe1"); @@ -2259,8 +2189,9 @@ fn active_viewers(registry: &moq_net::stats::Registry) -> u64 { #[tokio::test] async fn idle_subscription_releases_the_viewer_count() { let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("video", None).expect("create track"); @@ -2282,7 +2213,8 @@ async fn idle_subscription_releases_the_viewer_count() { let stats = registry.tier(moq_net::stats::Tier::default()).session(""); let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -2304,12 +2236,15 @@ async fn idle_subscription_releases_the_viewer_count() { .expect("connect timeout") .expect("connect failed"); - let moq_tokio::moq_net::announce::Update { broadcast: bc, .. } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timeout") - .expect("origin closed"); - let bc = bc.expect("expected announce"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timeout") + .expect("origin closed"); + assert!(update.active, "expected announce"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast(update.prefix.as_path())) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); let mut sub = bc.track("video").unwrap().subscribe(None).await.expect("subscribe"); let mut g = tokio::time::timeout(TIMEOUT, sub.recv_group()) @@ -2536,8 +2471,9 @@ async fn a_dead_session_unannounces_while_the_reconnect_retries() { let url: url::Url = format!("https://localhost:{}", addr.port()).parse().unwrap(); let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let _broadcast = pub_origin - .create_broadcast("live", moq_net::broadcast::Route::new().with_announce(true)) + let _broadcast = pub_origin.create_broadcast("live").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("live", Default::default()) .expect("create broadcast"); // Accept the first session and hand it back so the test can kill it. Later @@ -2554,7 +2490,8 @@ async fn a_dead_session_unannounces_while_the_reconnect_retries() { }); let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -2568,9 +2505,9 @@ async fn a_dead_session_unannounces_while_the_reconnect_retries() { .expect("connect timed out") .expect("connect failed"); - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "live"); - assert!(broadcast.is_some(), "expected the initial announce"); + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "live"); + assert!(update.active, "expected the initial announce"); // The server kills the session; the loop starts redialing into the void. let session = tokio::time::timeout(TIMEOUT, session_rx) @@ -2579,10 +2516,10 @@ async fn a_dead_session_unannounces_while_the_reconnect_retries() { .expect("server task gone"); session.abort(moq_net::Error::Cancel); - // The unannounce lands promptly, while the connection is still retrying. - let moq_net::announce::Update { path, broadcast } = next_announce(&mut announcements).await; - assert_eq!(path.as_str(), "live"); - assert!(broadcast.is_none(), "a dead session must unannounce, not linger"); + // The retraction lands promptly, while the connection is still retrying. + let update = next_announce(&mut announcements).await; + assert_eq!(update.prefix.as_path().as_str(), "live"); + assert!(!update.active, "a dead session must retract, not linger"); drop(connection); server_handle.abort(); @@ -2599,7 +2536,10 @@ async fn announce_interest_unauthorized_keeps_session_alive() { // ── publisher (server): only allowed to announce under "allowed" ── let pub_origin = moq_tokio::origin::spawn(Hop::random()); let mut broadcast = pub_origin - .create_broadcast("allowed/test", moq_net::broadcast::Route::new().with_announce(true)) + .create_broadcast("allowed/test") + .expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("allowed/test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast.create_track("video", None).expect("failed to create track"); let mut group = track.append_group().expect("failed to append group"); @@ -2621,7 +2561,8 @@ async fn announce_interest_unauthorized_keeps_session_alive() { let consume = sub_origin .scope(&["allowed".into(), "denied".into()]) .expect("failed to scope consume origin"); - let mut announcements = consume.consume().announced(); + let sub_consumer = consume.consume(); + let mut announcements = sub_consumer.announced(); let client = test_client(); let url: url::Url = format!("https://localhost:{}", addr.port()).parse().unwrap(); @@ -2642,13 +2583,12 @@ async fn announce_interest_unauthorized_keeps_session_alive() { .expect("client connect failed"); // The "allowed" announce stream still delivers even though "denied" was FINed. - let moq_tokio::moq_net::announce::Update { path, broadcast: bc } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timed out") - .expect("origin closed"); - assert_eq!(path.as_str(), "allowed/test"); - assert!(bc.is_some(), "expected announce, got unannounce"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timed out") + .expect("origin closed"); + assert_eq!(update.prefix.as_path().as_str(), "allowed/test"); + assert!(update.active, "expected announce, got retraction"); // The unauthorized "denied" interest must not have torn down the session. assert!( @@ -2679,7 +2619,8 @@ async fn publish_only_client_to_subscribe_only_server() { let consume = sub_origin .scope(&["allowed".into(), "denied".into()]) .expect("failed to scope consume origin"); - let mut announcements = consume.consume().announced(); + let sub_consumer = consume.consume(); + let mut announcements = sub_consumer.announced(); let (mut server, addr) = test_server().await; let url: url::Url = format!("https://localhost:{}", addr.port()).parse().unwrap(); @@ -2695,13 +2636,16 @@ async fn publish_only_client_to_subscribe_only_server() { // The client serves "allowed/test"; the "denied" interest is FINed but must not // tear down the session. - let moq_tokio::moq_net::announce::Update { path, broadcast: bc } = - tokio::time::timeout(TIMEOUT, announcements.next()) - .await - .expect("announce timed out") - .expect("origin closed"); - assert_eq!(path.as_str(), "allowed/test"); - let bc = bc.expect("expected announce, got unannounce"); + let update = tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timed out") + .expect("origin closed"); + assert_eq!(update.prefix.as_path().as_str(), "allowed/test"); + assert!(update.active, "expected announce, got retraction"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("allowed/test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); let mut track_sub = bc .track("video") @@ -2735,7 +2679,10 @@ async fn publish_only_client_to_subscribe_only_server() { // ── publisher (client): only allowed to serve under "allowed" ── let pub_origin = moq_tokio::origin::spawn(Hop::random()); let mut broadcast = pub_origin - .create_broadcast("allowed/test", moq_net::broadcast::Route::new().with_announce(true)) + .create_broadcast("allowed/test") + .expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("allowed/test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast.create_track("video", None).expect("failed to create track"); let mut group = track.append_group().expect("failed to append group"); @@ -2807,8 +2754,9 @@ async fn goaway_test(scheme: &str, version: &str, expect_wire_timeout: bool) { // ── publisher (server) ────────────────────────────────────────── let pub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("failed to create broadcast"); let mut track = broadcast.create_track("video", None).expect("failed to create track"); @@ -2829,7 +2777,8 @@ async fn goaway_test(scheme: &str, version: &str, expect_wire_timeout: bool) { // ── subscriber (client) ───────────────────────────────────────── let sub_origin = moq_tokio::origin::spawn(Hop::random()); - let mut announcements = sub_origin.consume().announced(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); @@ -2865,12 +2814,16 @@ async fn goaway_test(scheme: &str, version: &str, expect_wire_timeout: bool) { .expect("client connect failed"); // Subscribe and read the pre-GOAWAY group. - let moq_net::announce::Update { path, broadcast: bc } = tokio::time::timeout(TIMEOUT, announcements.next()) + let update = tokio::time::timeout(TIMEOUT, announcements.next()) .await .expect("announce timed out") .expect("origin closed"); - assert_eq!(path.as_str(), "test"); - let bc = bc.expect("expected announce, got unannounce"); + assert_eq!(update.prefix.as_path().as_str(), "test"); + assert!(update.active, "expected announce, got retraction"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); let mut sub = tokio::time::timeout(TIMEOUT, async { bc.track("video").expect("track handle").subscribe(None).await diff --git a/rs/moq-transcode/examples/transcode.rs b/rs/moq-transcode/examples/transcode.rs index d75336890f5..55df69a4918 100644 --- a/rs/moq-transcode/examples/transcode.rs +++ b/rs/moq-transcode/examples/transcode.rs @@ -59,8 +59,8 @@ async fn main() -> anyhow::Result<()> { // otherwise leave us waiting for an announcement that can never arrive. let consumer = remote.consume(); tokio::select! { - announced = consumer.announced_broadcast(&source_path) => { - announced.context("origin closed before the source broadcast was announced")?; + routed = consumer.routed(&source_path) => { + routed.context("origin closed before the source broadcast was announced")?; } closed = session.closed() => { closed.context("session failed before the source broadcast was announced")?; @@ -83,8 +83,11 @@ async fn main() -> anyhow::Result<()> { config.source = source_path.relative(&output_path).filter(|rel| !rel.is_empty()); let output = publish - .create_broadcast(&output_path, moq_net::broadcast::Route::new().with_announce(true)) + .create_broadcast(&output_path) .context("failed to create the derivative broadcast")?; + let _announce_output = publish + .announce(&output_path, Default::default()) + .context("failed to announce the derivative broadcast")?; tracing::info!(source = %source_path, output = %output_path, "transcoding"); tokio::select! { diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index a6d0940bf15..7bdf450c9cc 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -586,9 +586,7 @@ mod tests { // the output must be minted through an origin: a standalone producer has no path, and // `..` from it would escape, failing the catalog read below. let origin = moq_tokio::origin::spawn(moq_net::Hop::random()); - let output = origin - .create_broadcast("room/transcode", moq_net::broadcast::Route::new()) - .unwrap(); + let output = origin.create_broadcast("room/transcode").unwrap(); let consumer = output.consume(); let transcoder = tokio::spawn(run(source.broadcast.consume(), output, config)); diff --git a/rs/moq-uring/benches/session_lite.rs b/rs/moq-uring/benches/session_lite.rs index cb66744ec80..706a979b10d 100644 --- a/rs/moq-uring/benches/session_lite.rs +++ b/rs/moq-uring/benches/session_lite.rs @@ -147,8 +147,9 @@ mod linux { }); }); - let mut broadcast = pub_origin - .create_broadcast("bench", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("bench").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("bench", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("data", None).expect("create track"); @@ -192,11 +193,11 @@ mod linux { .connect_lite(handle.clone(), quic::web::Session::raw(conn)) .await .expect("connect_lite"); - let bc = sub_origin - .consume() - .announced_broadcast("bench") - .await - .expect("broadcast announced"); + let bc = { + let consumer = sub_origin.consume(); + consumer.routed("bench").await.expect("broadcast announced"); + consumer.request_broadcast("bench").await.expect("broadcast resolves") + }; let sub = bc .track("data") .expect("track") diff --git a/rs/moq-uring/tests/session.rs b/rs/moq-uring/tests/session.rs index d2bf995158a..7765d196194 100644 --- a/rs/moq-uring/tests/session.rs +++ b/rs/moq-uring/tests/session.rs @@ -61,8 +61,9 @@ fn lite_session_over_the_worker() { // Content ready before anyone connects: one broadcast, one track, one // finished group. - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("data", None).expect("create track"); let mut group = track.append_group().expect("append group"); @@ -120,11 +121,11 @@ fn lite_session_over_the_worker() { .await .expect("connect_lite"); - let bc = sub - .consume() - .announced_broadcast("test") - .await - .expect("broadcast announced"); + let bc = { + let consumer = sub.consume(); + consumer.routed("test").await.expect("broadcast announced"); + consumer.request_broadcast("test").await.expect("broadcast resolves") + }; let mut track = bc .track("data") .expect("track") @@ -179,8 +180,9 @@ fn two_lite_sessions_share_the_server_socket() { }); }); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("data", None).expect("create track"); let mut group = track.append_group().expect("append group"); @@ -241,11 +243,11 @@ fn two_lite_sessions_share_the_server_socket() { .await .expect("connect_lite"); - let bc = sub - .consume() - .announced_broadcast("test") - .await - .expect("broadcast announced"); + let bc = { + let consumer = sub.consume(); + consumer.routed("test").await.expect("broadcast announced"); + consumer.request_broadcast("test").await.expect("broadcast resolves") + }; let mut track = bc .track("data") .expect("track") diff --git a/rs/moq-uring/tests/web.rs b/rs/moq-uring/tests/web.rs index 11cb945b805..69699154ea3 100644 --- a/rs/moq-uring/tests/web.rs +++ b/rs/moq-uring/tests/web.rs @@ -219,8 +219,9 @@ fn lite_session_over_webtransport() { rt.block_on(pub_driver.run(support::TokioTimers)); }); - let mut broadcast = pub_origin - .create_broadcast("test", moq_net::broadcast::Route::new().with_announce(true)) + let mut broadcast = pub_origin.create_broadcast("test").expect("create broadcast"); + let _announce_broadcast = pub_origin + .announce("test", Default::default()) .expect("create broadcast"); let mut track = broadcast.create_track("data", None).expect("create track"); let mut group = track.append_group().expect("append group"); @@ -244,11 +245,11 @@ fn lite_session_over_webtransport() { .await .expect("connect_lite"); - let bc = sub_origin - .consume() - .announced_broadcast("test") - .await - .expect("broadcast announced"); + let bc = { + let consumer = sub_origin.consume(); + consumer.routed("test").await.expect("broadcast announced"); + consumer.request_broadcast("test").await.expect("broadcast resolves") + }; let mut track = bc .track("data") .expect("track") diff --git a/rs/moq-wasm/src/lib.rs b/rs/moq-wasm/src/lib.rs index 3dc92dbe5ca..f659e38edab 100644 --- a/rs/moq-wasm/src/lib.rs +++ b/rs/moq-wasm/src/lib.rs @@ -97,10 +97,15 @@ impl Session { Err(js_err(self.inner.closed().await)) } - /// Subscribe to a broadcast by path, waiting until it is announced. + /// Subscribe to a broadcast by path, waiting until a route covers it. pub async fn consume(&self, path: String) -> Result, JsValue> { - let broadcast = self.consumer.announced_broadcast(path.as_str()).await; - Ok(broadcast.map(|inner| Broadcast { inner })) + if self.consumer.routed(path.as_str()).await.is_none() { + return Ok(None); + } + match self.consumer.request_broadcast(path.as_str()).await { + Ok(inner) => Ok(Some(Broadcast { inner })), + Err(_) => Ok(None), + } } } diff --git a/swift/Sources/Moq/Aliases.swift b/swift/Sources/Moq/Aliases.swift index 9edb402ad67..7e69111f393 100644 --- a/swift/Sources/Moq/Aliases.swift +++ b/swift/Sources/Moq/Aliases.swift @@ -71,8 +71,8 @@ public typealias VideoEncoderKind = MoqFFI.MoqVideoEncoderKind public typealias Container = MoqFFI.MoqContainer /// A best-effort raw-track datagram as received: sequence, timestamp, and payload. public typealias Datagram = MoqFFI.MoqDatagram -/// The route a broadcast takes to reach this origin: relay hop ids (oldest -/// first), the publisher's advertised cost (lower wins), and whether it's announced. +/// A path-prefix route: the prefix it covers, relay hop ids (oldest first), +/// and the advertised cost (lower wins). public typealias Route = MoqFFI.MoqRoute /// Per-subscription delivery preferences: priority, group ordering, latency /// budget, and group range. diff --git a/swift/Sources/Moq/Broadcast.swift b/swift/Sources/Moq/Broadcast.swift index 76621d8bdd5..577a1414223 100644 --- a/swift/Sources/Moq/Broadcast.swift +++ b/swift/Sources/Moq/Broadcast.swift @@ -9,18 +9,6 @@ public final class BroadcastConsumer: Sendable { self.ffi = ffi } - /// The route the broadcast currently takes to reach this origin: relay hop - /// ids (oldest first) plus the publisher's advertised cost (lower wins). - public var route: Route { - ffi.route() - } - - /// Watch the broadcast's route: yields the current route first, then every - /// change (e.g. an upstream failover). - public func routeUpdates() -> RouteWatch { - RouteWatch(ffi.routeUpdates()) - } - /// Subscribe to the broadcast's catalog (the description of its tracks). public func subscribeCatalog() async throws -> CatalogConsumer { CatalogConsumer(try await ffi.subscribeCatalog()) @@ -131,38 +119,6 @@ public final class BroadcastConsumer: Sendable { } } -/// A watch over a broadcast's route: an async sequence yielding the current -/// route first, then every change, ending when the broadcast does. Created by -/// `BroadcastConsumer.routeUpdates`. -public final class RouteWatch: AsyncSequence, Sendable { - /// The route emitted by this sequence. - public typealias Element = Route - - let ffi: MoqRouteWatch - - init(_ ffi: MoqRouteWatch) { - self.ffi = ffi - } - - /// Suspend until the next route: the current one on the first call, then - /// each change. Returns nil once the broadcast ends. - public func next() async throws -> Route? { - try await ffi.next() - } - - /// Stop the watch, unblocking any in-flight `next()`. - public func cancel() { - ffi.cancel() - } - - /// Create an iterator that cancels native reads when iteration ends. - public func makeAsyncIterator() -> AsyncThrowingStream.Iterator { - moqStream(cancel: { [ffi] in ffi.cancel() }) { [ffi] in - try await ffi.next() - }.makeAsyncIterator() - } -} - /// Write side of a broadcast: open tracks and publish frames. /// /// Constructing one directly creates a standalone broadcast for serving dynamic @@ -192,15 +148,7 @@ public final class BroadcastProducer: Sendable { BroadcastDynamic(try ffi.dynamic()) } - /// Update the broadcast's route: the hop chain, cost, and liveness it advertises. - /// - /// Use this as conditions shift (e.g. a standby transcoder lowering its cost - /// once warm); consumers observe the change via `BroadcastConsumer.routeUpdates()`. - public func setRoute(_ route: Route) throws { - try ffi.setRoute(route: route) - } - - /// Set whether the broadcast is announced, keeping the rest of its route. + /// Set whether the broadcast's exact path is announced as a route. /// /// The origin advertises the path only while announced; an unannounced /// broadcast stays reachable by exact path for subscribes and fetches. This is diff --git a/swift/Sources/Moq/Origin.swift b/swift/Sources/Moq/Origin.swift index a909700ee4e..0c3917b3202 100644 --- a/swift/Sources/Moq/Origin.swift +++ b/swift/Sources/Moq/Origin.swift @@ -27,14 +27,44 @@ public final class OriginProducer: Sendable { /// Create a broadcast at `path`, returning the producer that feeds it. /// - /// The broadcast starts live: the origin announces the path so subscribers can - /// discover it, becoming visible shortly after this returns. Toggle - /// discoverability with `BroadcastProducer.setAnnounce(_:)`; `finish()` unpublishes - /// immediately, while releasing the producer without finishing also unpublishes - /// but reads to subscribers as a failure rather than a deliberate end. + /// The broadcast starts announced: the origin advertises the exact path as a + /// route so subscribers can discover it, becoming visible shortly after this + /// returns. Toggle discoverability with `BroadcastProducer.setAnnounce(_:)`; + /// `finish()` unpublishes immediately, while releasing the producer without + /// finishing also unpublishes but reads to subscribers as a failure rather + /// than a deliberate end. public func createBroadcast(path: String) throws -> BroadcastProducer { BroadcastProducer(try ffi.createBroadcast(path: path)) } + + /// Advertise a route: a claim that paths under `prefix` can be served. + /// + /// Hold the returned `Announce` for as long as the route should stay + /// advertised. Announcing is independent of `createBroadcast(path:)`: + /// announce one short prefix and serve requests beneath it with `dynamic()`. + public func announce(prefix: String, route: Route = Route()) throws -> Announce { + Announce(try ffi.announce(prefix: prefix, route: route)) + } +} + +/// A live route advertisement. The route stays advertised until `cancel()` +/// (or the handle is released). +public final class Announce: Sendable { + let ffi: MoqAnnounce + + init(_ ffi: MoqAnnounce) { + self.ffi = ffi + } + + /// Re-price the route in place: replace its hops and cost. + public func update(route: Route) throws { + try ffi.update(route: route) + } + + /// Retract the route. + public func cancel() { + ffi.cancel() + } } /// A requested broadcast that has not been accepted yet. @@ -100,26 +130,27 @@ public final class OriginConsumer: Sendable { self.ffi = ffi } - /// Stream every broadcast announced under a prefix. + /// Stream every route announced under a prefix. public func announced(prefix: String) throws -> Announced { Announced(try ffi.announced(prefix: prefix)) } - /// Wait for a single broadcast announced at an exact path. + /// Wait for a route covering an exact path, then resolve the broadcast there. public func announcedBroadcast(path: String) throws -> AnnouncedBroadcast { AnnouncedBroadcast(try ffi.announcedBroadcast(path: path)) } - /// Request a broadcast by path, resolving as soon as it can be served: an existing - /// exact-path broadcast whether announced or not, otherwise a dynamic fallback on the - /// origin, or an error if neither can serve it. Unlike `announcedBroadcast`, this does - /// not wait for a future announcement. + /// Request a broadcast by path, resolving as soon as it can be served: a local + /// broadcast at the exact path, then the best announced route covering the path + /// (served on demand by the session that announced it), then a dynamic fallback on + /// the origin, or an error if nothing can serve it. Unlike `announcedBroadcast`, + /// this does not wait for a future announcement. public func requestBroadcast(path: String) async throws -> BroadcastConsumer { BroadcastConsumer(try await ffi.requestBroadcast(path: path)) } } -/// A stream of broadcast announcements. Iterate directly: +/// A stream of route announcements and retractions. Iterate directly: /// `for try await announcement in announced { ... }`. The sequence ends when the /// origin closes; cancelling the consuming task cancels the subscription. public final class Announced: AsyncSequence, Sendable { @@ -150,7 +181,11 @@ public final class Announced: AsyncSequence, Sendable { } } -/// A single broadcast announcement. +/// A single route announcement or retraction. +/// +/// A route claims that paths under `path` can be served; it carries no +/// broadcast. Resolve a specific path with `OriginConsumer.requestBroadcast`. +/// By convention a publisher announces each broadcast's exact path. public final class Announcement: Sendable { let ffi: MoqAnnouncement @@ -158,14 +193,20 @@ public final class Announcement: Sendable { self.ffi = ffi } - /// The path of the announced broadcast. + /// The announced route's prefix, relative to the `announced` prefix. public var path: String { ffi.path() } - /// A consumer for the announced broadcast. - public var broadcast: BroadcastConsumer { - BroadcastConsumer(ffi.broadcast()) + /// Whether the route is active (`true`) or was retracted (`false`). A + /// repeated active announcement for the same path is a metadata update. + public var active: Bool { + ffi.active() + } + + /// The announced route: its prefix, relay hops, and cost. + public var route: Route { + ffi.route() } } @@ -177,8 +218,8 @@ public final class AnnouncedBroadcast: Sendable { self.ffi = ffi } - /// Suspend until the broadcast is announced. Throws `Closed` if cancelled or - /// the origin closes first. + /// Suspend until a route covers the path, then resolve the broadcast there. + /// Throws `Closed` if cancelled or the origin closes first. public func available() async throws -> BroadcastConsumer { BroadcastConsumer(try await ffi.available()) }