Iimprove sov-schema-db docs (#463)

Sovereign-Labs · Jul 5, 2023 · 6ab7625 · 6ab7625
1 parent 2d1f01c
commit 6ab7625
Show file tree

Hide file tree

Showing 9 changed files with 232 additions and 113 deletions.
diff --git a/full-node/db/sov-db/src/ledger_db/mod.rs b/full-node/db/sov-db/src/ledger_db/mod.rs
@@ -8,7 +8,7 @@ use sov_rollup_interface::{
     services::da::SlotData,
     stf::{BatchReceipt, Event},
 };
-use sov_schema_db::{interface::SeekKeyEncoder, Schema, SchemaBatch, DB};
+use sov_schema_db::{Schema, SchemaBatch, SeekKeyEncoder, DB};
 
 use crate::{
     rocks_db_config::gen_rocksdb_options,

diff --git a/full-node/db/sov-db/src/lib.rs b/full-node/db/sov-db/src/lib.rs
@@ -1,3 +1,5 @@
+#![forbid(unsafe_code)]
+
 use state_db::StateDB;
 
 pub mod ledger_db;

diff --git a/full-node/db/sov-db/src/schema/tables.rs b/full-node/db/sov-db/src/schema/tables.rs
@@ -28,8 +28,8 @@ use jmt::{
     Version,
 };
 use sov_rollup_interface::stf::{Event, EventKey};
-use sov_schema_db::interface::{KeyDecoder, KeyEncoder, SeekKeyEncoder, ValueCodec};
-use sov_schema_db::CodecError;
+use sov_schema_db::schema::{KeyDecoder, KeyEncoder, ValueCodec};
+use sov_schema_db::{CodecError, SeekKeyEncoder};
 
 pub const STATE_TABLES: &[&str] = &[
     KeyHashToKey::table_name(),
@@ -48,7 +48,7 @@ pub const LEDGER_TABLES: &[&str] = &[
     EventByNumber::table_name(),
 ];
 
-/// Macro to define a table that implements [`sov_schema_db::interface::Schema`].
+/// Macro to define a table that implements [`sov_schema_db::Schema`].
 /// KeyCodec<Schema> and ValueCodec<Schema> must be implemented separately.
 ///
 /// ```ignore
@@ -75,7 +75,7 @@ macro_rules! define_table_without_codec {
         #[derive(Clone, Copy, Debug, Default)]
         pub(crate) struct $table_name;
 
-        impl ::sov_schema_db::interface::Schema for $table_name {
+        impl ::sov_schema_db::schema::Schema for $table_name {
             const COLUMN_FAMILY_NAME: &'static str = $table_name::table_name();
             type Key = $key;
             type Value = $value;
@@ -98,7 +98,7 @@ macro_rules! define_table_without_codec {
 
 macro_rules! impl_borsh_value_codec {
     ($table_name:ident, $value:ty) => {
-        impl ::sov_schema_db::interface::ValueCodec<$table_name> for $value {
+        impl ::sov_schema_db::schema::ValueCodec<$table_name> for $value {
             fn encode_value(
                 &self,
             ) -> ::std::result::Result<
@@ -117,7 +117,7 @@ macro_rules! impl_borsh_value_codec {
     };
 }
 
-/// Macro to define a table that implements [`sov_schema_db::interface::Schema`].
+/// Macro to define a table that implements [`sov_schema_db::schema::Schema`].
 /// Automatically generates KeyCodec<...> and ValueCodec<...> implementations
 /// using the Encode and Decode traits from sov_rollup_interface
 ///
@@ -131,13 +131,13 @@ macro_rules! define_table_with_default_codec {
     ($(#[$docs:meta])+ ($table_name:ident) $key:ty => $value:ty) => {
         define_table_without_codec!($(#[$docs])+ ( $table_name ) $key => $value);
 
-        impl ::sov_schema_db::interface::KeyEncoder<$table_name> for $key {
+        impl ::sov_schema_db::schema::KeyEncoder<$table_name> for $key {
             fn encode_key(&self) -> ::std::result::Result<::sov_rollup_interface::maybestd::vec::Vec<u8>, ::sov_schema_db::CodecError> {
                 ::borsh::BorshSerialize::try_to_vec(self).map_err(Into::into)
             }
         }
 
-        impl ::sov_schema_db::interface::KeyDecoder<$table_name> for $key {
+        impl ::sov_schema_db::schema::KeyDecoder<$table_name> for $key {
             fn decode_key(data: &[u8]) -> ::std::result::Result<Self, ::sov_schema_db::CodecError> {
                 ::borsh::BorshDeserialize::deserialize_reader(&mut &data[..]).map_err(Into::into)
             }
@@ -156,7 +156,7 @@ macro_rules! define_table_with_seek_key_codec {
     ($(#[$docs:meta])+ ($table_name:ident) $key:ty => $value:ty) => {
         define_table_without_codec!($(#[$docs])+ ( $table_name ) $key => $value);
 
-        impl ::sov_schema_db::interface::KeyEncoder<$table_name> for $key {
+        impl ::sov_schema_db::schema::KeyEncoder<$table_name> for $key {
             fn encode_key(&self) -> ::std::result::Result<::sov_rollup_interface::maybestd::vec::Vec<u8>, ::sov_schema_db::CodecError> {
                 use ::anyhow::Context;
                 use ::bincode::Options;
@@ -169,7 +169,7 @@ macro_rules! define_table_with_seek_key_codec {
             }
         }
 
-        impl ::sov_schema_db::interface::KeyDecoder<$table_name> for $key {
+        impl ::sov_schema_db::schema::KeyDecoder<$table_name> for $key {
             fn decode_key(data: &[u8]) -> ::std::result::Result<Self, ::sov_schema_db::CodecError> {
                 use ::anyhow::Context;
                 use ::bincode::Options;
@@ -182,9 +182,9 @@ macro_rules! define_table_with_seek_key_codec {
             }
         }
 
-        impl ::sov_schema_db::interface::SeekKeyEncoder<$table_name> for $key {
+        impl ::sov_schema_db::SeekKeyEncoder<$table_name> for $key {
             fn encode_seek_key(&self) -> ::std::result::Result<::sov_rollup_interface::maybestd::vec::Vec<u8>, ::sov_schema_db::CodecError> {
-                <Self as ::sov_schema_db::interface::KeyEncoder<$table_name>>::encode_key(self)
+                <Self as ::sov_schema_db::schema::KeyEncoder<$table_name>>::encode_key(self)
             }
         }
 
@@ -239,22 +239,22 @@ define_table_without_codec!(
 );
 
 impl KeyEncoder<JmtNodes> for NodeKey {
-    fn encode_key(&self) -> sov_schema_db::interface::Result<Vec<u8>> {
+    fn encode_key(&self) -> sov_schema_db::schema::Result<Vec<u8>> {
         self.try_to_vec().map_err(CodecError::from)
     }
 }
 impl KeyDecoder<JmtNodes> for NodeKey {
-    fn decode_key(data: &[u8]) -> sov_schema_db::interface::Result<Self> {
+    fn decode_key(data: &[u8]) -> sov_schema_db::schema::Result<Self> {
         Ok(Self::deserialize_reader(&mut &data[..])?)
     }
 }
 
 impl ValueCodec<JmtNodes> for Node {
-    fn encode_value(&self) -> sov_schema_db::interface::Result<Vec<u8>> {
+    fn encode_value(&self) -> sov_schema_db::schema::Result<Vec<u8>> {
         self.try_to_vec().map_err(CodecError::from)
     }
 
-    fn decode_value(data: &[u8]) -> sov_schema_db::interface::Result<Self> {
+    fn decode_value(data: &[u8]) -> sov_schema_db::schema::Result<Self> {
         Ok(Self::deserialize_reader(&mut &data[..])?)
     }
 }
@@ -265,7 +265,7 @@ define_table_without_codec!(
 );
 
 impl<T: AsRef<[u8]> + PartialEq + core::fmt::Debug> KeyEncoder<JmtValues> for (T, Version) {
-    fn encode_key(&self) -> sov_schema_db::interface::Result<Vec<u8>> {
+    fn encode_key(&self) -> sov_schema_db::schema::Result<Vec<u8>> {
         let mut out =
             Vec::with_capacity(self.0.as_ref().len() + std::mem::size_of::<Version>() + 8);
         self.0
@@ -280,13 +280,13 @@ impl<T: AsRef<[u8]> + PartialEq + core::fmt::Debug> KeyEncoder<JmtValues> for (T
 }
 
 impl<T: AsRef<[u8]> + PartialEq + core::fmt::Debug> SeekKeyEncoder<JmtValues> for (T, Version) {
-    fn encode_seek_key(&self) -> sov_schema_db::interface::Result<Vec<u8>> {
+    fn encode_seek_key(&self) -> sov_schema_db::schema::Result<Vec<u8>> {
         self.encode_key()
     }
 }
 
 impl KeyDecoder<JmtValues> for (StateKey, Version) {
-    fn decode_key(data: &[u8]) -> sov_schema_db::interface::Result<Self> {
+    fn decode_key(data: &[u8]) -> sov_schema_db::schema::Result<Self> {
         let mut cursor = maybestd::io::Cursor::new(data);
         let key = Vec::<u8>::deserialize_reader(&mut cursor)?;
         let version = cursor.read_u64::<BigEndian>()?;
@@ -295,11 +295,11 @@ impl KeyDecoder<JmtValues> for (StateKey, Version) {
 }
 
 impl ValueCodec<JmtValues> for JmtValue {
-    fn encode_value(&self) -> sov_schema_db::interface::Result<Vec<u8>> {
+    fn encode_value(&self) -> sov_schema_db::schema::Result<Vec<u8>> {
         self.try_to_vec().map_err(CodecError::from)
     }
 
-    fn decode_value(data: &[u8]) -> sov_schema_db::interface::Result<Self> {
+    fn decode_value(data: &[u8]) -> sov_schema_db::schema::Result<Self> {
         Ok(Self::deserialize_reader(&mut &data[..])?)
     }
 }

diff --git a/full-node/db/sov-schema-db/Cargo.toml b/full-node/db/sov-schema-db/Cargo.toml
@@ -1,10 +1,10 @@
 [package]
 name = "sov-schema-db"
 description = "A low level interface transforming RocksDB into a type-oriented data store"
-version = { workspace = true }
 license = "Apache-2.0" # This license is inherited from Aptos 
 
 # Workspace inherited keys
+version = { workspace = true }
 authors = { workspace = true }
 edition = { workspace = true }
 homepage = { workspace = true }

diff --git a/full-node/db/sov-schema-db/src/iterator.rs b/full-node/db/sov-schema-db/src/iterator.rs
@@ -1,16 +1,39 @@
 use anyhow::Result;
+use std::iter::FusedIterator;
 use std::marker::PhantomData;
 
-use crate::interface::{KeyDecoder, Schema, SeekKeyEncoder, ValueCodec};
 use crate::metrics::{SCHEMADB_ITER_BYTES, SCHEMADB_ITER_LATENCY_SECONDS};
+use crate::schema::{KeyDecoder, Schema, ValueCodec};
+
+/// This defines a type that can be used to seek a [`SchemaIterator`], via
+/// interfaces like [`SchemaIterator::seek`]. Mind you, not all
+/// [`KeyEncoder`](crate::schema::KeyEncoder)s shall be [`SeekKeyEncoder`]s, and
+/// vice versa. E.g.:
+///
+/// - Some key types don't use an encoding that results in sensible
+/// seeking behavior under lexicographic ordering (what RocksDB uses by
+/// default), which means you shouldn't implement [`SeekKeyEncoder`] at all.
+/// - Other key types might maintain full lexicographic order, which means the
+/// original key type can also be [`SeekKeyEncoder`].
+/// - Other key types may be composite, and the first field alone may be
+/// a good candidate for [`SeekKeyEncoder`].
+pub trait SeekKeyEncoder<S: Schema + ?Sized>: Sized {
+    /// Converts `self` to bytes which is used to seek the underlying raw
+    /// iterator.
+    ///
+    /// If `self` is also a [`KeyEncoder`](crate::schema::KeyEncoder), then
+    /// [`SeekKeyEncoder::encode_seek_key`] MUST return the same bytes as
+    /// [`KeyEncoder::encode_key`](crate::schema::KeyEncoder::encode_key).
+    fn encode_seek_key(&self) -> crate::schema::Result<Vec<u8>>;
+}
 
-pub enum ScanDirection {
+pub(crate) enum ScanDirection {
     Forward,
     Backward,
 }
 
 /// DB Iterator parameterized on [`Schema`] that seeks with [`Schema::Key`] and yields
-/// [`Schema::Key`] and [`Schema::Value`]
+/// [`Schema::Key`] and [`Schema::Value`] pairs.
 pub struct SchemaIterator<'a, S> {
     db_iter: rocksdb::DBRawIterator<'a>,
     direction: ScanDirection,
@@ -95,3 +118,5 @@ where
         self.next_impl().transpose()
     }
 }
+
+impl<'a, S> FusedIterator for SchemaIterator<'a, S> where S: Schema {}