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
- Variables
- func Decode(data []byte, v interface{}) error
- func Dump(data []byte) (string, error)
- func Encode(v interface{}) ([]byte, error)
- func VDLReadPrimitive(dec vdl.Decoder, x *Primitive) error
- func VersionedEncode(version Version, v interface{}) ([]byte, error)
- type ControlKind
- type Decoder
- type DumpAtom
- type DumpKind
- type DumpStatus
- type DumpWriter
- type Dumper
- type Encoder
- type ExtractEncodedBytes
- type MergeEncodedBytes
- type Primitive
- type PrimitivePBool
- type PrimitivePByte
- type PrimitivePControl
- type PrimitivePFloat
- type PrimitivePInt
- type PrimitivePString
- type PrimitivePUint
- type RawBytes
- func (rb *RawBytes) Decoder() vdl.Decoder
- func (rb *RawBytes) IsNil() bool
- func (rb *RawBytes) String() string
- func (rb *RawBytes) ToValue(value interface{}) error
- func (rb *RawBytes) VDLEqual(x interface{}) bool
- func (rb *RawBytes) VDLIsZero() bool
- func (rb *RawBytes) VDLRead(dec vdl.Decoder) error
- func (RawBytes) VDLReflect(struct{ ... })
- func (rb *RawBytes) VDLWrite(enc vdl.Encoder) error
- type TypeDecoder
- type TypeEncoder
- type TypeId
- type Version
Examples ¶
Constants ¶
const DefaultVersion = Version(129)
const Version80 = Version(128)
const Version81 = Version(129)
const WireCtrlEnd = byte(225) // End of struct or union
const WireCtrlNil = byte(224) // Nil in optional or any
const WireCtrlTypeIncomplete = byte(226) // Marks that the type message is incomplete until future messages are received
const WireIdAny = TypeId(15)
const WireIdBool = TypeId(1)
Primitive types.
const WireIdByte = TypeId(2)
const WireIdByteList = TypeId(39)
Other commonly used composites.
const WireIdFirstUserType = TypeId(41)
The first user-defined TypeId is 41.
const WireIdFloat32 = TypeId(10)
const WireIdFloat64 = TypeId(11)
const WireIdInt16 = TypeId(7)
const WireIdInt32 = TypeId(8)
const WireIdInt64 = TypeId(9)
const WireIdInt8 = TypeId(16)
const WireIdString = TypeId(3)
const WireIdStringList = TypeId(40)
const WireIdTypeObject = TypeId(14)
Wire ids 12 and 13 were previously used for complex64 and complex 128.
const WireIdUint16 = TypeId(4)
const WireIdUint32 = TypeId(5)
const WireIdUint64 = TypeId(6)
Variables ¶
var ControlKindAll = [...]ControlKind{ControlKindNil, ControlKindEnd, ControlKindIncompleteType}
ControlKindAll holds all labels for ControlKind.
var DumpKindAll = [...]DumpKind{DumpKindVersion, DumpKindControl, DumpKindMsgId, DumpKindTypeMsg, DumpKindValueMsg, DumpKindMsgLen, DumpKindAnyMsgLen, DumpKindAnyLensLen, DumpKindTypeIdsLen, DumpKindTypeId, DumpKindPrimValue, DumpKindByteLen, DumpKindValueLen, DumpKindIndex, DumpKindWireTypeIndex}
DumpKindAll holds all labels for DumpKind.
Functions ¶
func Decode ¶
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 Encode ¶
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 VersionedEncode ¶
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) String ¶
func (x ControlKind) String() string
String returns the string label of x.
func (ControlKind) VDLIsZero ¶
func (x ControlKind) VDLIsZero() bool
func (ControlKind) VDLReflect ¶
func (ControlKind) VDLReflect(struct { Name string `vdl:"v.io/v23/vom.ControlKind"` Enum struct{ Nil, End, IncompleteType string } })
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 ¶
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.
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) VDLReflect ¶
type DumpKind ¶
type DumpKind int
DumpKind enumerates the different kinds of dump atoms.
func DumpKindFromString ¶
DumpKindFromString creates a DumpKind from a string label.
func (DumpKind) VDLReflect ¶
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 ¶
Close flushes buffered data and releases resources. Close must be called exactly once, when the dumper is no longer needed.
func (*Dumper) Flush ¶
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.
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 ¶
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 ¶
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.
type ExtractEncodedBytes ¶ added in v0.1.1
ExtractEncodedBytes represents an already encoded stream that has been extracted from a separate, independent vom stream. NumToDecode controls how many values are to be read from the existing stream, or 0 to read all values.
Example ¶
package main
import (
"bytes"
"fmt"
"v.io/v23/vom"
)
type m struct {
M string
}
func main() {
abuf := &bytes.Buffer{}
encA := vom.NewEncoder(abuf)
encA.Encode("first")
encA.Encode(&m{"stream-a"})
encA.Encode(int64(33))
encA.Encode("last")
var first, last string
var vm m
var vi int
dec := vom.NewDecoder(abuf)
dec.Decode(&first)
var extractor vom.ExtractEncodedBytes
dec.Decode(&extractor)
edec := vom.NewDecoder(bytes.NewBuffer(extractor.Data))
edec.Decode(&vm)
edec.Decode(&vi)
edec.Decode(&last)
fmt.Println(extractor.Decoded)
fmt.Println(first)
fmt.Println(vm.M)
fmt.Println(vi)
fmt.Println(last)
}
Output: 3 first stream-a 33 last
type MergeEncodedBytes ¶ added in v0.1.1
type MergeEncodedBytes struct {
Data []byte
}
MergeEncodedBytes represents an already encoded vom stream that is intended for use when merging the output of multiple, independent, vom encoders.
Example ¶
package main
import (
"bytes"
"fmt"
"v.io/v23/vom"
)
type m struct {
M string
}
func main() {
abuf := &bytes.Buffer{}
encA := vom.NewEncoder(abuf)
encA.Encode(&m{"stream-a"}) //nolint:errcheck
bbuf := &bytes.Buffer{}
encB := vom.NewEncoder(bbuf)
encB.Encode(m{"stream-b"})
encB.Encode(vom.MergeEncodedBytes{Data: abuf.Bytes()})
dec := vom.NewDecoder(bbuf)
va, vb := m{}, m{}
dec.Decode(&vb)
dec.Decode(&va)
fmt.Println(va.M)
fmt.Println(vb.M)
}
Output: stream-a stream-b
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(vdlPrimitiveReflect)
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(vdlPrimitiveReflect)
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(vdlPrimitiveReflect)
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(vdlPrimitiveReflect)
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(vdlPrimitiveReflect)
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(vdlPrimitiveReflect)
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(vdlPrimitiveReflect)
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(vdlPrimitiveReflect)
type RawBytes ¶
type RawBytes struct {
Version Version
Type *vdl.Type
RefTypes []*vdl.Type
AnyLengths []int
Data []byte
}
func RawBytesFromValue ¶
func RawBytesOf ¶
func RawBytesOf(value interface{}) *RawBytes
func (*RawBytes) String ¶
String outputs a string representation of RawBytes of the form RawBytes{Version81, int8, RefTypes{bool, string}, AnyLengths{4}, fa0e9dcc}
func (RawBytes) VDLReflect ¶
func (RawBytes) VDLReflect(struct { Type interface{} // ensure vdl.TypeOf(RawBytes{}) returns vdl.AnyType })
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) VDLReflect ¶
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
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. |