codec-http3

简体中文 | Documentation

HTTP/3 frame, QPACK, control stream, push stream, lifecycle, WebTransport settings, and bridge codecs for Gnalloy.

This module sits above transports and below application handlers. It translates bytes or Gnalloy messages into protocol objects, and translates outbound protocol objects back to bytes. It does not open sockets or own EventLoops.

Status

• Import path: gnalloy.org/codec-http3
• Repository: github.com/gnalloy/codec-http3
• Default branch: dev
• Preview install: go get gnalloy.org/codec-http3@dev
• License: Apache-2.0

Install

go get gnalloy.org/codec-http3@dev
go doc gnalloy.org/codec-http3
GOWORK=off GOTOOLCHAIN=local go test ./... -count=1

Documentation

• Overview (中文)
• Usage (中文)
• Examples (中文)
• Configuration (中文)
• Testing and Performance (中文)
• API Reference (中文)
• Notes and Caveats (中文)
• ADR-001 Module Boundary (中文)

Module Boundary

This repository owns: HTTP/3 frame, QPACK, control stream, push stream, lifecycle, WebTransport settings, and bridge codecs for Gnalloy.

It does not absorb neighboring module responsibilities. Core primitives stay in gnalloy.org/gnalloy; protocol codecs, transports, handlers, resolvers, examples, and benchmarks stay in their own repositories.

Packages

• gnalloy.org/codec-http3 (http3)
• gnalloy.org/codec-http3/http1bridge (http1bridge)

Gnalloy Dependencies

• gnalloy.org/codec-http1
• gnalloy.org/gnalloy

Common Integration Pattern

• Frame, header, body, and decoded-content limits must be selected from the trusted boundary of the service.
• Streaming or chunked modes should be used for large payloads instead of materializing unbounded bodies.
• Compression modules must set decoded-size limits to defend against expansion attacks.
• ByteBuf ownership follows Gnalloy message rules: release only after the current component consumes the message.
• QUIC and HTTP/3 paths require TLS 1.3 and a valid ALPN such as h3, doq, or the WebTransport profile in use.

Current Public Entry Points

The generated API reference lists the full public surface. Common constructors or option types currently include:

• const DefaultMaxFrameSize = 16 * 1024 * 1024 ...
• const HandlerNameHTTP3FrameDecoder = "http3-frame-decoder" ...
• const SettingQPACKMaxTableCapacity uint64 = 0x01 ...
• const SettingEnableConnectProtocol uint64 = 0x08 ...
• const WebTransportProtocolH3 = "webtransport-h3" ...
• var ErrInvalidFrame = errors.New("http3: invalid frame") ...
• type HeaderCodecConfig struct{ ... }
• type PipelineConfig struct{ ... }
• type QPACKDynamicStateConfig struct{ ... }
• type StateManagerConfig struct{ ... }
• var ErrInvalidHeadersBlock = errors.New("gnalloy/codec/http3/http1bridge: invalid headers block")
• type Config struct{ ... }

Verification

GOWORK=off GOTOOLCHAIN=local go test ./... -count=1
GOWORK=off GOTOOLCHAIN=local go vet ./...
GOWORK=off GOTOOLCHAIN=local go test ./... -run '^$' -bench . -benchmem -count=1

For pressure tests, assemble this module with the relevant transport, codec, and handler stack and run the scenario from gnalloy.org/benchmarks or gnalloy.org/examples. Keep host, operating system, payload, concurrency, warmup, and repetitions in the report.

Caveats

• This repository is intentionally narrow. Cross-module behavior should be assembled in applications, recipes, examples, or benchmark harnesses.
• Public APIs should remain Go-native and explicit; avoid runtime scanning, hidden global registries, and reflection-heavy behavior in hot paths.
• Treat network input as untrusted. Configure parser limits and return typed errors instead of panics.
• Keep benchmark claims tied to a concrete host, operating system, protocol, payload, concurrency, warmup, and repetition count.
• Codec modules do not provide a network server by themselves; combine them with a transport module and application handlers.