Crate walogs 

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

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.

Structs

Lsn

A Log Sequence Number. Newtype wrapper around u64 to prevent accidental mixing with raw byte offsets, file positions, or counts.

Wal

A handle to a multi-segment WAL directory. Single-writer (see I6). Drop closes the file handles.

WalConfig

Configuration for the WAL.

WalIter

Iterator over WAL entries across all segments, in LSN order.

Enums

TailState

Whether the WAL’s tail was clean or truncated on the most recent Wal::open.

WalError

Errors returned by crate::Wal operations.

Constants

MAX_ENTRY_SIZE

Maximum size in bytes of a single entry’s data payload (16 MiB).