Skip to main content

tuwunel_database/
txn.rs

1//! Atomic database writes backed by one RocksDB write batch.
2//!
3//! A transaction queues operations for maps owned by one database engine and
4//! commits them only when [`Txn::execute`] consumes it. Typed operations use
5//! the database codec, while raw operations preserve caller-provided bytes.
6
7use std::{
8	error::Error as StdError,
9	fmt::{self, Debug, Display},
10	iter::once,
11	sync::Arc,
12};
13
14use rocksdb::WriteBatch;
15use serde::Serialize;
16use tuwunel_core::{Error, Result, error, implement};
17
18use crate::{
19	Engine, Map,
20	keyval::{Key, Slice, serialize_key, serialize_val},
21	util::or_else,
22};
23
24/// Atomic write batch spanning one or more column families from one database.
25///
26/// Every queued map must belong to the captured engine because column family
27/// identifiers are interpreted within that database. Dropping an unexecuted
28/// transaction leaves the database unchanged.
29#[must_use = "does nothing until execute()"]
30pub struct Txn {
31	batch: WriteBatch,
32	engine: Arc<Engine>,
33}
34
35/// Failure stage of a fallible transaction commit.
36///
37/// A sync failure follows an accepted atomic write, so callers must reconcile
38/// the stored bytes before advancing dependent work.
39#[derive(Debug)]
40pub enum TxnError {
41	/// The engine rejected the batch write.
42	Write(Error),
43
44	/// The batch was accepted but the WAL durability barrier failed.
45	Sync(Error),
46}
47
48/// Record parser yielding each queued key with its resolved map.
49struct Keys<'a> {
50	engine: &'a Engine,
51	data: Key<'a>,
52}
53
54/// Batch representation header: a fixed64 sequence then a fixed32 count.
55const HEADER: usize = 12;
56
57/// Worst-case per-record overhead: a type tag and three varint32s.
58const PER_OP: usize = 16;
59
60/// Record tags per rocksdb `write_batch.cc`; puts and deletes against
61/// column family id 0 encode as the legacy untagged types.
62#[derive(Clone, Copy)]
63enum Tag {
64	Deletion = 0x0,
65	Value = 0x1,
66	CfDeletion = 0x4,
67	CfValue = 0x5,
68}
69
70impl TryFrom<u8> for Tag {
71	type Error = u8;
72
73	fn try_from(byte: u8) -> Result<Self, Self::Error> {
74		match byte {
75			| 0x0 => Ok(Self::Deletion),
76			| 0x1 => Ok(Self::Value),
77			| 0x4 => Ok(Self::CfDeletion),
78			| 0x5 => Ok(Self::CfValue),
79			| unrecognized => Err(unrecognized),
80		}
81	}
82}
83
84impl Display for TxnError {
85	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
86		match self {
87			| Self::Write(error) => write!(f, "transaction write failed: {error}"),
88			| Self::Sync(error) => write!(f, "transaction written but WAL sync failed: {error}"),
89		}
90	}
91}
92
93impl StdError for TxnError {}
94
95impl From<TxnError> for Error {
96	fn from(error: TxnError) -> Self { Self::Std(error.into()) }
97}
98
99/// Creates an empty transaction for one database engine.
100///
101/// Operations can be appended through the typed or raw queueing methods. The
102/// transaction remains inert until [`Txn::execute`] consumes it.
103#[implement(Txn)]
104pub fn new(engine: &Arc<Engine>) -> Self {
105	Self {
106		batch: WriteBatch::default(),
107		engine: engine.clone(),
108	}
109}
110
111/// Creates an empty transaction with reserved batch capacity.
112///
113/// `capacity_bytes` reserves storage for the serialized RocksDB batch
114/// representation. The reservation affects allocation only and does not queue
115/// an operation.
116#[implement(Txn)]
117pub fn with_capacity_bytes(engine: &Arc<Engine>, capacity_bytes: usize) -> Self {
118	Self {
119		batch: WriteBatch::with_capacity_bytes(capacity_bytes),
120		engine: engine.clone(),
121	}
122}
123
124/// Queues raw key and value pairs for one map from a single pass.
125///
126/// The database codec is not applied, and the write batch copies each supplied
127/// byte sequence. Empty input produces an empty transaction whose execution is
128/// a no-op.
129#[implement(Txn)]
130pub fn insert<I, K, V>(map: &Map, items: I) -> Self
131where
132	I: IntoIterator<Item = (K, V)>,
133	K: AsRef<Slice>,
134	V: AsRef<Slice>,
135{
136	items
137		.into_iter()
138		.fold(Self::new(map.engine()), |mut txn, (key, val)| {
139			txn.insert_raw(map, key, val);
140			txn
141		})
142}
143
144/// Queues a raw slice for one map with a precomputed capacity estimate.
145///
146/// The estimate includes payload lengths and worst-case record overhead before
147/// the items are copied into the write batch. Empty input produces an empty
148/// transaction.
149#[implement(Txn)]
150pub fn insert_slice<K, V>(map: &Map, items: &[(K, V)]) -> Self
151where
152	K: AsRef<Slice>,
153	V: AsRef<Slice>,
154{
155	let capacity_bytes = size_hint(items.iter().map(|(key, val)| (key, val)));
156
157	items.iter().fold(
158		Self::with_capacity_bytes(map.engine(), capacity_bytes),
159		|mut txn, (key, val)| {
160			txn.insert_raw(map, key, val);
161			txn
162		},
163	)
164}
165
166/// Queues raw entries across maps from a nonempty single pass.
167///
168/// The first item selects the database engine, and every subsequent map must
169/// belong to that same engine. The database codec is not applied to keys or
170/// values.
171///
172/// # Panics
173///
174/// Panics when `items` is empty or when any map belongs to a different database
175/// engine.
176#[implement(Txn)]
177pub fn insert_each<'a, I, K, V>(items: I) -> Self
178where
179	I: IntoIterator<Item = (&'a Map, K, V)>,
180	K: AsRef<Slice>,
181	V: AsRef<Slice>,
182{
183	let mut items = items.into_iter();
184	let (map, key, val) = items
185		.next()
186		.expect("insert_each: at least one item");
187
188	let mut txn = Self::new(map.engine());
189
190	txn.insert_raw(map, key, val);
191	txn.extend(items);
192
193	txn
194}
195
196/// Queues a nonempty raw slice across maps with a capacity estimate.
197///
198/// The first item selects the database engine, and every map must belong to
199/// that same engine. The database codec is not applied to keys or values.
200///
201/// # Panics
202///
203/// Panics when `items` is empty or when any map belongs to a different database
204/// engine.
205#[implement(Txn)]
206pub fn insert_each_slice<K, V>(items: &[(&Map, K, V)]) -> Self
207where
208	K: AsRef<[u8]>,
209	V: AsRef<[u8]>,
210{
211	let map = items
212		.first()
213		.expect("insert_each_slice: at least one item")
214		.0;
215
216	let capacity_bytes = size_hint(items.iter().map(|(_, key, val)| (key, val)));
217
218	let mut txn = Self::with_capacity_bytes(map.engine(), capacity_bytes);
219
220	txn.extend(
221		items
222			.iter()
223			.map(|(map, key, val)| (*map, key, val)),
224	);
225
226	txn
227}
228
229/// Serializes and queues entries across maps from a nonempty pass.
230///
231/// The first item selects the database engine, and every map must belong to
232/// that same engine. All keys and values are encoded with the database record
233/// codec before being copied into the batch.
234///
235/// # Panics
236///
237/// Panics when `items` is empty, a map belongs to another database engine, or
238/// serialization of a key or value fails.
239#[implement(Txn)]
240pub fn put_each<'a, I, K, V>(items: I) -> Self
241where
242	I: IntoIterator<Item = (&'a Map, K, V)>,
243	K: Serialize + Debug,
244	V: Serialize,
245{
246	let mut items = items.into_iter();
247	let (map, key, val) = items.next().expect("put_each: at least one item");
248	let txn = Self::new(map.engine());
249
250	once((map, key, val))
251		.chain(items)
252		.fold(txn, |mut txn, (map, key, val)| {
253			txn.put(map, key, val);
254			txn
255		})
256}
257
258/// Serializes and queues one insertion.
259///
260/// The key and value use the database record codec, and the operation remains
261/// pending until [`Txn::execute`]. The map must belong to the transaction's
262/// database engine.
263///
264/// # Panics
265///
266/// Panics when the map belongs to another database engine or serialization of
267/// the key or value fails.
268#[implement(Txn)]
269pub fn put<K, V>(&mut self, map: &Map, key: K, val: V)
270where
271	K: Serialize + Debug,
272	V: Serialize,
273{
274	self.assert_map(map);
275
276	let key = serialize_key(key).expect("failed to serialize batch key");
277	let val = serialize_val(val).expect("failed to serialize batch val");
278
279	self.batch.put_cf(&map.cf(), key, val);
280}
281
282/// Serializes the key and queues one raw-value insertion.
283///
284/// The key uses the database record codec, while the value bytes are copied
285/// unchanged into the batch. The operation remains pending until
286/// [`Txn::execute`], and the map must belong to the transaction's database
287/// engine.
288///
289/// # Panics
290///
291/// Panics when the map belongs to another database engine or serialization of
292/// the key fails.
293#[implement(Txn)]
294pub fn put_raw<K, V>(&mut self, map: &Map, key: K, val: V)
295where
296	K: Serialize + Debug,
297	V: AsRef<Slice>,
298{
299	self.assert_map(map);
300
301	let key = serialize_key(key).expect("failed to serialize batch key");
302
303	self.batch.put_cf(&map.cf(), key, val);
304}
305
306/// Queues one raw-key insertion after serializing the value.
307///
308/// The key bytes are copied unchanged into the batch, while the value uses the
309/// database record codec. The operation remains pending until [`Txn::execute`],
310/// and the map must belong to the transaction's database engine.
311///
312/// # Panics
313///
314/// Panics when the map belongs to another database engine or serialization of
315/// the value fails.
316#[implement(Txn)]
317pub fn raw_put<K, V>(&mut self, map: &Map, key: K, val: V)
318where
319	K: AsRef<Slice>,
320	V: Serialize,
321{
322	self.assert_map(map);
323
324	let val = serialize_val(val).expect("failed to serialize batch val");
325
326	self.batch.put_cf(&map.cf(), key, val);
327}
328
329/// Serializes and queues one deletion.
330///
331/// The key uses the database record codec, and the operation remains pending
332/// until [`Txn::execute`]. The map must belong to the transaction's database
333/// engine.
334///
335/// # Panics
336///
337/// Panics when the map belongs to another database engine or serialization of
338/// the key fails.
339#[implement(Txn)]
340pub fn del<K>(&mut self, map: &Map, key: K)
341where
342	K: Serialize + Debug,
343{
344	self.assert_map(map);
345
346	let key = serialize_key(key).expect("failed to serialize batch key");
347
348	self.batch.delete_cf(&map.cf(), key);
349}
350
351/// Queues one deletion for an already serialized key.
352///
353/// The key bytes are copied into the write batch without invoking the database
354/// codec. The map must belong to the transaction's database engine.
355///
356/// # Panics
357///
358/// Panics when the map belongs to another database engine.
359#[implement(Txn)]
360pub fn del_raw<K>(&mut self, map: &Map, key: K)
361where
362	K: AsRef<Slice>,
363{
364	self.assert_map(map);
365	self.batch.delete_cf(&map.cf(), key);
366}
367
368/// Commits the batch atomically, flushes unless corked, and notifies matching
369/// watchers.
370///
371/// An empty transaction returns without touching the engine. For a nonempty
372/// batch, notifications occur only after the write, and a failed flush is
373/// logged instead of panicking.
374///
375/// # Panics
376///
377/// Panics when RocksDB rejects the batch write.
378#[implement(Txn)]
379#[inline]
380pub fn execute(self) {
381	if self.is_empty() {
382		return;
383	}
384
385	self.commit();
386}
387
388/// Commits an atomic batch and explicitly synchronizes the WAL to disk.
389///
390/// Unlike [`Txn::execute`], the durability barrier runs even while corked.
391/// Watchers are notified after an accepted write, including a failed sync.
392/// Empty batches perform neither a write nor a sync.
393#[implement(Txn)]
394#[tracing::instrument(level = "trace", skip_all)]
395pub fn try_execute(self) -> Result<(), TxnError> {
396	if self.is_empty() {
397		return Ok(());
398	}
399
400	self.write().map_err(TxnError::Write)?;
401	let synced = self.sync().map_err(TxnError::Sync);
402
403	self.notify();
404	synced
405}
406
407/// Commits an atomic batch and leaves its durability barrier to the caller.
408///
409/// A rejected write is returned and watchers are notified after an accepted
410/// one, as in [`Txn::try_execute`]. Nothing is flushed or synchronized, so a
411/// run of these batches ends with [`Engine::sync`] before any write that
412/// depends on them. Empty batches perform no write.
413#[implement(Txn)]
414#[tracing::instrument(level = "trace", skip_all, err)]
415pub fn try_write(self) -> Result {
416	if self.is_empty() {
417		return Ok(());
418	}
419
420	self.write().inspect(|()| self.notify())
421}
422
423#[implement(Txn)]
424#[tracing::instrument(level = "trace", skip_all)]
425fn write(&self) -> Result {
426	self.engine
427		.db
428		.write_opt(&self.batch, &self.engine.write_options)
429		.or_else(or_else)
430}
431
432#[implement(Txn)]
433#[tracing::instrument(level = "trace", skip_all)]
434fn sync(&self) -> Result { self.engine.sync() }
435
436/// Commits the batch atomically, flushes unless corked, and notifies matchers.
437///
438/// Batch must not be empty. Notifications occur only after the write, and a
439/// failed flush is logged instead of panicking.
440///
441/// # Panics
442///
443/// Panics when RocksDB rejects the batch write.
444#[implement(Txn)]
445#[tracing::instrument(
446	level = "trace",
447	skip_all,
448	fields(
449		ops = self.len(),
450		bytes = self.size_in_bytes(),
451	)
452)]
453fn commit(self) {
454	debug_assert!(!self.is_empty(), "Txn must not be empty.");
455
456	self.write()
457		.expect("database transaction execute error");
458
459	if !self.engine.corked() {
460		self.engine
461			.flush()
462			.inspect_err(|e| error!(?e, "database flush error"))
463			.ok();
464	}
465
466	self.notify();
467}
468
469/// Notifies watchers after a successful commit for queued keys that resolve to
470/// catalog maps.
471///
472/// Keys are parsed lazily from the batch representation and consumed in queue
473/// order. Operations without a live map in the engine's startup catalog are
474/// skipped.
475#[implement(Txn)]
476fn notify(&self) {
477	for (map, key) in self.keys() {
478		map.notify(key);
479	}
480}
481
482/// Iterate queued put and delete keys in insertion order.
483///
484/// The iterator borrows keys directly from the serialized write batch without
485/// materializing a container. Keys whose column families are outside the
486/// startup map catalog are omitted.
487///
488/// # Panics
489///
490/// Iteration panics if a record has an unsupported operation tag, is truncated,
491/// or contains a varint whose fifth byte retains its continuation bit.
492#[implement(Txn)]
493pub fn keys(&self) -> impl Iterator<Item = (Arc<Map>, &Slice)> + '_ {
494	let data = self.batch.data();
495
496	Keys {
497		engine: &self.engine,
498		data: data.get(HEADER..).unwrap_or_default(),
499	}
500}
501
502/// Returns the number of operations queued in the batch.
503///
504/// Both insertions and deletions count as one operation. Inspecting the count
505/// does not execute the transaction.
506#[implement(Txn)]
507#[inline]
508#[must_use]
509pub fn len(&self) -> usize { self.batch.len() }
510
511/// Reports whether the batch contains no queued operations.
512///
513/// A newly created or cleared transaction is empty. Executing an empty
514/// transaction performs no database work.
515#[implement(Txn)]
516#[inline]
517#[must_use]
518pub fn is_empty(&self) -> bool { self.batch.is_empty() }
519
520/// Returns the encoded size of the RocksDB write batch in bytes.
521///
522/// The size includes batch metadata and queued record data. Inspecting it does
523/// not execute the transaction.
524#[implement(Txn)]
525#[inline]
526#[must_use]
527pub fn size_in_bytes(&self) -> usize { self.batch.size_in_bytes() }
528
529/// Removes every queued operation from the transaction.
530///
531/// The captured database engine remains attached, so the transaction can be
532/// populated again. Executing it before another operation is queued is a no-op.
533#[implement(Txn)]
534#[inline]
535pub fn clear(&mut self) { self.batch.clear(); }
536
537/// Queue one unencoded key and value after enforcing map ownership.
538///
539/// Both byte sequences are copied into the write batch without invoking the
540/// database codec. The operation remains pending until [`Txn::execute`].
541///
542/// # Panics
543///
544/// Panics when the map belongs to another database engine.
545#[implement(Txn)]
546pub fn insert_raw<K, V>(&mut self, map: &Map, key: K, val: V)
547where
548	K: AsRef<Slice>,
549	V: AsRef<Slice>,
550{
551	self.assert_map(map);
552	self.batch.put_cf(&map.cf(), key, val);
553}
554
555/// Verifies that a map belongs to the transaction's database engine.
556///
557/// RocksDB identifies column families numerically within one database, so
558/// accepting a foreign map could target a same-numbered column family in the
559/// captured engine.
560///
561/// # Panics
562///
563/// Panics when `map` belongs to a different database engine.
564#[implement(Txn)]
565#[inline]
566fn assert_map(&self, map: &Map) {
567	assert!(
568		Arc::ptr_eq(&self.engine, map.engine()),
569		"transaction map belongs to a different database"
570	);
571}
572
573impl<'a> Iterator for Keys<'a> {
574	type Item = (Arc<Map>, Key<'a>);
575
576	fn next(&mut self) -> Option<Self::Item> {
577		while !self.data.is_empty() {
578			let (cf_id, key) =
579				next_record(&mut self.data).expect("malformed write batch representation");
580
581			if let Some(map) = self.engine.map_by_cf_id(cf_id) {
582				return Some((map, key));
583			}
584		}
585
586		None
587	}
588}
589
590/// Extends this transaction with raw insertions across maps.
591///
592/// Each tuple queues its raw key and value through [`Txn::insert_raw`]. Use
593/// [`Txn::put_each`] when the keys and values need serialization. Every map
594/// must belong to the transaction's database engine.
595///
596/// # Panics
597///
598/// Panics when any map belongs to another database engine.
599impl<'a, K, V> Extend<(&'a Map, K, V)> for Txn
600where
601	K: AsRef<Slice>,
602	V: AsRef<Slice>,
603{
604	fn extend<I>(&mut self, items: I)
605	where
606		I: IntoIterator<Item = (&'a Map, K, V)>,
607	{
608		for (map, key, val) in items {
609			self.insert_raw(map, key, val);
610		}
611	}
612}
613
614/// Extends this transaction with raw-key deletions across maps.
615///
616/// Each tuple queues its raw key through [`Txn::del_raw`]. Every map must
617/// belong to the transaction's database engine.
618///
619/// # Panics
620///
621/// Panics when any map belongs to another database engine.
622impl<'a, K> Extend<(&'a Map, K)> for Txn
623where
624	K: AsRef<Slice>,
625{
626	fn extend<I>(&mut self, items: I)
627	where
628		I: IntoIterator<Item = (&'a Map, K)>,
629	{
630		for (map, key) in items {
631			self.del_raw(map, key);
632		}
633	}
634}
635
636/// Decodes one record into its column family identifier and borrowed key.
637///
638/// Value payloads are skipped after their lengths are consumed. Unsupported
639/// tags, truncated fields, and varints whose fifth byte retains its
640/// continuation bit return `None` and may leave the input advanced through the
641/// parsed prefix.
642pub(crate) fn next_record<'a>(data: &mut Key<'a>) -> Option<(u32, Key<'a>)> {
643	let (&tag, rest) = data.split_first()?;
644	*data = rest;
645
646	let tag = Tag::try_from(tag).ok()?;
647
648	let cf_id = match tag {
649		| Tag::Value | Tag::Deletion => 0,
650		| Tag::CfValue | Tag::CfDeletion => take_varint32(data)?,
651	};
652
653	let key = take_varstring(data)?;
654
655	if matches!(tag, Tag::Value | Tag::CfValue) {
656		take_varstring(data)?;
657	}
658
659	Some((cf_id, key))
660}
661
662/// Takes one length-prefixed byte string from the front of a batch record.
663///
664/// The returned slice borrows the original batch representation, and `data`
665/// advances past it. Invalid lengths or truncated input return `None`.
666fn take_varstring<'a>(data: &mut Key<'a>) -> Option<Key<'a>> {
667	let len = take_varint32(data)?.try_into().ok()?;
668
669	let (string, rest) = data.split_at_checked(len)?;
670	*data = rest;
671
672	Some(string)
673}
674
675/// Takes one RocksDB varint32 from the front of a batch record.
676///
677/// The parser consumes at most five bytes and advances `data` as bytes are
678/// read. A missing byte or a continuation bit on the fifth byte returns `None`.
679fn take_varint32(data: &mut &Slice) -> Option<u32> {
680	let mut result = 0_u32;
681
682	for shift in (0_u32..32).step_by(7) {
683		let (&byte, rest) = data.split_first()?;
684		*data = rest;
685		result |= u32::from(byte & 0x7F).checked_shl(shift)?;
686
687		if byte & 0x80 == 0 {
688			return Some(result);
689		}
690	}
691
692	None
693}
694
695/// Estimates write-batch capacity for a reusable sequence of raw pairs.
696///
697/// The estimate includes the fixed header, worst-case per-operation metadata,
698/// and payload lengths. Saturating arithmetic prevents an oversized input from
699/// wrapping the reservation.
700fn size_hint<'a, K, V, I>(items: I) -> usize
701where
702	I: Iterator<Item = (&'a K, &'a V)>,
703	K: AsRef<Slice> + 'a,
704	V: AsRef<Slice> + 'a,
705{
706	items.fold(HEADER, |capacity_bytes, (key, val)| {
707		capacity_bytes
708			.saturating_add(PER_OP)
709			.saturating_add(key.as_ref().len())
710			.saturating_add(val.as_ref().len())
711	})
712}