README
¶
Serialise
Serialises basic types, pointers to types, and slices to a byte slice.
Allows the serialisation approach to be extended via the Approach interface.
Supports optional encryption of the byte slice using aes-gcm.
func main() {
data := []string{"Hello", "World!"}
// Serialise the data using the default version of MinData serialisation
b, name, _ := ToBytes(data, WithSerialisationApproach(NewMinDataApproach()))
// Retrieve the Approach used for serialisation, from the returned name
approach, _ := GetApproach(name)
// Deserialise
v, _ := FromBytes(b, approach)
}
Documentation
¶
Overview ¶
Example ¶
data := []string{"Hello", "World!"}
key := []byte("01234567890123456789012345678912")
// Serialise the data using the default version of MinData serialisation,
// encrypting the serialised byte slice
b, name, _ := ToBytes(data, WithSerialisationApproach(NewMinDataApproach()), WithAESGCMEncryption(key))
// Retrieve the Approach used for serialisation, from the returned name
approach, _ := GetApproach(name)
// Decrypt and deserialise
v, _ := FromBytes(b, approach, WithAESGCMEncryption(key))
fmt.Println(strings.Join(data, " ") == strings.Join(v.([]string), " "))
Output: true
Index ¶
- Variables
- func FromBytes(data []byte, approach Approach, opts ...func(*Options)) (v any, e error)
- func FromBytesI64(data []byte) (int64, error)
- func FromBytesMany(data []byte, approach Approach, opts ...func(*Options)) (v []any, e error)
- func RegisterApproach(a Approach)
- func SizeOfI64() int64
- func ToBytes(data any, opts ...func(*Options)) ([]byte, string, error)
- func ToBytesI64(v int64) ([]byte, error)
- func ToBytesMany(data []any, opts ...func(*Options)) ([]byte, string, error)
- func WithAESGCMEncryption(key []byte) func(opt *Options)
- func WithFlateThreshold(thresholdInBytes int) func(*Options)
- func WithSerialisationApproach(approach Approach) func(*Options)
- type Approach
- type MinDataVersion
- type Options
- type TypeID
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrFromBytesInvalidData = errors.New("invalid data provided. data must be created using ToBytes()")
ErrFromBytesInvalidData raised if FromBytes is provided with invalid byte slice
var ErrFromBytesManyInvalidData = errors.New("invalid data provided. data must be created using ToBytesMany()")
ErrFromBytesManyInvalidData raised if FromBytesMany is provided with invalid byte slice
var ErrInvalidDecryptionData = errors.New("data provided for decryption is too short")
ErrInvalidDecryptionData is raised if the data to be decrypted is too short for aes-gcm
var ErrInvalidSerialisationApproach = errors.New("invalid serialisation approach provided")
ErrInvalidSerialisationApproach raised if the serialisation approach is not valid
var ErrMinDataTypeNotDeserialisable = errors.New("type specified within the data is not deserialisable")
ErrMinDataTypeNotDeserialisable is raised if a variable type is not deserialisable by the MinData approach
var ErrMinDataTypeNotSerialisable = errors.New("type of argument is not serialisable")
ErrMinDataTypeNotSerialisable is raised if a variable type is not serialisable by the MinData approach
var ErrNoDataToDeserialise = errors.New("no data provided for deserialisation")
ErrNoDataToDeserialise raised if nil or empty byte slice is used in FromBytes
var ErrUnexpectedDeserialisationError = errors.New("unexpected deserialisation failure - possible corrupted data provided")
ErrUnexpectedDeserialisationError is raised if a panic is generated during deserialisation
var ErrUnexpectedSerialisationError = errors.New("unexpected error during serialisation")
ErrUnexpectedSerialisationError raised if an invalid serialisation approach is specified
var ErrUnknownApproach = errors.New("specified Approach name is not registered")
ErrUnknownApproach raised if the specified name is not found in the Approach registry
Functions ¶
func FromBytes ¶
FromBytes returns deserialises the byte slice to an instance using the specified approach.
func FromBytesI64 ¶
FromBytesI64 deserialises an int64 from material created by ToBytesI64
func FromBytesMany ¶
FromBytesMany returns deserialises the byte slice to an array of instances using the specified Approach.
func RegisterApproach ¶
func RegisterApproach(a Approach)
RegisterApproach allows all registered Approach to be retrievable by Name()
func ToBytesI64 ¶
ToBytesI64 ensures a standard treatment of int64 serialisation
func ToBytesMany ¶
ToBytesMany returns a byte slice of the provded data, individually packing all the items into a single byte array. Use FromBytesMany to deserialise. An error will be generated if any of the items in the provided data are not serialisable by the selected Approach.
func WithAESGCMEncryption ¶
WithAESGCMEncryption establishes the option to encrypt/decrypt data using aes-gcm with the specified key
func WithFlateThreshold ¶
WithFlateThreshold sets the threshold for compression using Flate. If value is less than 0, no compression will be used. If value is 0 (or unset), then defaultFlateThreshold (25) is used. For other values, Flate will be invoked when serialised data is beyond the threshold value. This allows users to balance between runtime performance and size of serialised data.
func WithSerialisationApproach ¶
WithSerialisationApproach sets the serialisation approach to be used when calling ToBytes()
Types ¶
type Approach ¶
type Approach interface {
// Name of the approach
Name() string
// Pack serialises the instance to a byte slice
Pack(data any) ([]byte, error)
// Unpack deserialises an instance from the byte slice
//Unpack(data []byte, opts ...func(opt *TypeRegistryOptions)) (any, error)
Unpack(data []byte) (any, error)
// IsSerialisable returns true if the type of the instance is serialisable
IsSerialisable(v any) bool
}
Approach implements the mechanism to be used for serialisation
func Default ¶
func Default() Approach
Default returns the current serialisation approach that will be used by Pack, Unpack etc., if not set explicitly using the WithSerialisationApproach() option.
func GetApproach ¶
GetApproach returns the Approach with the specified name
func NewMinDataApproach ¶
func NewMinDataApproach() Approach
NewMinDataApproach creates an instance of the current default version of the MinData serialisation
func NewMinDataApproachWithVersion ¶
func NewMinDataApproachWithVersion(version MinDataVersion) Approach
NewMinDataApproachWithVersion creates an instance of the specified version of MinData serialisation
type MinDataVersion ¶
type MinDataVersion int8
MinDataVersion describes a version of a MinData serialisation implementation All breaking changes to serialisation will trigger an increment, to ensure backwards compatibility to any consumers of existing versions.
const ( UnknownVersion MinDataVersion = iota V1 OutOfRange )
type Options ¶
type Options struct {
// Approach specifies which serialisation method is to be used
Approach Approach
// Encryptor will encrypt the provided data
Encryptor func(data []byte) ([]byte, error)
// Decryptor will decrypt the provided data
Decryptor func(data []byte) ([]byte, error)
// FlateThreshold determines the point at which Flate compression will be applied
// Setting to -1 indicates no compression to be used, whatever size
FlateThreshold int
}
Options adjust how serialisation is performed
type TypeID ¶
type TypeID int8
TypeID identifies the types that are supported by serialisation
const ( UnknownType TypeID = iota Int8Type Pint8Type Int8SliceType Int16Type Pint16Type Int16SliceType Int32Type Pint32Type Int32SliceType Int64Type Pint64Type Int64SliceType Uint8Type Puint8Type Uint16Type Puint16Type Uint16SliceType Uint32Type Puint32Type Uint32SliceType Uint64Type Puint64Type Uint64SliceType Float32Type Pfloat32Type Float32SliceType Float64Type Pfloat64Type Float64SliceType BoolType PboolType BoolSliceType DurationType PdurationType DurationSliceType StringType PstringType StringSliceType TimeType PtimeType ByteSliceType ByteSliceSliceType NilType )
Source Files