wirecodec-go

README

wirecodec-go

Declarative, zero-copy binary codec generator for Go

wirecodec-go is a compile-time code generator that turns annotated Go structs into high-performance binary encoders and decoders — similar in spirit to protocol compilers, but with no external schema files and no runtime reflection.

It is the Go sibling of the Rust wirecodec project, offering a nearly identical feature set for expressive binary message modeling and fast, safe serialization.

---

Disclaimer

This is a port of my other experimental project that I created using LLM. Close to 100% of the code in this project has been written by an LLM based on my instructions using the wirecodec-rs project as the baseline which I referenced. I wanted to see how feasible porting project from one language to another is and how well can LLM do it.

---

✨ Features

• Zero-copy decoding for []byte fields
  Decoded byte slices become direct subslices of the original buffer.

• Bit-level fields

  Foo uint8 `wire:"bits=3"`
  Bar uint8 `wire:"bits=5"`
  

• Byte-level fields (fixed or dynamic)

  Payload []byte `wire:"bytes,length_of=Len"`
  Len     uint16 `wire:"bits=16,length_of=Payload"`
  

• Dependent field relationships

  • length_of=...
  • count_of=...

• Verification constraints

  Magic uint32 `wire:"bytes=4,verify=0x2112A442"`
  

• Endianness control

  Seq uint32 `wire:"bytes=4,endian=big"`
  

• Padding for RFC-style alignment

  Value []byte `wire:"bytes,pad_to=4,length_of=Length"`
  

• CRC32 auto-computation + verification

  Crc uint32 `wire:"bytes=4,crc32_of=Payload,endian=big"`
  

• Conditional encoding/decoding

  ExtLen  uint8  `wire:"bits=8,when=HasExt==1,length_of=ExtData"`
  ExtData []byte `wire:"bytes,when=HasExt==1"`
  

• Nested structures

  Header RTPHeader `wire:"nested"`
  

• Tagged enums (tagged unions)

  Kind uint8 `wire:"bits=8,enum_tag"`
  
  Foo FooAttr `wire:"nested,tag=1"`
  Bar BarAttr `wire:"nested,tag=2"`
  

• No reflection, no allocations (where avoidable)
  Generated code uses fixed offsets, bit-level math, and directly mutates the encoder/decoder state.

---

🚀 Quick Example

Define a struct

//go:generate go run github.com/petrijr/wirecodec-go/cmd/wirecodec-gen .

type Packet struct {
  Count   uint8  `wire:"bits=8,count_of=Payload"`
  Payload []byte `wire:"bytes"`
}

Generate the codec

go generate .

This creates wirecodec_gen.go with:

func (m *Packet) Encode(enc *wire.Encoder) error
func (m *Packet) Decode(dec *wire.Decoder) error

Use it

p := &Packet{Payload: []byte{10, 20, 30}}
enc := wire.NewEncoder(0)
_ = p.Encode(enc)

wireBytes := enc.Bytes()

dec := wire.NewDecoder(wireBytes)
var p2 Packet
_ = p2.Decode(dec)

p2.Payload is now a zero-copy subslice of wireBytes.

---

📦 Example Gallery

Examples under examples/:

• simple/
• tlv/
• bitfields/
• rtp/
• stun/
• taggedenum/
• ntp/
• ntpclient/
• zerocopy/

---

🧪 Tests

go test ./...

---

📜 Installation

go install github.com/petrijr/wirecodec-go/cmd/wirecodec-gen@latest

---

📄 License

MIT License © 2025