diff --git a/quest/m1/README.md b/quest/m1/README.md index 9136e7589c9..858d0979785 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -175,6 +175,7 @@ their end report, so an embedder's drain alert pages on real cuts. - [Main is no slower than release](/quest/m1/release-perf/README.md) - every benchmark where main is slower than release is fixed or accepted with a reason, checked by a final paired run before the cut - [Calibrate the paired nightly benchmarks](/quest/m1/bench-ci.md) - A/A and deliberately slowed Nightly runs set the paired comparison's threshold, so its regression alerts can be trusted - [Unbounded groups](/quest/m1/unbounded-groups/README.md) - groups and frames lose their size caps; a group keeps a 32 MB tail, and readers behind it replay through paced flights or refresh +- [Session policy lives in moq-net](/quest/m1/session-policy/README.md) - accept and connect deadlines, admission, window widening and reconnect live once in moq-net; moq-tokio and moq-relay's io_uring path call them - [Poll-first async](/quest/m1/poll-first/README.md) - library crates compile no coroutines by default: async wrappers are generated from `poll_*` and gated behind an `async` feature - [HLS export lists a same-codec reconfigure's first group under the new init](/quest/m1/hls-reinit-same-codec.md) - the hand-over pick, whichever of the catalog and the records arrives first, after the catalog `hls` removal is planned - [Ordered reads can skip owed holes, and snapshot latest() does](/quest/m1/ordered-owed-holes.md) - moq-net's `Ordered` gains a read that skips past an owed hole to the newest buffered group, while keeping the reader's bounds diff --git a/quest/m1/cut-audit/README.md b/quest/m1/cut-audit/README.md index 91ca4e0675a..a604c998485 100644 --- a/quest/m1/cut-audit/README.md +++ b/quest/m1/cut-audit/README.md @@ -41,9 +41,11 @@ internal and can ship after the cut: [resume as producer replacement](/quest/m2/resume-redesign.md), [moq-transport request leases](/quest/m2/ietf-request-lease.md), [group heads filled in place](/quest/m2/ietf-fill-refill.md), -[one relay serve path](/quest/m2/relay-serve-path.md), -moqsrc pad actors and publish rendition identity (both since landed). Other -redesign evidence went into the quests that already own the mechanism: +moqsrc pad actors and publish rendition identity (both since landed). The +[one relay serve path](/quest/m1/session-policy/uring.md) proposal moved into +m1 on 2026-11-04, as part of moving session policy into moq-net before the +cut. Other redesign evidence went into the quests that already own the +mechanism: [subscribe ranges](/quest/m1/subscribe-ranges/README.md), [drop set](/quest/m1/drop-set.md), [per-origin routes](/quest/m1/cluster-routing/routes/README.md), diff --git a/quest/m1/poll-first/README.md b/quest/m1/poll-first/README.md index 303a78e2085..738e8a26822 100644 --- a/quest/m1/poll-first/README.md +++ b/quest/m1/poll-first/README.md @@ -75,4 +75,3 @@ 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 -- [Server::accept and Handshake::ok are kio machines](/quest/m1/poll-first/server-machines.md) - moq-net's `Server::accept` and `server::Handshake::ok` are `#[kio::machine]` `poll_*` methods with one-line async wrappers, like the other straight-line bodies converted in [moq-dev/moq#7284](https://github.com/moq-dev/moq/pull/7284) diff --git a/quest/m1/poll-first/server-machines.md b/quest/m1/poll-first/server-machines.md deleted file mode 100644 index dd2ee6bc699..00000000000 --- a/quest/m1/poll-first/server-machines.md +++ /dev/null @@ -1,34 +0,0 @@ -# [S] Server::accept and Handshake::ok are kio machines - -## Goal - -moq-net's `Server::accept` and `server::Handshake::ok` are `#[kio::machine]` -`poll_*` methods with one-line async wrappers, like the other straight-line -bodies converted in [moq-dev/moq#7284](https://github.com/moq-dev/moq/pull/7284). Behavior, errors, and their public async -signatures stay the same. - -## Plan - -Decided 2026-10-31 (user, /quest-plan of the follow-ups from the 2026-10-31 -/quest-complete run), from -[moq-dev/moq#7284](https://github.com/moq-dev/moq/pull/7284). - -Milestone: ✅ m1. Not chosen: m2. - -- Both are straight-line in spirit (`rs/moq-net/src/server.rs:283` and - `:769` at be39188000; [moq-dev/moq#7284](https://github.com/moq-dev/moq/pull/7284) called the second - `Request::ok`), but they wait on the session handshake, which has no poll form, so - [moq-dev/moq#7284](https://github.com/moq-dev/moq/pull/7284) left them as `async fn`. - [Generated async wrappers](/quest/m1/poll-first/async-feature.md) converts - the handshake by hand; once it has, convert these two through - `#[kio::machine]`, following the conventions in `kio::machine`'s docs and - the bodies [moq-dev/moq#7284](https://github.com/moq-dev/moq/pull/7284) (merged) converted. -- If the handshake's poll form makes either body a loop rather than - straight-line, hand-write that `poll_*` instead and say so in the PR. - -Public API: adds `poll_accept`/`poll_ok` beside the existing async methods. -Wire: none. - -## Required - -- [Generated async wrappers](/quest/m1/poll-first/async-feature.md) - gives the handshake a poll form these bodies wait on diff --git a/quest/m1/session-policy/README.md b/quest/m1/session-policy/README.md new file mode 100644 index 00000000000..62ba3e31c82 --- /dev/null +++ b/quest/m1/session-policy/README.md @@ -0,0 +1,69 @@ +# Session policy lives in moq-net + +## Goal + +Session policy lives once, in moq-net. Accept and connect deadlines (spanning +SETUP, admission and the reply, closing with Timeout), the admission bound, +widening the receive window on admit, and reconnect with backoff come from +moq-net for tokio, io_uring and WebRTC sessions alike. moq-tokio keeps only +sockets, DNS, TLS, accept loops, the fallback runtime and spawning. The epic is +done when moq-relay's hand-copied policy in `uring.rs` is deleted in favour of +the moq-net calls, and the WebRTC transport's session runs through the same +policy. + +## Plan + +Planned 2026-11-04 with the maintainer, from the WebRTC consolidation draft +[moq-dev/moq#7804](https://github.com/moq-dev/moq/pull/7804), which asked +where moq-webrtc should plug its externally established transport in. The +maintainer asked what that means for io_uring and how much of moq-tokio belongs +in moq-net, and decided: + +- ✅ **Move the policy first**, then give moq-tokio thin handoffs; #7804 waits + on [moq-tokio becomes a thin shell](/quest/m1/session-policy/tokio-handoff.md). + Not chosen: a moq-tokio handoff now with the move later; moq-webrtc calling + moq-net directly with its own policy. +- ✅ **Reconnect is in scope**: the reconnect, backoff and GOAWAY candidate + walk move too, as a poll machine. Not chosen: leaving them in moq-tokio + until io_uring dials. +- ✅ **Fold** the m2 relay-serve-path quest into + [the io_uring path](/quest/m1/session-policy/uring.md) and the + poll-first server-machines quest into + [accept policy](/quest/m1/session-policy/accept.md). +- ✅ **Break moq-net's public API in m1**, before the cut, with MIGRATE notes. + Not chosen: additive APIs beside the old ones. + +Research (2026-11-04, `origin/main` at e6be13d5f8): + +- moq-tokio owns the accept deadline (`server.rs` `Setup::deadline`, + `within`, `Deadline::bound`, default 10 s in `listen.rs`) up to the SETUP + reply, which moq-net already bounds through `Handshake::with_deadline` + (`rs/moq-net/src/server.rs`), the connect + deadline (`client.rs`, default 30 s in `connect.rs`), receive-window holding + and widening on admit (`Request::ok`, `qmux_limits`), `Request` + construction per transport, and reconnect (`connection.rs` `Backoff`, + `Goaway`, `run`). All of it runs on `kio::clock`, so none of it needs tokio. + Only sockets, DNS, Happy Eyeballs, TLS, accept loops, `runtime::scope`, + spawning and WebRTC's own UDP socket are tokio-specific. +- moq-relay's io_uring path re-implements the server side by hand + (`rs/moq-relay/src/uring.rs`: its own `Deadline`, the admission bound, + the drain-bounded reply, and the `with_deadline` and `set_limits` calls + that wire them up). Eight commits + patched drift between the copies (58eaa6afd5, 8a13d58910, 6bd1306d6e, + 1f56330d21, d17b84ee7f, 4576bb1231, c11192c7e6, 67df70012d). moq-uring + itself has no client side. +- Widening on admit needs a transport hook: moq-net's `transport::poll` + session exposes only `receive_window()`, while tokio QUIC, qmux and uring's + `web::Session` all have `set_limits`. Add a trait method whose default + reports unsupported, the same move [QUIC deadline](/quest/m2/quic-deadline.md) + plans for per-stream deadlines. +- moq-net stays poll-first and spawns nothing + ([libraries spawn nothing](https://github.com/moq-dev/moq/pull/6849)): + policy returns drivers and machines, and the caller spawns and does the I/O. + +## Required + +- [Accept policy in moq-net](/quest/m1/session-policy/accept.md) - one accept deadline, admission bound and window widening for every transport +- [Connect policy in moq-net](/quest/m1/session-policy/connect.md) - the connect deadline and reconnect as a poll machine +- [The io_uring relay path uses moq-net's policy](/quest/m1/session-policy/uring.md) - deletes `uring.rs`'s copy +- [moq-tokio becomes a thin shell](/quest/m1/session-policy/tokio-handoff.md) - sockets, TLS, accept loops and spawning, plus the transport handoffs WebRTC needs diff --git a/quest/m1/session-policy/accept.md b/quest/m1/session-policy/accept.md new file mode 100644 index 00000000000..44e7d35c7a2 --- /dev/null +++ b/quest/m1/session-policy/accept.md @@ -0,0 +1,44 @@ +# [M] Accept policy in moq-net + +## Goal + +moq-net's server accepts a session under one policy for every transport: an +accept deadline that spans the transport handshake, SETUP, admission and the +reply and closes with the Timeout code; the admission bound; and a held-back +receive window widened on admit through a new `set_limits` method on +`transport::poll::Session` (default: unsupported). `Server::accept_request` +(which `Server::accept` wraps, and which moq-tokio and moq-relay's io_uring +path call) and `server::Handshake::ok` are `#[kio::machine]` poll methods with +one-line async wrappers. moq-tokio's `Setup::deadline`, `within`, `Deadline::bound` and its +window widening call this instead of implementing it. + +## Plan + +Part of [Session policy lives in moq-net](/quest/m1/session-policy/README.md); +see it for the decisions and research. + +- Folded in 2026-11-04 (maintainer): the poll-first server-machines quest + ([last version](https://github.com/moq-dev/moq/blob/e6be13d5f8/quest/m1/poll-first/server-machines.md)). + Convert `Server::accept` and `Handshake::ok` to poll machines, following + `kio::machine`'s conventions and [moq-dev/moq#7284](https://github.com/moq-dev/moq/pull/7284); + if the handshake's poll form makes either a loop, hand-write that `poll_*` + and say so. The policy then moves onto those machines rather than the async + bodies they replace. +- moq-net already bounds the reply: `Handshake::with_deadline` refuses a SETUP + reply the peer never takes. Extend that deadline back over SETUP and + admission rather than adding a second one. The transport handshake runs + before moq-net has a session, so the caller bounds it against the same + instant, as moq-tokio's `within` does today. +- WebRTC's receive-window exception (`qmux_limits` in moq-tokio's `server.rs`) + becomes a property the transport reports, not a special case in the accept + path. +- Keep today's defaults (10 s accept) and error codes; tests cover a deadline + hit at each phase and widening on admit for QUIC, qmux and a transport that + can't widen. + +Public API: breaking in moq-net (`Server`, `Handshake`, the transport session +trait), with MIGRATE notes. Wire: none. + +## Required + +- [Generated async wrappers](/quest/m1/poll-first/async-feature.md) - gives the handshake a poll form these machines wait on diff --git a/quest/m1/session-policy/connect.md b/quest/m1/session-policy/connect.md new file mode 100644 index 00000000000..aab876ced54 --- /dev/null +++ b/quest/m1/session-policy/connect.md @@ -0,0 +1,32 @@ +# [L] Connect policy in moq-net + +## Goal + +moq-net owns client connect policy as poll machines: the connect deadline over +dial plus handshake, and reconnect with backoff, GOAWAY handling and the +candidate walk. moq-net does no I/O: the caller supplies each dial attempt and +the machine decides when to start, abandon, back off or move to the next +candidate. moq-tokio's `Client`/`Connection` drive these machines instead of +implementing the policy. + +## Plan + +Part of [Session policy lives in moq-net](/quest/m1/session-policy/README.md); +see it for the decisions and research. Decided 2026-11-04 (maintainer): +reconnect moves too, not just the deadline. + +- Today's policy: the connect deadline in moq-tokio's `client.rs` (default 30 s + in `connect.rs`), and `Backoff`, `Goaway`, `run`, `attempt_timeout`, + `settles_walk` and `refreshed` in `connection.rs`. All of it runs on + `kio::clock` and `select!`; only the dialing (DNS, Happy Eyeballs, sockets, + TLS) is tokio-specific and stays in moq-tokio. +- Keep the current behaviour and defaults; port the existing + `connection.rs` tests to the moq-net machines on kio's simulator, so the same + timings are asserted without tokio. +- This also gives a future io_uring client + ([uring-cluster-dial](/quest/m3/uring-cluster-dial.md)) the policy to reuse + rather than copy. + +Public API: breaking in moq-net's `Client` and new reconnect types; moq-tokio's +`Connection` API keeps its shape where possible, with MIGRATE notes otherwise. +Wire: none. diff --git a/quest/m1/session-policy/tokio-handoff.md b/quest/m1/session-policy/tokio-handoff.md new file mode 100644 index 00000000000..efcdec89f3d --- /dev/null +++ b/quest/m1/session-policy/tokio-handoff.md @@ -0,0 +1,40 @@ +# [S] moq-tokio becomes a thin shell + +## Goal + +moq-tokio keeps only sockets, DNS, TLS, accept loops, the fallback runtime and +spawning, and calls moq-net for all session policy. It gains two public +handoffs for transports established elsewhere: `accept_with(transport, link)` +on the listener and `connect_with(transport)` on the client, which run the +moq-net accept or connect policy over an already-connected session and return +the usual request or session. moq-tokio's own `webrtc` module goes through +them, so the [WebRTC rename](/quest/m1/webrtc-rename.md) moves it into +moq-webrtc without reaching into moq-tokio's internals. + +## Plan + +Part of [Session policy lives in moq-net](/quest/m1/session-policy/README.md); +see it for the decisions and research. This is what +[moq-dev/moq#7804](https://github.com/moq-dev/moq/pull/7804) and the +[WebRTC rename](/quest/m1/webrtc-rename.md) wait on: the maintainer decided on +2026-11-04 to move the policy first, so the handoff is a few lines over +moq-net rather than a copy of the policy. + +- The handoff's signature (transport plus link metadata in, request or session + out) is fixed by this quest and does not change if policy moves further. +- Delete moq-tokio's now-unused `Deadline`, `Backoff` and the like, and its + per-transport `Request` construction that moq-net now owns. Bounding the + transport handshake (`within`) stays here, since moq-net has no session yet + at that point. +- Its consumer is the WebRTC transport: moq-tokio's `webrtc` module here, and + moq-webrtc once the rename moves it, so the + [API audit](/quest/m1/api-audit/README.md) rule (a new public surface needs a + consumer) is met. + +Public API: moq-tokio adds `accept_with` and `connect_with` and drops internals +it re-exported, with MIGRATE notes. Wire: none. + +## Required + +- [Accept policy in moq-net](/quest/m1/session-policy/accept.md) - the accept policy the handoff runs +- [Connect policy in moq-net](/quest/m1/session-policy/connect.md) - the connect policy the handoff runs diff --git a/quest/m1/session-policy/uring.md b/quest/m1/session-policy/uring.md new file mode 100644 index 00000000000..352223d1e00 --- /dev/null +++ b/quest/m1/session-policy/uring.md @@ -0,0 +1,40 @@ +# [M] The io_uring relay path uses moq-net's policy + +## Goal + +moq-relay serves io_uring sessions through the same moq-net accept policy and +the same `Connection::run` and listen-config mapping as tokio, so a +lifecycle or config fix lands once. The hand-copied deadline, admission bound +and drain-bounded reply in `rs/moq-relay/src/uring.rs`, and the `with_deadline` +and `set_limits` calls that wire them up, are deleted. + +## Plan + +Part of [Session policy lives in moq-net](/quest/m1/session-policy/README.md); +see it for the decisions and research. + +- Folded in 2026-11-04 (maintainer): the m2 relay-serve-path quest + ([last version](https://github.com/moq-dev/moq/blob/e6be13d5f8/quest/m2/relay-serve-path.md)). + Its finding stands: `uring::serve_request` re-implements moq-relay's + `Connection::run` (`rs/moq-relay/src/connection.rs`; the old quest called it + `Connection::serve`) step for step, `Workers::bind` re-implements the config + mapping also at moq-tokio's `server.rs` and `websocket.rs`, and eight commits + patched the drift (58eaa6afd5, 8a13d58910, 6bd1306d6e, 1f56330d21, + d17b84ee7f, 4576bb1231, c11192c7e6, 67df70012d). +- Implement the sealed `incoming::Sealed` for a uring `Request` whose driver + runs on the worker handle, with admission hopping to the shared runtime + through `Lifecycle::shared`, so one `Connection::run` serves every runtime. + Use one listen-config mapping at all three sites. +- Do this before the io_uring packaging work publishes the duplicated path. +- The relay's existing drain, admission and handshake-deadline tests must + pass on both runtimes. + +Public API: none. Wire: none. + +## Required + +- [Accept policy in moq-net](/quest/m1/session-policy/accept.md) - the shared policy this path calls + +## Related + +- [io_uring relay package](/quest/m2/relay-io-uring-package.md) - ships the path this unifies diff --git a/quest/m1/webrtc-rename.md b/quest/m1/webrtc-rename.md index 0c31beae4e3..88adb4b524f 100644 --- a/quest/m1/webrtc-rename.md +++ b/quest/m1/webrtc-rename.md @@ -11,12 +11,17 @@ Decided 2026-10-30 with the maintainer (planning interview); see the [epic](/que Milestone: ✅ m1 (moved from m2, maintainer, 2026-11-03). Not chosen: keep it in m2, or send [moq-rtc on rind](/quest/m1/rind/rtc.md) back to m2. [Vendor and trim the WebRTC stack](/quest/m1/webrtc-vendor.md) requires this, and m1's rind epic requires the vendoring, so this sits at the m1 top level. It stays a child of the m2 [WebRTC epic](/quest/m2/webrtc/README.md). - Move `rs/moq-rtc` to `rs/moq-webrtc` and merge `rs/moq-ice` in as a module. Keep the gateway's `server` feature; add a feature for the data-channel transport so WHIP/WHEP-only builds skip SCTP. -- Move moq-tokio's `webrtc` module (`rs/moq-tokio/src/webrtc.rs`, host gathering, `.local` resolution) into moq-webrtc, built on moq-tokio's public session types. If the move needs something moq-tokio keeps private, bring the shape to the maintainer. +- Move moq-tokio's `webrtc` module (`rs/moq-tokio/src/webrtc.rs`, host gathering, `.local` resolution) into moq-webrtc, built on moq-tokio's public session types. Its connect and accept go through moq-tokio's `connect_with`/`accept_with` handoffs, which run moq-net's session policy over the established data channel. +- Boundary decided 2026-11-04 (maintainer, from [moq-dev/moq#7804](https://github.com/moq-dev/moq/pull/7804)): ✅ move session policy into moq-net first ([Session policy lives in moq-net](/quest/m1/session-policy/README.md)), then this rename uses the thin handoffs. Not chosen: a moq-tokio handoff over today's policy, or moq-webrtc calling moq-net with its own policy. Removing SCTP stays with [Vendor and trim the WebRTC stack](/quest/m1/webrtc-vendor.md). - Update moq-cli's `rtc` subcommand, the bindings or examples that use the transport, `test/p2p`, and every doc and quest naming the old crates. - Publishing: the last `moq-rtc`/`moq-ice` releases stay on crates.io; `doc/setup/upgrade.md` says where things moved. Version numbers are the maintainer's. Public API: breaking (crate rename; `moq_tokio::webrtc` moves). Wire: none. +## Required + +- [moq-tokio becomes a thin shell](/quest/m1/session-policy/tokio-handoff.md) - the `accept_with`/`connect_with` handoffs moq-webrtc uses + ## Related - [moq-rtc REMB and TIAS](/rs/moq-rtc/src/server/whip.rs) - #7373 adds the capped answer in moq-rtc; carry it through the move diff --git a/quest/m2/README.md b/quest/m2/README.md index f42c9265759..0dfdf0a053e 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -117,7 +117,6 @@ lite-07; bitrate enforcement is not part of this release. - [A moq-transport group head fills its hole in place](/quest/m2/ietf-fill-refill.md) - fills and joining FETCHes write into the tail's group, deleting the `Fill` handoff - [moq-transport hole markers](/quest/m2/ietf-hole-marker.md) - a negotiated extension names a SUBSCRIBE's holes, so our publishers answer multi-group FETCH from caches that know every group; built when an IETF client wants it - [Announce interest streams share one route table](/quest/m2/announce-interest-memory.md) - per-stream announce cost follows what is in flight, not every route -- [One relay serve path for every runtime](/quest/m2/relay-serve-path.md) - io_uring serves through the shared `Connection::serve` and config mapping - [A parked read of a resumed group reads its budget without re-syncing](/quest/m2/recover-budget.md) - measure, then drop the per-frame reader sync - [One port](/quest/m2/one-port/README.md) - one UDP port carries QUIC, SRT, and WebRTC media through an embedder hook, and one TCP port carries HTTP, RTMP, and RTMPS - [WebSocket caps](/quest/m2/rate-websocket.md) - paced reads and writes over bounded socket buffers hold WebSocket to the same caps diff --git a/quest/m2/relay-serve-path.md b/quest/m2/relay-serve-path.md deleted file mode 100644 index d5f3ca2939f..00000000000 --- a/quest/m2/relay-serve-path.md +++ /dev/null @@ -1,37 +0,0 @@ -# [M] One relay serve path for every runtime - -## Goal - -The relay serves a session through one `Connection::serve` on every -runtime, and one `listen::Config` to `moq_net::Server` mapping in moq-tokio -serves the tokio, WebSocket, and io_uring listeners, so a lifecycle or -config fix lands once instead of drifting between runtimes. - -## Plan - -From the 2026-10-24 pre-cut audit at 151a529670. Internal only. - -`uring::serve_request` (`rs/moq-relay/src/uring.rs:803-926`) re-implements -`Connection::serve` (`connection.rs:90-164`) step for step (admit, QUIC -limits, stats, limits, origins, `preparing`, `serve()`, a drain-bounded -`ok()`, spawn the driver, supervise), and `Workers::bind` re-implements the -config mapping also found at `rs/moq-tokio/src/server.rs:424` and -`websocket.rs:66`. Fixes patching exactly this gap: 58eaa6afd5 -(listen.extensions), 8a13d58910 (MTU), 6bd1306d6e (SETUP tokens), -1f56330d21 (handshake deadline), d17b84ee7f (drain across handshakes), -4576bb1231 (admission bound), c11192c7e6, 67df70012d. -`Workers::bind` now destructures `moq_tokio::listen::Resolved` (from -`listen::Config::resolve`) exhaustively, so a new listen field fails to -compile there; the tokio sites still read `listen::Config` directly. - -Implement the sealed `incoming::Sealed` for a uring `Request` whose -`Driver` runs on the worker handle, with admission hopping to the shared -runtime through `Lifecycle::shared`, so one `Connection::serve` serves -every runtime. Use that one config mapping at all three sites. Do this before the io_uring packaging work publishes the -duplicated path. - -Public API: none. Wire: none. - -## Related - -- [io_uring relay package](/quest/m2/relay-io-uring-package.md) - ships the path this unifies