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 (*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 (*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 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 NewFrame ¶
func NewFrame() *Frame
NewFrame initializes a new frame with a 12-byte header and 100-byte reserved space for the payload.
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.
func ReadHeader ¶
ReadHeader reads only the header (first 12 bytes) from data, without payload.
func (*Frame) AppendOptions ¶
AppendOptions appends raw option bytes to the header.
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 empty payload.
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) 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 pointer is required because the slice is reallocated.
func (*Frame) WritePayload ¶
WritePayload copies data into the frame's payload.
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