Cloudflare opens up its async QUIC and HTTP/3 toolkit
Cloudflare has released tokio-quiche as an open-source library, pairing its QUIC implementation with the Tokio async runtime for Rust. The library has been in production use at Cloudflare for years, handling millions of HTTP/3 requests per second across services like Apple iCloud Private Relay, Oxy-based proxies, and Warp's MASQUE client.
The project's history traces back to quiche, Cloudflare's sans-io QUIC implementation. That design keeps the QUIC state machine separate from any specific I/O strategy, so developers must write their own socket handling, datagram management, and runtime integration. tokio-quiche removes that burden by providing a complete asynchronous integration layer.
Bridging the sans-io gap
The original quiche library was built as a low-level, protocol-only implementation. While that made it portable across many types of software, integrating it into applications proved error-prone and time-consuming. Developers had to manually manage UDP sockets, feed datagrams into the quiche state machine, and handle the resulting output while also coordinating with an async runtime.
The motivation to build tokio-quiche as a standalone library came from Cloudflare's own need for MASQUE-capable HTTP/3 clients. The Zero Trust and Privacy teams wanted clients that could tunnel data through Warp and Privacy Proxies, and Cloudflare wanted a shared technology base for both client and server implementations.
Open sourcing the library is meant to lower the barrier for others building HTTP/3 and QUIC services. Cloudflare's own adoption of these protocols matters less if external systems can't easily interoperate with them, so the company is contributing the async integration code back to the Rust ecosystem.
Note that tokio-quiche is not a turnkey HTTP/3 client or server. It implements low-level protocols and exposes the building blocks that higher-level projects can be built upon. The README includes examples for both server and client event loops.
Actor-based architecture
tokio-quiche uses an actor model to drive the QUIC and HTTP/3 state machines. Actors are small tasks with internal state that communicate with the outside world through message passing over channels. This pattern fits naturally with sans-io libraries, since both rely on exclusive state access and message-like interactions with their environment.
The actor approach translates raw events into quiche-friendly inputs: awaiting new messages or I/O, converting them to something quiche understands, advancing the state machine, and converting outputs back into messages or I/O operations.
At the center of the architecture is an I/O loop actor that moves packets between quiche and the UDP socket. Since QUIC is a transport protocol supporting any application layer, tokio-quiche defines the ApplicationOverQuic trait to abstract over application protocols. This trait covers quiche's methods and the underlying I/O so developers can focus on their own application logic.
The library ships with an HTTP/3 implementation of that trait called H3Driver, which connects quiche's HTTP/3 module to the I/O loop. It transforms quiche's raw HTTP/3 events into higher-level events and provides asynchronous body data streams. The generic H3Driver is specialized into ServerH3Driver and ClientH3Driver variants that layer server- or client-specific behavior on top.
Packet routing internals
Two tasks manage data flow from the socket to quiche. The InboundPacketRouter owns the receiving half of the socket and routes incoming datagrams by destination connection ID to a per-connection channel. The second task, the IoWorker, is the I/O loop that drives a single quiche connection, interleaving quiche calls with ApplicationOverQuic methods so callers can inspect the connection before and after I/O operations.
Future work includes releasing higher-level HTTP client and server abstractions similar to those used in Oxy proxies and Warp clients. Cloudflare says more technical posts on actor models, mutexes, UDP GRO/GSO, and Tokio task cooperation budgeting are in the pipeline.
