kbfscodec

README

kbfscodec

The serialization logic for KBFS. The package is named kbfscodec rather than codec for two reasons:

1. We already have a keybase/go-codec/codec that is commonly used.
2. A lot of variables are named codec already.

All errors returned by this package are wrapped with pkg/errors, and so need errors.Cause() to unwrap them.

Documentation

Index

• Constants
• func DeserializeFromFile(c Codec, path string, objPtr interface{}) error
• func Equal(c Codec, x, y interface{}) (bool, error)
• func SerializeToFile(c Codec, obj interface{}, path string) error
• func SerializeToFileIfNotExist(c Codec, obj interface{}, path string) error
• func TestStructUnknownFields(t require.TestingT, cFuture, cCurrent, cCurrentKnownOnly Codec, ...)
• func TestStructUnknownFieldsMsgpack(t require.TestingT, sFuture FutureStruct)
• func Update(c Codec, dstPtr interface{}, src interface{}) error
• type Codec
• type CodecMsgpack
  • func NewMsgpack() *CodecMsgpack
  • func NewMsgpackNoUnknownFields() *CodecMsgpack
  • func (c *CodecMsgpack) Decode(buf []byte, obj interface{}) error
  • func (c *CodecMsgpack) Encode(obj interface{}) (buf []byte, err error)
  • func (c *CodecMsgpack) RegisterIfaceSliceType(rt reflect.Type, code ExtCode, typer func(interface{}) reflect.Value)
  • func (c *CodecMsgpack) RegisterType(rt reflect.Type, code ExtCode)
• type CurrentStruct
• type ExtCode
• type Extra
  • func MakeExtraOrBust(prefix string, t require.TestingT) Extra
• type FutureStruct
• type MockCodec
  • func NewMockCodec(ctrl *gomock.Controller) *MockCodec
  • func (_m *MockCodec) Decode(buf []byte, obj interface{}) error
  • func (_m *MockCodec) EXPECT() *_MockCodecRecorder
  • func (_m *MockCodec) Encode(obj interface{}) ([]byte, error)
  • func (_m *MockCodec) RegisterIfaceSliceType(rt reflect.Type, code ExtCode, typer func(interface{}) reflect.Value)
  • func (_m *MockCodec) RegisterType(rt reflect.Type, code ExtCode)

Constants

const (
	ExtCodeOpsRangeStart  = 1
	ExtCodeListRangeStart = 101
)

these track the start of a range of unique ExtCodes for various types of extensions.

Functions

func DeserializeFromFile

func DeserializeFromFile(c Codec, path string, objPtr interface{}) error

DeserializeFromFile deserializes the given file into the object pointed to by objPtr. It may return an error for which ioutil.IsNotExist() returns true.

func Equal

func Equal(c Codec, x, y interface{}) (bool, error)

Equal returns whether or not the given objects serialize to the same byte string. x or y (or both) can be nil.

func SerializeToFile

func SerializeToFile(c Codec, obj interface{}, path string) error

SerializeToFile serializes the given object and writes it to the given file, making its parent directory first if necessary.

func SerializeToFileIfNotExist

func SerializeToFileIfNotExist(c Codec, obj interface{}, path string) error

SerializeToFileIfNotExist is like SerializeToFile, but does nothing if the file already exists.

func TestStructUnknownFields

func TestStructUnknownFields(t require.TestingT,
	cFuture, cCurrent, cCurrentKnownOnly Codec,
	sFuture FutureStruct)

TestStructUnknownFields tests that hypothetical future versions of a struct can be deserialized by current clients and preserve unknown fields.

func TestStructUnknownFieldsMsgpack

func TestStructUnknownFieldsMsgpack(t require.TestingT, sFuture FutureStruct)

TestStructUnknownFieldsMsgpack calls TestStructUnknownFields with codecs with the msgpack codec.

func Update

func Update(c Codec, dstPtr interface{}, src interface{}) error

Update encodes src into a byte string, and then decode it into the object pointed to by dstPtr.

Types

type Codec

type Codec interface {
	// Decode unmarshals the given buffer into the given object, if possible.
	Decode(buf []byte, obj interface{}) error
	// Encode marshals the given object into a returned buffer.
	Encode(obj interface{}) ([]byte, error)
	// RegisterType should be called for all types that are stored
	// under ambiguous types (like interface{} or nil interface) in a
	// struct that will be encoded/decoded by the codec.  Each must
	// have a unique ExtCode.  Types that include other extension
	// types are not supported.
	RegisterType(rt reflect.Type, code ExtCode)
	// RegisterIfaceSliceType should be called for all encoded slices
	// that contain ambiguous interface types.  Each must have a
	// unique ExtCode.  Slice element types that include other
	// extension types are not supported.
	//
	// If non-nil, typer is used to do a type assertion during
	// decoding, to convert the encoded value into the value expected
	// by the rest of the code.  This is needed, for example, when the
	// codec cannot decode interface types to their desired pointer
	// form.
	RegisterIfaceSliceType(rt reflect.Type, code ExtCode,
		typer func(interface{}) reflect.Value)
}

Codec encodes and decodes arbitrary data

type CodecMsgpack

type CodecMsgpack struct {
	ExtCodec *CodecMsgpack
	// contains filtered or unexported fields
}

CodecMsgpack implements the Codec interface using msgpack marshaling and unmarshaling.

func NewMsgpack

func NewMsgpack() *CodecMsgpack

NewMsgpack constructs a new CodecMsgpack.

func NewMsgpackNoUnknownFields

func NewMsgpackNoUnknownFields() *CodecMsgpack

NewMsgpackNoUnknownFields constructs a new CodecMsgpack that doesn't handle unknown fields.

func (*CodecMsgpack) Decode

func (c *CodecMsgpack) Decode(buf []byte, obj interface{}) error

Decode implements the Codec interface for CodecMsgpack

func (*CodecMsgpack) Encode

func (c *CodecMsgpack) Encode(obj interface{}) (buf []byte, err error)

Encode implements the Codec interface for CodecMsgpack

func (*CodecMsgpack) RegisterIfaceSliceType

func (c *CodecMsgpack) RegisterIfaceSliceType(
	rt reflect.Type, code ExtCode, typer func(interface{}) reflect.Value)

RegisterIfaceSliceType implements the Codec interface for CodecMsgpack

func (*CodecMsgpack) RegisterType

func (c *CodecMsgpack) RegisterType(rt reflect.Type, code ExtCode)

RegisterType implements the Codec interface for CodecMsgpack

type CurrentStruct

type CurrentStruct interface{}

CurrentStruct is an interface for the current version of a struct type.

type ExtCode

type ExtCode uint64

ExtCode is used to register codec extensions

type Extra

type Extra struct {
	Extra1 fakeEncryptedData
	Extra2 []byte
	Extra3 string
}

Extra contains some fake extra fields that can be embedded into a struct to test handling of unknown fields.

func MakeExtraOrBust

func MakeExtraOrBust(prefix string, t require.TestingT) Extra

MakeExtraOrBust returns a filled-in Extra structure based on the given prefix.

type FutureStruct

type FutureStruct interface {
	// toCurrentStruct returns the fields of the current object
	// copied to the current struct, with all unknown fields
	// discarded.
	ToCurrentStruct() CurrentStruct
}

FutureStruct is an interface for a hypothetical future version of a struct type.

type MockCodec

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

Mock of Codec interface

func NewMockCodec

func NewMockCodec(ctrl *gomock.Controller) *MockCodec

func (*MockCodec) Decode

func (_m *MockCodec) Decode(buf []byte, obj interface{}) error

func (*MockCodec) EXPECT

func (_m *MockCodec) EXPECT() *_MockCodecRecorder

func (*MockCodec) Encode

func (_m *MockCodec) Encode(obj interface{}) ([]byte, error)

func (*MockCodec) RegisterIfaceSliceType

func (_m *MockCodec) RegisterIfaceSliceType(rt reflect.Type, code ExtCode, typer func(interface{}) reflect.Value)

func (*MockCodec) RegisterType

func (_m *MockCodec) RegisterType(rt reflect.Type, code ExtCode)