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}