Struct microkv::kv::MicroKV

pub struct MicroKV { /* fields omitted */ }

MicroKV defines the main interface structure in order to represent the most recent state of the data store.

Implementations

impl MicroKV

pub fn new(dbname: &str) -> Self

new() initializes a new empty and unencrypted MicroKV store with an identifying database name. This is the bare minimum that can operate as a key-value store, and can be configured using other builder methods.

pub fn open(dbname: &str) -> Result<Self>

open() opens a previously instantiated and encrypted MicroKV given a db name. The public nonce generated from a previous session is also retrieved in order to do authenticated encryption later on.

pub fn get_db_path(name: &str) -> PathBuf

get_db_path() is an inlined helper that forms an absolute path from a given database name and the default workspace path.

pub fn with_pwd_clear(self, unsafe_pwd: String) -> Self

with_pwd_clear() builds up the MicroKV with a cleartext password, which is hashed using the defaultly supported SHA-256 by sodiumoxide, in order to instantiate a 32-byte hash.

Ideally, this should be used if the password to encrypt is not naturally pseudorandom and secured in-memory, and is instead read elsewhere, like a file or stdin (developer should guarentee security when implementing such methods, as MicroKV only guarentees hashing and secure storage).

pub fn with_pwd_hash(self, _pwd: [u8; 32]) -> Self

with_pwd_hash() builds up the MicroKV with a hashed buffer, which is then locked securely for later use.

Ideally, this should be used if the password to encrypt is generated as a pseudorandom value, or previously hashed by another preferred one-way function within or outside the application.

pub fn get<V>(&self, _key: &str) -> Result<V> where
    V: DeserializeOwned + 'static, 

get() retrieves a deserializable value based on a given input key. Can return errors if lock is poisoned, ciphertext decryption doesn't work, and if bincode can not parse the raw bytes properly.

pub fn put<V>(&self, _key: &str, _value: V) -> Result<()> where
    V: Serialize, 

put() adds a new key-value pair to storage. It consumes a string-type as a key, and any serializable value. It can return errors if the lock is poisoned.

pub fn delete(&self, _key: &str) -> Result<()>

delete() removes an entry in the key value store. Errors if the entry does not exist or if the database is poisoned.

pub fn lock_read<C, R>(&self, callback: C) -> Result<R> where
    C: Fn(&IndexMap<String, SecVec<u8>>) -> R, 

lock_read() is an arbitrary read-lock that encapsulates a read-only closure. This means that multiple concurrent readers can hold a lock and parse out data.

pub fn lock_write<C, R>(&self, callback: C) -> Result<R> where
    C: FnMut(&IndexMap<String, SecVec<u8>>) -> R, 

lock_write() is an arbitrary write-lock that encapsulates a write-only closure. This means that only one single writer can hold a lock and mutate data, blocking any other readers/writers before the lock is released.

pub fn exists<K>(&self, _key: &str) -> Result<bool>

exists() is a helper routine that acquires a reader lock and checks if a key exists within the IndexMap structure.

pub fn keys(&self) -> Result<Vec<String>>

keys() safely consumes an iterator over the keys in the IndexMap and returns a Vec<String> for further use.

Note that key iteration, not value iteration, is only supported in order to preserve security guarentees.

pub fn sorted_keys(&self) -> Result<Vec<String>>

keys() safely consumes an iterator over a copy of in-place sorted keys in the IndexMap and returns a Vec<String> for further use.

Note that key iteration, not value iteration, is only supported in order to preserve security guarentees.

pub fn clear(&self) -> Result<()>

clear() empties out the entire underlying IndexMap in O(n) time, but does not delete the persistent storage file from disk. This ensures that the IndexMap remains, and its capacity is kept the same.

pub fn commit(&self) -> Result<()>

commit() writes the IndexMap to a deserializable bincode file for fast persistent storage. A secure crypto construction is used in order to encrypt information to the store, such that it can't be read out.

pub fn destruct(&self) -> Result<()>

destruct() securely clears the underlying data structure for the key-value store, and deletes the database file, removing all traces of the database's existence.

Trait Implementations

impl<'de> Deserialize<'de> for MicroKV

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl Drop for MicroKV

fn drop(&mut self)

Executes the destructor for this type.

impl Serialize for MicroKV

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.