README
¶
bincodec
Zero-reflection binary codec for Go with schema-driven serialization, designed for compact state and protocol data.
Features
- Zero reflection — no
reflect, no struct tags parsed at runtime, nointerface{}dispatch - Fixed-width types —
uint8/16/32/64,int32/64,bool,[]byte(cross-platform consistent) - Big-endian — network byte order, deterministic output
- Schema-driven — objects declare their field layout; codec handles encode/decode automatically
- Code generation —
bincodec-gengeneratesBinaryObjectimplementations from struct definitions viago:generate - Near hand-written performance — the only overhead is a
switchon field type (compiler-optimized jump table)
Install
go get github.com/iamkivae/bincodec
Quick Start
Using BinaryObject interface
type cursorState struct {
Version uint8
Offset uint32
Finished bool
}
// Implement BinaryObject (or use code generation, see below)
func (s *cursorState) Schema() []bincodec.FieldDef {
return []bincodec.FieldDef{bincodec.FUint8(), bincodec.FUint32(), bincodec.FBool()}
}
func (s *cursorState) Get(i int) bincodec.Value {
switch i {
case 0: return bincodec.Uint8Val(s.Version)
case 1: return bincodec.Uint32Val(s.Offset)
case 2: return bincodec.BoolVal(s.Finished)
default: return bincodec.Value{}
}
}
func (s *cursorState) Set(i int, v bincodec.Value) {
switch i {
case 0: s.Version = v.AsUint8()
case 1: s.Offset = v.AsUint32()
case 2: s.Finished = v.AsBool()
}
}
// Encode
state := &cursorState{Version: 1, Offset: 42, Finished: false}
data, err := bincodec.Encode(state) // 6 bytes: [01 00 00 00 2A 00]
// Decode
restored := &cursorState{}
err = bincodec.Decode(data, restored)
Using primitives directly
// Encode
enc := bincodec.NewEncoder(16)
enc.PutUint8(1)
enc.PutUint32(1024)
enc.PutBool(true)
enc.PutBytes([]byte("hello"))
data := enc.Bytes()
// Decode
dec := bincodec.NewDecoder(data)
version, _ := dec.Uint8()
offset, _ := dec.Uint32()
flag, _ := dec.Bool()
payload, _ := dec.Bytes()
Code generation
Add a go:generate directive to your struct file:
//go:generate go run github.com/iamkivae/bincodec/generate -type=cursorState
type cursorState struct {
Version uint8
Offset uint32
Finished bool
}
Run go generate ./... to produce cursor_state_gen.go with Schema(), Get(), and Set() implementations.
Generated files follow Go naming conventions (snake_case_gen.go) and include the standard // Code generated ... DO NOT EDIT. header.
Binary Layout
All types use big-endian encoding:
| Type | Size | Notes |
|---|---|---|
uint8 |
1 byte | |
uint16 |
2 bytes | big-endian |
uint32 |
4 bytes | big-endian |
uint64 |
8 bytes | big-endian |
int32 |
4 bytes | two's complement, big-endian |
int64 |
8 bytes | two's complement, big-endian |
bool |
1 byte | 0x00=false, 0x01=true |
[]byte |
4 + N bytes | 4-byte big-endian length prefix + data |
Version Compatibility
Include a version field as the first struct field:
type myState struct {
Version uint8 // always field 0
// ... other fields
}
After decoding, validate:
if state.Version != expectedVersion {
return bincodec.ErrVersionMismatch
}
Adding new fields in future versions is safe — append to the struct and regenerate. Older decoders will return ErrBufferTooShort if the data is shorter than expected.
Performance
- No reflection, no JSON, no
interface{}dynamic dispatch Valueis a 24-byte fixed struct (stack-allocated)Schema()returns a package-level static variable (no per-call allocation)- Encode/Decode path is a single
switchonValueType - Benchmarks show performance within 5% of hand-written binary encoding
License
Documentation
¶
Overview ¶
Package bincodec provides a lightweight fixed-width binary encoding/decoding toolkit.
Design goals:
- Zero reflection, zero JSON, zero interface{} dynamic dispatch
- Fixed-width types (cross-platform safe: amd64/arm64/32bit consistent)
- Big-endian byte order (network byte order)
- Near hand-written binary encoding performance
- Minimal memory allocation
Use cases:
- Pagination cookie encoding/decoding
- Backend-defined cursor state
- Internal tokens and binary state
This package is NOT a general-purpose serialization framework. Each consumer defines its own field order and semantics via the BinaryObject interface or hand-written Encode/Decode using the primitives.
Index ¶
- Variables
- func Decode(data []byte, obj BinaryObject) error
- func Encode(obj BinaryObject) ([]byte, error)
- type BinaryObject
- type Decoder
- func (d *Decoder) Bool() (bool, error)
- func (d *Decoder) Bytes() ([]byte, error)
- func (d *Decoder) Int32() (int32, error)
- func (d *Decoder) Int64() (int64, error)
- func (d *Decoder) Pos() int
- func (d *Decoder) Remaining() int
- func (d *Decoder) RemainingBytes() []byte
- func (d *Decoder) String() (string, error)
- func (d *Decoder) Uint8() (uint8, error)
- func (d *Decoder) Uint16() (uint16, error)
- func (d *Decoder) Uint32() (uint32, error)
- func (d *Decoder) Uint64() (uint64, error)
- type Encoder
- func (e *Encoder) Bytes() []byte
- func (e *Encoder) Len() int
- func (e *Encoder) PutBool(v bool)
- func (e *Encoder) PutBytes(v []byte)
- func (e *Encoder) PutInt32(v int32)
- func (e *Encoder) PutInt64(v int64)
- func (e *Encoder) PutString(v string)
- func (e *Encoder) PutUint8(v uint8)
- func (e *Encoder) PutUint16(v uint16)
- func (e *Encoder) PutUint32(v uint32)
- func (e *Encoder) PutUint64(v uint64)
- func (e *Encoder) Reset()
- type FieldDef
- type Value
- type ValueType
Constants ¶
This section is empty.
Variables ¶
var ( // ErrBufferTooShort is returned when the decoder runs out of data. ErrBufferTooShort = errors.New("bincodec: buffer too short") // ErrVersionMismatch is returned when the version field does not match. ErrVersionMismatch = errors.New("bincodec: version mismatch") )
Predefined errors.
Functions ¶
func Decode ¶
func Decode(data []byte, obj BinaryObject) error
Decode deserializes data into obj following the field order defined by obj.Schema().
Returns ErrBufferTooShort if data is insufficient. Zero reflection, zero JSON, zero dynamic types.
func Encode ¶
func Encode(obj BinaryObject) ([]byte, error)
Encode serializes obj into a binary byte slice following the field order defined by obj.Schema().
Zero reflection, zero JSON, zero dynamic types. Performance is near hand-written binary encoding.
Types ¶
type BinaryObject ¶
type BinaryObject interface {
// Schema returns the field definition list. List order is the binary encoding order.
Schema() []FieldDef
// Get returns the value of the field at the given index. Called during Encode.
Get(index int) Value
// Set sets the value of the field at the given index. Called during Decode.
Set(index int, v Value)
}
BinaryObject declares its own field layout; the codec handles encoding/decoding automatically.
Implementors declare field order and types via Schema(), and provide indexed access to field values via Get/Set.
Example:
type myState struct {
Offset uint32
Finished bool
}
func (s *myState) Schema() []bincodec.FieldDef {
return []bincodec.FieldDef{bincodec.FUint32(), bincodec.FBool()}
}
func (s *myState) Get(i int) bincodec.Value {
switch i {
case 0: return bincodec.Uint32Val(s.Offset)
case 1: return bincodec.BoolVal(s.Finished)
default: return bincodec.Value{}
}
}
func (s *myState) Set(i int, v bincodec.Value) {
switch i {
case 0: s.Offset = v.AsUint32()
case 1: s.Finished = v.AsBool()
}
}
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder reads fixed-width fields in big-endian order from a byte slice.
All read methods return ErrBufferTooShort when data is insufficient. Callers should stop decoding after the first error.
Usage:
dec := bincodec.NewDecoder(data) version, err := dec.Uint8() offset, err := dec.Uint32() finished, err := dec.Bool()
func CheckVersion ¶
CheckVersion reads the first byte as a version number and compares it to expected. Returns ErrVersionMismatch if they differ.
func NewDecoder ¶
NewDecoder creates a decoder over the given data.
func (*Decoder) Bytes ¶
Bytes reads a variable-length byte slice (4-byte big-endian length prefix + data). The returned slice is a sub-slice of the original data (zero-copy); callers must not modify it.
func (*Decoder) RemainingBytes ¶
RemainingBytes returns the unread portion as a byte slice (zero-copy).
func (*Decoder) String ¶ added in v0.1.1
String reads a variable-length UTF-8 string (4-byte big-endian length prefix + data).
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder writes fixed-width fields in big-endian order to an internal buffer.
Usage:
enc := bincodec.NewEncoder(16) enc.PutUint8(1) enc.PutUint32(offset) enc.PutBool(finished) data := enc.Bytes()
func NewEncoder ¶
NewEncoder creates an encoder with pre-allocated capacity (reduces reallocation).
func (*Encoder) PutBytes ¶
PutBytes writes a variable-length byte slice (4-byte big-endian length prefix + data). A nil slice is encoded as length 0.
func (*Encoder) PutString ¶ added in v0.1.1
PutString writes a variable-length UTF-8 string (4-byte big-endian length prefix + data). An empty string is encoded as length 0.
type FieldDef ¶
type FieldDef struct {
Type ValueType
}
FieldDef describes the type of a single field in a BinaryObject. The position in the slice returned by Schema() defines the encoding order.
type Value ¶
type Value struct {
// Type identifies which value is currently held.
Type ValueType
// Num stores all fixed-width values:
// - Uint8/16/32/64: stored directly
// - Int32/64: stored as two's complement uint64
// - Bool: 0=false, 1=true
Num uint64
// Data is used only for TypeBytes (variable-length byte slice).
Data []byte
// Str is used only for TypeString (variable-length UTF-8 string).
Str string
}
Value is a fixed-layout tagged union holding a single field's value.
Non-Bytes types are zero-allocation (only the Num field is used). No interface{}, no reflection, no dynamic type assertion.
type ValueType ¶
type ValueType uint8
ValueType describes the binary encoding type of a single field in a BinaryObject.
const ( TypeUint8 ValueType = iota // 1 byte TypeUint16 // 2 bytes big-endian TypeUint32 // 4 bytes big-endian TypeUint64 // 8 bytes big-endian TypeInt32 // 4 bytes big-endian (signed) TypeInt64 // 8 bytes big-endian (signed) TypeBool // 1 byte (0x00/0x01) TypeBytes // 4-byte big-endian length prefix + data TypeString // 4-byte big-endian length prefix + UTF-8 data )
Source Files
Directories