inferadb_ledger_store/
lib.rs

1//! inferadb-ledger-store: A purpose-built embedded storage engine for InferaDB.
2//!
3//! B+ tree storage engine designed for InferaDB's specific requirements:
4//!
5//! - **Fixed schema**: All tables known at compile time (see [`TableId`])
6//! - **Single writer**: Leverages Raft's serialization (no write-write MVCC needed)
7//! - **Raft-friendly**: Optimized for append-heavy Raft log access patterns
8//! - **Checksummed pages**: Crash safety with XXH3-64 verification
9//! - **Dual-slot commit**: Atomic commits via shadow paging (no WAL)
10//!
11//! ## Architecture
12//!
13//! ```text
14//! ┌─────────────────────────────────────────────┐
15//! │                Database API                  │
16//! │     (open, read, write, commit, etc.)       │
17//! └────────────────┬────────────────────────────┘
18//!                  │
19//! ┌────────────────▼────────────────────────────┐
20//! │             Transaction Layer                │
21//! │  (ReadTxn: snapshot, WriteTxn: COW+commit)  │
22//! └────────────────┬────────────────────────────┘
23//!                  │
24//! ┌────────────────▼────────────────────────────┐
25//! │              B+ Tree Layer                   │
26//! │  (get, insert, delete, range, compact)      │
27//! └────────────────┬────────────────────────────┘
28//!                  │
29//! ┌────────────────▼────────────────────────────┐
30//! │              Page Layer                      │
31//! │  (allocator, cache, checksum, COW)          │
32//! └────────────────┬────────────────────────────┘
33//!                  │
34//! ┌────────────────▼────────────────────────────┐
35//! │            Storage Backend                   │
36//! │      (FileBackend / InMemoryBackend)        │
37//! └─────────────────────────────────────────────┘
38//! ```
39//!
40//! ## Quick Start
41//!
42//! ```no_run
43//! use inferadb_ledger_store::{Database, DatabaseConfig};
44//! use inferadb_ledger_store::tables::Entities;
45//!
46//! // Create an in-memory database
47//! let db = Database::open_in_memory()?;
48//!
49//! // Write transaction
50//! let mut txn = db.write()?;
51//! txn.insert::<Entities>(&b"key".to_vec(), &b"value".to_vec())?;
52//! txn.commit()?;
53//!
54//! // Read transaction
55//! let txn = db.read()?;
56//! let value = txn.get::<Entities>(&b"key".to_vec())?;
57//! # Ok::<(), inferadb_ledger_store::Error>(())
58//! ```
59
60#![deny(unsafe_code)]
61#![warn(missing_docs)]
62#![warn(clippy::all)]
63// `.unwrap()` is in the project's disallowed_methods list. All uses in this crate are infallible:
64// - try_into().unwrap() on slices with pre-validated sizes (e.g., u16::from_le_bytes)
65// - write_all().unwrap() on growable Vec<u8> buffers
66#![allow(clippy::disallowed_methods)]
67// Explicit drops used for clarity in COW page management (releasing borrows)
68#![allow(clippy::drop_non_drop)]
69// Test code style - allow field reassignment after default
70#![cfg_attr(test, allow(clippy::field_reassign_with_default))]
71// B+ tree operations use complex return types for split propagation
72#![allow(clippy::type_complexity)]
73// Low-level page arithmetic uses explicit bounds checking for clarity
74#![allow(clippy::manual_range_contains)]
75#![allow(clippy::implicit_saturating_sub)]
76
77/// Storage backend abstraction (file-based and in-memory implementations).
78pub mod backend;
79pub(crate) mod bloom;
80/// B+ tree index structure with get, insert, delete, range, and compaction operations.
81pub mod btree;
82/// Envelope encryption for data at rest (AES-256-GCM + AES-KWP).
83pub mod crypto;
84/// Database API: open, read, write, commit, and iteration.
85pub mod db;
86/// Bitmap for tracking pages modified since the last backup checkpoint.
87pub mod dirty_bitmap;
88/// Error types and result aliases for the store crate.
89pub mod error;
90/// Integrity scrubbing for detecting page-level corruption.
91pub mod integrity;
92/// Page management: allocation, caching, checksums, and copy-on-write.
93pub mod page;
94/// Compile-time table definitions mapping logical tables to B+ tree instances.
95pub mod tables;
96/// Transaction tracking and snapshot management for copy-on-write semantics.
97pub mod transaction;
98/// Key and value type definitions used across the storage engine.
99pub mod types;
100
101// Re-export commonly used types
102pub use backend::{
103    DEFAULT_PAGE_SIZE, DatabaseHeader, FileBackend, HEADER_SIZE, InMemoryBackend, MAGIC,
104    StorageBackend,
105};
106pub use btree::{BTree, CompactionStats, PageProvider};
107pub use db::{
108    Database, DatabaseConfig, DatabaseStats, ReadTransaction, TableIterator, WriteTransaction,
109};
110pub use dirty_bitmap::DirtyBitmap;
111pub use error::{Error, PageId, PageType, Result};
112pub use integrity::{IntegrityScrubber, ScrubError, ScrubResult};
113pub use page::{PAGE_HEADER_SIZE, Page, PageAllocator, PageCache};
114pub use tables::{Table, TableEntry, TableId};
115pub use types::{Key, KeyType, Value};
116
117/// Crate API version. For on-disk format version, see [`backend::FORMAT_VERSION`].
118pub const VERSION: u16 = 1;
inferadb_ledger_store/lib.rs

inferadb_ledger_store/
lib.rs
