vom

package
v0.0.0-...-3dadef2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 11, 2016 License: BSD-3-Clause Imports: 13 Imported by: 0

Documentation

Overview

Package vom implements the Vanadium Object Marshaling serialization format.

Concept: https://vanadium.github.io/concepts/rpc.html#vom
Specification: https://vanadium.github.io/designdocs/vom-spec.html

VOM supports serialization of all types representable by v.io/v23/vdl, and is a self-describing format that retains full type information. It is the underlying serialization format used by v.io/v23/rpc.

The API is almost identical to encoding/gob. To marshal objects create an Encoder and present it with a series of values. To unmarshal objects create a Decoder and retrieve values. The implementation creates a stream of messages between the Encoder and Decoder.

Index

Constants

View Source
const DefaultVersion = Version(129)
View Source
const Version80 = Version(128)
View Source
const Version81 = Version(129)
View Source
const WireCtrlEnd = byte(225) // End of struct or union
View Source
const WireCtrlNil = byte(224) // Nil in optional or any
View Source
const WireCtrlTypeIncomplete = byte(226) // Marks that the type message is incomplete until future messages are received
View Source
const WireIdAny = TypeId(15)
View Source
const WireIdBool = TypeId(1)

Primitive types.

View Source
const WireIdByte = TypeId(2)
View Source
const WireIdByteList = TypeId(39)

Other commonly used composites.

View Source
const WireIdFirstUserType = TypeId(41)

The first user-defined TypeId is 41.

View Source
const WireIdFloat32 = TypeId(10)
View Source
const WireIdFloat64 = TypeId(11)
View Source
const WireIdInt16 = TypeId(7)
View Source
const WireIdInt32 = TypeId(8)
View Source
const WireIdInt64 = TypeId(9)
View Source
const WireIdInt8 = TypeId(16)
View Source
const WireIdString = TypeId(3)
View Source
const WireIdStringList = TypeId(40)
View Source
const WireIdTypeObject = TypeId(14)

Wire ids 12 and 13 were previously used for complex64 and complex 128.

View Source
const WireIdUint16 = TypeId(4)
View Source
const WireIdUint32 = TypeId(5)
View Source
const WireIdUint64 = TypeId(6)

Variables

ControlKindAll holds all labels for ControlKind.

DumpKindAll holds all labels for DumpKind.

Functions

func Decode

func Decode(data []byte, v interface{}) error

Decode reads the value from the given data, and stores it in value v. The semantics of value decoding are described by Decoder.Decode.

This is a "single-shot" decoding; the data must have been encoded by a call to vom.Encode.

func Dump

func Dump(data []byte) (string, error)

Dump returns a human-readable dump of the given vom data, in the default string format.

func Encode

func Encode(v interface{}) ([]byte, error)

Encode writes the value v and returns the encoded bytes. The semantics of value encoding are described by Encoder.Encode.

This is a "single-shot" encoding; full type information is always included in the returned encoding, as if a new encoder were used for each call.

func VDLReadPrimitive

func VDLReadPrimitive(dec vdl.Decoder, x *Primitive) error

func VersionedEncode

func VersionedEncode(version Version, v interface{}) ([]byte, error)

VersionedEncode performs single-shot encoding to a specific version of VOM

Types

type ControlKind

type ControlKind int

ControlKind enumerates the different kinds of control bytes.

const (
	ControlKindNil ControlKind = iota
	ControlKindEnd
	ControlKindIncompleteType
)

func ControlKindFromString

func ControlKindFromString(label string) (x ControlKind, err error)

ControlKindFromString creates a ControlKind from a string label.

func (*ControlKind) Set

func (x *ControlKind) Set(label string) error

Set assigns label to x.

func (ControlKind) String

func (x ControlKind) String() string

String returns the string label of x.

func (ControlKind) VDLIsZero

func (x ControlKind) VDLIsZero() bool

func (*ControlKind) VDLRead

func (x *ControlKind) VDLRead(dec vdl.Decoder) error

func (ControlKind) VDLReflect

func (ControlKind) VDLReflect(struct {
	Name string `vdl:"v.io/v23/vom.ControlKind"`
	Enum struct{ Nil, End, IncompleteType string }
})

func (ControlKind) VDLWrite

func (x ControlKind) VDLWrite(enc vdl.Encoder) error

type Decoder

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

Decoder manages the receipt and unmarshalling of typed values from the other side of a connection.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new Decoder that reads from the given reader. The Decoder understands all formats generated by the Encoder.

func NewDecoderWithTypeDecoder

func NewDecoderWithTypeDecoder(r io.Reader, typeDec *TypeDecoder) *Decoder

NewDecoderWithTypeDecoder returns a new Decoder that reads from the given reader. Types are decoded separately through the typeDec.

func (*Decoder) Decode

func (d *Decoder) Decode(v interface{}) error

Decode reads the next value and stores it in value v. The type of v need not exactly match the type of the originally encoded value; decoding succeeds as long as the values are convertible.

func (*Decoder) Decoder

func (d *Decoder) Decoder() vdl.Decoder

Decoder returns d as a vdl.Decoder.

type DumpAtom

type DumpAtom struct {
	Kind  DumpKind  // The kind of this atom.
	Bytes []byte    // Raw bytes in the vom encoding representing this atom.
	Data  Primitive // Primitive data corresponding to the raw bytes.
	Debug string    // Free-form debug string with more information.
}

DumpAtom describes a single indivisible piece of the vom encoding. The vom encoding is composed of a stream of these atoms.

func (DumpAtom) String

func (a DumpAtom) String() string

func (DumpAtom) VDLIsZero

func (x DumpAtom) VDLIsZero() bool

func (*DumpAtom) VDLRead

func (x *DumpAtom) VDLRead(dec vdl.Decoder) error

func (DumpAtom) VDLReflect

func (DumpAtom) VDLReflect(struct {
	Name string `vdl:"v.io/v23/vom.DumpAtom"`
})

func (DumpAtom) VDLWrite

func (x DumpAtom) VDLWrite(enc vdl.Encoder) error

type DumpKind

type DumpKind int

DumpKind enumerates the different kinds of dump atoms.

const (
	DumpKindVersion DumpKind = iota
	DumpKindControl
	DumpKindMsgId
	DumpKindTypeMsg
	DumpKindValueMsg
	DumpKindMsgLen
	DumpKindAnyMsgLen
	DumpKindAnyLensLen
	DumpKindTypeIdsLen
	DumpKindTypeId
	DumpKindPrimValue
	DumpKindByteLen
	DumpKindValueLen
	DumpKindIndex
	DumpKindWireTypeIndex
)

func DumpKindFromString

func DumpKindFromString(label string) (x DumpKind, err error)

DumpKindFromString creates a DumpKind from a string label.

func (*DumpKind) Set

func (x *DumpKind) Set(label string) error

Set assigns label to x.

func (DumpKind) String

func (x DumpKind) String() string

String returns the string label of x.

func (DumpKind) VDLIsZero

func (x DumpKind) VDLIsZero() bool

func (*DumpKind) VDLRead

func (x *DumpKind) VDLRead(dec vdl.Decoder) error

func (DumpKind) VDLReflect

func (DumpKind) VDLReflect(struct {
	Name string `vdl:"v.io/v23/vom.DumpKind"`
	Enum struct{ Version, Control, MsgId, TypeMsg, ValueMsg, MsgLen, AnyMsgLen, AnyLensLen, TypeIdsLen, TypeId, PrimValue, ByteLen, ValueLen, Index, WireTypeIndex string }
})

func (DumpKind) VDLWrite

func (x DumpKind) VDLWrite(enc vdl.Encoder) error

type DumpStatus

type DumpStatus struct {
	MsgId      int64
	MsgLen     int
	MsgN       int
	Buf        []byte
	Debug      string
	RefTypes   []*vdl.Type
	RefAnyLens []uint64
	Value      *vdl.Value
	Err        error
}

DumpStatus represents the state of the dumper. It is written to the DumpWriter at the end of decoding each value, and may also be triggered explicitly via Dumper.Status calls to get information for partial dumps.

func (DumpStatus) String

func (s DumpStatus) String() string

type DumpWriter

type DumpWriter interface {
	// WriteAtom is called by the Dumper for each atom it decodes.
	WriteAtom(atom DumpAtom)
	// WriteStatus is called by the Dumper to indicate the status of the dumper.
	WriteStatus(status DumpStatus)
}

DumpWriter is the interface that describes how to write out dumps produced by the Dumper. Implement this interface to customize dump output behavior.

func NewDumpWriter

func NewDumpWriter(w io.Writer) DumpWriter

NewDumpWriter returns a DumpWriter that outputs dumps to w, writing each atom and status on its own line, in their default string format.

type Dumper

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

Dumper produces dumps of vom data. It implements the io.WriteCloser interface; Data is fed to the dumper via Write, and Close must be called at the end of usage to release resources.

Dumps of vom data consist of a single stream of DumpAtom and DumpStatus. Each atom describes a single piece of the vom encoding; the vom encoding is composed of a stream of atoms. The status describes the state of the dumper at that point in the stream.

func NewDumper

func NewDumper(w DumpWriter) *Dumper

NewDumper returns a new Dumper, which writes dumps of vom data to w.

Close must be called on the returned Dumper to release resources.

func (*Dumper) Close

func (d *Dumper) Close() error

Close flushes buffered data and releases resources. Close must be called exactly once, when the dumper is no longer needed.

func (*Dumper) Flush

func (d *Dumper) Flush() error

Flush flushes buffered data, and causes the dumper to restart decoding at the start of a new message. This is useful if the previous data in the stream was corrupt, and subsequent data will be for new vom messages. Previously buffered type information remains intact.

func (*Dumper) Status

func (d *Dumper) Status()

Status triggers an explicit dump of the current status of the dumper to the DumpWriter. Status is normally generated at the end of each each decoded message; call Status to get extra information for partial dumps and errors.

func (*Dumper) Write

func (d *Dumper) Write(data []byte) (int, error)

Write implements the io.Writer interface method. This is the mechanism by which data is fed into the dumper.

type Encoder

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

Encoder manages the transmission and marshaling of typed values to the other side of a connection.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new Encoder that writes to the given writer in the VOM binary format. The binary format is compact and fast.

func NewEncoderWithTypeEncoder

func NewEncoderWithTypeEncoder(w io.Writer, typeEnc *TypeEncoder) *Encoder

NewEncoderWithTypeEncoder returns a new Encoder that writes to the given writer, where types are encoded separately through the typeEnc.

func NewVersionedEncoder

func NewVersionedEncoder(version Version, w io.Writer) *Encoder

NewVersionedEncoder returns a new Encoder that writes to the given writer with the specified version.

func NewVersionedEncoderWithTypeEncoder

func NewVersionedEncoderWithTypeEncoder(version Version, w io.Writer, typeEnc *TypeEncoder) *Encoder

NewVersionedEncoderWithTypeEncoder returns a new Encoder that writes to the given writer with the specified version, where types are encoded separately through the typeEnc.

func (*Encoder) Encode

func (e *Encoder) Encode(v interface{}) error

Encode transmits the value v. Values of type T are encodable as long as the T is a valid vdl type.

func (*Encoder) Encoder

func (e *Encoder) Encoder() vdl.Encoder

Encoder returns e as a vdl.Encoder.

type Primitive

type Primitive interface {
	// Index returns the field index.
	Index() int
	// Interface returns the field value as an interface.
	Interface() interface{}
	// Name returns the field name.
	Name() string
	// VDLReflect describes the Primitive union type.
	VDLReflect(__PrimitiveReflect)
	VDLIsZero() bool
	VDLWrite(vdl.Encoder) error
}

Primitive represents any single field of the Primitive union type.

Primitive represents one of the primitive vom values. All vom values are composed of combinations of these primitives.

type PrimitivePBool

type PrimitivePBool struct{ Value bool }

PrimitivePBool represents field PBool of the Primitive union type.

func (PrimitivePBool) Index

func (x PrimitivePBool) Index() int

func (PrimitivePBool) Interface

func (x PrimitivePBool) Interface() interface{}

func (PrimitivePBool) Name

func (x PrimitivePBool) Name() string

func (PrimitivePBool) VDLIsZero

func (x PrimitivePBool) VDLIsZero() bool

func (PrimitivePBool) VDLReflect

func (x PrimitivePBool) VDLReflect(__PrimitiveReflect)

func (PrimitivePBool) VDLWrite

func (x PrimitivePBool) VDLWrite(enc vdl.Encoder) error

type PrimitivePByte

type PrimitivePByte struct{ Value byte }

PrimitivePByte represents field PByte of the Primitive union type.

func (PrimitivePByte) Index

func (x PrimitivePByte) Index() int

func (PrimitivePByte) Interface

func (x PrimitivePByte) Interface() interface{}

func (PrimitivePByte) Name

func (x PrimitivePByte) Name() string

func (PrimitivePByte) VDLIsZero

func (x PrimitivePByte) VDLIsZero() bool

func (PrimitivePByte) VDLReflect

func (x PrimitivePByte) VDLReflect(__PrimitiveReflect)

func (PrimitivePByte) VDLWrite

func (x PrimitivePByte) VDLWrite(enc vdl.Encoder) error

type PrimitivePControl

type PrimitivePControl struct{ Value ControlKind }

PrimitivePControl represents field PControl of the Primitive union type.

func (PrimitivePControl) Index

func (x PrimitivePControl) Index() int

func (PrimitivePControl) Interface

func (x PrimitivePControl) Interface() interface{}

func (PrimitivePControl) Name

func (x PrimitivePControl) Name() string

func (PrimitivePControl) VDLIsZero

func (x PrimitivePControl) VDLIsZero() bool

func (PrimitivePControl) VDLReflect

func (x PrimitivePControl) VDLReflect(__PrimitiveReflect)

func (PrimitivePControl) VDLWrite

func (x PrimitivePControl) VDLWrite(enc vdl.Encoder) error

type PrimitivePFloat

type PrimitivePFloat struct{ Value float64 }

PrimitivePFloat represents field PFloat of the Primitive union type.

func (PrimitivePFloat) Index

func (x PrimitivePFloat) Index() int

func (PrimitivePFloat) Interface

func (x PrimitivePFloat) Interface() interface{}

func (PrimitivePFloat) Name

func (x PrimitivePFloat) Name() string

func (PrimitivePFloat) VDLIsZero

func (x PrimitivePFloat) VDLIsZero() bool

func (PrimitivePFloat) VDLReflect

func (x PrimitivePFloat) VDLReflect(__PrimitiveReflect)

func (PrimitivePFloat) VDLWrite

func (x PrimitivePFloat) VDLWrite(enc vdl.Encoder) error

type PrimitivePInt

type PrimitivePInt struct{ Value int64 }

PrimitivePInt represents field PInt of the Primitive union type.

func (PrimitivePInt) Index

func (x PrimitivePInt) Index() int

func (PrimitivePInt) Interface

func (x PrimitivePInt) Interface() interface{}

func (PrimitivePInt) Name

func (x PrimitivePInt) Name() string

func (PrimitivePInt) VDLIsZero

func (x PrimitivePInt) VDLIsZero() bool

func (PrimitivePInt) VDLReflect

func (x PrimitivePInt) VDLReflect(__PrimitiveReflect)

func (PrimitivePInt) VDLWrite

func (x PrimitivePInt) VDLWrite(enc vdl.Encoder) error

type PrimitivePString

type PrimitivePString struct{ Value string }

PrimitivePString represents field PString of the Primitive union type.

func (PrimitivePString) Index

func (x PrimitivePString) Index() int

func (PrimitivePString) Interface

func (x PrimitivePString) Interface() interface{}

func (PrimitivePString) Name

func (x PrimitivePString) Name() string

func (PrimitivePString) VDLIsZero

func (x PrimitivePString) VDLIsZero() bool

func (PrimitivePString) VDLReflect

func (x PrimitivePString) VDLReflect(__PrimitiveReflect)

func (PrimitivePString) VDLWrite

func (x PrimitivePString) VDLWrite(enc vdl.Encoder) error

type PrimitivePUint

type PrimitivePUint struct{ Value uint64 }

PrimitivePUint represents field PUint of the Primitive union type.

func (PrimitivePUint) Index

func (x PrimitivePUint) Index() int

func (PrimitivePUint) Interface

func (x PrimitivePUint) Interface() interface{}

func (PrimitivePUint) Name

func (x PrimitivePUint) Name() string

func (PrimitivePUint) VDLIsZero

func (x PrimitivePUint) VDLIsZero() bool

func (PrimitivePUint) VDLReflect

func (x PrimitivePUint) VDLReflect(__PrimitiveReflect)

func (PrimitivePUint) VDLWrite

func (x PrimitivePUint) VDLWrite(enc vdl.Encoder) error

type RawBytes

type RawBytes struct {
	Version    Version
	Type       *vdl.Type
	RefTypes   []*vdl.Type
	AnyLengths []int
	Data       []byte
}

func RawBytesFromValue

func RawBytesFromValue(value interface{}) (*RawBytes, error)

func RawBytesOf

func RawBytesOf(value interface{}) *RawBytes

func (*RawBytes) Decoder

func (rb *RawBytes) Decoder() vdl.Decoder

func (*RawBytes) IsNil

func (rb *RawBytes) IsNil() bool

func (*RawBytes) String

func (rb *RawBytes) String() string

String outputs a string representation of RawBytes of the form RawBytes{Version81, int8, RefTypes{bool, string}, AnyLengths{4}, fa0e9dcc}

func (*RawBytes) ToValue

func (rb *RawBytes) ToValue(value interface{}) error

func (*RawBytes) VDLEqual

func (rb *RawBytes) VDLEqual(x interface{}) bool

TODO(toddw) This is slow - we should fix this.

func (*RawBytes) VDLIsZero

func (rb *RawBytes) VDLIsZero() bool

func (*RawBytes) VDLRead

func (rb *RawBytes) VDLRead(dec vdl.Decoder) error

func (RawBytes) VDLReflect

func (RawBytes) VDLReflect(struct {
	Type interface{} // ensure vdl.TypeOf(RawBytes{}) returns vdl.AnyType
})

func (*RawBytes) VDLWrite

func (rb *RawBytes) VDLWrite(enc vdl.Encoder) error

type TypeDecoder

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

TypeDecoder manages the receipt and unmarshalling of types from the other side of a connection. Start must be called to start decoding types, and Stop must be called to reclaim resources.

func NewTypeDecoder

func NewTypeDecoder(r io.Reader) *TypeDecoder

NewTypeDecoder returns a new TypeDecoder that reads from the given reader. The TypeDecoder understands all wire type formats generated by the TypeEncoder.

func (*TypeDecoder) Start

func (d *TypeDecoder) Start()

Start must be called to start decoding types.

func (*TypeDecoder) Stop

func (d *TypeDecoder) Stop()

Stop must be called after Start, to stop decoding types and reclaim resources. Once Stop is called, subsequent Decode calls on Decoders initialized with d will return errors.

type TypeEncoder

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

TypeEncoder manages the transmission and marshaling of types to the other side of a connection.

func NewTypeEncoder

func NewTypeEncoder(w io.Writer) *TypeEncoder

NewTypeEncoder returns a new TypeEncoder that writes types to the given writer in the binary format.

func NewVersionedTypeEncoder

func NewVersionedTypeEncoder(version Version, w io.Writer) *TypeEncoder

NewTypeEncoderVersion returns a new TypeEncoder that writes types to the given writer in the specified VOM version.

type TypeId

type TypeId uint64

TypeId uniquely identifies a type definition within a vom stream.

func (TypeId) VDLIsZero

func (x TypeId) VDLIsZero() bool

func (*TypeId) VDLRead

func (x *TypeId) VDLRead(dec vdl.Decoder) error

func (TypeId) VDLReflect

func (TypeId) VDLReflect(struct {
	Name string `vdl:"v.io/v23/vom.TypeId"`
})

func (TypeId) VDLWrite

func (x TypeId) VDLWrite(enc vdl.Encoder) error

type Version

type Version byte

Version is the vom version.

func (Version) String

func (v Version) String() string

func (Version) VDLIsZero

func (x Version) VDLIsZero() bool

func (*Version) VDLRead

func (x *Version) VDLRead(dec vdl.Decoder) error

func (Version) VDLReflect

func (Version) VDLReflect(struct {
	Name string `vdl:"v.io/v23/vom.Version"`
})

func (Version) VDLWrite

func (x Version) VDLWrite(enc vdl.Encoder) error

Directories

Path Synopsis
gen
Package vomtest provides protocol conformance tests for the Vanadium Object Marshaller (VOM).
Package vomtest provides protocol conformance tests for the Vanadium Object Marshaller (VOM).
internal/vomforever
Command vomforever is a tool that searches for bugs in vom.
Command vomforever is a tool that searches for bugs in vom.
internal/vomtestgen
Command vomtestgen generates test cases for the vomtest package.
Command vomtestgen generates test cases for the vomtest package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL