frame

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 24, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package frame implements HTTP/2 frame reading and writing per RFC 9113.

Index

Constants

View Source 
const (
	DefaultMaxFrameSize = 16384     // 2^14
	MaxMaxFrameSize     = 1<<24 - 1 // 2^24 - 1

)

Frame size limits per RFC 9113 §4.2.

View Source 
const MaxSettingsPerFrame = 32

MaxSettingsPerFrame is the max number of settings in the fixed array. Real-world SETTINGS frames contain at most 6 defined parameters.

Variables

View Source 
var (
	ErrFrameTooLarge = errors.New("frame: payload exceeds max frame size")
	ErrTruncated     = errors.New("frame: truncated")
)

Sentinel errors for common validation failures.

Functions

func ReleaseFrameReader 

func ReleaseFrameReader(fr *FrameReader)

ReleaseFrameReader returns a FrameReader to the pool.

func ReleaseFrameWriter 

func ReleaseFrameWriter(fw *FrameWriter)

ReleaseFrameWriter returns a FrameWriter to the pool.

Types

type ConnError 

type ConnError struct {
	Code   ErrorCode
	Reason string
}

ConnError represents an HTTP/2 connection error with an error code. The connection layer should send GOAWAY with the given code.

func (*ConnError) Error 

func (e *ConnError) Error() string

type ErrorCode 

type ErrorCode uint32

HTTP/2 error codes per RFC 9113 §7. 

const (
	ErrCodeNoError            ErrorCode = 0x0
	ErrCodeProtocolError      ErrorCode = 0x1
	ErrCodeInternalError      ErrorCode = 0x2
	ErrCodeFlowControlError   ErrorCode = 0x3
	ErrCodeSettingsTimeout    ErrorCode = 0x4
	ErrCodeStreamClosed       ErrorCode = 0x5
	ErrCodeFrameSizeError     ErrorCode = 0x6
	ErrCodeRefusedStream      ErrorCode = 0x7
	ErrCodeCancel             ErrorCode = 0x8
	ErrCodeCompressionError   ErrorCode = 0x9
	ErrCodeConnectError       ErrorCode = 0xa
	ErrCodeEnhanceYourCalm    ErrorCode = 0xb
	ErrCodeInadequateSecurity ErrorCode = 0xc
	ErrCodeHTTP11Required     ErrorCode = 0xd
)

func (ErrorCode) String 

func (c ErrorCode) String() string

String returns the error code name.

type Flags 

type Flags uint8

Frame flags per RFC 9113 §6. 

const (
	FlagEndStream  Flags = 0x01
	FlagACK        Flags = 0x01 // Same bit, different context (SETTINGS, PING).
	FlagEndHeaders Flags = 0x04
	FlagPadded     Flags = 0x08
	FlagPriority   Flags = 0x20
)

func (Flags) Has 

func (f Flags) Has(flag Flags) bool

Has reports whether f contains the given flag.

type Frame 

type Frame struct {
	// Header fields (always valid).
	Type     FrameType
	Flags    Flags
	StreamID uint32
	Length   uint32 // payload length from the wire

	// DATA
	Data []byte

	// HEADERS / PUSH_PROMISE / CONTINUATION (assembled)
	HeaderBlock []byte

	// Priority fields (HEADERS with FlagPriority, or PRIORITY frame).
	StreamDep uint32
	Weight    uint8
	Exclusive bool

	// PUSH_PROMISE
	PromisedStreamID uint32

	// RST_STREAM / GOAWAY
	ErrorCode ErrorCode

	// SETTINGS
	Settings    [MaxSettingsPerFrame]Setting
	NumSettings int

	// PING
	PingData [8]byte

	// GOAWAY
	LastStreamID uint32
	DebugData    []byte

	// WINDOW_UPDATE
	WindowIncrement uint32
}

Frame is a reusable, zero-allocation frame representation. Only fields relevant to the frame Type are valid after a read. Data, HeaderBlock, and DebugData slices point into the reader's buffer and are valid only until the next ReadFrame call.

func (*Frame) HasACK 

func (f *Frame) HasACK() bool

HasACK reports whether the ACK flag is set.

func (*Frame) HasEndHeaders 

func (f *Frame) HasEndHeaders() bool

HasEndHeaders reports whether the END_HEADERS flag is set.

func (*Frame) HasEndStream 

func (f *Frame) HasEndStream() bool

HasEndStream reports whether the END_STREAM flag is set.

func (*Frame) HasPadded 

func (f *Frame) HasPadded() bool

HasPadded reports whether the PADDED flag is set.

func (*Frame) HasPriority 

func (f *Frame) HasPriority() bool

HasPriority reports whether the PRIORITY flag is set.

func (*Frame) Reset 

func (f *Frame) Reset()

Reset clears all frame fields for reuse.

type FrameReader 

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

FrameReader reads HTTP/2 frames from an io.Reader. It automatically assembles CONTINUATION frames into a single header block. The returned *Frame is valid until the next ReadFrame call.

func AcquireFrameReader 

func AcquireFrameReader(r io.Reader) *FrameReader

AcquireFrameReader gets a FrameReader from the pool.

func (*FrameReader) MaxFrameSize 

func (fr *FrameReader) MaxFrameSize() uint32

MaxFrameSize returns the current maximum frame payload size.

func (*FrameReader) ReadFrame 

func (fr *FrameReader) ReadFrame() (*Frame, error)

ReadFrame reads the next frame. The returned *Frame is reused on the next call.

func (*FrameReader) SetMaxFrameSize 

func (fr *FrameReader) SetMaxFrameSize(size uint32)

SetMaxFrameSize sets the maximum allowed frame payload size.

type FrameType 

type FrameType uint8

Frame type codes per RFC 9113 §6. 

const (
	FrameData         FrameType = 0x0
	FrameHeaders      FrameType = 0x1
	FramePriority     FrameType = 0x2
	FrameRSTStream    FrameType = 0x3
	FrameSettings     FrameType = 0x4
	FramePushPromise  FrameType = 0x5
	FramePing         FrameType = 0x6
	FrameGoAway       FrameType = 0x7
	FrameWindowUpdate FrameType = 0x8
	FrameContinuation FrameType = 0x9
)

func (FrameType) String 

func (t FrameType) String() string

String returns the frame type name.

type FrameWriter 

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

FrameWriter encodes HTTP/2 frames into a batched write buffer. Frames are accumulated and flushed together to reduce syscalls.

func AcquireFrameWriter 

func AcquireFrameWriter(w io.Writer) *FrameWriter

AcquireFrameWriter gets a FrameWriter from the pool.

func (*FrameWriter) Buffered 

func (fw *FrameWriter) Buffered() int

Buffered returns the number of bytes buffered.

func (*FrameWriter) Flush 

func (fw *FrameWriter) Flush() error

Flush writes all buffered frames to the underlying writer.

func (*FrameWriter) MaxFrameSize 

func (fw *FrameWriter) MaxFrameSize() uint32

MaxFrameSize returns the current maximum frame payload size.

func (*FrameWriter) Reset 

func (fw *FrameWriter) Reset()

Reset clears the write buffer.

func (*FrameWriter) SetMaxFrameSize 

func (fw *FrameWriter) SetMaxFrameSize(size uint32)

SetMaxFrameSize sets the maximum frame payload size for fragmentation.

func (*FrameWriter) WriteData 

func (fw *FrameWriter) WriteData(streamID uint32, endStream bool, data []byte)

WriteData writes a DATA frame.

func (*FrameWriter) WriteDataPadded 

func (fw *FrameWriter) WriteDataPadded(streamID uint32, endStream bool, data []byte, padLen uint8)

WriteDataPadded writes a DATA frame with padding.

func (*FrameWriter) WriteGoAway 

func (fw *FrameWriter) WriteGoAway(lastStreamID uint32, code ErrorCode, debugData []byte)

WriteGoAway writes a GOAWAY frame.

func (*FrameWriter) WriteHeaders 

func (fw *FrameWriter) WriteHeaders(streamID uint32, endStream bool, headerBlock []byte, priority *PriorityParam)

WriteHeaders writes a HEADERS frame, automatically fragmenting into CONTINUATION frames if the header block exceeds maxFrameSize.

func (*FrameWriter) WriteHeadersPadded 

func (fw *FrameWriter) WriteHeadersPadded(streamID uint32, endStream bool, headerBlock []byte, priority *PriorityParam, padLen uint8)

WriteHeadersPadded writes a HEADERS frame with padding. Does not fragment (caller must ensure the padded frame fits within maxFrameSize).

func (*FrameWriter) WritePing 

func (fw *FrameWriter) WritePing(ack bool, data [8]byte)

WritePing writes a PING frame.

func (*FrameWriter) WritePriority 

func (fw *FrameWriter) WritePriority(streamID uint32, p PriorityParam)

WritePriority writes a PRIORITY frame.

func (*FrameWriter) WritePushPromise 

func (fw *FrameWriter) WritePushPromise(streamID, promisedStreamID uint32, headerBlock []byte)

WritePushPromise writes a PUSH_PROMISE frame, automatically fragmenting into CONTINUATION frames if the header block exceeds maxFrameSize.

func (*FrameWriter) WriteRSTStream 

func (fw *FrameWriter) WriteRSTStream(streamID uint32, code ErrorCode)

WriteRSTStream writes a RST_STREAM frame.

func (*FrameWriter) WriteRaw 

func (fw *FrameWriter) WriteRaw(ftype FrameType, flags Flags, streamID uint32, payload []byte)

WriteRaw writes a raw frame with the given header fields and payload. Useful for testing or forwarding unknown frame types.

func (*FrameWriter) WriteSettings 

func (fw *FrameWriter) WriteSettings(settings ...Setting)

WriteSettings writes a SETTINGS frame.

func (*FrameWriter) WriteSettingsACK 

func (fw *FrameWriter) WriteSettingsACK()

WriteSettingsACK writes a SETTINGS ACK frame.

func (*FrameWriter) WriteWindowUpdate 

func (fw *FrameWriter) WriteWindowUpdate(streamID uint32, increment uint32)

WriteWindowUpdate writes a WINDOW_UPDATE frame.

type PriorityParam 

type PriorityParam struct {
	Exclusive bool
	StreamDep uint32
	Weight    uint8 // 0-255, actual priority weight is Weight+1
}

PriorityParam holds stream priority fields for HEADERS and PRIORITY frames.

type Setting 

type Setting struct {
	ID    SettingsID
	Value uint32
}

Setting is a single SETTINGS parameter.

type SettingsID 

type SettingsID uint16

SETTINGS parameter IDs per RFC 9113 §6.5.2. 

const (
	SettingsHeaderTableSize      SettingsID = 0x1
	SettingsEnablePush           SettingsID = 0x2
	SettingsMaxConcurrentStreams SettingsID = 0x3
	SettingsInitialWindowSize    SettingsID = 0x4
	SettingsMaxFrameSize         SettingsID = 0x5
	SettingsMaxHeaderListSize    SettingsID = 0x6
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.