Struct microkv::kv::MicroKV

pub struct MicroKV { /* fields omitted */ }

Defines the main interface structure to represent the most recent state of the data store.

Implementations

impl MicroKV

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

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>

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

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

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.

Use 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

Builds up the MicroKV with a hashed buffer, which is then locked securely `for later use.

Use 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, 

Decrypts and retrieves a value. Can return errors if lock is poisoned, ciphertext decryption doesn't work, and if parsing bytes fail.

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

Encrypts and adds a new key-value pair to storage.

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

Delete removes an entry in the key value store.

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

Arbitrary read-lock that encapsulates a read-only closure. 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, 

Arbitrary write-lock that encapsulates a write-only closure 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>

Helper routine that acquires a reader lock and checks if a key exists.

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

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>>

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<'_, ()>

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

pub fn commit(&self) -> Result<'_, ()>

Writes the IndexMap to persistent storage after encrypting with secure crypto construction.

pub fn destruct(&self) -> Result<'_, ()>

Clears the underlying data structure for the key-value store, and deletes the database file to remove all traces.

Trait Implementations

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

pub 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

pub fn drop(&mut self)

Executes the destructor for this type.

impl Serialize for MicroKV

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

Serialize this value into the given Serde serializer.