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}