diff --git a/quest/m1/poll-first/README.md b/quest/m1/poll-first/README.md index 653eb03aab6..882587d683b 100644 --- a/quest/m1/poll-first/README.md +++ b/quest/m1/poll-first/README.md @@ -75,4 +75,4 @@ and their alternatives: ## Required - [Generated async wrappers behind a feature](/quest/m1/poll-first/async-feature.md) - each library's `async fn` wrappers are generated from its `poll_*` signatures and compile only with its `async` feature -- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md) - moq-ffi, moq-stats, and moq-relay's cluster and auth run as polled `kio::Tasks` children instead of spawned tasks +- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn/README.md) - moq-ffi, moq-stats, and moq-relay's cluster and auth run as polled `kio::Tasks` children instead of spawned tasks diff --git a/quest/m1/poll-first/no-spawn.md b/quest/m1/poll-first/no-spawn.md deleted file mode 100644 index 35c35d270a8..00000000000 --- a/quest/m1/poll-first/no-spawn.md +++ /dev/null @@ -1,39 +0,0 @@ -# [L] Libraries spawn nothing - -## Goal - -moq-ffi, moq-stats, and moq-relay's cluster and auth decider spawn no tasks: -their background work runs as `kio::Tasks` children that the owner polls, -returned as a handle whose poll drives it. Only the edges spawn a root task: -binaries and the bindings' runtime. moq-relay's in-memory integration tests -(`rs/moq-relay/tests/integration/connection.rs`) run on kio's simulator -instead of paused tokio. - -## Plan - -Decided with the maintainer on 2026-10-25, replacing the m2 runtime trait -(spawn and time for tokio, browser, io_uring, and sim): - -- **Poll everywhere, no spawn.** A spawn trait keeps `'static` detached tasks - in the library, which poll-first rejects; `kio::Tasks` already gives a - library structured children with no runtime. Time is - `kio::clock`, so nothing is left for a runtime trait. - `rs/AGENTS.md` already treats `tokio::spawn` in a library as a smell. -- **No I/O seam.** I/O stays at moq-net's `transport::poll` traits and - moq-sock: tokio's readiness model and io_uring's completion model (the - kernel owns the buffer) can't share a zero-cost API. -- **Blocking work is out of scope.** OS threads for blocking capture, encode, - or file I/O are not async tasks and stay. - -Per crate: moq-ffi spawns only its root at the binding boundary; moq-stats and moq-relay's `Cluster::new` and auth decider -return work their owner polls. List any spawn that has to stay, with why, in -the PR. - -Public API: constructors that spawned return a handle to poll or await -instead. The PR's Impact section describes migration for the published crates whose API changes. Wire: -none. - -## Related - -- [The remaining spawns](/quest/m2/spawn-audit.md) - the same rule for every other library crate -- [Generated async wrappers](/quest/m1/poll-first/async-feature.md) - the poll-first sibling that gates the async layer diff --git a/quest/m1/poll-first/no-spawn/README.md b/quest/m1/poll-first/no-spawn/README.md new file mode 100644 index 00000000000..ca02cfbac92 --- /dev/null +++ b/quest/m1/poll-first/no-spawn/README.md @@ -0,0 +1,61 @@ +# Libraries spawn nothing + +## Goal + +moq-ffi, moq-stats, and moq-relay's cluster and auth decider spawn no tasks: +their background work runs as `kio::Tasks` children that the owner polls, +returned as a handle whose poll drives it. Only the edges spawn a root task: +binaries and the bindings' runtime. moq-relay's in-memory integration tests +(`rs/moq-relay/tests/integration/connection.rs`) run on kio's simulator +instead of paused tokio. + +## Plan + +Decided with the maintainer on 2026-10-25, replacing the m2 runtime trait +(spawn and time for tokio, browser, io_uring, and sim): + +- **Poll everywhere, no spawn.** A spawn trait keeps `'static` detached tasks + in the library, which poll-first rejects; `kio::Tasks` already gives a + library structured children with no runtime. Time is + `kio::clock`, so nothing is left for a runtime trait. + `rs/AGENTS.md` already treats `tokio::spawn` in a library as a smell. +- **No I/O seam.** I/O stays at moq-net's `transport::poll` traits and + moq-sock: tokio's readiness model and io_uring's completion model (the + kernel owns the buffer) can't share a zero-cost API. +- **Blocking work is out of scope.** OS threads for blocking capture, encode, + or file I/O are not async tasks and stay. + +✅ **Split into four children** (maintainer, 2026-11-01, D1 on +[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519)), landed in the +order of Required below. One PR could not hold them all, and two open PRs +already changed part of the scope: +[moq-dev/moq#7360](https://github.com/moq-dev/moq/pull/7360) (merged +2026-11-01) removed the auth decider loop and returns moq-stats' publisher from +`Producer::new`, and +[moq-dev/moq#7497](https://github.com/moq-dev/moq/pull/7497) rewrites moq-ffi's +`Task` and `Background` plumbing. Each child records its own decisions. + +Every child lists any spawn that has to stay, with why, in its PR. Public API: +constructors that spawned return a handle to poll or await instead. Each PR's +Impact section describes migration for the published crates whose API changes. +Wire: none. + +These spawns stay and belong to [the spawn audit](/quest/m2/spawn-audit.md): +`Critical`'s ACME renewal (`rs/moq-relay/src/relay.rs`) and web certificate +reload (`rs/moq-relay/src/web.rs`), the io_uring handoff in +`rs/moq-relay/src/connection.rs`, and moq-relay's web, shutdown, and uring +spawns. Each UniFFI call's task on the bindings' runtime stays too: that is the +binding boundary. + +## Required + +- [Cluster polls its own work](/quest/m1/poll-first/no-spawn/cluster.md) - `Cluster::new` returns a `Driver` the relay polls, and the dial loop runs as `kio::Tasks` children +- [Admissions and stats are polled](/quest/m1/poll-first/no-spawn/admissions.md) - HTTP admissions run inside their waiter, and the stats publisher runs in the cluster's driver +- [moq-ffi spawns only its root](/quest/m1/poll-first/no-spawn/ffi.md) - one runtime-owned driver task holds every `Background` as `kio::Tasks` children +- [The relay's in-memory tests run on kio's simulator](/quest/m1/poll-first/no-spawn/sim-tests.md) - `rs/moq-relay/tests/integration/connection.rs` runs on the simulator instead of paused tokio + +## Related + +- [The remaining spawns](/quest/m2/spawn-audit.md) - the same rule for every other library crate +- [Generated async wrappers](/quest/m1/poll-first/async-feature.md) - the poll-first sibling that gates the async layer +- [Poll-native async in moq-ffi](/quest/m2/ffi-poll-migrate.md) - its PR reworks the moq-ffi task plumbing this epic touches diff --git a/quest/m1/poll-first/no-spawn/admissions.md b/quest/m1/poll-first/no-spawn/admissions.md new file mode 100644 index 00000000000..86c63132c59 --- /dev/null +++ b/quest/m1/poll-first/no-spawn/admissions.md @@ -0,0 +1,41 @@ +# [S] Admissions and stats are polled + +## Goal + +moq-relay spawns no task per HTTP admission, and `Cluster::with_stats` spawns +no stats publisher. The `Server` decider's request runs inside the caller that +waits on its answer, and the publisher runs as a child of the cluster's +`Driver`. + +## Plan + +Spawns in scope on `main` (2026-11-01): + +- `rs/moq-relay/src/auth.rs`, `Decider::Server`: one + `tokio::spawn(moq_tokio::panic::isolate(..))` per admission HTTP request. + [moq-dev/moq#7360](https://github.com/moq-dev/moq/pull/7360) (merged + 2026-11-01) already removed the decider loop around it. +- `rs/moq-relay/src/cluster.rs`, `Cluster::with_stats`: the stats publisher, + through `Critical`. Since #7360, `moq_stats::Producer::new` returns + `(Producer, Publisher)`, so moq-stats itself spawns nothing. + +✅ **The waiter polls the admission** (maintainer, 2026-11-01, D3 on +[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519)): the caller +waiting on `Answer` polls the `moq_auth::Client` request inline, and dropping +the wait cancels the request, which replaces the `reply.closed()` select. A +panic then ends the session being admitted, the same scope the per-admission +`isolate` gives today. Rejected: one long-lived `kio::Tasks` of admissions +polled by `Relay::run`, which brings back the long-lived decider task that +#7360 removed. + +The publisher joins `Driver`, the type +[Cluster polls its own work](/quest/m1/poll-first/no-spawn/cluster.md) +introduces, so a publisher panic still ends the relay. `Publisher::run` is an +`async fn`; giving `Publisher` a `poll` is optional and only worth it if +`Driver` needs it. + +Public API: `Cluster::with_stats` no longer needs a tokio runtime. Wire: none. + +## Required + +- [Cluster polls its own work](/quest/m1/poll-first/no-spawn/cluster.md) - provides the `Driver` the publisher joins diff --git a/quest/m1/poll-first/no-spawn/cluster.md b/quest/m1/poll-first/no-spawn/cluster.md new file mode 100644 index 00000000000..b7cde935748 --- /dev/null +++ b/quest/m1/poll-first/no-spawn/cluster.md @@ -0,0 +1,52 @@ +# [L] Cluster polls its own work + +## Goal + +moq-relay's `Cluster` spawns no tasks. `Cluster::new` returns the origin +driver and cache governor as work its owner polls, and `Started::run` drives +every dial, the `api.url` reconciler, and mDNS discovery as `kio::Tasks` +children instead of a tokio `JoinSet` and detached tasks. The relay still exits +with the panic message when a task it cannot serve without panics. + +## Plan + +Spawns in scope on `main` (2026-11-01), all in `rs/moq-relay/src/cluster.rs`: + +- `Cluster::new`: the cache governor and the origin driver, through `Critical`. +- `run_work`: the dial `JoinSet`, the `api.url` reconciler, and mDNS. +- `run_mdns` and `apply_peer_list`: one detached task per peer, tracked by an + `AbortHandle` in `DialMap`. These become a queue into the `run` loop's + `Tasks`, so `DialMap` holds `TaskKey`s. +- `Held::drop`: the close of a LAN dial's client. `Dialers` polls its existing + close set instead. + +✅ **`Cluster::new` returns a driver** (maintainer, 2026-11-01, D2 on +[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519)): +`Cluster::new(options) -> anyhow::Result<(Cluster, Driver)>`, the same shape as +`origin::Producer::new`. `Relay::run` polls `Driver` next to `Started::run`. +`Driver` catches each child's panic and turns it into an error, so the relay +still exits with "origin driver panicked: ..." the way `Critical` does now. +Tests spawn the driver, because they are edges. Rejected: keeping the signature +and moving the driver into `Started::run`, which breaks `Cluster::new`'s +documented promise that the origin serves sessions whether or not `start` is +ever called. There are about 68 `Cluster::new(` call sites across moq-relay, +moq-cli, the benches, and moq-net's `mesh_withdraw` test. + +✅ **Peer dials stop running in parallel** (maintainer, 2026-11-01, D5 on +[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519)): as `kio::Tasks` +children, every peer dial supervisor runs on the task that polls +`Started::run` instead of its own tokio task. The heavy session I/O is still +spawned inside moq-tokio, which the spawn audit owns, so the cost is probably +small. Measure it once in this PR and report the result. + +`Critical` stays for ACME renewal and the web certificate reload, which belong +to the spawn audit; `Cluster::with_stats` keeps spawning the publisher until +[the admissions child](/quest/m1/poll-first/no-spawn/admissions.md) moves it +into `Driver`. + +Public API: `Cluster::new` returns `(Cluster, Driver)`; the PR's Impact section +describes the migration. Wire: none. + +## Related + +- [The remaining spawns](/quest/m2/spawn-audit.md) - owns moq-tokio's session spawns and `Critical`'s remaining tasks diff --git a/quest/m1/poll-first/no-spawn/ffi.md b/quest/m1/poll-first/no-spawn/ffi.md new file mode 100644 index 00000000000..c11a7fad8a9 --- /dev/null +++ b/quest/m1/poll-first/no-spawn/ffi.md @@ -0,0 +1,35 @@ +# [M] moq-ffi spawns only its root + +## Goal + +moq-ffi spawns one task outside its UniFFI calls: a runtime-owned driver that +polls every `Background` as a `kio::Tasks` child. Origin drivers, the server +accept loop, cleanups, and demand waits no longer spawn tasks of their own. + +## Plan + +Spawns in scope on `main` (2026-11-01), all in `rs/moq-ffi/src/`: + +- `ffi.rs`, `ffi::spawn` and `Background::driver`: origin drivers + (`origin.rs`), the server accept loop (`server.rs`), and cleanups. +- `ffi.rs`, `detached`: demand waits (`demand.rs`, `producer.rs`). +- `ffi.rs`, each UniFFI call's task on the bindings' runtime. This stays: each + call's own future is the binding boundary. + +✅ **One root driver** (maintainer, 2026-11-01, D4 on +[moq-dev/moq#7519](https://github.com/moq-dev/moq/pull/7519)): moq-ffi's root +is one runtime-owned driver task that holds every `Background` as `kio::Tasks` +children. Rejected: having each handle's calls poll its `Background`, which +fails for an origin with no reader, since nobody would poll its driver. + +[moq-dev/moq#7497](https://github.com/moq-dev/moq/pull/7497) replaces +`ffi::Task` with `ffi::Polled` and changes `Background` and shutdown in +`ffi.rs`, keeping demand waits `detached` for now. Build on it: converting +before it lands would conflict on almost every line. Recount the sites above +once it merges. + +Public API: no binding signature changes. Wire: none. + +## Required + +- [Poll-native async in moq-ffi](/quest/m2/ffi-poll-migrate.md) - its PR rewrites the `Task` and `Background` plumbing this changes diff --git a/quest/m1/poll-first/no-spawn/sim-tests.md b/quest/m1/poll-first/no-spawn/sim-tests.md new file mode 100644 index 00000000000..f5f4c7e581c --- /dev/null +++ b/quest/m1/poll-first/no-spawn/sim-tests.md @@ -0,0 +1,23 @@ +# [M] The relay's in-memory tests run on kio's simulator + +## Goal + +moq-relay's in-memory integration tests +(`rs/moq-relay/tests/integration/connection.rs`) run on kio's simulator +instead of paused tokio. + +## Plan + +This needs the cluster's and the admissions' work to be polled, which the +children it requires deliver. It also needs `moq_tokio::origin::spawn` and the +memory connect helper the tests use to run without tokio. moq-tokio belongs to +[the spawn audit](/quest/m2/spawn-audit.md) (m2), so this quest may move to +m2, or require the part of the spawn audit that converts those two helpers. +Decide that when it starts. + +Public API: none. Wire: none. + +## Required + +- [Cluster polls its own work](/quest/m1/poll-first/no-spawn/cluster.md) - the cluster's driver and dials stop spawning on tokio +- [Admissions and stats are polled](/quest/m1/poll-first/no-spawn/admissions.md) - admissions stop spawning on tokio diff --git a/quest/m2/ffi-poll-migrate.md b/quest/m2/ffi-poll-migrate.md index c211625940c..91ef76c574b 100644 --- a/quest/m2/ffi-poll-migrate.md +++ b/quest/m2/ffi-poll-migrate.md @@ -77,4 +77,4 @@ get items in call order; sequence and arrival order are unchanged. Wire: none. ## Related - [Foreign poll for hot reads](https://github.com/moq-dev/rust2/blob/main/quest/m1/ffi-poll-protocol.md) - the generated protocol that follows this, once the fork exists -- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md) - moq-ffi spawns only its root at the binding boundary +- [moq-ffi spawns only its root](/quest/m1/poll-first/no-spawn/ffi.md) - one runtime-owned driver task holds every `Background` as `kio::Tasks` children diff --git a/quest/m2/net-wrap/README.md b/quest/m2/net-wrap/README.md index 6c36e493cd2..def14e4acfb 100644 --- a/quest/m2/net-wrap/README.md +++ b/quest/m2/net-wrap/README.md @@ -15,7 +15,7 @@ Compression is not a wrapper: it moves into moq-net as a track flag moq-flate, so moq-flate is out of scope. Non-goals: -- A runtime seam: libraries poll and spawn nothing ([Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md)). +- A runtime seam: libraries poll and spawn nothing ([Libraries spawn nothing](/quest/m1/poll-first/no-spawn/README.md)). - The transport seam: custom transports implement moq-net's `transport::poll` traits ([native WebTransport](/quest/m1/quic-api/native-web.md) moves the last backend onto them). ## Plan diff --git a/quest/m2/spawn-audit.md b/quest/m2/spawn-audit.md index ef8f07a03d5..196c0c4fe22 100644 --- a/quest/m2/spawn-audit.md +++ b/quest/m2/spawn-audit.md @@ -3,7 +3,7 @@ ## Goal Every async task spawn left in a library crate after -[Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md) is either converted +[Libraries spawn nothing](/quest/m1/poll-first/no-spawn/README.md) is either converted to a `kio::Tasks` child its owner polls or listed with the reason it must stay. Blocking OS threads are out of scope. @@ -26,4 +26,4 @@ migration note per published crate. Wire: none. ## Required -- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md) - the rule and the pattern this applies +- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn/README.md) - the rule and the pattern this applies diff --git a/quest/m3/studio/web/video-web.md b/quest/m3/studio/web/video-web.md index 99bb372055a..7df8c0047d5 100644 --- a/quest/m3/studio/web/video-web.md +++ b/quest/m3/studio/web/video-web.md @@ -35,4 +35,4 @@ target; confirm the web studio still wants it before starting. ## Required -- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn.md) - library work polled by its owner, with no runtime to spawn on +- [Libraries spawn nothing](/quest/m1/poll-first/no-spawn/README.md) - library work polled by its owner, with no runtime to spawn on