net: migrate subscriptions transparently across connections

[kixelated]

Summary

Subscriptions migrate transparently across connections: the model is no longer tied to a single session. N connections feed the same logical tracks, and applications never observe a route change or resubscribe.

Two-layer design. track::Producer/track::Consumer stay tied to a single session. A new crate-internal resume model splices per-session tracks into one logical track at group boundaries:

• resume::Producer::switch(track, N) appends a segment serving groups from N and caps the previous segment at N - 1, so segments always partition the sequence space. takeover(track) computes the boundary (one past the newest spliced group) for callers reacting to a route change.
• resume::Subscriber reads across segments as one track. Bounds are enforced on the read side: a route delivering past its cap is silently filtered, never an error, so wire compliance is an optimization rather than a correctness requirement. A dead segment stalls the subscriber (no error) until the next switch resumes it.
• Demand forwards to each session's track intersected with its segment bounds, so a serving session just sees an ordinary subscription that happens to start or end at a boundary. The resume point is the slice's group_start, riding the normal SUBSCRIBE with zero special-casing.

The resume module is pub(crate): applications only ever see track::Consumer/Subscriber (that's the transparency), so nothing new is exposed for the consuming side. Exposing manual splicing later is additive.

Origin routes. attach_route(path, route) returns a Route, the lifecycle owner: dropping it detaches (failover semantics), unannounce(self) detaches gracefully. The first route creates and announces the (spliced) broadcast; later routes join silently as standbys. A serving task drains Route::assignments() (an origin::Assignments queue that outlives the handle); only the best route (shortest hops) is dispatched origin::Assignments. Assignment::serve(self, info) splices in the session's own track and returns an origin::Serving that derefs to the track::Producer; complete()/retire() end it deliberately (absorbing the track finish), while dropping an assignment or serving hands the track back (re-queued for the next route, bounded retries). When a route detaches, its tracks re-queue and the replacement resumes at the boundary; when the last route detaches the broadcast lingers 5s for a reconnect, and a deliberate Route::unannounce closes immediately so clean shutdowns propagate promptly and a re-announce is a fresh broadcast.

Live handover: a strictly better route attaching mid-subscription takes live tracks over at an explicit group boundary. The old route's demand is capped via SUBSCRIBE_UPDATE and it winds down; the subscriber reads a seamless sequence.

Dynamic routes. broadcast::Info is now purely static identity; the path a broadcast takes lives in a new broadcast::Route { hops, cost } that changes over the broadcast's lifetime. broadcast::Producer::set_route publishes a change; broadcast::Consumer::route() / route_changed() observe it (current value first, then every update). Route selection orders by (cost, hop length, deterministic hash): a publisher can advertise how expensive it is to serve (a standby transcoder at cost 10, dropping to 0 once warm) and change its mind as capacity shifts. Cost is local-only until the wire carries it (with the lite announce-id work). Internally, a session updates its attached route's metadata in place; the origin re-picks the winner and hands live tracks over at a boundary exactly like an attach. Updates propagate end to end: the lite publisher watches announced broadcasts and forwards hop changes as a restart (duplicate ANNOUNCE on lite-05, ANNOUNCE_RESTART by id on lite-06), including announces that cross the forwarding filter in either direction; the lite subscriber applies a received restart as an in-place route update rather than a route swap. A front promoting a standby route now re-advertises downstream automatically, closing the stale-hops gap.

The first hop identifies the publisher. A received restart is applied as an in-place route update only when the incoming chain's first hop (the publisher's origin) matches the currently attached route; a different first hop is a different publisher and resolves as a separate route (attach/detach), not a splice. Versions without wire hop ids get a per-session random origin so distinct upstream sessions still resolve as distinct routes. The rule is now normative in draft-lcurley-moq-relay-hops, updated in this PR.

Announced::Restart is removed. Route churn is invisible to announced(); a direct publish replaced by a better one is delivered as Ended + Active. Wire format unchanged; ANNOUNCE_RESTART decodes as an internal route swap.

Public API changes (rs/moq-net)

• Added: broadcast::Route (builder: new/with_hop/with_hops/with_cost) + broadcast::Producer::set_route + broadcast::Consumer::{route, route_changed, poll_route_changed}; track::Consumer::latest.
• Removed (breaking): Announced::Restart / announce::Event::Restart; broadcast::Info.hops (moved to the dynamic broadcast::Route); track::{Consumer,Subscriber}::get_group (see below). Hence the dev target.
• Changed (breaking): none beyond the removals. (Subscriber::closed is untouched: dev removed it in feat(moq-net): let finish_at declare a future exclusive end group (#2219) #2234, and this branch now merges that.)
• get_group removed, both halves. Consumer::get_group had no callers outside moq-net, and inside the crate only itself (its spliced arm delegated to resume::Consumer::get_group, which walked back to each segment's plain get_group -- a cycle with no entry point). Subscriber::get_group was a footgun: waiting on a sequence that may never arrive (gaps are legal, an evicted group waits for the track to close) parks forever on a live track with no error to act on. fetch_group covers both: cached resolves immediately, uncached asks a Dynamic (wire FETCH), unservable fails with NotFound. The relay's ?group=latest now fetches the sequence latest() reports, matching how ?group=<n> already worked. This also squares the Rust surface with js/net, which never had getGroup.

FFI / wrappers

moq-ffi drops MoqAnnouncement.hops (a static snapshot of now-dynamic state) and mirrors the Route API: a MoqRoute record (hops + cost), MoqBroadcastProducer.set_route, and on the consumer a route() snapshot plus route_updates(), a cancellable watch (current route first, then every change) following the MoqAnnounced stream pattern so Go can cancel via context. Wrappers updated per cross-package sync: Python (moq.Route, route/route_changed, set_route), Swift (Route, route, routeUpdates() AsyncSequence, setRoute), Kotlin (Route/RouteWatch typealiases, routes() Flow), Go (Route alias, Route()/RouteUpdates()/SetRoute), plus the Python docs. libmoq never exposed hops, so the C surface is untouched; a C route watch is deferred until a consumer needs one.

• track::Consumer/Subscriber internally dispatch between plain and spliced backings; no new public types in track.

Testing

• resume model: splice, boundary filtering, demand slicing and re-slicing, takeover boundaries, dead-segment stall, finish semantics, read_frame/get_group/fetch across segments, fetch waiting for the first segment.
• Origin: failover with boundary resume, live handover, linger + re-attach, linger expiry, immediate graceful unannounce, direct-publish replacement as Ended+Active.
• Dynamic routes: route_changed watch semantics (initial value, coalescing, dropped); a cost update flipping the winner hands live tracks over at a boundary and re-advertises, with zero announce events.
• e2e (real QUIC + WebTransport): broadcast_route_migration kills the serving session mid-subscription and the same track::Subscriber keeps reading from the standby with zero announce events; broadcast_route_reannounce (lite-05 and lite-06 variants) updates the publisher's route mid-subscription and the subscriber observes the new hop chain on the same broadcast handle, no announce churn, subscription uninterrupted; full lite/ietf version matrix green; clippy clean.
• just test smoke-full (cross-language interop, built from this checkout): all 21 cells pass — rust/python/browser-js publishers x rust/python/browser-js/js-native-node/js-native-bun/c/gst subscribers. Two pre-existing harness breaks were fixed along the way (see below).

Kept current with dev

The branch absorbed three dev landings mid-review, re-porting the route machinery onto each: the flattened announce updates + kio::Shared broadcasts, the stats module + kio Pollable + guard-driven announce lifetimes (announce guards now own the advert; the route watch plugs into the guard), and #2377's tokio removal (every former tokio::select! in the announce loop, serve loop, decode paths, and origin linger now polls under a single kio::wait waiter). Each merge was re-verified with strict clippy and the full moq-net suite.

Unrelated fixes bundled (pre-existing, found by smoke-full)

• macOS static-link flags: libmoq.a/moq-ffi bundle moq-video, so static consumers need Foundation/CoreMedia/CoreVideo/AVFoundation/VideoToolbox + -lc++ (openh264). dev has since fixed the smoke harness itself (feat(capture): macOS window/app/system-audio sources and device enumeration #2293 adds ScreenCaptureKit too, so its list wins on merge), but the libmoq CMake config (build + the installed moq-config.cmake.in that CMake consumers like the OBS plugin inherit) and the Go cgo flags still carried the pre-moq-video list; both are fixed here. Linux-only smoke CI can't catch macOS link rot, same as the earlier CoreServices gap.

Deliberately deferred

• Broadcast epoch/id on the wire: same-path announces are assumed to be alternate routes of the same content (matching the existing backup-route assumption). An epoch in ANNOUNCE would make the check exact; natural fit for the lite-06 announce-id work.
• Segment/track reaping: a front's logical tracks and old segments are kept until the broadcast closes, so idle session tracks pause (near-zero cost) rather than tear down. Reaping and demand-triggered re-assignment are follow-up.
• Cost on the wire: broadcast::Route.cost drives local selection but only hops ride ANNOUNCE, so a received route always has default cost. An explicit cost field (and its aggregation rule across relays) belongs with the lite announce-id work.
• Node-level re-selection on route update: selection among same-path direct publishes samples routes at (un)publish time; a later set_route doesn't re-run that compare. Fronts (the normal network path) re-select on every update.
• IETF sessions still direct-publish (no route attach); moq-transport ingress keeps today's churn semantics.
• js/net mirror owed per Cross-Package Sync.
• A group mid-transfer when its route dies is not re-delivered live (subscribers may already hold it); it stays reachable via FETCH like any other loss.

🤖 Generated with Claude Code

(Written by Claude Fable 5)

[sourcery-ai]

Sorry @kixelated, your pull request is larger than the review limit of 150000 diff characters