Documentation
¶
Overview ¶
Package frame implements a binary frame protocol for inter-process communication.
Each frame consists of a header (12 bytes minimum) followed by a variable-length payload. The header is laid out as follows:
Byte 0: version (upper 4 bits) | header length in 32-bit words (lower 4 bits)
Byte 1: flags — codec selection (CodecRaw, CodecJSON, CodecGob, CodecProto)
and control flags (CONTROL, ERROR)
Bytes 2-5: payload length (little-endian uint32, max ~4 GB)
Bytes 6-9: CRC32 (IEEE) of bytes 0-5
Bytes 10-11: stream control bits (STREAM, STOP, PING, PONG)
When header length exceeds 3 words (12 bytes), the additional words carry up to 10 option values (uint32 each, 40 bytes maximum) appended after the base header.
Index ¶
- Constants
- type Frame
- func (f *Frame) AllocPayload(n int) []byte
- func (*Frame) AppendOptions(header *[]byte, options []byte)
- func (f *Frame) Bytes() []byte
- func (f *Frame) Header() []byte
- func (f *Frame) HeaderPtr() *[]byte
- func (*Frame) IsPing(header []byte) bool
- func (*Frame) IsPong(header []byte) bool
- func (*Frame) IsStop(header []byte) bool
- func (*Frame) IsStream(header []byte) bool
- func (f *Frame) Payload() []byte
- func (f *Frame) ReadFlags() byte
- func (*Frame) ReadHL(header []byte) byte
- func (f *Frame) ReadOptions(header []byte) []uint32
- func (*Frame) ReadPayloadLen(header []byte) uint32
- func (*Frame) ReadVersion(header []byte) byte
- func (f *Frame) Reset()
- func (*Frame) SetPingBit(header []byte)
- func (*Frame) SetPongBit(header []byte)
- func (*Frame) SetStopBit(header []byte)
- func (*Frame) SetStreamFlag(header []byte)
- func (*Frame) VerifyCRC(header []byte) bool
- func (f *Frame) Wire() (wire []byte, ok bool)
- func (*Frame) WriteCRC(header []byte)
- func (*Frame) WriteFlags(header []byte, flags ...byte)
- func (f *Frame) WriteOptions(header *[]byte, options ...uint32)
- func (f *Frame) WritePayload(data []byte)
- func (*Frame) WritePayloadLen(header []byte, payloadLen uint32)
- func (*Frame) WriteVersion(header []byte, version byte)
Constants ¶
const ( CONTROL byte = 0x01 CodecRaw byte = 0x04 CodecJSON byte = 0x08 CodecMsgpack byte = 0x10 CodecGob byte = 0x20 ERROR byte = 0x40 CodecProto byte = 0x80 // Version1 byte Version1 byte = 0x01 // STREAM bit STREAM byte = 0x01 // STOP command STOP byte = 0x02 // PING command PING byte = 0x04 // PONG command PONG byte = 0x08 )
BYTE flags, it means, that we can set multiply flags from this group using bitwise OR For example CONTEXT_SEPARATOR | CodecRaw
const Headroom = 12 + OptionsMaxSize
Headroom is the space kept in front of a pooled payload for the header, so that Wire can hand the whole frame to a single Write without copying the payload.
const OptionsMaxSize = 40
OptionsMaxSize represents header's options maximum size
const WORD = 4
WORD represents 32bit word
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Frame ¶
type Frame struct {
// contains filtered or unexported fields
}
Frame defines new user level package format.
func From ¶
From wraps the given header and payload slices as a Frame. The frame takes ownership of both slices: WritePayload, WriteOptions, AppendOptions and Reset write into them.
func NewFrame ¶
func NewFrame() *Frame
NewFrame initializes a new frame with a 12-byte header and no payload. The header has capacity for the maximum of 10 options, so WriteOptions does not allocate. The payload is borrowed from the buffer pool on the first AllocPayload or WritePayload; Reset returns it when it is larger than the smallest pool tier.
func ReadFrame ¶
ReadFrame produces a Frame from raw bytes. The first 12 bytes (or more if options are present) form the header; the rest is the payload. Without options, ReadFrame clears bytes 10 and 11 of data. The frame aliases data: WritePayload, WriteOptions, AppendOptions and Reset write into it, and a header extension overwrites the start of the payload.
func ReadHeader ¶
ReadHeader reads only the header (first 12 bytes) from data, without payload. The frame aliases data: WriteOptions, AppendOptions and Reset write into it.
func (*Frame) AllocPayload ¶
AllocPayload sets the payload length to n and returns it for the caller to fill. The contents are undefined. The payload is resliced in place when its capacity fits, both for a pooled buffer and for caller memory; otherwise a buffer of the right tier is taken from the pool. n == 0 never takes a buffer. A pooled payload starts Headroom bytes into its buffer, see Wire.
func (*Frame) AppendOptions ¶
AppendOptions appends raw option bytes to the header. The header is extended in place when its capacity is sufficient, otherwise it is reallocated.
func (*Frame) Payload ¶
Payload returns the frame payload without the header. The slice is valid until the next AllocPayload, WritePayload or Reset on the frame.
func (*Frame) ReadHL ¶
ReadHL reads the header length from the lower 4 bits of byte 0. The upper 4 bits (version) are masked off with bitwise AND 0x0F.
func (*Frame) ReadOptions ¶
ReadOptions reads uint32 option values from the extended header. Returns nil if no options are present (HL <= 3). Option count is derived from HL - 3.
func (*Frame) ReadPayloadLen ¶
ReadPayloadLen reads the payload length from bytes 2-5 of the header in little-endian format.
func (*Frame) ReadVersion ¶
ReadVersion returns the protocol version from the upper 4 bits of byte 0. 1111_0000 -> 0000_1111 (15)
func (*Frame) Reset ¶
func (f *Frame) Reset()
Reset clears the frame, restoring it to its initial state with a 12-byte header and an empty payload. The header keeps its capacity. A payload buffer of the smallest pool tier stays on the frame, so small frames do not pay a pool round trip per cycle; a larger one goes back to the pool. Either way slices returned earlier by Payload are invalid after Reset. A payload that aliases caller memory is only truncated. The header capacity must be at least 12 bytes.
func (*Frame) SetPingBit ¶
SetPingBit sets the PING bit on byte 10 of the header.
func (*Frame) SetPongBit ¶
SetPongBit sets the PONG bit on byte 10 of the header.
func (*Frame) SetStopBit ¶
SetStopBit sets the STOP bit on byte 10 of the header.
func (*Frame) SetStreamFlag ¶
SetStreamFlag sets the STREAM bit on byte 10 of the header.
func (*Frame) VerifyCRC ¶
VerifyCRC verifies the CRC32 checksum stored in bytes 6-9 against the computed checksum of bytes 0-5. Returns false if the checksums do not match, indicating a corrupted frame.
func (*Frame) Wire ¶
Wire writes the header into the headroom in front of a pooled payload and returns the contiguous header-plus-payload slice, valid until the next write or Reset. ok is false when the frame has no pooled payload, an empty payload, or a header longer than Headroom; the caller then sends the header and the payload separately.
func (*Frame) WriteCRC ¶
WriteCRC calculates the CRC32 checksum of bytes 0-5 and writes it into bytes 6-9 of the header.
func (*Frame) WriteFlags ¶
WriteFlags sets one or more flags on byte 1 of the header using bitwise OR.
func (*Frame) WriteOptions ¶
WriteOptions writes uint32 option values into the header, extending it by 4 bytes per option. At most 10 options (40 bytes) are allowed. The header is extended in place when its capacity is sufficient, otherwise it is reallocated, so the header pointer is required.
func (*Frame) WritePayload ¶
WritePayload copies data into the frame's payload. See AllocPayload for where the buffer comes from.
func (*Frame) WritePayloadLen ¶
WritePayloadLen writes the payload length into bytes 2-5 of the header in little-endian format.
func (*Frame) WriteVersion ¶
WriteVersion writes the protocol version (0-15) into the upper 4 bits of byte 0. The version is shifted left by 4 and OR'd with the existing byte to preserve the header length.
Source Files