//! [`ManagedDb`] and [`StateSyncDb`] implementations for QMDB databases. //! //! Every database that implements [`Qmdb`] gets both traits. Batches add family-specific methods //! to [`Unmerkleized`] and [`Merkleized`]: //! //! - [`any`](commonware_storage::qmdb::any) and [`current`](commonware_storage::qmdb::current) //! batches upsert and delete keys (`write`), read them (`get`, `get_many`), and stage reads //! (`stage`). //! - [`immutable`](commonware_storage::qmdb::immutable) batches accept new keyed values (`set`) //! but no updates or deletions. //! - [`keyless`](commonware_storage::qmdb::keyless) batches are append-only (`append`) and read //! operations by location rather than by key. //! - [`compact`](commonware_storage::qmdb::compact) databases retain only the current Merkle //! peaks. Their batches `append` (keyless operations) or `set` (immutable operations) and //! merkleize, but support no historical reads. //! //! Batch reads consult the database at the time of the read for data their batch chain does not //! hold, and return a `StaleRead` error once the database is at no state of that chain. use super::{ BatchContext, InitError, ManagedDb, Merkleized as MerkleizedTrait, Shared, StateSyncDb, SyncEngineConfig, Unmerkleized as UnmerkleizedTrait, validate_initialization, }; use commonware_runtime::Handle; use commonware_storage::qmdb::{ Error, sync::{self, MerkleizedBatch as _}, }; use commonware_utils::channel::{mpsc, ring}; use std::{future::Future, ops::Deref, sync::Arc}; /// A QMDB database that glue can manage and state-sync. pub trait Qmdb: sync::Database + Sync { /// Storage batch before merkleization. type Batch: Send; /// Storage batch after merkleization. type MerkleizedBatch: sync::MerkleizedBatch + Send + Sync; /// Batch rooted at the applied state. fn new_batch(&self) -> Self::Batch; /// Batch rooted at `parent`. fn new_child(parent: &Arc) -> Self::Batch; /// Merkleize `batch` against the applied state. fn merkleize( &self, batch: Self::Batch, ) -> impl Future, Error>> + Send; /// Apply a merkleized batch. fn apply_batch( self, batch: Arc, ) -> impl Future>> + Send; /// Begin persisting every applied batch. The handle resolves once they are durable. fn start_sync( self, ) -> impl Future), Error>> + Send; } /// A [`Qmdb`] batch before merkleization, reading through to its database's applied state. pub struct Unmerkleized { pub(super) batch: D::Batch, pub(super) db: Shared, } impl Deref for Unmerkleized { type Target = D::Batch; fn deref(&self) -> &D::Batch { &self.batch } } impl UnmerkleizedTrait for Unmerkleized { type Merkleized = Merkleized; type Error = Error; async fn merkleize(self) -> Result, Error> { let Self { batch, db } = self; let inner = { let guard = db.read().await; guard.merkleize(batch).await? }; Ok(Merkleized { inner, db }) } } /// A [`Qmdb`] batch after merkleization, reading through to its database's applied state. pub struct Merkleized { pub(super) inner: Arc, pub(super) db: Shared, } impl Merkleized { /// Sync target reached once this batch is applied. pub fn target(&self) -> sync::Target { self.inner.target() } } impl Clone for Merkleized { fn clone(&self) -> Self { Self { inner: Arc::clone(&self.inner), db: self.db.clone(), } } } impl Deref for Merkleized { type Target = D::MerkleizedBatch; fn deref(&self) -> &D::MerkleizedBatch { &self.inner } } impl MerkleizedTrait for Merkleized { type Digest = D::Digest; type Unmerkleized = Unmerkleized; fn root(&self) -> D::Digest { self.inner.root() } fn new_batch(&self) -> Unmerkleized { Unmerkleized { batch: D::new_child(&self.inner), db: self.db.clone(), } } } impl ManagedDb for D { type Unmerkleized = Unmerkleized; type Merkleized = Merkleized; type Error = Error; type Config = D::Config; type SyncTarget = sync::Target; async fn init( context: D::Context, config: D::Config, expected: Option, ) -> Result> { let db = ::init( context, config, expected.as_ref().map(|target| target.range.end()), ) .await .map_err(InitError::Database)?; validate_initialization(db, expected) } fn initial_sync_target() -> Self::SyncTarget { D::initial_target() } fn new_batch(database: BatchContext<'_, Self>) -> Unmerkleized { let (database, shared) = database.into_parts(); Unmerkleized { batch: Qmdb::new_batch(database), db: shared, } } fn matches_sync_target(batch: &Merkleized, target: &Self::SyncTarget) -> bool { batch.target() == *target } async fn apply(self, batch: Merkleized) -> Result> { Qmdb::apply_batch(self, batch.inner).await } async fn finalize(self) -> Result<(Self, Handle<()>), Error> { Qmdb::start_sync(self).await } async fn prune(self, target: &Self::SyncTarget) -> Result> { sync::Database::prune_to_target(self, target).await } fn sync_target(&self) -> Self::SyncTarget { sync::Database::target(self) } } impl StateSyncDb for D where D: Qmdb, R: sync::SourceFor, { type SyncError = sync::Error; async fn sync_db( context: D::Context, config: D::Config, source: R, target: Self::SyncTarget, tip_updates: ring::Receiver, finish: Option>, reached_target: Option>, sync_config: SyncEngineConfig, ) -> Result { sync::sync(sync::Config { context, source, target, max_outstanding_requests: sync_config.max_outstanding_requests, fetch_batch_size: sync_config.fetch_batch_size, apply_batch_size: sync_config.apply_batch_size, db_config: config, update_rx: Some(tip_updates), finish_rx: finish, reached_target_tx: reached_target, }) .await } }