protobuf

README

ProtoBuf

In the name of the warrior, I charge you to be brave.
In the name of the father, I charge you to be just.
In the name of the mother, I charge you to defend the innocent.

A Knight of the Seven Kingdoms (Game of Thrones) (2019)

Protocol Buffers

This module parses and formats the raw wire encoding.

• https://protobuf.dev/programming-guides/encoding#order
• https://wikipedia.org/wiki/Protocol_Buffers

prior art

• https://github.com/VictoriaMetrics/easyproto/issues/5
• https://github.com/philpearl/plenc/issues/12
• https://github.com/richardartoul/molecule/issues/24
• https://github.com/segmentio/encoding/issues/135

Documentation

Index

• func DecodeVarint(buffer []byte) (uint64, int)
• func EncodeFixed32(value uint32) []byte
• func EncodeFixed64(value uint64) []byte
• func EncodeVarint(value uint64) []byte
• func ParseFixed32(buffer []byte) (uint32, int, error)
• func ParseFixed64(buffer []byte) (uint64, int, error)
• func ParseLengthPrefixed(buffer []byte) (uint64, int, error)
• type Field
  • func Bytes(fieldNum uint32, value []byte) *Field
  • func Embed(fieldNum uint32, value ...*Field) *Field
  • func Fixed32(fieldNum uint32, value uint32) *Field
  • func Fixed64(fieldNum uint32, value uint64) *Field
  • func String(fieldNum uint32, value string) *Field
  • func Varint(fieldNum uint32, value uint64) *Field
• type Iterator
  • func (it *Iterator) Field() *Field
  • func (it *Iterator) Next() bool
• type Message
  • func (m Message) Encode() ([]byte, error)
  • func (m Message) Field(fieldNum uint32) (*Field, bool)
  • func (m Message) Iterator(fieldNum uint32) *Iterator
  • func (m *Message) Parse(data []byte) error
• type Tag
  • func ParseTag(buffer []byte) (Tag, int, error)
• type Type

Functions

func DecodeVarint

func DecodeVarint(buffer []byte) (uint64, int)

DecodeVarint reads a varint from the buffer and returns the decoded uint64 and the number of bytes read. A negative number of bytes indicates an overflow. A zero indicates an unterminated varint.

func EncodeFixed32

func EncodeFixed32(value uint32) []byte

EncodeFixed32 encodes a uint32 into 4 bytes (little-endian).

func EncodeFixed64

func EncodeFixed64(value uint64) []byte

EncodeFixed64 encodes a uint64 into 8 bytes (little-endian).

func EncodeVarint

func EncodeVarint(value uint64) []byte

EncodeVarint encodes a uint64 into varint bytes.

func ParseFixed32

func ParseFixed32(buffer []byte) (uint32, int, error)

ParseFixed32 parses a 32-bit little-endian integer from the buffer.

func ParseFixed64

func ParseFixed64(buffer []byte) (uint64, int, error)

ParseFixed64 parses a 64-bit little-endian integer from the buffer.

func ParseLengthPrefixed

func ParseLengthPrefixed(buffer []byte) (uint64, int, error)

ParseLengthPrefixed parses a length-prefixed field from the buffer. It returns the length of the data, the number of bytes read for the length header, and an error if any.

Types

type Field

type Field struct {
	Tag     Tag
	Numeric uint64
	Bytes   []byte
	Message Message
}

Field represents a single, decoded field in a protobuf message.

func Bytes

func Bytes(fieldNum uint32, value []byte) *Field

Bytes creates a new Bytes field and returns a pointer to it.

func Embed

func Embed(fieldNum uint32, value ...*Field) *Field

Embed creates a new embedded message field from the provided sub-fields.

func Fixed32

func Fixed32(fieldNum uint32, value uint32) *Field

Fixed32 creates a new Fixed32 field and returns a pointer to it.

func Fixed64

func Fixed64(fieldNum uint32, value uint64) *Field

Fixed64 creates a new Fixed64 field and returns a pointer to it.

func String

func String(fieldNum uint32, value string) *Field

String creates a new String (WireBytes) field and returns a pointer to it.

func Varint

func Varint(fieldNum uint32, value uint64) *Field

Varint creates a new Varint field and returns a pointer to it.

type Iterator

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

Iterator provides a stateful, memory-efficient way to loop over all occurrences of a specific field number within a message.

func (*Iterator) Field

func (it *Iterator) Field() *Field

Field returns a pointer to the current field the iterator is pointing to.

func (*Iterator) Next

func (it *Iterator) Next() bool

Next advances the iterator to the next matching field. It returns false when there are no more matching fields.

type Message

type Message []*Field

Message is a named type for a slice of field pointers, representing a parsed protobuf message.

func (Message) Encode

func (m Message) Encode() ([]byte, error)

Encode serializes the message into the protobuf wire format.

func (Message) Field

func (m Message) Field(fieldNum uint32) (*Field, bool)

Field finds and returns the first field matching the given field number. The boolean return value is false if no matching field is found.

func (Message) Iterator

func (m Message) Iterator(fieldNum uint32) *Iterator

Iterator creates a new iterator to loop over all fields with the given number.

func (*Message) Parse

func (m *Message) Parse(data []byte) error

Parse populates the message by parsing the protobuf wire format data. It will overwrite any existing fields in the message.

type Tag

type Tag struct {
	Number uint32
	Type   Type
}

Tag represents a field's tag (Field Number + Wire Type).

func ParseTag

func ParseTag(buffer []byte) (Tag, int, error)

ParseTag decodes a varint from the input buffer and returns it as a Tag struct.

type Type

type Type uint8

Type represents the type of data encoding on the wire.

const (
	WireVarint     Type = 0
	WireFixed64    Type = 1
	WireBytes      Type = 2
	WireStartGroup Type = 3 // Deprecated
	WireEndGroup   Type = 4 // Deprecated
	WireFixed32    Type = 5
)