codec

Documentation

Overview

Package codec is the reference decoder for the tickbatch wire format.

It reads frames produced by tickbatch.Batcher and passed to a Sink: it parses the 8-byte header, verifies the CRC, and - for delta-encoded streams - reverses the XOR delta against the previous frame, honoring keyframes. See ../SPEC.md for the full wire-format contract this package implements.

The package is stdlib-only and has no dependency on the tickbatch core, so consumers (which may be separate services in another language's absence, or Go receivers) can vendor just this decoder.

Index

• Variables
• type DeltaReconstructor
  • func (d *DeltaReconstructor) Reconstruct(frame []byte) ([]byte, Header, error)
• type Header
  • func Decode(frame []byte) (Header, []byte, error)
  • func ParseHeader(frame []byte) (Header, error)

Variables

var (
	// ErrShortFrame is returned when a frame is smaller than the fixed header.
	ErrShortFrame = errors.New("tickbatch/codec: frame shorter than header")
	// ErrCRCMismatch is returned when the body CRC does not match the header tag.
	ErrCRCMismatch = errors.New("tickbatch/codec: CRC mismatch")
)

Types

type DeltaReconstructor

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

DeltaReconstructor reverses tickbatch's XOR delta encoding, reconstructing each raw frame from the transmitted (possibly XOR-encoded) frame. It maintains the previous raw frame as the delta baseline. The zero value is ready to use.

It is not safe for concurrent use; drive it from a single consumer goroutine.

func (*DeltaReconstructor) Reconstruct

func (d *DeltaReconstructor) Reconstruct(frame []byte) ([]byte, Header, error)

Reconstruct recovers the raw frame from a transmitted frame and returns the raw frame (a fresh slice), its parsed header, and any error.

A frame is treated as a keyframe when its header reads as a keyframe and its CRC validates directly; such frames are sent raw and reset the baseline. Otherwise the frame is delta-decoded by XORing against the previous raw frame (zero-extended to the current length), and the recovered frame's CRC is verified. The CRC is the keyframe/delta disambiguator (see ../SPEC.md).

type Header

type Header struct {
	// Seq is the frame sequence ID. It increments on every attempted flush, so
	// gaps do not imply a delta desync (see ../SPEC.md).
	Seq uint32
	// Count is the number of items in the body.
	Count uint16
	// CRC is the low 15 bits of CRC-32/IEEE over the raw body.
	CRC uint16
	// Keyframe reports whether bit 15 of the integrity tag is set, marking a
	// full-frame delta baseline reset.
	Keyframe bool
}

Header is the decoded fixed header of a frame.

func Decode

func Decode(frame []byte) (Header, []byte, error)

Decode parses a single raw (non-delta) frame, verifies its CRC, and returns the header and the body slice (aliasing frame, not copied). Use it for streams where the producer's Config.DeltaEncoding is false. For delta-encoded streams use a DeltaReconstructor instead.

func ParseHeader

func ParseHeader(frame []byte) (Header, error)

ParseHeader decodes the 8-byte header at the start of frame without verifying the CRC or interpreting the body.