h3engine

Documentation

Overview

Package h3engine provides HTTP/3 client functionality using fasthttp.

Index

• Constants
• Variables
• func ReadFrameHeader(r quicvarint.Reader) (frameType uint64, payloadLen uint64, err error)
• type Client
  • func NewClient(tlsCfg *tls.Config, quicCfg *quic.Config) *Client
  • func (c *Client) Close() error
  • func (c *Client) Do(ctx context.Context, req *fasthttp.Request, resp *fasthttp.Response, ...) (map[string][]string, error)
• type ClientConn
  • func NewClientConn(conn *quic.Conn, settings *Settings) (*ClientConn, error)
  • func (cc *ClientConn) Close() error
  • func (cc *ClientConn) Do(ctx context.Context, req *fasthttp.Request, resp *fasthttp.Response, ...) (map[string][]string, error)
• type QPACKCodec
  • func NewQPACKCodec() *QPACKCodec
  • func (q *QPACKCodec) DecodeResponseHeaders(headerBlock []byte, res *fasthttp.ResponseHeader) (int, error)
  • func (q *QPACKCodec) DecodeResponseTrailers(headerBlock []byte) (map[string][]string, error)
  • func (q *QPACKCodec) EncodeRequestHeaders(w io.Writer, req *fasthttp.Request, orderedKeys []string) error
  • func (q *QPACKCodec) WriteDecoderTable(_ []byte) error
• type Settings
  • func (s *Settings) Encode() []byte

Constants

const (
	FrameTypeData        uint64 = 0x00
	FrameTypeHeaders     uint64 = 0x01
	FrameTypeCancelPush  uint64 = 0x03
	FrameTypeSettings    uint64 = 0x04
	FrameTypePushPromise uint64 = 0x05
	FrameTypeGoAway      uint64 = 0x07
	FrameTypeMaxPushID   uint64 = 0x0D
)

const (
	StreamTypeControl      uint64 = 0x00
	StreamTypePush         uint64 = 0x01
	StreamTypeQPACKEncoder uint64 = 0x02
	StreamTypeQPACKDecoder uint64 = 0x03
)

const (
	SettingQpackMaxTableCapacity uint64 = 0x01
	SettingMaxFieldSectionSize   uint64 = 0x06
	SettingQpackBlockedStreams   uint64 = 0x07
	SettingEnableConnectProtocol uint64 = 0x08
	SettingH3Datagram            uint64 = 0x33
)

Variables

var (
	ErrServerClosed           = errors.New("aoni h3engine: server closed HTTP/3 connection")
	ErrFrameUnexpected        = errors.New("aoni h3engine: received unexpected frame type")
	ErrHeaderTooLarge         = errors.New("aoni h3engine: response headers exceed size limit")
	ErrStreamClosed           = errors.New("aoni h3engine: stream closed prematurely")
	ErrInvalidStreamType      = errors.New("aoni h3engine: invalid unidirectional stream type")
	ErrMissingSettings        = errors.New("aoni h3engine: server did not send initial SETTINGS frame")
	ErrDuplicateControlStream = errors.New("aoni h3engine: duplicate control stream received")
	ErrClosedCriticalStream   = errors.New("aoni h3engine: critical unidirectional stream was closed")
	ErrQPACKDecompressFailed  = errors.New("aoni h3engine: QPACK header decompression failed")
	ErrMissingStatusHeader    = errors.New("aoni h3engine: response missing mandatory :status header")
	ErrInvalidHostHeader      = errors.New("aoni h3engine: invalid Host or :authority header")
)

Functions

func ReadFrameHeader

func ReadFrameHeader(r quicvarint.Reader) (frameType uint64, payloadLen uint64, err error)

ReadFrameHeader decodes the QUIC varint frame type and payload length from stream r.

Types

type Client

type Client struct {
	TLSConfig  *tls.Config
	QUICConfig *quic.Config
	Settings   *Settings
	// contains filtered or unexported fields
}

Client manages connection pooling and multiplexing for HTTP/3 over QUIC.

func NewClient

func NewClient(tlsCfg *tls.Config, quicCfg *quic.Config) *Client

NewClient initializes a new HTTP/3 Client instance.

func (*Client) Close

func (c *Client) Close() error

Close terminates all active HTTP/3 client connections in the pool.

func (*Client) Do

func (c *Client) Do(
	ctx context.Context,
	req *fasthttp.Request,
	resp *fasthttp.Response,
	headerOrder []string,
) (map[string][]string, error)

Do executes a fasthttp.Request over HTTP/3 to the destination server, writing response into resp and returning trailers.

type ClientConn

type ClientConn struct {
	// contains filtered or unexported fields
}

ClientConn manages HTTP/3 frame exchanges over a quic.Conn session.

func NewClientConn

func NewClientConn(conn *quic.Conn, settings *Settings) (*ClientConn, error)

NewClientConn initializes an HTTP/3 client connection and opens control streams.

func (*ClientConn) Close

func (cc *ClientConn) Close() error

Close gracefully terminates the HTTP/3 client connection.

func (*ClientConn) Do

func (cc *ClientConn) Do(
	ctx context.Context,
	req *fasthttp.Request,
	resp *fasthttp.Response,
	headerOrder []string,
) (map[string][]string, error)

Do executes a fasthttp.Request over a QUIC stream and populates fasthttp.Response and captured trailers.

type QPACKCodec

type QPACKCodec struct {
	// contains filtered or unexported fields
}

QPACKCodec manages zero-allocation QPACK header serialization and deserialization.

func NewQPACKCodec

func NewQPACKCodec() *QPACKCodec

NewQPACKCodec instantiates a new QPACKCodec.

func (*QPACKCodec) DecodeResponseHeaders

func (q *QPACKCodec) DecodeResponseHeaders(headerBlock []byte, res *fasthttp.ResponseHeader) (int, error)

DecodeResponseHeaders parses a QPACK header block directly into fasthttp ResponseHeader, returning the parsed status code and ignoring 1xx informational frames.

func (*QPACKCodec) DecodeResponseTrailers

func (q *QPACKCodec) DecodeResponseTrailers(headerBlock []byte) (map[string][]string, error)

DecodeResponseTrailers decodes a QPACK header block containing response trailers into a key-value map.

func (*QPACKCodec) EncodeRequestHeaders

func (q *QPACKCodec) EncodeRequestHeaders(w io.Writer, req *fasthttp.Request, orderedKeys []string) error

EncodeRequestHeaders encodes a fasthttp request header into a QPACK block, strictly maintaining the specified orderedKeys sequence for Anti-DPI fingerprinting.

func (*QPACKCodec) WriteDecoderTable

func (q *QPACKCodec) WriteDecoderTable(_ []byte) error

WriteDecoderTable processes instructions received over the QPACK Encoder Stream.

Note: Currently quic-go/qpack operates on static tables and does not expose dynamic table instructions, so incoming bytes are safely consumed.

type Settings

type Settings struct {
	MaxFieldSectionSize int64
	QpackMaxTableCap    uint64
	QpackBlockedStreams uint64
	EnableDatagrams     bool
	EnableConnect       bool
	Other               map[uint64]uint64
}

Settings encapsulates HTTP/3 connection parameters negotiated during control stream setup.

func (*Settings) Encode

func (s *Settings) Encode() []byte

Encode serializes Settings into a binary H3 SETTINGS frame payload.