v0.1.0 to v0.1.0

---

name: http3-server

description: Embed sparq's internal opt-in HTTP/3-over-QUIC bridge into an axum server with rustls 0.23/aws-lc-rs, Quinn, peer ConnectInfo injection, and graceful shutdown.

license: MIT

metadata:

version: "0.1.0"

homepage: https://github.com/jeswr/sparq

---

# sparq HTTP/3 server bridge

Use `sparq-http3` when a sparq HTTP server needs a second, encrypted UDP listener that

dispatches into the same `axum::Router` as its existing HTTP/1.1 or HTTP/2 listener. The

crate is internal and unstable (`publish = false`), and its `server` feature is off by

default so Quinn and the pre-1.0 h3 stack do not enter ordinary workspace builds.

## Add the opt-in dependency

```toml

[features]

default = []

http3 = ["dep:sparq-http3"]

[dependencies]

sparq-http3 = { path = "../sparq-http3", optional = true, features = ["server"] }

```

The downstream crate owns certificate/key loading and runtime configuration. Build a

`rustls::ServerConfig` with the aws-lc-rs provider, TLS 1.3, and the exact `h3` ALPN token:

```rust

use std::sync::Arc;

let provider = Arc::new(rustls::crypto::aws_lc_rs::default_provider());

let mut tls = rustls::ServerConfig::builder_with_provider(provider)

.with_protocol_versions(&[&rustls::version::TLS13])?

.with_no_client_auth()

.with_single_cert(certificates, private_key)?;

tls.alpn_protocols = vec![b"h3".to_vec()];

let quic = sparq_http3::quic_server_config(tls)?;

let endpoint = quinn::Endpoint::server(quic, udp_addr)?;

# Ok::<(), Box<dyn std::error::Error>>(())

```

`quic_server_config` fails closed when `h3` is missing from ALPN or the provider lacks

QUIC's required initial cipher suite. It also replaces Quinn's effectively unbounded default

connection receive window with an owned finite bound; a caller may still replace the returned

config's transport settings before binding the endpoint.

## Serve the shared router

```rust

sparq_http3::serve_h3(endpoint, router.clone(), async move {

shutdown_signal.await;

})

.await?;

# Ok::<(), std::io::Error>(())

```

Existing callers need no changes. To tune the caps, use the additive variant:

```rust

let limits = sparq_http3::H3ConnectionLimits {

max_connections: 2_000,

max_connections_per_ip: Some(128),

exempt_internal_ips: true,

};

sparq_http3::serve_h3_with_limits(endpoint, router.clone(), limits, shutdown_signal).await?;

# Ok::<(), std::io::Error>(())

```

Set `max_connections_per_ip` to `None` only when the global cap is sufficient for the deployment.

router per connection and request, streams request and response bodies, and inserts the Quinn peer

address as `axum::extract::ConnectInfo<SocketAddr>`.

That extension is load-bearing for request policies keyed by the remote socket address.

Protocol failures are isolated to their connection or stream; resolving the shutdown

future closes the endpoint and waits for its QUIC connections to drain.

## Advertise a bound endpoint to TCP clients

After the QUIC endpoint has bound successfully, apply the shared response layer to the separate

HTTP/1.1 or HTTP/2 router. Derive the advertised port from `Endpoint::local_addr`; do not use the

requested configuration because binding port `0` may select a different live port:

```rust

let endpoint = quinn::Endpoint::server(quic, udp_addr)?;

let bound_addr = endpoint.local_addr()?;

let h3_router = router.clone();

let tcp_router = router.layer(sparq_http3::alt_svc_layer(bound_addr.port()));

```

`alt_svc_layer` overwrites `Alt-Svc` with `h3=":<port>"; ma=86400`. Serve `tcp_router` only

while the bound endpoint is also being served; use the unlayered `h3_router` for `serve_h3`.

Feature-enabled but unconfigured servers must keep serving the original router without this layer.

## Solid/LDP server integration

`sparq-lws-core` carries this bridge behind its default-off `http3` feature

([GPT-5.6] sq-oprna.2):

```sh

SOLID_SERVER_TLS_CERT=/path/to/cert.pem \

SOLID_SERVER_TLS_KEY=/path/to/key.pem \

cargo run -p sparq-lws-core --features http3

```

When both TLS paths are configured, the binary binds QUIC/UDP to the same resolved

`SOLID_SERVER_BIND` address and port as TLS/TCP and serves one cloned

`build_router_with_overload` router. The TCP rustls configuration remains exactly

`[h2, http/1.1]`; a clone used only by Quinn advertises the exact `h3` token. Every

QUIC request receives peer `ConnectInfo`, so the pre-crypto per-IP rate limiter does

not fail open to the ordinary auth stack. With no TLS configuration, enabling the

Cargo feature does not create a QUIC listener. WebSocket notifications continue over

HTTP/1.1 or HTTP/2 because RFC 9220 extended CONNECT is outside this integration.

## Boundaries

- The caller owns rustls policy, certificates, client authentication, any Quinn transport

tuning beyond the helper's bounded receive window, listener binding, and process-wide provider

installation.

- HTTP/3 is a separate UDP listener. Keep the existing TCP listener running for HTTP/1.1

and HTTP/2 clients.

- `h3` and `h3-quinn` are pre-1.0 dependencies; keep all direct use inside this helper.

- WebSocket-over-HTTP/3 extended CONNECT is not implemented. WebSocket clients fall back

to the existing TCP listener.

- Do not call `alt_svc_layer` until the UDP listener has successfully bound, and remove the

advertisement whenever that listener is not served.

## Related material

- `crates/sparq-http3/README.md` — crate scope and opt-in posture.

- `research/http3-quic-servers-design.md` — shared-listener architecture and maturity

boundary.

- `skills/http-server/SKILL.md` — the SPARQL Protocol server surface.