massa_db_exports/
controller.rs

1use crate::{DBBatch, Key, MassaDBError, StreamBatch, Value};
2use massa_hash::{HashXof, HASH_XOF_SIZE_BYTES};
3use massa_models::{error::ModelsError, slot::Slot, streaming_step::StreamingStep};
4use parking_lot::RwLock;
5use std::path::PathBuf;
6use std::{fmt::Debug, sync::Arc};
7
8#[cfg(feature = "test-exports")]
9use std::collections::BTreeMap;
10
11pub type ShareableMassaDBController = Arc<RwLock<Box<dyn MassaDBController>>>;
12
13/// Controller trait for the MassaDB
14/// TODO: MOCK IT WITH MOCKALL. HAVING LIFETIMES ERRORS WITH AUTO MOCK
15pub trait MassaDBController: Send + Sync + Debug {
16    /// Creates a new hard copy of the DB, for the given slot
17    fn backup_db(&self, slot: Slot) -> PathBuf;
18
19    /// Get the current change_id attached to the database.
20    fn get_change_id(&self) -> Result<Slot, ModelsError>;
21
22    /// Set the initial change_id. This function should only be called at startup/reset, as it does not batch this set with other changes.
23    fn set_initial_change_id(&self, change_id: Slot);
24
25    /// Writes the batch to the DB
26    fn write_batch(&mut self, batch: DBBatch, versioning_batch: DBBatch, change_id: Option<Slot>);
27
28    /// Utility function to put / update a key & value in the batch
29    fn put_or_update_entry_value(&self, batch: &mut DBBatch, key: Vec<u8>, value: &[u8]);
30
31    /// Utility function to delete a key & value in the batch
32    fn delete_key(&self, batch: &mut DBBatch, key: Vec<u8>);
33
34    /// Utility function to delete all keys in a prefix
35    fn delete_prefix(&mut self, prefix: &str, handle_str: &str, change_id: Option<Slot>);
36
37    /// Reset the database, and attach it to the given slot.
38    /// Note that this does not clear the db's content, only the change_id and the history.
39    fn reset_slot_and_history(&mut self, slot: Slot);
40
41    /// Exposes RocksDB's "get_cf" function
42    fn get_cf(&self, handle_cf: &str, key: Key) -> Result<Option<Value>, MassaDBError>;
43
44    /// Exposes RocksDB's "multi_get_cf" function
45    fn multi_get_cf(&self, query: Vec<(&str, Key)>) -> Vec<Result<Option<Value>, MassaDBError>>;
46
47    /// Exposes RocksDB's "iterator_cf" function, without filling up the read cache
48    fn iterator_cf_for_full_db_traversal(
49        &self,
50        handle_cf: &str,
51        mode: MassaIteratorMode,
52    ) -> Box<dyn Iterator<Item = (Key, Value)> + '_>;
53
54    /// Exposes RocksDB's "iterator_cf" function
55    fn iterator_cf(
56        &self,
57        handle_cf: &str,
58        mode: MassaIteratorMode,
59    ) -> Box<dyn Iterator<Item = (Key, Value)> + '_>;
60
61    /// Exposes RocksDB's "prefix_iterator_cf" function
62    fn prefix_iterator_cf(
63        &self,
64        handle_cf: &str,
65        prefix: &[u8],
66    ) -> Box<dyn Iterator<Item = (Key, Value)> + '_>;
67
68    /// Get the current extended state hash of the database
69    ///
70    /// # Security
71    ///
72    /// This is an incremental fingerprint, NOT a collision-resistant commitment.
73    /// It is the XOR of `HashXof(key ‖ value)` over every row of the state, which is
74    /// linear over GF(2): any 4,097 distinct rows contain a non-empty subset that XORs
75    /// to zero, and Gaussian elimination finds it offline. Distinct states can thus be
76    /// crafted to share the same fingerprint, or to reach a chosen value.
77    ///
78    /// It is fine for detecting accidental divergence, and as the cycle snapshot mixed
79    /// into the PoS draw seed (combined there with the later `rng_seed`, see
80    /// `PoSFinalState::feed_selector`). Do not use it as a binding commitment to the
81    /// state (trust-minimized bootstrap, state proofs, snapshot verification): that
82    /// needs a different construction, gated behind `MipComponent::FinalStateHashKind`.
83    fn get_xof_db_hash(&self) -> HashXof<HASH_XOF_SIZE_BYTES>;
84
85    /// Flushes the underlying db.
86    fn flush(&self) -> Result<(), MassaDBError>;
87
88    /// Write a stream_batch of database entries received from a bootstrap server
89    fn write_batch_bootstrap_client(
90        &mut self,
91        stream_changes: StreamBatch<Slot>,
92        stream_changes_versioning: StreamBatch<Slot>,
93    ) -> Result<(StreamingStep<Key>, StreamingStep<Key>), MassaDBError>;
94
95    /// Used for bootstrap servers (get a new batch of data from STATE_CF to stream to the client)
96    ///
97    /// Returns a StreamBatch<Slot>
98    fn get_batch_to_stream(
99        &self,
100        last_state_step: &StreamingStep<Vec<u8>>,
101        last_change_id: Option<Slot>,
102    ) -> Result<StreamBatch<Slot>, MassaDBError>;
103
104    /// Used for bootstrap servers (get a new batch of data from VERSIONING_CF to stream to the client)
105    ///
106    /// Returns a StreamBatch<Slot>
107    fn get_versioning_batch_to_stream(
108        &self,
109        last_versioning_step: &StreamingStep<Vec<u8>>,
110        last_change_id: Option<Slot>,
111    ) -> Result<StreamBatch<Slot>, MassaDBError>;
112
113    /// Get the total size of the change history and the change versioning history respectively
114    fn get_change_history_sizes(&self) -> (usize, usize);
115
116    /// Used in test to compare a prebuilt ledger with a ledger that has been built by the code
117    #[cfg(feature = "test-exports")]
118    fn get_entire_database(&self) -> Vec<BTreeMap<Vec<u8>, Vec<u8>>>;
119}
120
121/// Similar to RocksDB's IteratorMode
122pub enum MassaIteratorMode<'a> {
123    Start,
124    End,
125    From(&'a [u8], MassaDirection),
126}
127
128/// Similar to RocksDB's Direction
129pub enum MassaDirection {
130    Forward,
131    Reverse,
132}