Tidy store crate, add comments

beacon_node/store/src/leveldb_store.rs

@@ -6,11 +6,13 @@ use leveldb::error::Error as LevelDBError;
 use leveldb::options::{Options, ReadOptions, WriteOptions};
 use std::path::Path;
 
+/// A wrapped leveldb database.
 pub struct LevelDB {
     db: Database<BytesKey>,
 }
 
 impl LevelDB {
+    /// Open a database at `path`, creating a new database if one does not already exist.
     pub fn open(path: &Path) -> Result<Self, Error> {
         let mut options = Options::new();
 
@@ -36,6 +38,7 @@ impl LevelDB {
     }
 }
 
+/// Used for keying leveldb.
 pub struct BytesKey {
     key: Vec<u8>,
 }
@@ -51,7 +54,8 @@ impl Key for BytesKey {
 }
 
 impl Store for LevelDB {
-    fn get_bytes(&self, col: &str, key: &[u8]) -> Result<Option<DBValue>, Error> {
+    /// Retrieve some bytes in `column` with `key`.
+    fn get_bytes(&self, col: &str, key: &[u8]) -> Result<Option<Vec<u8>>, Error> {
         let column_key = Self::get_key_for_col(col, key);
 
         self.db
@@ -59,6 +63,7 @@ impl Store for LevelDB {
             .map_err(Into::into)
     }
 
+    /// Store some `value` in `column`, indexed with `key`.
     fn put_bytes(&self, col: &str, key: &[u8], val: &[u8]) -> Result<(), Error> {
         let column_key = Self::get_key_for_col(col, key);
 
@@ -67,6 +72,7 @@ impl Store for LevelDB {
             .map_err(Into::into)
     }
 
+    /// Return `true` if `key` exists in `column`.
     fn key_exists(&self, col: &str, key: &[u8]) -> Result<bool, Error> {
         let column_key = Self::get_key_for_col(col, key);
 
@@ -76,6 +82,7 @@ impl Store for LevelDB {
             .and_then(|val| Ok(val.is_some()))
     }
 
+    /// Removes `key` from `column`.
     fn key_delete(&self, col: &str, key: &[u8]) -> Result<(), Error> {
         let column_key = Self::get_key_for_col(col, key);
         self.db

beacon_node/store/src/lib.rs

@@ -1,33 +1,55 @@
-// mod disk_db;
+//! Storage functionality for Lighthouse.
+//!
+//! Provides the following stores:
+//!
+//! - `DiskStore`: an on-disk store backed by leveldb. Used in production.
+//! - `MemoryStore`: an in-memory store backed by a hash-map. Used for testing.
+//!
+//! Provides a simple API for storing/retrieving all types that sometimes needs type-hints. See
+//! tests for implementation examples.
+
 mod block_at_slot;
 mod errors;
 mod impls;
 mod leveldb_store;
-mod memory_db;
+mod memory_store;
 
 pub use self::leveldb_store::LevelDB as DiskStore;
-pub use self::memory_db::MemoryStore;
+pub use self::memory_store::MemoryStore;
 pub use errors::Error;
 pub use types::*;
-pub type DBValue = Vec<u8>;
 
+/// An object capable of storing and retrieving objects implementing `StoreItem`.
+///
+/// A `Store` is fundamentally backed by a key-value database, however it provides support for
+/// columns. A simple column implementation might involve prefixing a key with some bytes unique to
+/// each column.
 pub trait Store: Sync + Send + Sized {
+    /// Store an item in `Self`.
     fn put(&self, key: &Hash256, item: &impl StoreItem) -> Result<(), Error> {
         item.db_put(self, key)
     }
 
+    /// Retrieve an item from `Self`.
     fn get<I: StoreItem>(&self, key: &Hash256) -> Result<Option<I>, Error> {
         I::db_get(self, key)
     }
 
+    /// Returns `true` if the given key represents an item in `Self`.
     fn exists<I: StoreItem>(&self, key: &Hash256) -> Result<bool, Error> {
         I::db_exists(self, key)
     }
 
+    /// Remove an item from `Self`.
     fn delete<I: StoreItem>(&self, key: &Hash256) -> Result<(), Error> {
         I::db_delete(self, key)
     }
 
+    /// Given the root of an existing block in the store (`start_block_root`), return a parent
+    /// block with the specified `slot`.
+    ///
+    /// Returns `None` if no parent block exists at that slot, or if `slot` is greater than the
+    /// slot of `start_block_root`.
     fn get_block_at_preceeding_slot(
         &self,
         start_block_root: Hash256,
@@ -36,15 +58,20 @@ pub trait Store: Sync + Send + Sized {
         block_at_slot::get_block_at_preceeding_slot(self, slot, start_block_root)
     }
 
-    fn get_bytes(&self, col: &str, key: &[u8]) -> Result<Option<DBValue>, Error>;
+    /// Retrieve some bytes in `column` with `key`.
+    fn get_bytes(&self, column: &str, key: &[u8]) -> Result<Option<Vec<u8>>, Error>;
 
-    fn put_bytes(&self, col: &str, key: &[u8], val: &[u8]) -> Result<(), Error>;
+    /// Store some `value` in `column`, indexed with `key`.
+    fn put_bytes(&self, column: &str, key: &[u8], value: &[u8]) -> Result<(), Error>;
 
-    fn key_exists(&self, col: &str, key: &[u8]) -> Result<bool, Error>;
+    /// Return `true` if `key` exists in `column`.
+    fn key_exists(&self, column: &str, key: &[u8]) -> Result<bool, Error>;
 
-    fn key_delete(&self, col: &str, key: &[u8]) -> Result<(), Error>;
+    /// Removes `key` from `column`.
+    fn key_delete(&self, column: &str, key: &[u8]) -> Result<(), Error>;
 }
 
+/// A unique column identifier.
 pub enum DBColumn {
     BeaconBlock,
     BeaconState,
@@ -62,22 +89,31 @@ impl<'a> Into<&'a str> for DBColumn {
     }
 }
 
+/// An item that may be stored in a `Store`.
+///
+/// Provides default methods that are suitable for most applications, however when overridden they
+/// provide full customizability of `Store` operations.
 pub trait StoreItem: Sized {
+    /// Identifies which column this item should be placed in.
     fn db_column() -> DBColumn;
 
+    /// Serialize `self` as bytes.
     fn as_store_bytes(&self) -> Vec<u8>;
 
+    /// De-serialize `self` from bytes.
     fn from_store_bytes(bytes: &mut [u8]) -> Result<Self, Error>;
 
+    /// Store `self`.
     fn db_put(&self, store: &impl Store, key: &Hash256) -> Result<(), Error> {
         let column = Self::db_column().into();
         let key = key.as_bytes();
 
         store
             .put_bytes(column, key, &self.as_store_bytes())
-            .map_err(|e| e.into())
+            .map_err(Into::into)
     }
 
+    /// Retrieve an instance of `Self`.
     fn db_get(store: &impl Store, key: &Hash256) -> Result<Option<Self>, Error> {
         let column = Self::db_column().into();
         let key = key.as_bytes();
@@ -88,6 +124,7 @@ pub trait StoreItem: Sized {
         }
     }
 
+    /// Return `true` if an instance of `Self` exists in `Store`.
     fn db_exists(store: &impl Store, key: &Hash256) -> Result<bool, Error> {
         let column = Self::db_column().into();
         let key = key.as_bytes();
@@ -95,6 +132,7 @@ pub trait StoreItem: Sized {
         store.key_exists(column, key)
     }
 
+    /// Delete `self` from the `Store`.
     fn db_delete(store: &impl Store, key: &Hash256) -> Result<(), Error> {
         let column = Self::db_column().into();
         let key = key.as_bytes();

beacon_node/store/src/memory_store.rs

@@ -1,14 +1,16 @@
-use super::{DBValue, Error, Store};
+use super::{Error, Store};
 use parking_lot::RwLock;
 use std::collections::HashMap;
 
 type DBHashMap = HashMap<Vec<u8>, Vec<u8>>;
 
+/// A thread-safe `HashMap` wrapper.
 pub struct MemoryStore {
     db: RwLock<DBHashMap>,
 }
 
 impl MemoryStore {
+    /// Create a new, empty database.
     pub fn open() -> Self {
         Self {
             db: RwLock::new(HashMap::new()),
@@ -24,7 +26,7 @@ impl MemoryStore {
 
 impl Store for MemoryStore {
     /// Get the value of some key from the database. Returns `None` if the key does not exist.
-    fn get_bytes(&self, col: &str, key: &[u8]) -> Result<Option<DBValue>, Error> {
+    fn get_bytes(&self, col: &str, key: &[u8]) -> Result<Option<Vec<u8>>, Error> {
         let column_key = MemoryStore::get_key_for_col(col, key);
 
         Ok(self

beacon_node/store/src/store.rs

@@ -0,0 +1,37 @@
+use super::*;
+
+pub type Vec<u8> = Vec<u8>;
+
+pub trait Store: Sync + Send + Sized {
+    fn put(&self, key: &Hash256, item: &impl StoreItem) -> Result<(), Error> {
+        item.db_put(self, key)
+    }
+
+    fn get<I: StoreItem>(&self, key: &Hash256) -> Result<Option<I>, Error> {
+        I::db_get(self, key)
+    }
+
+    fn exists<I: StoreItem>(&self, key: &Hash256) -> Result<bool, Error> {
+        I::db_exists(self, key)
+    }
+
+    fn delete<I: StoreItem>(&self, key: &Hash256) -> Result<(), Error> {
+        I::db_delete(self, key)
+    }
+
+    fn get_block_at_preceeding_slot(
+        &self,
+        start_block_root: Hash256,
+        slot: Slot,
+    ) -> Result<Option<(Hash256, BeaconBlock)>, Error> {
+        block_at_slot::get_block_at_preceeding_slot(self, slot, start_block_root)
+    }
+
+    fn get_bytes(&self, col: &str, key: &[u8]) -> Result<Option<Vec<u8>>, Error>;
+
+    fn put_bytes(&self, col: &str, key: &[u8], val: &[u8]) -> Result<(), Error>;
+
+    fn key_exists(&self, col: &str, key: &[u8]) -> Result<bool, Error>;
+
+    fn key_delete(&self, col: &str, key: &[u8]) -> Result<(), Error>;
+}