varvedb/
lib.rs

1// This file is part of VarveDB.
2//
3// Copyright (C) 2025 Matheus Cardoso <varvedb@matheus.sbs>
4//
5// This Source Code Form is subject to the terms of the Mozilla Public License
6// v. 2.0. If a copy of the MPL was not distributed with this file, You can
7// obtain one at http://mozilla.org/MPL/2.0/.
8
9//! # VarveDB
10//!
11//! A high-performance, embedded, append-only event store.
12//!
13//! VarveDB provides a persistent, ACID-compliant event log optimized for high-throughput event sourcing.
14//! It is built on top of [LMDB](http://www.lmdb.tech/doc/) (via `heed`) for reliable transaction support
15//! and uses [rkyv](https://rkyv.org/) for zero-copy deserialization, ensuring minimal overhead during reads.
16//!
17//! ## Features
18//!
19//! *   **Zero-Copy Access**: Events are mapped directly from disk to memory, avoiding costly deserialization steps (when encryption is disabled).
20//! *   **Optimistic Concurrency**: Writes are guarded by stream versions, preventing race conditions in concurrent environments.
21//! *   **Reactive Interface**: Real-time event subscriptions via `tokio::watch`.
22//! *   **Authenticated Encryption**: Optional per-stream encryption (AES-256-GCM) with AAD binding to prevent tampering and replay attacks.
23//! *   **GDPR Compliance**: Built-in crypto-shredding support via key deletion.
24//!
25//! ## Example
26//!
27//! ```rust
28//! use varvedb::engine::{Writer, Reader};
29//! use varvedb::storage::{Storage, StorageConfig};
30//! use rkyv::{Archive, Serialize, Deserialize};
31//! use tempfile::tempdir;
32//!
33//! #[derive(Archive, Serialize, Deserialize, Debug)]
34//! #[archive(check_bytes)]
35//! #[archive_attr(derive(Debug))]
36//! struct MyEvent {
37//!     pub id: u32,
38//!     pub data: String,
39//! }
40//!
41//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
42//! let dir = tempdir()?;
43//! let config = StorageConfig {
44//!     path: dir.path().to_path_buf(),
45//!     ..Default::default()
46//! };
47//!
48//! let storage = Storage::open(config)?;
49//!
50//! // Append an event
51//! let mut writer = Writer::new(storage.clone());
52//! writer.append(1, 1, MyEvent { id: 1, data: "Hello".to_string() })?;
53//!
54//! // Read the event back
55//! let reader = Reader::<MyEvent>::new(storage.clone());
56//! let txn = storage.env.read_txn()?;
57//!
58//! if let Some(event) = reader.get(&txn, 1)? {
59//!     println!("Read event: {:?}", event);
60//! }
61//! # Ok(())
62//! # }
63//! ```
64
65pub mod constants;
66pub mod crypto;
67pub mod engine;
68pub mod error;
69pub mod metrics;
70pub mod storage;
71
72pub use error::Error;
varvedb/lib.rs

varvedb/
lib.rs
