Trait KVStore

pub trait KVStore {
    // Required methods
    fn read(
        &self,
        primary_namespace: &str,
        secondary_namespace: &str,
        key: &str,
    ) -> Result<Vec<u8>, Error>;
    fn write(
        &self,
        primary_namespace: &str,
        secondary_namespace: &str,
        key: &str,
        buf: &[u8],
    ) -> Result<(), Error>;
    fn remove(
        &self,
        primary_namespace: &str,
        secondary_namespace: &str,
        key: &str,
        lazy: bool,
    ) -> Result<(), Error>;
    fn list(
        &self,
        primary_namespace: &str,
        secondary_namespace: &str,
    ) -> Result<Vec<String>, Error>;
}

Provides an interface that allows storage and retrieval of persisted values that are associated with given keys.

In order to avoid collisions the key space is segmented based on the given primary_namespaces and secondary_namespaces. Implementations of this trait are free to handle them in different ways, as long as per-namespace key uniqueness is asserted.

Keys and namespaces are required to be valid ASCII strings in the range of KVSTORE_NAMESPACE_KEY_ALPHABET and no longer than KVSTORE_NAMESPACE_KEY_MAX_LEN. Empty primary namespaces and secondary namespaces ("") are assumed to be a valid, however, if primary_namespace is empty, secondary_namespace is required to be empty, too. This means that concerns should always be separated by primary namespace first, before secondary namespaces are used. While the number of primary namespaces will be relatively small and is determined at compile time, there may be many secondary namespaces per primary namespace. Note that per-namespace uniqueness needs to also hold for keys and namespaces in any given namespace, i.e., conflicts between keys and equally named primary namespaces/secondary namespaces must be avoided.

Note: Users migrating custom persistence backends from the pre-v0.0.117 KVStorePersister interface can use a concatenation of [{primary_namespace}/[{secondary_namespace}/]]{key} to recover a key compatible with the data model previously assumed by KVStorePersister::persist.

Required Methods

fn read( &self, primary_namespace: &str, secondary_namespace: &str, key: &str, ) -> Result<Vec<u8>, Error>

Returns the data stored for the given primary_namespace, secondary_namespace, and key.

Returns an ErrorKind::NotFound if the given key could not be found in the given primary_namespace and secondary_namespace.

fn write( &self, primary_namespace: &str, secondary_namespace: &str, key: &str, buf: &[u8], ) -> Result<(), Error>

Persists the given data under the given key.

Will create the given primary_namespace and secondary_namespace if not already present in the store.

fn remove( &self, primary_namespace: &str, secondary_namespace: &str, key: &str, lazy: bool, ) -> Result<(), Error>

Removes any data that had previously been persisted under the given key.

If the lazy flag is set to true, the backend implementation might choose to lazily remove the given key at some point in time after the method returns, e.g., as part of an eventual batch deletion of multiple keys. As a consequence, subsequent calls to KVStore::list might include the removed key until the changes are actually persisted.

Note that while setting the lazy flag reduces the I/O burden of multiple subsequent remove calls, it also influences the atomicity guarantees as lazy removes could potentially get lost on crash after the method returns. Therefore, this flag should only be set for remove operations that can be safely replayed at a later time.

Returns successfully if no data will be stored for the given primary_namespace, secondary_namespace, and key, independently of whether it was present before its invokation or not.

fn list( &self, primary_namespace: &str, secondary_namespace: &str, ) -> Result<Vec<String>, Error>

Returns a list of keys that are stored under the given secondary_namespace in primary_namespace.

Returns the keys in arbitrary order, so users requiring a particular order need to sort the returned keys. Returns an empty list if primary_namespace or secondary_namespace is unknown.

Implementors