collective

package
v4.7.2 Latest Latest
Warning

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

 Go to latest Published: Jan 26, 2024 License: BSD-2-Clause, BSD-2-Clause Imports: 30 Imported by: 0

Documentation

Overview

Package collective covers logic regarding account synchronization.

Index

Constants

View Source 
const (

	// KeyUpdateCallback statuses.
	Disconnected = "Disconnected"
	Connected    = "Connected"
	Successful   = "UpdatedKey"
)

KV kv-related constants.

View Source 
const StandardRemoteSyncPrefix = "remoteSync"
View Source 
const TestingKVPath = "versionedKV_TestWorkDir"

params used by the testing KV

Variables

View Source 
var (
	ErrEmptyInstance                = errors.New("empty instance ID")
	ErrShortRead                    = errors.New("short read generating instance ID")
	ErrIncorrectSize                = errors.New("incorrect instance ID size")
	ErrInstanceIDAlreadyInitialized = errors.New("instanceID already " +
		"initialized, cannot do a second instanceID")
)
View Source 
var ErrMapElementNotFound = os.ErrNotExist
View Source 
var ErrMapInconsistent = errors.New("element is in the map file but not" +
	"in the ekv")
View Source 
var StandardPrefexs = []string{StandardRemoteSyncPrefix}

StandardPrefexs will be passed into tests for syncPrefixes

Functions

func CloneFromRemoteStorage 

func CloneFromRemoteStorage(remoteStoragePathPrefix string, deviceSecret []byte,
	remote RemoteStore, kv ekv.KeyValue,
	rng *fastRNG.StreamGenerator) (*versionedKV, error)

CloneFromRemoteStorage copies state from RemoteStore and instantiates a SynchronizedKV

func IsLocalInstanceID 

func IsLocalInstanceID(kv ekv.KeyValue, expected InstanceID) (bool, error)

func NewCountingReader 

func NewCountingReader() csprng.Source

func NewMockRemote 

func NewMockRemote() *mockRemote

func NewReaderSourceBuilder 

func NewReaderSourceBuilder(rng io.Reader) csprng.SourceConstructor

func SynchronizedKV 

func SynchronizedKV(remoteStoragePathPrefix string, deviceSecret []byte,
	remote RemoteStore, kv ekv.KeyValue, synchedPrefixes []string,
	rng *fastRNG.StreamGenerator) (*versionedKV, error)

SynchronizedKV loads or creates a synchronized remote KV that uses a remote RemoteStore to store defined synchronization prefixes to the network.

func TestingKV 

func TestingKV(t interface{}, kv ekv.KeyValue, syncPrefixes []string,
	remoteStore RemoteStore) versioned.KV

TestingKV returns a versioned ekv which can be used for testing. it does not do remote writes but maintains the proper interface

Types

type CountingReader 

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

CountingReader is a platform-independent deterministic RNG that adheres to io.Reader.

func (*CountingReader) Read 

func (c *CountingReader) Read(b []byte) (int, error)

Read just counts until 254 then starts over again

func (*CountingReader) SetSeed 

func (c *CountingReader) SetSeed(s []byte) error

type FileIO 

type FileIO interface {
	// Read reads from the provided file path and returns the data
	// at that path.  An error is returned if it failed to Read
	// the file.
	Read(path string) ([]byte, error)

	// Write writes to the file path the provided data. An error
	// is returned if it fails to Write to file.
	Write(path string, data []byte) error
}

FileIO is a simplified filesystem interface, providing Read and Write operations. Directories are implicitly created by the implementor of the interface, if necessary.

func NewKVFilesystem 

func NewKVFilesystem(kv ekv.KeyValue) FileIO

NewKVFilesystem initializes a KVFilesystem object and returns it. If the KVFilesystem exists inside the ekv, it loads the file listing from it. If an error occurs loading the files on start it can panic.

func NewKVFilesystemWithPrefix 

func NewKVFilesystemWithPrefix(prefix string, kv ekv.KeyValue) FileIO

NewKVFilesystemWithPrefix creats a KVFilesystem using a custom prefix.

type FileSystemStorage 

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

FileSystemStorage implements RemoteStore, and can be used as a local FileIO for the mutate log as well as for testing RemoteStorage users. This utilizes the os.File IO operations.

func NewFileSystemRemoteStorage 

func NewFileSystemRemoteStorage(baseDir string) *FileSystemStorage

NewFileSystemRemoteStorage is a constructor for FileSystemRemoteStorage.

Arguments:

  • baseDir - string. Represents the base directory for which all file operations will be performed. Must contain a file delimiter (i.e. `/`).

func (*FileSystemStorage) GetLastModified 

func (f *FileSystemStorage) GetLastModified(path string) (
	time.Time, error)

GetLastModified will return the last modified timestamp of the file at path. It will return an error if it cannot retrieve any os.FileInfo from the file path.

This utilizes utils.GetLastModified under the hood.

func (*FileSystemStorage) GetLastWrite 

func (f *FileSystemStorage) GetLastWrite() (time.Time, error)

GetLastWrite will retrieve the most recent successful Write operation that was received by RemoteStore.

func (*FileSystemStorage) Read 

func (f *FileSystemStorage) Read(path string) ([]byte, error)

Read reads data from path. This will return an error if it fails to Read from the file path.

This utilizes utils.ReadFile under the hood.

func (*FileSystemStorage) ReadDir 

func (f *FileSystemStorage) ReadDir(path string) ([]string, error)

ReadDir implements [RemoteStore.ReadDir] and gets a file listing.

func (*FileSystemStorage) Write 

func (f *FileSystemStorage) Write(path string, data []byte) error

Write will Write data to path. This will return an error if it fails to Write.

This utilizes utils.WriteFileDef under the hood.

type InstanceID 

type InstanceID [instanceIDLength]byte

InstanceID is a random, URL Safe, base64 string generated when an xxdk client is initialized. It is used to differentiate different instances of clients using the same cMix identity. We represent it internally as a byte array.

func GetInstanceID 

func GetInstanceID(kv ekv.KeyValue) (InstanceID, error)

func InitInstanceID 

func InitInstanceID(kv ekv.KeyValue, rng io.Reader) (InstanceID, error)

InitInstanceID creates the InstanceID and returns it if it doesnt exist. If it already exists, Init will return an error.

func NewInstanceIDFromBytes 

func NewInstanceIDFromBytes(idBytes []byte) (InstanceID, error)

NewInstanceIDFromBytes creates an InstanceID from raw bytes This returns errors if the number of bytes is incorrect or the slice is empty.

func NewInstanceIDFromString 

func NewInstanceIDFromString(idStr string) (InstanceID, error)

NewInstanceIDFromString creates an instanceID from a string object This returns errors if the number of bytes is incorrect or the slice is empty.

func NewRandomInstanceID 

func NewRandomInstanceID(csprng io.Reader) (InstanceID, error)

NewRandomInstanceID creates a new random InstanceID from the provided cryptographically secured random number generator.

func (InstanceID) Cmp 

func (i InstanceID) Cmp(j InstanceID) int

Cmp determines which instance id is greater assuming they are numbers. -1 - i and j are lesser 

0 - i and j are equal
1 - i is greater than j

func (InstanceID) Equals 

func (i InstanceID) Equals(j InstanceID) bool

Equals determines if the two instances are the same.

func (InstanceID) MarshalText 

func (i InstanceID) MarshalText() (text []byte, err error)

MarshalText implements the encoding.MarshalText interface function

func (InstanceID) String 

func (i InstanceID) String() string

String implements the [Stringer.String] interface function

func (*InstanceID) UnmarshalText 

func (i *InstanceID) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface function

type KVFilesystem 

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

KVFilesystem implements filesystem (FileIO) operations inside the provided EKV instance.

func (*KVFilesystem) Read 

func (k *KVFilesystem) Read(path string) ([]byte, error)

Read reads data from path. This will return an error if it fails to Read from the file path.

This utilizes ekv.KeyValue under the hood.

func (*KVFilesystem) Write 

func (k *KVFilesystem) Write(path string, data []byte) error

Write writes data to the path. This will return an error if it fails to Write.

This utilizes ekv.KeyValue under the hood.

type Mutate 

type Mutate struct {
	Timestamp int64
	Value     []byte
	Deletion  bool
}

Mutate is the object that is uploaded to a remote service responsible for account synchronization. It inherits the private mutate object. This prevents recursive calls by json.Marshal on header.MarshalJSON. Any changes to the header object fields should be done in header.

func NewMutate 

func NewMutate(ts time.Time, value []byte, deletion bool) Mutate

NewMutate is the constructor of a Mutate object.

func (*Mutate) GetTimestamp 

func (m *Mutate) GetTimestamp() time.Time

GetTimestamp returns the timestamp of the mutation in standard go format instead of the stored uinx nano count

func (*Mutate) String 

func (m *Mutate) String() string

type Notifier 

type Notifier interface {
	Register(nc NotifyCallback)
}

type NotifyCallback 

type NotifyCallback func(state bool)

type Patch 

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

Patch is the structure which stores both local and remote patches, which are sets of commands to update the local KV There is one command per key, which is the latest command from the device which originated the patch they are ordered by timestamp, so they can be quickly iterated over to determine which mutations have been processed by a given receiver.

func (*Patch) AddUnsafe 

func (p *Patch) AddUnsafe(key string, m Mutate)

AddUnsafe adds a given mutation to the Patch. This must only be called on the creator of the patch Only call within the transaction log

func (*Patch) Deserialize 

func (p *Patch) Deserialize(b []byte) error

func (*Patch) Diff 

func (p *Patch) Diff(patches []*Patch, lastSeen []time.Time) (
	map[string]*Mutate, []time.Time)

Diff combines multiple patches into a single set of updates which can be applied to the local KV. It will not process mutations from each patch which is not newer thant he lastSeen for that patch unless the key that mutation edits was edited by another patch. The patches need to be ordered in ascending order by supremacy, defined as having larger device IDs. This supremacy will determine which mutation is applied in the event they have the same timestamp O(2*numPatches*numMutations) Diff does not check the _____ for updates because they should already be applied

func (*Patch) Serialize 

func (p *Patch) Serialize() ([]byte, error)

type RemoteKV 

type RemoteKV interface {
	ekv.KeyValue

	// SetRemote will Write a mutate to the remote and write the key to the
	// local store.
	// Does not allow writing to keys with the suffix "_🗺️MapKeys",
	// it is reserved
	SetRemote(key string, value []byte) error

	// DeleteRemote will write a mutate to the remote with an instruction to delete
	// the key and will delete it locally.
	// Does not allow writing to keys with the suffix "_🗺️MapKeys",
	// it is reserved
	DeleteRemote(key string) error
}

RemoteKV exposes some internal KV functions. you cannot create a RemoteKV, and generally you should never access it on the versionedKV object. It is provided so that external xxdk libraries can access specific functionality. This is considered internal api and may be changed or removed at any time.

type RemoteStore 

type RemoteStore interface {
	// FileIO is used to Write and Read files.
	FileIO

	// GetLastModified returns when the file at the given file
	// path was last modified. If the implementation that adheres
	// to this interface does not support this, FileIO.Write or
	// [FileIO.Read] should be implemented to either Write a
	// separate timestamp file or add a prefix.
	GetLastModified(path string) (time.Time, error)

	// GetLastWrite retrieves the most recent successful Write
	// operation that was received by RemoteStore.
	GetLastWrite() (time.Time, error)

	// ReadDir reads the named directory, returning all its directory entries
	// sorted by filename.
	ReadDir(path string) ([]string, error)
}

RemoteStore is a FileIO interface with additional functions for Write operation information. It is used to store mutate logs on cloud storage or another remote storage solution like an sftp server run by the user.

type RemoteStoreCallback 

type RemoteStoreCallback func(newTx Mutate, err error)

RemoteStoreCallback is a callback for reporting the status of writing the new mutate to remote storage.

type SyncKV 

type SyncKV interface {
	versioned.KV
	StartProcesses() (stoppable.Stoppable, error)
	RegisterConnectionTracker(nc NotifyCallback)
	IsConnected() bool
	IsSynched() bool
	WaitForRemote(timeout time.Duration) bool
}

func LocalKV 

func LocalKV(deviceSecret []byte, kv ekv.KeyValue,
	rng *fastRNG.StreamGenerator) (SyncKV, error)

LocalKV Loads or Creates a synchronized remote KV that uses a local-only mutate log. It panics if the underlying KV has ever been used for remote operations in the past.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.