msquic-h3

A Rust adapter that lets you run hyperium's h3 HTTP/3 stack on top of Microsoft's msquic QUIC implementation.

msquic-h3 implements h3's transport traits (OpenStreams, Connection, SendStream, RecvStream, …) over msquic's FFI, so you can drive an HTTP/3 client or server with the standard h3 API while msquic handles the QUIC protocol and the socket I/O.

It can also be used as a QUIC transport backend for tonic-h3 to run gRPC over HTTP/3.

Status: experimental (0.0.x). The API may change between releases. It can run HTTP/3 clients and servers today.

How it fits together

   your app  ──uses──►  h3 (HTTP/3)  ──transport traits──►  msquic-h3  ──FFI──►  msquic (QUIC + UDP)

h3 owns HTTP/3 framing and request/response semantics; msquic owns the QUIC protocol, TLS, and the network threads. msquic-h3 is the thin, runtime-agnostic bridge between them: its core depends only on futures (no built-in async runtime), and it turns msquic's callback/threading model into the poll-based streams h3 expects.

Installation

Add the crate and h3 to your Cargo.toml:

[dependencies]
msquic-h3 = "0.0.7"
h3 = "0.0.8"
http = "1"

The msquic native library is loaded dynamically at run time — it is not needed to compile the Rust code. Choose how the library is provided via a mutually-exclusive Cargo feature (see Native library below).

Quick start

Client

use bytes::Buf;
use msquic::{BufferRef, CredentialConfig, RegistrationConfig, Settings};
use msquic_h3::{Connection, Registration};

async fn run() -> Result<(), Box<dyn std::error::Error>> {
    // One registration per process/app; it owns msquic's worker threads.
    let reg = Registration::new(&RegistrationConfig::new().set_app_name("myapp"))?;

    // A configuration describes ALPN + TLS credentials for the connection.
    let alpn = BufferRef::from("h3");
    let config = reg.open_configuration(&[alpn], Some(&Settings::new().set_IdleTimeoutMs(5000)))?;
    config.load_credential(&CredentialConfig::new_client())?;

    // Connect and hand the connection to h3.
    let conn = Connection::connect(&reg, &config, "example.com", 443).await?;
    let (mut driver, mut send_request) = h3::client::new(conn).await?;

    // Drive the connection in the background.
    let drive = tokio::spawn(async move {
        futures::future::poll_fn(|cx| driver.poll_close(cx)).await
    });

    // Send a request and read the response.
    let req = http::Request::builder().uri("https://example.com/").body(())?;
    let mut stream = send_request.send_request(req).await?;
    stream.finish().await?;

    let resp = stream.recv_response().await?;
    println!("status: {}", resp.status());
    while let Some(mut chunk) = stream.recv_data().await? {
        let mut buf = vec![0u8; chunk.remaining()];
        chunk.copy_to_slice(&mut buf);
        // ... use buf ...
    }
    drop(send_request);
    let _ = drive.await;
    Ok(())
}

Server

use msquic::{BufferRef, RegistrationConfig};
use msquic_h3::{Listener, Registration};
use std::sync::Arc;

// `config` carries the server ALPN + certificate.
async fn run(config: Arc<msquic::Configuration>) -> Result<(), Box<dyn std::error::Error>> {
    let reg = Registration::new(&RegistrationConfig::default())?;
    let alpn = BufferRef::from("h3");

    // Bind an address (or pass None).
    let mut listener = Listener::new(&reg, config, &[alpn], Some("127.0.0.1:443".parse()?))?;

    while let Some(conn) = listener.accept().await? {
        tokio::spawn(async move {
            let mut h3_conn =
                h3::server::Connection::<_, bytes::Bytes>::new(conn).await.unwrap();
            while let Ok(Some(resolver)) = h3_conn.accept().await {
                // handle each request stream ...
                let _ = resolver;
            }
        });
    }
    Ok(())
}

See docs/Development.md for a runnable end-to-end walkthrough, and the crate's tests for complete client/server flows.

Native library

The Rust code compiles without the native library, but linking/running resolves msquic symbols. Pick exactly one provenance feature — they are mutually exclusive:

Selecting neither is a supported type-check-only configuration (the crate compiles without linking a native library); selecting both is rejected by msquic's build script. --all-features is therefore not a valid build command — choose one provenance, e.g. --no-default-features --features native-find.

Getting the msquic library at run time

• Linux: sudo apt-get install libmsquic (loaded dynamically), or download a release from msquic releases.
• Windows: PowerShell 7 ships msquic.dll; installing pwsh 7 lets the app load it. You can also place the DLL anywhere on the library search path.
• Other: download a release build and place the library where your app can load it.

Configuring memory budgets

The adapter bounds per-stream memory with finite defaults: 16 MiB per send, and 1 MiB + 16384 buffered units per receive stream. Existing Connection::connect / Listener::new callers get these automatically. To tune them, build an H3Config and use the additive *_with_config constructors:

use msquic_h3::{Connection, H3Config};

let cfg = H3Config::builder()
    .with_max_send_bytes(4 * 1024 * 1024) // 4 MiB per send (default 16 MiB)
    .with_max_recv_bytes(512 * 1024)      // 512 KiB per stream (default 1 MiB)
    .with_max_recv_units(4096)            // buffered units per stream (default 16384)
    .build()?;

let conn = Connection::connect_with_config(&reg, &config, "example.com", 443, cfg).await?;
// server: Listener::with_config(&reg, config, &alpn, Some(addr), cfg)?;

The receive caps are enforced as backpressure. The send side has no aggregate cap: per-connection send memory scales as max_send_bytes × concurrent streams, so bound it by choosing max_send_bytes and limiting concurrent streams at the application level. Details in docs/receive-and-send.md.

Documentation

The docs/ folder describes the library as built today:

API reference: docs.rs/msquic-h3.

Building and testing

Verify with a single provenance (see Native library):

cargo test  --no-default-features --features native-find
cargo clippy --all-targets --no-default-features --features native-find -- -D warnings
cargo fmt --all -- --check

License

Licensed under the MIT license.