HTTP/3 (QUIC) Listener#

Added in v0.5. Modern browsers negotiate H3 first via Alt-Svc; a redirector that only speaks H1/H2 stands out to defenders watching for the H3 upgrade dance. InfraGuard’s H3 listener wires straight into DomainRouter.handle, so every filter and drop-action already in place works unchanged for QUIC clients.

Enable#

Install the extra:

pip install infraguard[quic]     # once shipped in pyproject; today: pip install aioquic

Add an H3 listener to config.yaml:

listeners:
  - protocol: h3
    bind: 0.0.0.0
    port: 443
    tls:
      cert: /app/certs/live/cdn.example.com/fullchain.pem
      key:  /app/certs/live/cdn.example.com/privkey.pem

Emit Alt-Svc from your existing HTTP/1.1 or HTTP/2 listener so clients discover the H3 endpoint:

Alt-Svc: h3=":443"; ma=86400

Docker#

Publish UDP/443 (in addition to TCP/443). The bundled Docker Compose file already does this for the proxy service:

proxy:
  ports:
    - "443:443"
    - "443:443/udp"      # HTTP/3
    - "80:80"

For Kubernetes, the Helm chart’s proxy Service publishes both protocols on 443 already (see kubernetes).

What’s in the box#

  • infraguard/listeners/experimental/quic.py implements the listener. Handles HeadersReceived / DataReceived per H3 stream and builds a Starlette Request for DomainRouter.handle.
  • Response goes back as HEADERS + DATA frames on the same stream.
  • One QUIC connection can carry many concurrent H3 streams; each is dispatched independently on the asyncio event loop.

Limitations#

  • The listener does not yet emit Alt-Svc upstream automatically. Set it as a custom response header in domain_config.custom_response_headers until that lands.
  • WebTransport (over QUIC) is not supported; use the WebSocket beacon transport for long-lived duplex channels.

See also: advanced-listeners for the WebSocket beacon transport that shipped alongside HTTP/3.