quic-go

quic-go implements the QUIC transport protocol (RFC 9000/9001/9002) and HTTP/3 (RFC 9114) entirely in Go, with no cgo or external C dependencies. It covers the full QUIC specification surface — connection migration, 0-RTT resumption, unreliable datagrams (RFC 9221), Path MTU discovery (RFC 8899), QUIC v2 (RFC 9369), and stream resets with partial delivery — alongside an HTTP/3 client and server built on top of it.

The project is maintained with production rigor: continuous fuzzing via OSS-Fuzz and ClusterFuzzLite, interop testing against other QUIC implementations, benchmark regression tracking via Codspeed, and FIPS 140-3 support when built with Go’s standard-library cryptography. It is the transport layer behind large infrastructure projects including Caddy, Traefik, cloudflared, syncthing, and go-libp2p (which underlies IPFS and Filecoin), making it one of the most battle-tested QUIC stacks outside of browser vendors’ own implementations.

What You Get

• Core QUIC transport - Transport and Conn types for dialing and listening for QUIC connections with full control over tls.Config and QUIC-specific options.
• Bidirectional and unidirectional streams - multiplexed, flow-controlled streams with OpenStream/AcceptStream, independent of the underlying connection’s congestion state.
• HTTP/3 client and server (http3 package) - implements http.RoundTripper and http.Handler so existing net/http code can serve or fetch over HTTP/3 with minimal changes.
• Unreliable datagrams (RFC 9221) - send unordered, unreliable messages over an established QUIC connection for latency-sensitive use cases.
• Connection migration and path management - built-in path_manager handles address changes (e.g. Wi-Fi to cellular handoff) without tearing down the connection.
• qlog and qlogwriter packages - structured QUIC event logging conforming to the IETF qlog schema, for debugging and interop analysis.
• 0-RTT resumption - TokenStore interface for caching resumption tokens to skip a round trip on reconnection.
• Pluggable congestion control - a Cubic-based sender in internal/congestion with hybrid slow start and pacing, plus a ConnectionIDGenerator interface for custom connection ID schemes.

Common Use Cases

• Web servers wanting HTTP/3 - drop the http3 package’s Server in alongside (or instead of) net/http to serve HTTP/3 traffic, as Caddy and Traefik do.
• Tunneling and reverse-proxy tools - cloudflared, frp, and Hysteria use quic-go’s low-level Transport/Conn API to multiplex tunneled traffic over a single encrypted, congestion-controlled connection.
• P2P and overlay networks - go-libp2p uses quic-go as a transport for IPFS (Kubo) and Filecoin (Lotus), relying on its connection migration for mobile/NAT scenarios.
• File sync and real-time apps - syncthing and Mercure use QUIC streams and datagrams for low-latency, loss-tolerant data exchange between peers.
• Custom application protocols over QUIC - the Conn/Stream API lets you build a bespoke wire protocol (RPC, streaming, pub/sub) directly on QUIC’s multiplexed, encrypted transport instead of TCP.

Under The Hood

Architecture quic-go is organized as a layered stack: the root package exposes the public Conn/Stream/Transport API and orchestrates a connection.go state machine (over 100KB, the largest file in the repo) that ties together packet packing/unpacking, the crypto/handshake state machine (internal/handshake), flow control (flow_controller_*.go), stream multiplexing (streams_map*.go), and ACK/loss handling (internal/ackhandler). Congestion control lives in its own internal/congestion package (Cubic sender, hybrid slow start, pacer), and wire-format encoding/decoding is isolated in internal/wire and quicvarint. The http3 package is a separate, self-contained layer built entirely on top of the public Conn/Stream interfaces rather than reaching into internals, which keeps HTTP/3 swappable and demonstrates the core transport’s API is genuinely usable by third parties. This is a textbook layered protocol-stack architecture: replacing the congestion controller or the handshake crypto backend would touch internal/congestion or internal/handshake without rippling into stream or connection-migration logic.

Tech Stack Pure Go with zero cgo dependencies, targeting the latest two Go releases (currently requiring Go 1.26 for FIPS support). Direct dependencies are minimal and deliberate: golang.org/x/crypto and golang.org/x/net for TLS 1.3/QUIC-adjacent primitives, github.com/quic-go/qpack for HTTP/3 header compression, golang.org/x/sys for platform syscalls (used heavily in sys_conn_*.go for OS-specific UDP socket tuning like GSO and the Don’t-Fragment bit across Linux/Darwin/Windows/OpenBSD/FreeBSD), and go.uber.org/mock plus stretchr/testify for testing. No web framework or database layer applies here — this is infrastructure, not an application.

Code Quality Exceptionally strong signals for a low-level networking library: 230 _test.go files against 443 total .go files (roughly 1:1), extensive use of generated mocks (mockgen.go files throughout) for interface-boundary testing, and multiple dedicated CI workflows for unit tests, lint (golangci-lint with a curated ruleset banning math/rand in favor of math/rand/v2, enforcing prealloc, unparam, etc.), interop testing against other QUIC stacks, cross-compilation, govulncheck scanning, and continuous fuzzing via OSS-Fuzz/ClusterFuzzLite — unusually thorough for a protocol implementation where malformed-input handling is a real attack surface. Benchmark regressions are tracked via Codspeed CI.

Tech Stack (API Design) The public API deliberately mirrors Go’s standard net package idioms (Dial, Listen, Conn, Stream with Read/Write) so developers already familiar with TCP-based Go networking code have almost no new mental model to learn, while http3.Server/http3.RoundTripper implement the standard net/http interfaces directly so a server can add HTTP/3 support by wiring in one additional type rather than restructuring routing or handler code. Configuration is a single flat Config struct with well-documented defaults for every timeout and flow-control window, avoiding the builder-pattern sprawl common in comparable libraries.