Crate tokio_quiche

Bridging the gap between [quiche] and [tokio].

tokio-quiche connects [quiche::Connection]s and [quiche::h3::Connection]s to tokio’s event loop. Users have the choice between implementing their own, custom ApplicationOverQuic or using the ready-made H3Driver for HTTP/3 clients and servers.

Starting an HTTP/3 Server

A server listens on a UDP socket for QUIC connections and spawns a new tokio task to handle each individual connection.

use futures::stream::StreamExt;
use tokio_quiche::http3::settings::Http3Settings;
use tokio_quiche::listen;
use tokio_quiche::metrics::DefaultMetrics;
use tokio_quiche::quic::SimpleConnectionIdGenerator;
use tokio_quiche::ConnectionParams;
use tokio_quiche::ServerH3Driver;

let socket = tokio::net::UdpSocket::bind("0.0.0.0:443").await?;
let mut listeners = listen(
    [socket],
    ConnectionParams::default(),
    SimpleConnectionIdGenerator,
    DefaultMetrics,
)?;
let mut accept_stream = &mut listeners[0];

while let Some(conn) = accept_stream.next().await {
    let (driver, mut controller) =
        ServerH3Driver::new(Http3Settings::default());
    conn?.start(driver);

    tokio::spawn(async move {
        // `controller` is the handle to our established HTTP/3 connection.
        // For example, inbound requests are available as H3Events via:
        let event = controller.event_receiver_mut().recv().await;
    });
}

For client-side use cases, check out our connect API.

Feature Flags

tokio-quiche supports a number of feature flags to enable experimental features, performance enhancements, and additional telemetry. By default, no feature flags are enabled.

• rpk: Support for raw public keys (RPK) in QUIC handshakes (via [boring]).
• gcongestion: Replace quiche’s original congestion control implementation with one adapted from google/quiche (via quiche-mallard).
• zero-copy: Use zero-copy sends with quiche-mallard (implies gcongestion).
• perf-quic-listener-metrics: Extra telemetry for QUIC handshake durations, including protocol overhead and network delays.
• tokio-task-metrics: Scheduling & poll duration histograms for tokio tasks.

Other parts of the crate are enabled by separate build flags instead, to be controlled by the final binary:

• --cfg capture_keylogs: Optional SSLKEYLOGFILE capturing for QUIC connections.

Re-exports

pub extern crate quiche_mallard as quiche;

pub use crate::http3::driver::ClientH3Controller;

pub use crate::http3::driver::ClientH3Driver;

pub use crate::http3::driver::ServerH3Controller;

pub use crate::http3::driver::ServerH3Driver;

pub use crate::http3::ClientH3Connection;

pub use crate::http3::ServerH3Connection;

pub use crate::settings::ConnectionParams;

pub use buffer_pool;

pub use datagram_socket;

Modules

buf_factory

Pooled buffers for zero-copy packet handling.

http3

HTTP/3 integrations for tokio-quiche.

metrics

Metrics collected across QUIC connections.

quic

async-ified QUIC connections powered by [quiche].

settings

Configuration for QUIC connections.

socket

Network socket utilities and wrappers.

Structs

InitialQuicConnection

A QUIC connection that has not performed a handshake yet.

QuicConnection

Metadata about an established QUIC connection.

Traits

ApplicationOverQuic

A trait to implement an application served over QUIC.

ConnectionIdGenerator

A customizable generator to derive and verify QUIC connection IDs.

Functions

listen

Starts listening for inbound QUIC connections on the given sockets.

listen_with_capabilities

Starts listening for inbound QUIC connections on the given QuicListeners.

Type Aliases

BoxError

Generic thread-safe boxed error.

QuicConnectionStream

A stream of accepted InitialQuicConnections from a listen call.

QuicResult

Result alias based on BoxError for this crate.