Skip to main content

tuwunel_database/
mod.rs

1//! Persistent storage primitives for Tuwunel.
2//!
3//! The crate wraps RocksDB with typed maps, serialization helpers, and atomic
4//! transactions. Database handles expose the configured column families and the
5//! engine that owns them.
6
7#![deny(missing_docs)]
8
9extern crate rust_rocksdb as rocksdb;
10
11tuwunel_core::mod_ctor! {}
12tuwunel_core::mod_dtor! {}
13tuwunel_core::rustc_flags_capture! {}
14
15mod cork;
16mod de;
17mod deserialized;
18mod engine;
19mod handle;
20pub mod keyval;
21mod map;
22pub mod maps;
23mod pool;
24mod ser;
25mod stream;
26#[cfg(test)]
27mod tests;
28mod txn;
29pub(crate) mod util;
30
31use std::{ops::Index, sync::Arc};
32
33use log as _;
34use tuwunel_core::{Result, Server, err};
35
36pub use self::{
37	cork::Cork,
38	de::{Ignore, IgnoreAll, from_slice as deserialize_from_slice},
39	deserialized::Deserialized,
40	engine::Engine,
41	handle::Handle,
42	keyval::{KeyBuf, KeyVal, Slice, deserialize_key, serialize_key, serialize_val},
43	map::{Get, Map, MapId, Qry, compact},
44	ser::{Cbor, Interfix, Json, SEP, Separator, serialize, serialize_to, serialize_to_vec},
45	txn::{Txn, TxnError},
46};
47pub(crate) use self::{engine::context::Context, util::or_else};
48use crate::maps::{Indexed, Maps, MapsKey, MapsVal, open as open_maps};
49
50/// An open Tuwunel database and its configured maps.
51///
52/// Each instance owns maps created by one RocksDB engine. Typed accessors
53/// preserve that ownership relationship for individual reads and atomic
54/// transactions.
55pub struct Database {
56	maps: Maps,
57	indexed: Indexed,
58	/// The RocksDB engine backing every map in this database.
59	///
60	/// Callers use the engine for database-wide operations such as backups and
61	/// memory reporting. Maps and transactions must remain associated with
62	/// this same engine.
63	pub engine: Arc<Engine>,
64	pub(crate) _ctx: Arc<Context>,
65}
66
67impl Database {
68	/// Loads an existing database or creates a new one.
69	///
70	/// The configured map catalog is opened after the engine and indexed by
71	/// column family identity. The returned shared handle keeps the engine
72	/// context alive for its full lifetime.
73	pub async fn open(server: &Arc<Server>) -> Result<Arc<Self>> {
74		let ctx = Context::new(server)?;
75		let engine = Engine::open(ctx.clone(), maps::MAPS).await?;
76		let (maps, indexed) = open_maps(&engine)?;
77		let cf_index = maps
78			.values()
79			.map(|map| (map.cf_id(), Arc::downgrade(map)))
80			.collect();
81
82		engine.set_cf_index(cf_index);
83
84		Ok(Arc::new(Self { maps, indexed, engine, _ctx: ctx }))
85	}
86
87	#[inline]
88	/// Creates an empty transaction for this database.
89	///
90	/// The transaction is bound to this database's engine and accepts writes
91	/// only for maps owned by that engine. Queued operations remain unapplied
92	/// until the transaction is executed.
93	pub fn txn(&self) -> Txn { Txn::new(&self.engine) }
94
95	#[inline]
96	/// Retrieves a configured map by name.
97	///
98	/// The returned map belongs to this database's engine. An unknown name
99	/// produces a not-found database error.
100	pub fn get(&self, name: &str) -> Result<&Arc<Map>> {
101		self.maps
102			.get(name)
103			.ok_or_else(|| err!(Request(NotFound("column not found"))))
104	}
105
106	/// Opens an existing column family outside the configured map catalog.
107	///
108	/// Migration readers use this for foreign database families that are not
109	/// described by `MAPS`, and an integrity walk for every family at all. An
110	/// absent family returns `None` without creating it.
111	pub fn open_cf(&self, name: &str) -> Result<Option<Arc<Map>>> {
112		self.engine
113			.has_cf(name)
114			.then(|| Map::open(&self.engine, name))
115			.transpose()
116	}
117
118	#[inline]
119	/// Iterates over configured map names and handles.
120	///
121	/// Entries follow the catalog's sorted map order. Every yielded handle
122	/// belongs to this database's engine.
123	pub fn iter(&self) -> impl Iterator<Item = (&MapsKey, &MapsVal)> + Send + '_ {
124		self.maps.iter()
125	}
126
127	#[inline]
128	/// Iterates over the configured map names.
129	///
130	/// Names follow the catalog's sorted map order. The iterator borrows this
131	/// database for the duration of the traversal.
132	pub fn keys(&self) -> impl Iterator<Item = &MapsKey> + Send + '_ { self.maps.keys() }
133
134	/// Iterates over the open column families this build's catalog omits.
135	///
136	/// Such a family holds data from another server or an older schema. The
137	/// iterator owns its names, in no particular order, and skips RocksDB's
138	/// unused `default` family.
139	pub fn undescribed(&self) -> impl Iterator<Item = String> + Send + '_ {
140		self.engine
141			.column_names()
142			.filter(|name| name != "default")
143			.filter(|name| !self.maps.contains_key(name.as_str()))
144	}
145
146	#[inline]
147	#[must_use]
148	/// Reports whether the engine rejects writes.
149	///
150	/// Writes are rejected when the database is opened read-only or as a
151	/// secondary instance. The value applies to every map owned by this
152	/// database.
153	pub fn is_read_only(&self) -> bool { self.engine.is_read_only() }
154
155	#[inline]
156	#[must_use]
157	/// Reports whether this database is a secondary RocksDB instance.
158	///
159	/// A secondary instance follows another database and does not act as its
160	/// primary writer. The value applies to every map owned by this database.
161	pub fn is_secondary(&self) -> bool { self.engine.is_secondary() }
162}
163
164impl Index<MapId> for Database {
165	type Output = Arc<Map>;
166
167	#[inline]
168	fn index(&self, id: MapId) -> &Self::Output {
169		self.indexed[id.0]
170			.as_ref()
171			.expect("column in database does not exist")
172	}
173}
174
175impl Index<&str> for Database {
176	type Output = Arc<Map>;
177
178	/// Retrieves a configured map by name.
179	///
180	/// Indexing offers concise access when the map name is a static database
181	/// invariant. Use [`Database::get`] when absence should be handled as an
182	/// error.
183	///
184	/// # Panics
185	///
186	/// Panics if this database has no configured map with the requested name.
187	fn index(&self, name: &str) -> &Self::Output {
188		self.maps
189			.get(name)
190			.expect("column in database does not exist")
191	}
192}