Cloudflare’s tokio-quiche How to Make QUIC and HTTP/3 a First Class Citizen on Rust Backends

Cloudflare has an open source tokio-quiche, an asynchronous QUIC and HTTP/3 Rust library that wraps its battle-tested quiche implementation in the Tokio runtime. The library has been refined within production systems such as Apple iCloud Private Relay, next-generation Oxy-based proxies and WARP’s MASQUE client, where it handles millions of HTTP/3 requests per second with low latency and high performance. tokio-quiche guides Rust teams who want QUIC and HTTP/3 without writing their own UDP and event loop integration code.

From quiche to tokio-quiche

quiche is Cloudflare’s open source QUIC and HTTP/3 implementation written in Rust and designed as a low-level, sans-io library. It uses the QUIC transport state machine, which includes connection establishment, flow control and broadcast replication, while not considering how applications perform IO. To use quiche directly, compilers must open UDP sockets, send and receive datagrams, manage sessions and feed all packet data to quiche correctly. This design provides flexibility, but makes assembly error prone and time consuming.

tokio-quiche packs this activity into a reusable crate. It combines the use of sans-io QUIC or HTTP/3 from quiche with the Tokio async runtime, and exposes an API that already handles UDP sockets, packet routing and calls to the quiche state machine.

Character-based architecture in Tokyo

Internally, the tokio-quiche uses an actor model over Tokio. Actors are small functions with a local state that communicate via messages over channels, which are compatible with sans-io protocol implementations that manage internal state and operate on message-like buffers.

The main actor is the IO loop actor, which routes packets between the quiche and the UDP socket. One of the key message types is Incoming structure that describes the received UDP packets. Async integration follows a fixed pattern, the IO loop waits for new messages, translates them into quiche input, advances the QUIC state machine, and translates the output into output packets written back to the socket.

For each UDP socket, tokio-quiche exposes two important functions. InboundPacketRouter owns the receiving portion of the socket and routes incoming datagrams through the connection’s local ID to each connection’s channels. IoWorker is a communication IO loop and calls one quiche Connectionomitting calls to quiche and calls to specific application logic implemented by using ApplicationOverQuic. This design encapsulates the connection state within each actor and keeps QUIC processing separate from the high-level protocol code.

ApplicationOverQuic and H3Driver

QUIC is a transport protocol and can handle many application protocols. HTTP/3, DNS over QUIC and Media over QUIC are examples covered by the IETF specification. To avoid consolidating tokio-quiche into a single protocol, the Cloudflare team exposes the ApplicationOverQuic feature. The feature extends beyond quiche methods and basic IO, and introduces high-level events and hooks to the application that implements the protocol. For example, the HTTP/3 debugging and testing client h3i uses a non-HTTP/3 installation ApplicationOverQuic.

On top of this feature, tokio-quiche ships with an HTTP/3-centric implementation named H3Driver. H3Driver connects the HTTP/3 quiche module to the IO loop actor and converts raw HTTP/3 events into high-level events with an asynchronous body flow suitable for application code. H3Driver it is familiar and revealing ServerH3Driver again ClientH3Driver variants that add server-side and client-side behavior on top of the main driver. These components provide the building blocks for HTTP/3 servers and clients that share usage patterns with Cloudflare’s internal infrastructure.

Production implementation and roadmap

tokio-quiche was used for several years within Cloudflare before its public release. It enables Proxy B on Apple iCloud Private Relay, Oxy-based HTTP/3 servers and the WARP MASQUE client, and the async version of h3i. For the WARP client, MASQUE-based tunnels built into tokio-quiche replace the previous WireGuard-based tunnels with QUIC-based tunnels. These systems run at Cloudflare edge scale and demonstrate that the integration can support millions of HTTP/3 requests per second in production.

Cloudflare uses tokio-quiche as a base rather than a complete HTTP/3 framework. The library exposes low-level protocol capabilities and instance client and server event loops, and leaves room for high-level projects to use conceptual HTTP servers, DNS in addition to QUIC clients, MASQUE-based VPNs and other QUIC applications in addition. By releasing Crate, Cloudflare aims to lower the barrier for Rust teams to use QUIC, HTTP/3 and MASQUE, and align external integration with the same transport stack used in its edge services.

Key Takeaways

• tokio-quiche = quiche + Tokio: tokio-quiche is an async Rust library that includes Cloudflare’s sans-io QUIC and HTTP/3 implementations, quiche, and the Tokio runtime, so developers don’t need to manually write UDP and event loop pipelines.
• Character-based architecture for QUIC connections: The library uses an actor model in Tokio, with InboundPacketRouter which transmits the UDP datagram by connection ID and IoWorker what drives you one quiche Connection for each function, to keep the transport state single and integrated.
• ApplicationOverQuic abstraction: The protocol logic is divided by ApplicationOverQuic feature, which summarizes the details of quiche and IO for very different QUIC-based protocols such as HTTP/3, DNS over QUIC or custom protocols that can be used over the same transport context.
• HTTP/3 with H3Driver, ServerH3Driver and ClientH3Driver: tokio-quiche ships H3Driver plus ServerH3Driver again ClientH3Driver a variant including the HTTP/3 quiche module for async Rust code, which exposes HTTP/3 streams and bodies in a way that matches standard Tokio-based services.

Check it out Technical details. Also, feel free to follow us Twitter and don’t forget to join our 100k+ ML SubReddit and Subscribe to Our newspaper. Wait! are you on telegram? now you can join us on telegram too.