1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
//! A crash-safe write-ahead log (WAL) library for Rust.
//!
//! `walogs` gives you a durable, append-only sequence of byte entries with
//! automatic crash recovery. Every successful [`Wal::append`] call has been
//! `fdatasync`'d before it returns `Ok`. On the next [`Wal::open`], any
//! partial (torn) write at the tail is detected and truncated automatically.
//!
//! # Quick start
//!
//! ```no_run
//! use walogs::{Wal, Lsn, TailState};
//!
//! // Open or create a WAL directory.
//! let mut wal = Wal::open(std::path::Path::new("/tmp/my-wal")).unwrap();
//!
//! // Append entries — each Ok means durable on disk.
//! let _lsn1 = wal.append(b"first entry").unwrap();
//! let lsn2 = wal.append(b"second entry").unwrap();
//!
//! // Iterate all entries.
//! for result in wal.iter() {
//! let (lsn, data) = result.unwrap();
//! println!("lsn={} data={:?}", lsn.0, data);
//! }
//!
//! // Checkpoint: delete completed segments up to and including lsn2.
//! wal.checkpoint(lsn2).unwrap();
//!
//! // Recovery is automatic on the next open.
//! let wal = Wal::open(std::path::Path::new("/tmp/my-wal")).unwrap();
//! match wal.tail_state() {
//! TailState::Clean => {}
//! TailState::TruncatedAt(offset) => {
//! println!("crash recovery: partial write discarded at offset {offset}");
//! }
//! }
//! ```
//!
//! # Guarantees
//!
//! - **Durable on `Ok`** — `fdatasync` completes before `append` returns `Ok`.
//! - **At most one lost write after a crash** — the last in-flight write may be
//! lost; every prior entry is guaranteed intact.
//! - **Dense LSNs** — LSNs are `1, 2, 3, …` with no gaps across all segments.
//! - **No buried garbage** — corrupt tails are truncated before any new write.
//! - **Segment integrity** — LSN continuity and sequence gaps are detected on open.
//!
//! # What this library does NOT do
//!
//! - No transactions or multi-entry atomicity.
//! - No file locking — callers must ensure a single writer per directory.
//! - No async API.
//! - No seek-by-LSN; [`Wal::iter`] walks the whole log from the beginning.
pub use WalError;
pub use MAX_ENTRY_SIZE;
pub use ;