store

Documentation

Overview

Package store provides a basic API for modules to interact with kv-stores independently of any implementation of that functionality. Additionally, it provides a set of interfaces for store implementations to adhere to, so that they can be used interchangeably by modules.

Index

• type Batch
• type BatchCreator
• type Changeset
  • func NewChangeset(version uint64) *Changeset
  • func NewChangesetWithPairs(version uint64, pairs map[string]KVPairs) *Changeset
  • func (cs *Changeset) Add(storeKey, key, value []byte, remove bool)
  • func (cs *Changeset) AddKVPair(storeKey []byte, pair KVPair)
  • func (cs *Changeset) Size() int
• type Hash
• type Iterator
• type IteratorCreator
• type KVPair
• type KVPairs
• type KVStore
• type KVStoreService
• type KVStoreServiceFactory
• type KVStoreWithBatch
• type MemoryStoreService
• type Reader
• type ReaderMap
• type StateChanges
• type StoreUpgrades
  • func (s *StoreUpgrades) IsAdded(key string) bool
  • func (s *StoreUpgrades) IsDeleted(key string) bool
• type TransientStoreService
• type Writer
• type WriterMap

Types

type Batch

type Batch = interface {
	// Set sets a key/value pair.
	// CONTRACT: key, value readonly []byte
	Set(key, value []byte) error

	// Delete deletes a key/value pair.
	// CONTRACT: key readonly []byte
	Delete(key []byte) error

	// Write writes the batch, possibly without flushing to disk. Only Close() can be called after,
	// other methods will error.
	Write() error

	// WriteSync writes the batch and flushes it to disk. Only Close() can be called after, other
	// methods will error.
	WriteSync() error

	// Close closes the batch. It is idempotent, but calls to other methods afterwards will error.
	Close() error

	// GetByteSize that returns the current size of the batch in bytes. Depending on the implementation,
	// this may return the size of the underlying LSM batch, including the size of additional metadata
	// on top of the expected key and value total byte count.
	GetByteSize() (int, error)
}

Batch represents a group of writes. They may or may not be written atomically depending on the backend. Callers must call Close on the batch when done.

As with KVStore, given keys and values should be considered read-only, and must not be modified after passing them to the batch.

type BatchCreator

type BatchCreator interface {
	// NewBatch creates a new batch for atomic updates. The caller must call Batch.Close.
	NewBatch() Batch

	// NewBatchWithSize create a new batch for atomic updates, but with pre-allocated size.
	// This will does the same thing as NewBatch if the batch implementation doesn't support pre-allocation.
	NewBatchWithSize(int) Batch
}

BatchCreator defines an interface for creating a new batch.

type Changeset

type Changeset struct {
	Version uint64
	Changes []StateChanges
}

Changeset is a list of changes to be written to disk

func NewChangeset

func NewChangeset(version uint64) *Changeset

func NewChangesetWithPairs

func NewChangesetWithPairs(version uint64, pairs map[string]KVPairs) *Changeset

func (*Changeset) Add

func (cs *Changeset) Add(storeKey, key, value []byte, remove bool)

Add adds a key-value pair to the ChangeSet.

func (*Changeset) AddKVPair

func (cs *Changeset) AddKVPair(storeKey []byte, pair KVPair)

AddKVPair adds a KVPair to the ChangeSet.

func (*Changeset) Size

func (cs *Changeset) Size() int

Size returns the number of key-value pairs in the batch.

type Hash

type Hash = []byte

type Iterator

type Iterator = interface {
	// Domain returns the start (inclusive) and end (exclusive) limits of the iterator.
	Domain() (start, end []byte)

	// Valid returns whether the current iterator is valid. Once invalid, the Iterator remains
	// invalid forever.
	Valid() bool

	// Next moves the iterator to the next key in the database, as defined by order of iteration.
	// If Valid returns false, this method will panic.
	Next()

	// Key returns the key at the current position. Panics if the iterator is invalid.
	// Note, the key returned should be a copy and thus safe for modification.
	Key() []byte

	// Value returns the value at the current position. Panics if the iterator is
	// invalid.
	// Note, the value returned should be a copy and thus safe for modification.
	Value() []byte

	// Error returns the last error encountered by the iterator, if any.
	Error() error

	// Close closes the iterator, releasing any allocated resources.
	Close() error
}

Iterator represents an iterator over a domain of keys. Callers must call Close when done. No writes can happen to a domain while there exists an iterator over it. Some backends may take out database locks to ensure this will not happen.

Callers must make sure the iterator is valid before calling any methods on it, otherwise these methods will panic.

type IteratorCreator

type IteratorCreator interface {
	// Iterator creates a new iterator for the given store name and domain, where
	// domain is defined by [start, end). Note, both start and end are optional.
	Iterator(storeKey string, start, end []byte) (Iterator, error)

	// ReverseIterator creates a new reverse iterator for the given store name
	// and domain, where domain is defined by [start, end). Note, both start and
	// end are optional.
	ReverseIterator(storeKey string, start, end []byte) (Iterator, error)
}

IteratorCreator defines an interface for creating forward and reverse iterators.

type KVPair

type KVPair = struct {
	// Key defines the key being updated.
	Key []byte
	// Value defines the value associated with the updated key.
	Value []byte
	// Remove is true when the key must be removed from state.
	Remove bool
}

KVPair represents a change in a key and value of state. Remove being true signals the key must be removed from state.

type KVPairs

type KVPairs = []KVPair

KVPairs represents a set of key-value pairs.

type KVStore

type KVStore = interface {
	// Get returns nil iff key doesn't exist. Errors on nil key.
	Get(key []byte) ([]byte, error)

	// Has checks if a key exists. Errors on nil key.
	Has(key []byte) (bool, error)

	// Set sets the key. Errors on nil key or value.
	Set(key, value []byte) error

	// Delete deletes the key. Errors on nil key.
	Delete(key []byte) error

	// Iterator iterates over a domain of keys in ascending order. End is exclusive.
	// Start must be less than end, or the Iterator is invalid.
	// Iterator must be closed by caller.
	// To iterate over entire domain, use store.Iterator(nil, nil)
	// CONTRACT: No writes may happen within a domain while an iterator exists over it.
	// Exceptionally allowed for cachekv.Store, safe to write in the modules.
	Iterator(start, end []byte) (Iterator, error)

	// ReverseIterator iterates over a domain of keys in descending order. End is exclusive.
	// Start must be less than end, or the Iterator is invalid.
	// Iterator must be closed by caller.
	// CONTRACT: No writes may happen within a domain while an iterator exists over it.
	// Exceptionally allowed for cachekv.Store, safe to write in the modules.
	ReverseIterator(start, end []byte) (Iterator, error)
}

KVStore describes the basic interface for interacting with key-value stores.

type KVStoreService

type KVStoreService interface {
	// OpenKVStore retrieves the KVStore from the context.
	OpenKVStore(context.Context) KVStore
}

KVStoreService represents a unique, non-forgeable handle to a regular merkle-tree backed KVStore. It should be provided as a module-scoped dependency by the runtime module being used to build the app.

type KVStoreServiceFactory

type KVStoreServiceFactory func([]byte) KVStoreService

KVStoreServiceFactory is a function that creates a new KVStoreService. It can be used to override the default KVStoreService bindings for cases where an application must supply a custom stateful backend.

type KVStoreWithBatch

type KVStoreWithBatch interface {
	KVStore
	BatchCreator

	// Close closes the KVStoreWithBatch, releasing any resources held.
	Close() error
}

KVStoreWithBatch is an extension of KVStore that allows for batch writes.

type MemoryStoreService

type MemoryStoreService interface {
	// OpenMemoryStore retrieves the memory store from the context.
	OpenMemoryStore(context.Context) KVStore
}

MemoryStoreService represents a unique, non-forgeable handle to a memory-backed KVStore. It should be provided as a module-scoped dependency by the runtime module being used to build the app.

type Reader

type Reader interface {
	Has(key []byte) (bool, error)
	Get([]byte) ([]byte, error)
	Iterator(start, end []byte) (Iterator, error)        // consider removing iterate?
	ReverseIterator(start, end []byte) (Iterator, error) // consider removing reverse iterate
}

Reader defines a sub-set of the methods exposed by store.KVStore. The methods defined work only at read level.

type ReaderMap

type ReaderMap interface {
	// GetReader must return the state for the provided actor.
	// Storage implements might treat this as a prefix store over an actor.
	// Prefix safety is on the implementer.
	GetReader(actor []byte) (Reader, error)
}

ReaderMap represents a readonly view over all the accounts state.

type StateChanges

type StateChanges = struct {
	Actor        []byte  // actor represents the space in storage where state is stored, previously this was called a "storekey"
	StateChanges KVPairs // StateChanges is a list of key-value pairs representing the changes to the state.
}

StateChanges represents a set of changes to the state of an actor in storage.

type StoreUpgrades

type StoreUpgrades struct {
	Added   []string `json:"added"`
	Deleted []string `json:"deleted"`
}

StoreUpgrades defines a series of transformations to apply the multistore db upon load

func (*StoreUpgrades) IsAdded

func (s *StoreUpgrades) IsAdded(key string) bool

IsAdded returns true if the given key should be added

func (*StoreUpgrades) IsDeleted

func (s *StoreUpgrades) IsDeleted(key string) bool

IsDeleted returns true if the given key should be deleted

type TransientStoreService

type TransientStoreService interface {
	// OpenTransientStore retrieves the transient store from the context.
	OpenTransientStore(context.Context) KVStore
}

TransientStoreService represents a unique, non-forgeable handle to a memory-backed KVStore which is reset at the start of every block. It should be provided as a module-scoped dependency by the runtime module being used to build the app. WARNING: This service is not available in server/v2 apps. Store/v2 does not support transient stores.

type Writer

type Writer interface {
	Reader
	Set(key, value []byte) error
	Delete(key []byte) error
	ApplyChangeSets(changes []KVPair) error
	ChangeSets() ([]KVPair, error)
}

Writer defines an instance of an actor state at a specific version that can be written to.

type WriterMap

type WriterMap interface {
	ReaderMap
	// GetWriter must the return a WritableState
	// for the provided actor namespace.
	GetWriter(actor []byte) (Writer, error)
	// ApplyStateChanges applies all the state changes
	// of the accounts. Ordering of the returned state changes
	// is an implementation detail and must not be assumed.
	ApplyStateChanges(stateChanges []StateChanges) error
	// GetStateChanges returns the list of the state
	// changes so far applied. Order must not be assumed.
	GetStateChanges() ([]StateChanges, error)
}

WriterMap represents a writable actor state.