HTTP/3 (QUIC) Support

MockServer can optionally accept HTTP/3 requests over QUIC (UDP). HTTP/3 is the third major version of the HTTP protocol, using QUIC as the transport instead of TCP. This is useful when you want to test clients that connect using HTTP/3.

HTTP/3 requests are routed through the same expectation matching pipeline as HTTP/1.1 and HTTP/2 requests. This means all features work the same way: expectation matching, response actions, template actions, recording for verification, and proxy forwarding.

Enabling HTTP/3

HTTP/3 is disabled by default (http3Port defaults to 0). Set it to a non-zero UDP port number to start the listener:

When http3Port is 0 (the default), the HTTP/3 listener is not started and has no impact on the existing TCP/HTTP server.

Lifecycle

When http3Port is configured, the HTTP/3 server starts automatically with MockServer and stops when MockServer shuts down. No separate lifecycle management is needed.

If the native QUIC transport is not available on the platform (see native platform requirement), MockServer logs a warning and continues without HTTP/3. The existing TCP/HTTP server is never affected.

The bound HTTP/3 port can be retrieved programmatically via MockServer.getHttp3Port().

Native platform requirement

HTTP/3 uses the mainline io.netty:netty-codec-http3 library (Netty 4.2), which requires a native BoringSSL library for the QUIC transport. The native library is included automatically for the following platforms:

• linux-x86_64
• linux-aarch_64
• osx-x86_64
• osx-aarch_64
• windows-x86_64

If the native library cannot be loaded on the current platform, the HTTP/3 server will not start (a warning is logged). The existing TCP/HTTP server is not affected.

TLS

The HTTP/3 server uses MockServer's configured TLS certificate material — the same private key and certificate chain used by the HTTPS server. This means the TLS configuration properties (privateKeyPath, x509CertificatePath, etc.) apply to HTTP/3 as well.

If no custom certificate is configured, MockServer's auto-generated certificate (created via BouncyCastle) is used, which is suitable for testing.

Tuning / configuration

The QUIC transport parameters can be tuned for high-throughput or long-lived connection tests. Each has a sensible default and rarely needs changing:

• http3MaxIdleTimeout — idle timeout in milliseconds before a QUIC connection is closed
• http3InitialMaxData — connection-level flow-control limit (bytes)
• http3InitialMaxStreamDataBidirectional — per-stream flow-control limit (bytes)
• http3InitialMaxStreamsBidirectional — maximum number of concurrent bidirectional streams
• http3QpackMaxTableCapacity — QPACK dynamic header-table capacity (bytes)

See the HTTP/3 configuration properties on the configuration page for defaults, value ranges, and the full four-form reference (Java code, system property, environment variable, property file).

What works

• Expectation matching — HTTP/3 requests are matched against expectations identically to HTTP/1.1 and HTTP/2
• Response actions — all response action types (static, template, callback, etc.)
• Streaming / SSE responses — Server-Sent Events, chunked proxy forwarding, and LLM streaming responses are fully supported. Each body chunk is delivered as an HTTP/3 DATA frame with backpressure; the QUIC stream is cleanly shut down on completion or error
• Request recording — HTTP/3 requests are recorded for verification
• Proxy forwarding — unmatched requests can be forwarded when proxy mode is configured
• Request body — text and binary request bodies are read and matched correctly
• Configurable TLS — uses the same TLS certificate as the HTTPS server
• Lifecycle integration — starts and stops automatically with MockServer
• Fail-soft startup — graceful fallback when native QUIC is unavailable
• Alt-Svc auto-discovery — when http3Port is set, MockServer automatically adds an Alt-Svc header to all TCP (HTTP/1.1 and HTTP/2) responses advertising the HTTP/3 endpoint. HTTP/3-capable clients will automatically upgrade to QUIC on subsequent requests, with transparent fallback to HTTP/2 or HTTP/1.1 if QUIC is unavailable. The advertisement max-age is configurable via http3AltSvcMaxAge (default 86400 seconds). Set http3AdvertiseAltSvc=false to disable advertising while keeping HTTP/3 enabled
• W3C trace-context propagation — traceparent and tracestate headers on inbound HTTP/3 requests are parsed and stored for OpenTelemetry span parenting, matching the TCP path. When otelPropagateTraceContext is enabled, the headers are copied to outbound HTTP/3 responses. When otelGenerateTraceId is enabled, a trace context is generated for requests without a traceparent header. Both features are default-off (same config as TCP)
• mTLS client-certificate capture — when mTLS is configured (tlsMutualAuthenticationRequired or tlsMutualAuthenticationCertificateChain), client certificates are captured from the QUIC TLS handshake and attached to the request, enabling cert-based expectation matching and verification over HTTP/3
• MCP over HTTP/3 — the Model Context Protocol Streamable HTTP transport works over HTTP/3 with the same control-plane authentication (JWT / mTLS) and CORS behaviour as the TCP path; the request processing is shared between the two transports
• gRPC over HTTP/3 — unary, server-streaming, and bidirectional-streaming gRPC calls work over HTTP/3 with correct trailing-HEADERS grpc-status framing. Bidirectional streaming requires grpcBidiStreamingEnabled (the same flag as the TCP path)
• CONNECT-UDP (MASQUE) relay — a working forward-proxy relay for tunnelling UDP through MockServer (RFC 9298). When enabled via http3ConnectUdpEnabled (default false), the server advertises SETTINGS_ENABLE_CONNECT_PROTOCOL (RFC 9220) and handles extended-CONNECT requests with :protocol=connect-udp: it opens a UDP socket to the target authority and relays datagrams bidirectionally (one HTTP/3 DATA frame per UDP datagram). Normal (non-CONNECT) HTTP/3 requests are unaffected. Security — this is an open UDP relay. When enabled there is no restriction on the relay target, so a client can reach any UDP host:port reachable from MockServer (including private networks, loopback, and cloud metadata endpoints such as 169.254.169.254). It is intended for controlled test environments only — leave it disabled (the default) and never expose a CONNECT-UDP–enabled HTTP/3 port to untrusted clients. See HTTP/3 CONNECT-UDP (MASQUE) Enabled on the configuration page

Limitations

• Codec API maturity — the HTTP/3 codec has graduated from the Netty incubator into mainline Netty 4.2, but the API may still evolve in future releases

HTTP/3 parity and known differences

All expectation matching, actions, recording, verification, HTTP chaos profiles, forward-proxy, trace-context propagation, mTLS, MCP (Model Context Protocol Streamable HTTP, including control-plane authentication), and gRPC (unary, server-streaming, and bidirectional streaming) work over HTTP/3, matching the TCP (HTTP/1.1 and HTTP/2) path.

Inherently not applicable over HTTP/3

• TCP chaos (TcpChaosHandler) — QUIC has no TCP RST/FIN/slow_close semantics. HTTP-level chaos profiles (latency, error responses, degradation ramp) DO work over HTTP/3
• WebSocket callbacks + dashboard WebSocket — RFC 6455 HTTP/1.1 Upgrade has no HTTP/3 equivalent. The analog is WebTransport (not yet implemented)
• HTTP/1.1 framing fixups — handlers like PreserveHeadersNettyRemoves and EarlyMatchingHandler are HTTP/1.1-specific and have no meaning in HTTP/3

Not yet supported (deferred)

• Per-connection dashboard detail — the dashboard shows the HTTP/3 port and an aggregate active-connection count; per-connection detail (remote address, stream count, duration) is deferred

Previously deferred, now supported: MCP-over-HTTP/3 (shared Streamable-HTTP processor with full control-plane authentication) and gRPC-over-HTTP/3 (unary, server-streaming, and bidirectional streaming) both work over HTTP/3.