From 7c3972925999fcdf5bcb52ca67028397d03b408b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 21:46:49 -0700 Subject: [PATCH] quest: plan a runtime-free QUIC driver Co-Authored-By: Claude Opus 5.5 --- quest/m2/README.md | 1 + quest/m2/quic-sansio-driver.md | 57 ++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) create mode 100644 quest/m2/quic-sansio-driver.md diff --git a/quest/m2/README.md b/quest/m2/README.md index 27a83af8d80..284683dbc33 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -29,6 +29,7 @@ lite-07; bitrate enforcement is not part of this release. - [rust2 publishes its UniFFI fork](/quest/m2/rust2-uniffi.md) - waiting on kixelated/rust2 to import UniFFI and moq's generators and publish them - [Switch to rust2's UniFFI](/quest/m2/uniffi-fork.md) - moq-ffi and every wrapper build from kixelated/rust2's fork under one pin, and moq's generator code is deleted - [Generated C bindings](/quest/m2/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written crate +- [A runtime-free QUIC driver](/quest/m2/quic-sansio-driver.md) - a caller's own loop moves UDP datagrams and polls moq sessions over moq-quic, for rust2's bindings - [MoQ on rind](/quest/m2/rind/README.md) - every MoQ crate takes its crypto from rind, a pure-Rust graviola fork, so no build compiles C crypto - [Benchmark sources](/quest/m2/bench-sources.md) - every measuring nightly benchmark feeds the regression table, and none is a smoke run - [Poll-native async](/quest/m2/ffi-poll-migrate.md) - moq-ffi's pure-kio async exports poll their state directly instead of going through `ffi::Task` diff --git a/quest/m2/quic-sansio-driver.md b/quest/m2/quic-sansio-driver.md new file mode 100644 index 00000000000..73aa68c98b8 --- /dev/null +++ b/quest/m2/quic-sansio-driver.md @@ -0,0 +1,57 @@ +# [L] A runtime-free QUIC driver + +## Goal + +A caller with its own event loop and UDP socket runs moq sessions over moq-quic, with no +runtime in the library. The driver owns moq-quic's endpoint, its connections, and TLS. The +caller hands it each datagram it receives, sends each one the driver returns, and polls it +on each wake and at the deadline the poll returns. Its connections implement moq-net's +`transport::poll::Session`, so moq-net's `Client::connect` and `Server::accept` take them. +No tokio or io_uring is in its dependency tree. + +The first consumer is [kixelated/rust2](https://github.com/kixelated/rust2)'s exporter, +whose C, C++, and Kotlin bindings drive it from their own loops +([sessions on sans-IO QUIC](https://github.com/kixelated/rust2/blob/main/quest/m1/ffi-export/session-quic.md)). + +## Plan + +Decided with the maintainer on 2026-10-28, from +[kixelated/rust2#215](https://github.com/kixelated/rust2/pull/215): + +- **After [waits](/quest/m1/quic-api/waits.md) and [poll](/quest/m1/quic-api/poll.md).** + Once moq-quic owns its waits, a driver is I/O, timers, and a lock. This one is the + timers and the lock, with the caller doing the I/O. Built earlier, it would carry the + waiter tables that waits deletes. +- **Pull, like moq-net's `Driver`s.** The caller passes in each received datagram with its + source address. It polls with its `kio::Waiter` on each wake, after each datagram, and + at the deadline the poll returns, then drains outgoing datagrams, each with its + destination, until none is left. The driver makes no calls back into the caller, and + hands out owned bytes, since a binding can't lend a mutable buffer across a C ABI. A + transmit into a caller's buffer, such as a GSO batch, can follow on + [the QUIC I/O boundary](/quest/m2/quic-io-boundary.md). + +Open, for whoever starts it: + +- Where it lives: a module in moq-quic, which doesn't depend on moq-net today, or a crate + of its own. +- Whether it ships with WebTransport over HTTP/3, sharing + [native WebTransport](/quest/m1/quic-api/native-web.md)'s `quic::web`, or with raw + QUIC's moq ALPN first. +- How it builds its TLS configs (identity, roots, fingerprint pinning) without + moq-tokio's `tls` module. + +Mirror the two drivers' names and signatures where they overlap. Test it against +moq-tokio's server over loopback on simulated time. Bound a hostile peer's cost as the +other drivers do. + +Public API: a new driver, its endpoint and connection types, and their `poll::Session` +impl. + +## Required + +- [Waits](/quest/m1/quic-api/waits.md) - moq-quic owns every wait, so the driver keeps no waiter table +- [Poll forms](/quest/m1/quic-api/poll.md) - the drivers' poll shape this one mirrors + +## Related + +- [UDP demux](/quest/m2/p2p/udp-demux.md) - also feeds datagrams from a socket the endpoint doesn't own