http3

README

Go+ HTTP/3

goforge.dev/goplus/std/http3 provides a native RFC 9114 client, server, and wire layer. It runs on RFC 9000 QUIC, creates the required control and QPACK streams, exchanges SETTINGS, supports streaming DATA and trailers in both directions, and supports RFC 9220 extended CONNECT. The client can use either quic-go or the Go+ owned RFC 9000 engine; NativeServer and QUICGoServer provide native HTTP/3 server data paths over either engine. XNetServer remains as a deprecated alias.

The request field encoder deliberately uses a zero-capacity QPACK strategy. That removes encoder-stream blocking and permits every request stream to encode independently. Common static fields use direct QPACK indices; short literals use the raw representation to avoid paying more CPU for marginal Huffman wire savings. Long literals use Huffman encoding only when it saves at least eight bytes. Both endpoints advertise and enforce a 1 MiB decoded field-section limit, and outgoing headers and trailers honor a smaller limit advertised by the peer.

The executable comparative gate covers a warmed native client/server round trip as well as ordinary HTTP and WebSocket field sets. A parallel full-stack benchmark remains available as diagnostic throughput coverage, while the release gate uses the reproducible Linux sequential latency workload:

go run ./http3/cmd/benchgate

Every case must remain at least 2× faster than quic-go and allocate no more bytes. Additional native-stack latency, parallel-throughput, header-heavy, and payload benchmarks can be run with:

go test ./http3 -run '^$' -bench '^BenchmarkNativeStack' -benchmem

The executable performance contract includes a complete warmed HTTP/3 request and response through the native client and server, in addition to the isolated wire-format hot paths. This prevents encoder-only improvements from being reported as a 2x HTTP/3 implementation result.

Documentation

Overview

Package http3 contains optimized HTTP/3 wire primitives used by the Go+ HTTP transport. The primitives deliberately avoid mutable QPACK state, so a field section can be produced concurrently without blocking on an encoder stream.

Index

• Variables
• func AppendDataFrameHeader(dst []byte, payloadLength uint64) ([]byte, error)
• func AppendFieldSection(dst []byte, fields []HeaderField) ([]byte, error)
• func AppendFrameHeader(dst []byte, frameType, payloadLength uint64) ([]byte, error)
• func AppendHeadersFrameHeader(dst []byte, payloadLength uint64) ([]byte, error)
• func EncodeDataFrameHeader(dst *[9]byte, payloadLength uint64) int
• func EncodeHeadersFrameHeader(dst *[9]byte, payloadLength uint64) int
• type HeaderField
• type NativeServer
  • func (s *NativeServer) Close() error
  • func (s *NativeServer) Serve(packetConn net.PacketConn) error
  • func (s *NativeServer) Shutdown(ctx context.Context) error
• type QUICBackend
• type QUICGoServer
  • func (s *QUICGoServer) Close() error
  • func (s *QUICGoServer) Serve(packetConn net.PacketConn) error
  • func (s *QUICGoServer) Shutdown(context.Context) error
• type RFC9000Config
• type Transport
  • func (t *Transport) Close() error
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)
• type XNetServer

Variables

var ErrFieldSectionTooLarge = errors.New("http3: field section too large")

Functions

func AppendDataFrameHeader

func AppendDataFrameHeader(dst []byte, payloadLength uint64) ([]byte, error)

AppendDataFrameHeader appends a DATA frame header without dispatching on a runtime frame type.

func AppendFieldSection

func AppendFieldSection(dst []byte, fields []HeaderField) ([]byte, error)

AppendFieldSection appends a complete QPACK field section using only the static table and literal representations. It never mutates shared state and is therefore safe to call concurrently when dst is not shared.

func AppendFrameHeader

func AppendFrameHeader(dst []byte, frameType, payloadLength uint64) ([]byte, error)

AppendFrameHeader appends an RFC 9114 frame type and payload length.

func AppendHeadersFrameHeader

func AppendHeadersFrameHeader(dst []byte, payloadLength uint64) ([]byte, error)

AppendHeadersFrameHeader appends a HEADERS frame header without dispatching on a runtime frame type.

func EncodeDataFrameHeader

func EncodeDataFrameHeader(dst *[9]byte, payloadLength uint64) int

EncodeDataFrameHeader writes a DATA frame header into dst and returns its length. payloadLength must be less than 2^62.

func EncodeHeadersFrameHeader

func EncodeHeadersFrameHeader(dst *[9]byte, payloadLength uint64) int

EncodeHeadersFrameHeader writes a HEADERS frame header into dst and returns its length. payloadLength must be less than 2^62. Fixed-buffer encoding is intended for QUIC writers that already own per-stream scratch space.

Types

type HeaderField

type HeaderField struct {
	Name      string
	Value     string
	Sensitive bool
}

HeaderField is one QPACK field line.

type NativeServer

type NativeServer struct {
	Handler    http.Handler
	TLSConfig  *tls.Config
	QUICConfig *xquic.Config
	// contains filtered or unexported fields
}

NativeServer is an RFC 9114 server running on the Go+ owned RFC 9000 engine. It is independent of quic-go's server so the Go+ HTTP/3 data path can be deployed and measured without the reference implementation.

func (*NativeServer) Close

func (s *NativeServer) Close() error

Close aborts active connections and stops accepting new ones.

func (*NativeServer) Serve

func (s *NativeServer) Serve(packetConn net.PacketConn) error

Serve serves HTTP/3 on packetConn and owns the packet connection.

func (*NativeServer) Shutdown

func (s *NativeServer) Shutdown(ctx context.Context) error

Shutdown stops accepting connections and waits for active QUIC connections to close until ctx expires.

type QUICBackend

type QUICBackend uint8

QUICBackend selects the RFC 9000 engine used below HTTP/3.

const (
	QUICGo QUICBackend = iota
	// NativeQUIC selects the Go+ owned RFC 9000 engine.
	NativeQUIC
	// XNetQUIC is retained as a compatibility spelling for NativeQUIC.
	// Deprecated: use NativeQUIC.
	XNetQUIC = NativeQUIC
)

type QUICGoServer

type QUICGoServer struct {
	Handler    http.Handler
	TLSConfig  *tls.Config
	QUICConfig *quic.Config
	// contains filtered or unexported fields
}

QUICGoServer runs Go+'s native RFC 9114 server over quic-go's RFC 9000 transport. This is useful when applications want quic-go's mature packet engine without using its HTTP/3 implementation.

func (*QUICGoServer) Close

func (s *QUICGoServer) Close() error

func (*QUICGoServer) Serve

func (s *QUICGoServer) Serve(packetConn net.PacketConn) error

Serve serves HTTP/3 on packetConn and owns the packet connection.

func (*QUICGoServer) Shutdown

func (s *QUICGoServer) Shutdown(context.Context) error

type RFC9000Config

type RFC9000Config = xquic.Config

RFC9000Config configures the Go+ owned RFC 9000 transport engine.

type Transport

type Transport struct {
	Backend          QUICBackend
	TLSClientConfig  *tls.Config
	QUICConfig       *quic.Config
	NativeQUICConfig *RFC9000Config
	// XQUICConfig is retained for compatibility. NativeQUICConfig takes
	// precedence when both are set.
	// Deprecated: use NativeQUICConfig.
	XQUICConfig *RFC9000Config
	Dial        func(context.Context, string, *tls.Config, *quic.Config) (*quic.Conn, error)
	// MaxConnectionsPerOrigin bounds adaptive connection sharding. Zero uses
	// one connection. Sequential traffic continues to use one connection;
	// additional connections are created only while all existing connections
	// have active requests.
	MaxConnectionsPerOrigin int
	// contains filtered or unexported fields
}

Transport is a native Go+ HTTP/3 client transport. It uses QUIC v1 for transport and the package's stateless QPACK encoder for request fields.

func (*Transport) Close

func (t *Transport) Close() error

Close closes all pooled HTTP/3 connections.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

type XNetServer

type XNetServer = NativeServer

XNetServer is retained as a compatibility spelling for NativeServer. Deprecated: use NativeServer.