versioned

Documentation

Index

• Constants
• Variables
• func DetectMapElement(key string) (isMapElement bool, mapName, elementName string)
• func GetElementName(key string) (mapName, elementName string)
• func GetMapName(mapKey string) string
• func IsMapElement(key string) (IsMapElement bool, mapName, elementName string)
• func IsValidKey(str string) error
• func MakeElementKey(mapName, elementName string) string
• func MakeMapKey(mapName string) string
• func MakePartnerPrefix(id *id.ID) string
• type ElementEdit
• type KV
  • func NewKV(data ekv.KeyValue) KV
• type KeyChangedByRemoteCallback
• type KeyOperation
  • func (ko KeyOperation) String() string
• type KeyType
  • func DetectMap(key string) (result KeyType, mapName, elementName string)
• type MapChangedByRemoteCallback
• type Object
  • func (v *Object) Marshal() []byte
  • func (v *Object) Unmarshal(data []byte) error
• type TransactionOperation
• type Upgrade
• type UpgradeTable

Constants

const (
	// map handler constants
	MapDesignator     = "🗺️"
	MapKeysListSuffix = "_🗺️MapKeys"
	//MapKeysListFmt     = "%s" + MapKeysListSuffix
	MapElementKeySuffix = "_🗺️MapElement"
	//MapElementKeyFmt   = "%s:%s_%d" + MapElementKeySuffix
	UsedMapDesignatorError = "cannot use \"" + MapDesignator + "\" in a key " +
		"name, it is reserved"
)

const PrefixSeparator = `\`

PrefixSeparator is the separator added when prefixing a KV (see [KV.Prefix]). No prefix may contain this character. This value has been defined as `backwards-slash` (\) rather than the typical `forward-slash` (/) for explicit purposes. There are many valid reasons for the consumer to want to define their prefixes with a `/`, such as using the base64 encoding of some value (see base64.StdEncoding].

Variables

var (
	EmptyPrefixErr               = errors.New("empty prefix")
	PrefixContainingSeparatorErr = errors.New("cannot accept prefix with the default separator")
	DuplicatePrefixErr           = errors.New("prefix has already been added, cannot overwrite")
	UnimplementedErr             = errors.New("not implemented")
)

Functions

func DetectMapElement

func DetectMapElement(key string) (isMapElement bool, mapName, elementName string)

DetectMapElement Detects if the key is a map element

func GetElementName

func GetElementName(key string) (mapName, elementName string)

GetElementName returns the element name, will garble a non mapKey

func GetMapName

func GetMapName(mapKey string) string

GetMapName returns the map name, will garble a non mapKey use DetectMap

func IsMapElement

func IsMapElement(key string) (IsMapElement bool, mapName, elementName string)

IsMapElement detects if the key is a mapElement

func IsValidKey

func IsValidKey(str string) error

IsValidKey checks if a map name or element name is allowable by now allowing the designator character '🗺️'

func MakeElementKey

func MakeElementKey(mapName, elementName string) string

MakeElementKey creates the storage key for an element in a map

func MakeMapKey

func MakeMapKey(mapName string) string

MakeMapKey creates the storage key for a map

func MakePartnerPrefix

func MakePartnerPrefix(id *id.ID) string

MakePartnerPrefix creates a string prefix to denote who a conversation or relationship is with

Types

type ElementEdit

type ElementEdit struct {
	OldElement *Object
	NewElement *Object
	Operation  KeyOperation
}

type KV

type KV interface {
	// Get returns the object stored at the specified version.
	Get(key string, version uint64) (*Object, error)

	// GetAndUpgrade gets and upgrades data stored in the key/value store.
	// Make sure to inspect the version returned in the versioned object.
	GetAndUpgrade(key string, ut UpgradeTable) (*Object, error)

	// Delete removes a given key from the data store.
	Delete(key string, version uint64) error

	// Set upserts new data into the storage
	Set(key string, object *Object) error

	// StoreMapElement stores a versioned map element into the KV. This relies
	// on the underlying remote [KV.StoreMapElement] function to lock and control
	// updates, but it uses [versioned.Object] values.
	// The version of the value must match the version of the map.
	// All Map storage functions update the remote.
	StoreMapElement(mapName, elementName string, value *Object,
		mapVersion uint64) error

	// StoreMap saves a versioned map element into the KV. This relies
	// on the underlying remote [KV.StoreMap] function to lock and control
	// updates, but it uses [versioned.Object] values.
	// the version of values must match the version of the map
	// All Map storage functions update the remote.
	StoreMap(mapName string, values map[string]*Object, mapVersion uint64) error

	// GetMap loads a versioned map from the KV. This relies
	// on the underlying remote [KV.GetMap] function to lock and control
	// updates, but it uses [versioned.Object] values.
	GetMap(mapName string, mapVersion uint64) (map[string]*Object, error)

	// GetMapElement loads a versioned map element from the KV. This relies
	// on the underlying remote [KV.GetMapElement] function to lock and control
	// updates, but it uses [versioned.Object] values.
	GetMapElement(mapName, elementName string, mapVersion uint64) (
		*Object, error)

	// DeleteMapElement removes a map element from the list. It
	// returns the element that was deleted and any errors if they occur.
	DeleteMapElement(mapName, elementName string, mapVersion uint64) (
		*Object, error)

	// ListenOnRemoteKey allows the caller to receive updates when
	// a key is updated by synching with another client.
	// Only one callback can be written per key.
	// On call, a state update will be created on the callback containing
	// the current state of the key as a creation event. This call will occur
	// in the go routine that ListenOnRemoteKey is called from, blocking its
	// return until the callback returns.
	// If local Events is true, the callback will also trigger when
	// setting this key locally
	ListenOnRemoteKey(key string, version uint64,
		callback KeyChangedByRemoteCallback, localEvents bool) error

	// ListenOnRemoteMap allows the caller to receive updates when
	// the map or map elements are updated
	// Only one callback can be written per map.
	// On call, a state update will be created on the callback containing
	// the entire state of the map as a creation event. This call will occur
	// in the go routine that ListenOnRemoteMap is called from, blocking its
	// return until the callback returns.
	// If local Events is true, the callback will also trigger when
	// modifying this map locally
	ListenOnRemoteMap(mapName string, version uint64,
		callback MapChangedByRemoteCallback, localEvents bool) error

	// GetPrefix returns the full Prefix of the KV
	GetPrefix() string

	// HasPrefix returns whether this prefix exists in the KV
	HasPrefix(prefix string) bool

	// Prefix returns a new KV with the new prefix appending
	Prefix(prefix string) (KV, error)

	// Root returns the KV with no prefixes
	Root() KV

	// IsMemStore returns true if the underlying KV is memory based
	IsMemStore() bool

	// GetFullKey returns the key with all prefixes appended
	GetFullKey(key string, version uint64) string

	// Exists returns if the error indicates a KV error showing
	// the key exists.
	Exists(err error) bool

	// StartProcesses starts any applicable networking processes
	StartProcesses() (stoppable.Stoppable, error)
}

KV is a key value store interface that supports versioned and upgradable entries.

func NewKV

func NewKV(data ekv.KeyValue) KV

Create a versioned key/value store backed by something implementing KeyValue

type KeyChangedByRemoteCallback

type KeyChangedByRemoteCallback func(old, new *Object, op KeyOperation)

KeyChangedByRemoteCallback is the callback used to report local updates caused by a remote client editing their EKV

type KeyOperation

type KeyOperation uint8

const (
	Created KeyOperation = iota
	Updated
	Deleted
	Loaded
)

func (KeyOperation) String

func (ko KeyOperation) String() string

type KeyType

type KeyType uint8

const (
	KeyTypeNormal KeyType = iota
	KeyTypeMapFile
	KeyTypeMapElement
)

func DetectMap

func DetectMap(key string) (result KeyType, mapName, elementName string)

DetectMap Detects either a map or an element and its map

type MapChangedByRemoteCallback

type MapChangedByRemoteCallback func(edits map[string]ElementEdit)

MapChangedByRemoteCallback is the callback used to report local updates caused by a remote client editing their EKV

type Object

type Object struct {
	// Used to determine version Upgrade, if any
	Version uint64

	// Set when this object is written
	Timestamp time.Time

	// Serialized version of original object
	Data []byte
}

Object is used by VersionedKeyValue to keep track of versioning and time of storage

func (*Object) Marshal

func (v *Object) Marshal() []byte

Marshal serializes a Object into a byte slice. It's used to make these storable in a KeyValue. Object exports all fields and they have simple types, so json.Marshal works fine.

func (*Object) Unmarshal

func (v *Object) Unmarshal(data []byte) error

Unmarshal deserializes a Object from a byte slice. It's used to make these storable in a KeyValue. Object exports all fields and they have simple types, so json.Unmarshal works fine.

type TransactionOperation

type TransactionOperation func(old *Object, existed bool) (data *Object,
	err error)

type Upgrade

type Upgrade func(oldObject *Object) (*Object,
	error)

Upgrade functions must be of this type

type UpgradeTable

type UpgradeTable struct {
	CurrentVersion uint64
	Table          []Upgrade
}

UpgradeTable contains a table of upgrade functions for a versioned KV.