//! [`Qmdb`] implementation for QMDB [`immutable`](commonware_storage::qmdb::immutable) //! databases. //! //! Immutable databases accept new keyed values but no updates or deletions. Batch reads consult //! the database at the time of the read for keys their batch chain does not write, and return a //! `StaleRead` error once the database is at no state of that chain. use crate::stateful::db::qmdb::{Merkleized, Qmdb, Unmerkleized}; use commonware_codec::EncodeShared; use commonware_cryptography::Hasher; use commonware_parallel::Strategy; use commonware_runtime::Handle; use commonware_storage::{ Context, journal::contiguous::Mutable, merkle::{Family, Location}, qmdb::{ Error, immutable::{ Db, Operation, batch::{MerkleizedBatch, UnmerkleizedBatch}, }, operation::Key, sync, value::ValueEncoding, }, translator::Translator, }; use core::borrow::Borrow; use std::sync::Arc; impl Unmerkleized> where Db: Qmdb>, F: Family, E: Context, K: Key, V: ValueEncoding, C: Mutable>, H: Hasher, T: Translator, S: Strategy, Operation: EncodeShared, { /// Sets the metadata committed by [`merkleize`](crate::stateful::db::Unmerkleized::merkleize). /// `None` clears it. pub fn with_metadata(mut self, metadata: impl Into>) -> Self { self.batch = self.batch.with_metadata(metadata); self } /// Sets the inactivity floor committed by /// [`merkleize`](crate::stateful::db::Unmerkleized::merkleize) (inherited from the database or /// parent batch when unset). pub fn with_inactivity_floor(mut self, floor: Location) -> Self { self.batch = self.batch.with_inactivity_floor(floor); self } /// Reads a value by key, falling back to applied state. pub async fn get(&self, key: &K) -> Result, Error> { let db = self.db.read().await; self.batch.get(key, &db).await } /// Reads multiple values by key, falling back to applied state. /// /// Returns results in the same order as `keys`. pub async fn get_many( &self, keys: &[impl Borrow + Sync], ) -> Result>, Error> { let db = self.db.read().await; self.batch.get_many(keys, &db).await } /// Sets `key` to `value` in the batch. pub fn set(mut self, key: K, value: V::Value) -> Self { self.batch = self.batch.set(key, value); self } } impl Merkleized> where Db: Qmdb>, F: Family, E: Context, K: Key, V: ValueEncoding, C: Mutable>, H: Hasher, T: Translator, S: Strategy, Operation: EncodeShared, { /// Reads a value by key, falling back to applied state. pub async fn get(&self, key: &K) -> Result, Error> { let db = self.db.read().await; self.inner.get(key, &db).await } /// Reads multiple values by key, falling back to applied state. /// /// Returns results in the same order as `keys`. pub async fn get_many( &self, keys: &[impl Borrow + Sync], ) -> Result>, Error> { let db = self.db.read().await; self.inner.get_many(keys, &db).await } } impl Qmdb for Db where Self: sync::Database, F: Family, E: Context, K: Key, V: ValueEncoding, C: Mutable>, H: Hasher, T: Translator, S: Strategy, Operation: EncodeShared, { type Batch = UnmerkleizedBatch; type MerkleizedBatch = MerkleizedBatch; fn new_batch(&self) -> Self::Batch { self.new_batch() } fn new_child(parent: &Arc) -> Self::Batch { parent.new_batch::() } async fn merkleize(&self, batch: Self::Batch) -> Result, Error> { batch.merkleize(self).await } async fn apply_batch(self, batch: Arc) -> Result> { self.apply_batch(batch).await } async fn start_sync(self) -> Result<(Self, Handle<()>), Error> { self.start_sync().await } } #[cfg(test)] mod tests { use super::*; use crate::stateful::db::{ManagedDb, Merkleized as MerkleizedTrait, Shared}; use commonware_cryptography::{Sha256, sha256::Digest}; use commonware_parallel::Sequential; use commonware_runtime::{ Runner as _, Supervisor as _, buffer::paged::CacheRef, deterministic, }; use commonware_storage::{ journal::{ authenticated::Config as MerkleConfig, contiguous::fixed::Config as FixedJournalConfig, }, merkle::mmr, qmdb::immutable::fixed, translator::TwoCap, }; use commonware_utils::{NZU16, NZU64, NZUsize}; type FixedDb = fixed::Db; fn fixed_config(suffix: &str) -> fixed::Config { let page_cache = CacheRef::new(NZU16!(101), NZUsize!(11)); fixed::Config { merkle: MerkleConfig { partition: format!("stateful-immutable-metadata-{suffix}"), replay_buffer: NZUsize!(1024), strategy: Sequential, resident_height: Default::default(), }, log: FixedJournalConfig { partition: format!("stateful-immutable-log-{suffix}"), items_per_blob: NZU64!(7), page_cache, write_buffer: NZUsize!(1024), replay_buffer: NZUsize!(1024), }, translator: TwoCap, init_buffer: NZUsize!(1 << 21), init_concurrency: NZUsize!(2), } } #[test] fn unset_inactivity_floor_inherits_parent_floor() { deterministic::Runner::default().start(|context| async move { let config = fixed_config("inherit-parent-floor"); let db = FixedDb::init(context.child("db"), config, None) .await .unwrap(); let db = Shared::new("test", db); let parent = db .new_batch_for_test::<_>() .await .set(Sha256::hash(&[&[1]]), Sha256::hash(&[&[2]])) .with_inactivity_floor(mmr::Location::new(1)); let parent = crate::stateful::db::Unmerkleized::merkleize(parent) .await .unwrap(); let child = MerkleizedTrait::new_batch(&parent) .set(Sha256::hash(&[&[3]]), Sha256::hash(&[&[4]])); let child = crate::stateful::db::Unmerkleized::merkleize(child) .await .unwrap(); assert_eq!(child.bounds().inactivity_floor, mmr::Location::new(1)); }); } #[test] fn unset_inactivity_floor_inherits_applied_floor() { deterministic::Runner::default().start(|context| async move { let config = fixed_config("inherit-applied-floor"); let db = FixedDb::init(context.child("db"), config, None) .await .unwrap(); let db = Shared::new("test", db); let first = db .new_batch_for_test::<_>() .await .set(Sha256::hash(&[&[1]]), Sha256::hash(&[&[2]])) .with_inactivity_floor(mmr::Location::new(1)); let first = crate::stateful::db::Unmerkleized::merkleize(first) .await .unwrap(); { let (slot, database) = db.write().await; let database = >::apply(database, first) .await .unwrap(); slot.put(database); } let next = db .new_batch_for_test::<_>() .await .set(Sha256::hash(&[&[3]]), Sha256::hash(&[&[4]])); let next = crate::stateful::db::Unmerkleized::merkleize(next) .await .unwrap(); assert_eq!(next.bounds().inactivity_floor, mmr::Location::new(1)); let (slot, database) = db.write().await; let database = >::apply(database, next) .await .unwrap(); assert_eq!(database.inactivity_floor(), mmr::Location::new(1)); slot.put(database); }); } }