nano_wal/lib.rs
1//! A concurrent Write-Ahead Log (WAL) with CAS-based segment rotation
2//! and coalesced preadv reads.
3//!
4//! # Features
5//!
6//! - Lock-free segment rotation via ArcSwap + CAS
7//! - Concurrent reads via dup'd file descriptors (preadv)
8//! - Coalesced batch reads for minimal syscalls
9//! - Clock-aligned segment expiration windows
10//! - Vectored writes (writev) for batch appends
11//!
12//! # Examples
13//!
14//! ```ignore
15//! use nano_wal::{Wal, WalOptions};
16//! use std::time::Duration;
17//!
18//! let options = WalOptions {
19//! retention: Duration::from_secs(3600),
20//! segment_duration: Duration::from_secs(600),
21//! };
22//! let wal = Wal::new("/tmp/my_wal", "stream-0", options).unwrap();
23//!
24//! let now_ms = 1711234567890i64;
25//! let entry = wal.append(None, b"hello world", now_ms, false).unwrap();
26//! ```
27
28mod error;
29mod segment;
30mod wal;
31mod read;
32mod cleanup;
33
34pub use error::{WalError, Result};
35pub use segment::Segment;
36pub use wal::{Wal, WalOptions};
37pub use read::{ReadDescriptor, Record, read_batch};
38pub use cleanup::{CleanupResult, DeletedSegment};
39
40/// Re-exported for callers who need to hold segment read fds.
41pub use bytes::Bytes;
42
43/// UTF-8 'NANO-LOG' signature for segment file headers.
44pub(crate) const NANO_LOG_SIGNATURE: [u8; 8] = *b"NANO-LOG";
45
46/// UTF-8 'NANORC' signature for individual records.
47pub(crate) const NANO_REC_SIGNATURE: [u8; 6] = *b"NANORC";
48
49/// Segment file header size: NANO-LOG (8) + expiration_ms (8)
50pub(crate) const FILE_HEADER_SIZE: usize = 16;
51
52/// Record framing overhead: NANORC (6) + header_len (2) + content_len (8)
53pub(crate) const RECORD_FRAMING_SIZE: usize = 16;
54
55/// Maximum size for record headers in bytes (64KB).
56pub(crate) const MAX_HEADER_SIZE: usize = 65535;
57
58/// EntryRef returned from append operations.
59#[derive(Debug, Clone, Copy, PartialEq, Eq)]
60pub struct EntryRef {
61 /// Byte offset within the segment file
62 pub file_offset: u64,
63 /// Total on-disk size (NANORC framing + header + content)
64 pub byte_size: usize,
65}
66
67/// A single entry for batch append operations.
68#[derive(Debug)]
69pub struct WriteEntry<'a> {
70 pub header: Option<&'a [u8]>,
71 pub content: &'a [u8],
72}