pack

README

Proto-Pack format

File

name	type	description
magic	byte[9]	'p', 'r', 'o', 't', 'o', 'p', 'a', 'c', 'k'
header	Chunk<Header>	Header chunk
data	Chunk<Section>[]	File content

Chunk<T>

name	type	description
size	varint	Size of the chunk data
data	byte[size]	T data

Section

A section is either a type or a object:

Type

name	type	description
tag	varint	0
name	varstr	Proto type name
desc	DescriptorProto	Proto type descriptor

Object

name	type	description
tag	varint	Type index - 1
data	byte[]	Proto data

Documentation

Overview

Package pack provides methods to deal with self describing files of proto data.

The file format consists of a magic marker, followed by a Header. After that is a repeated sequence of uvarint length, tag and matching encoded message pair. Some section tags will also be followed by a string. The tag 0 is special, and marks a type entry, the body will be a descriptor.DescriptorProto.

Index

• Constants
• type ErrUnknownType
  • func (e ErrUnknownType) Error() string
• type ErrUnknownVersion
  • func (e ErrUnknownVersion) Error() string
• type Reader
  • func NewReader(from io.Reader) (*Reader, error)
  • func (r *Reader) Unmarshal() (proto.Message, error)
• type Type
• type Types
  • func NewTypes() *Types
  • func (t *Types) AddMessage(msg proto.Message) (Type, bool)
  • func (t *Types) AddName(name string) (Type, bool)
  • func (t *Types) AddType(typ reflect.Type) (Type, bool)
  • func (t *Types) Count() uint64
  • func (t *Types) Get(index uint64) (Type, bool)
  • func (t *Types) GetName(name string) Type
• type Writer
  • func NewWriter(to io.Writer) (*Writer, error)
  • func (w *Writer) Marshal(msg proto.Message) error

Constants

const (
	// Magic is the file magic that prefixes all pack files.
	Magic = "protopack"

	// ErrIncorrectMagic is the error returned when the file header is not matched.
	ErrIncorrectMagic = fault.Const("Incorrect pack magic header")

	// VersionMajor is the curent major version the package writes.
	VersionMajor = 1
	// VersionMinor is the current minor version the package writes.
	VersionMinor = 0
)

Types

type ErrUnknownType

type ErrUnknownType struct{ TypeName string }

ErrUnknownType is the error returned by Reader.Unmarshal() when it encounters an unknown proto type.

func (ErrUnknownType) Error

func (e ErrUnknownType) Error() string

type ErrUnknownVersion

type ErrUnknownVersion struct{ Version *Version }

ErrUnknownVersion is the error returned when the header version is one this package cannot handle.

func (ErrUnknownVersion) Error

func (e ErrUnknownVersion) Error() string

type Reader

type Reader struct {
	// Types is the set of registered types this reader will decode.
	Types *Types
	// contains filtered or unexported fields
}

Reader is the type for a pack file reader. They should only be constructed by NewReader.

func NewReader

func NewReader(from io.Reader) (*Reader, error)

NewReader builds a pack file reader that gets it's data from the supplied stream. This function will read the header from the stream, adjusting it's position. It may read extra bytes from the stream into an internal buffer.

func (*Reader) Unmarshal

func (r *Reader) Unmarshal() (proto.Message, error)

Unmarshal reads the next data section from the file, consuming any special sections on the way.

type Type

type Type struct {
	// Name is the cannocial unique name of the type.
	// This will be the same name as used in the proto registry.
	Name string
	// Index is the tag index used for the type in this packfile.
	Index uint64
	// Type is the reflection type that maps to this type registry.
	Type reflect.Type
	// Descriptor is the proto description of this type, it is packed
	// into the file and can be used to reflect on the type.
	Descriptor *descriptor.DescriptorProto
}

Type is an entry in the map of types stored in a packfile.

type Types

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

Types stores the full type registry for a packfile. It is exposed so that you can pre-build a cannocial type registry rather than constructing on demand.

func NewTypes

func NewTypes() *Types

NewTypes constructs a new empty type registry.

func (*Types) AddMessage

func (t *Types) AddMessage(msg proto.Message) (Type, bool)

AddMessage adds a registry entry for a given message if needed. It returns the registry entry, and a bool that is true if the entry was newly added.

func (*Types) AddName

func (t *Types) AddName(name string) (Type, bool)

AddName adds a type by name. It uses the proto type registry to look up the name.

func (*Types) AddType

func (t *Types) AddType(typ reflect.Type) (Type, bool)

AddType adds a type by it's reflection type.

func (*Types) Count

func (t *Types) Count() uint64

Count returns the number of types in the registry.

func (*Types) Get

func (t *Types) Get(index uint64) (Type, bool)

Get returns a type given it's tag index.

func (*Types) GetName

func (t *Types) GetName(name string) Type

GetName returns a type given it's cannocial type name.

type Writer

type Writer struct {
	// Types is the set of registered types encoded through this writer.
	Types *Types
	// contains filtered or unexported fields
}

Writer is the type for a pack file writer. They should only be constructed by NewWriter.

func NewWriter

func NewWriter(to io.Writer) (*Writer, error)

NewWriter constructs and returns a new Writer that writes to the supplied output stream. This method will write the packfile magic and header to the underlying stream.

func (*Writer) Marshal

func (w *Writer) Marshal(msg proto.Message) error

Marshal writes a new object to the packfile, preceding it with a type entry if needed.