Skip to main content

forgedb_wal/
lib.rs

1//! Write-Ahead Log (WAL) Implementation
2//!
3//! `forgedb-wal` is a **schema-agnostic substrate** crate. It stores and
4//! returns opaque byte records and knows nothing about any application schema.
5//!
6//! ## Wire format
7//!
8//! Each entry on disk:
9//! ```text
10//! [4 bytes: total entry length (excluding this field)]
11//! [1 byte: operation type]
12//! [2 bytes: model name length]
13//! [N bytes: model name (UTF-8, opaque routing tag)]
14//! [M bytes: serialized operation data]
15//! [4 bytes: CRC32 checksum]
16//! ```
17//!
18//! Only one operation type exists:
19//! - `Raw` (`0x20`): `[payload_len (4 bytes LE)][payload_bytes...]`
20//!
21//! The WAL breaks at the first corrupt or incomplete entry and returns the
22//! valid prefix (torn-tail crash safety).
23use std::io;
24#[cfg(not(target_arch = "wasm32"))]
25use std::path::{Path, PathBuf};
26#[cfg(target_arch = "wasm32")]
27use std::path::Path;
28
29mod entry;
30#[cfg(not(target_arch = "wasm32"))]
31mod reader;
32#[cfg(not(target_arch = "wasm32"))]
33mod writer;
34
35pub use entry::{WalEntry, WalOperation};
36#[cfg(not(target_arch = "wasm32"))]
37pub use reader::{CorruptionInfo, WalReader};
38#[cfg(not(target_arch = "wasm32"))]
39pub use writer::WalWriter;
40
41/// Fsync policy determines when a native WAL is flushed to disk.
42///
43/// Defined at the crate root (not in the native-only `writer` module) because it
44/// is part of the schema-agnostic substrate surface `forgedb-storage` re-exports
45/// and generated code names (`FsyncPolicy::Always`) — it must exist on **both**
46/// the native and the `wasm32` follower target. On `wasm32` there is no file WAL
47/// (see the in-memory [`WalManager`] below), so the policy is inert there.
48#[derive(Debug, Clone, Copy, PartialEq, Eq)]
49pub enum FsyncPolicy {
50    /// Fsync after every write (maximum durability, slower).
51    Always,
52    /// Fsync periodically based on elapsed time.
53    Periodic(std::time::Duration),
54    /// Never fsync automatically (fastest, less durable — must call flush manually).
55    Never,
56}
57
58/// WAL Manager — high-level interface for WAL operations.
59///
60/// Wraps a [`WalWriter`] and [`WalReader`] over a single WAL file. The
61/// manager provides the crash-recovery entry point ([`replay`]) and common
62/// lifecycle operations (`flush`, `rotate`, `truncate`).
63///
64/// [`replay`]: WalManager::replay
65#[cfg(not(target_arch = "wasm32"))]
66pub struct WalManager {
67    writer: WalWriter,
68    reader: WalReader,
69    path: PathBuf,
70}
71
72#[cfg(not(target_arch = "wasm32"))]
73impl WalManager {
74    /// Open or create a WAL at `path`.
75    ///
76    /// Creates any missing parent directories. The WAL file is opened for
77    /// append-only writes; an existing file is not truncated.
78    pub fn open<P: AsRef<Path>>(path: P, fsync_policy: FsyncPolicy) -> io::Result<Self> {
79        let path = path.as_ref().to_path_buf();
80
81        if let Some(parent) = path.parent() {
82            std::fs::create_dir_all(parent)?;
83        }
84
85        let writer = WalWriter::new(&path, fsync_policy)?;
86        let reader = WalReader::new(&path)?;
87
88        Ok(WalManager { writer, reader, path })
89    }
90
91    /// Append an entry to the WAL.
92    pub fn write(&mut self, entry: &WalEntry) -> io::Result<()> {
93        self.writer.write(entry)
94    }
95
96    /// Append an entry WITHOUT fsyncing (#170 group commit) — durability deferred
97    /// to a later [`flush`](Self::flush). Only for writes gated on a later durable
98    /// marker (MVCC-Tier-1 staged rows). See [`WalWriter::write_buffered`].
99    pub fn write_buffered(&mut self, entry: &WalEntry) -> io::Result<()> {
100        self.writer.write_buffered(entry)
101    }
102
103    /// Flush buffered bytes to disk (fsync).
104    pub fn flush(&mut self) -> io::Result<()> {
105        self.writer.flush()
106    }
107
108    /// Replay every entry from the WAL in file order, passing each to
109    /// `callback`.
110    ///
111    /// The replay is **schema-blind**: entries are returned as `WalEntry`
112    /// values carrying opaque `Raw` payloads. No decode step is applied.
113    /// Stops at the first corrupt or incomplete entry (torn tail) and returns
114    /// the entries recovered up to that point.
115    pub fn replay<F>(&mut self, mut callback: F) -> io::Result<Vec<WalEntry>>
116    where
117        F: FnMut(&WalEntry) -> io::Result<()>,
118    {
119        let entries = self.reader.read_all()?;
120
121        for entry in &entries {
122            callback(entry)?;
123        }
124
125        Ok(entries)
126    }
127
128    /// Truncate the WAL, removing all entries.
129    pub fn truncate(&mut self) -> io::Result<()> {
130        self.writer.truncate()?;
131        self.reader = WalReader::new(&self.path)?;
132        Ok(())
133    }
134
135    /// Truncate the WAL to a specific byte `offset`, dropping every byte after it
136    /// (MVCC Tier 1 transaction rollback).
137    ///
138    /// Unlike [`truncate`] (which clears the whole log), this rolls the file back
139    /// to a previously-recorded [`size`] mark, so a committed WAL prefix survives
140    /// and only the aborted transaction's staged records are discarded.
141    /// A no-op if `offset` is already `>=` the current length.
142    ///
143    /// [`truncate`]: WalManager::truncate
144    /// [`size`]: WalManager::size
145    pub fn truncate_to(&mut self, offset: u64) -> io::Result<()> {
146        self.writer.truncate_to(offset)?;
147        self.reader = WalReader::new(&self.path)?;
148        Ok(())
149    }
150
151    /// Rotate the WAL: archive the current file under a timestamped name and
152    /// start a fresh, empty WAL at the original path.
153    ///
154    /// Returns the path of the archived WAL file.
155    pub fn rotate(&mut self) -> io::Result<PathBuf> {
156        let timestamp = std::time::SystemTime::now()
157            .duration_since(std::time::UNIX_EPOCH)
158            .map(|d| d.as_secs())
159            .unwrap_or(0);
160
161        let archive_path = self.path.with_extension(format!("log.{}", timestamp));
162
163        self.writer.flush()?;
164        std::fs::rename(&self.path, &archive_path)?;
165
166        self.writer = WalWriter::new(&self.path, self.writer.fsync_policy())?;
167        self.reader = WalReader::new(&self.path)?;
168
169        Ok(archive_path)
170    }
171
172    /// Returns `true` if the WAL file contains no entries (file length is 0).
173    pub fn is_empty(&self) -> io::Result<bool> {
174        let metadata = std::fs::metadata(&self.path)?;
175        Ok(metadata.len() == 0)
176    }
177
178    /// Returns the size of the WAL file in bytes.
179    pub fn size(&self) -> io::Result<u64> {
180        let metadata = std::fs::metadata(&self.path)?;
181        Ok(metadata.len())
182    }
183}
184
185/// In-memory `WalManager` for the `wasm32` browser read-replica target (#110).
186///
187/// The wasm build drops the **file** WAL: the browser follower is durable at
188/// IndexedDB/OPFS *commit* granularity,
189/// and its upstream (the server) is the authoritative durable log, so a
190/// crash-recovery WAL is unnecessary there. But the generated `database.rs` is
191/// emitted **once** and compiled for both targets — it unconditionally
192/// constructs a `forgedb_wal::WalManager` in `new_at` and names `FsyncPolicy`.
193///
194/// So rather than fork the generator (forbidden — the data logic stays
195/// byte-identical across targets), the *substrate* absorbs the difference: on
196/// wasm the WAL is a functional **in-memory** append log with the same public
197/// surface. It framing-encodes entries into a `Vec<u8>` exactly like the file
198/// writer, replays them with the same torn-tail-safe parse, and truncates by
199/// clearing the buffer. It never touches the (absent) wasm filesystem, so
200/// `open`/`recover`/`checkpoint` all succeed; nothing persists across a reload
201/// (that is the IDB/OPFS column commit's job, not the WAL's).
202#[cfg(target_arch = "wasm32")]
203pub struct WalManager {
204    buffer: Vec<u8>,
205}
206
207#[cfg(target_arch = "wasm32")]
208impl WalManager {
209    /// Open an in-memory WAL. The `path` and `fsync_policy` are accepted for
210    /// signature parity with the native constructor and then ignored — there is
211    /// no file and no fsync on this target.
212    pub fn open<P: AsRef<Path>>(_path: P, _fsync_policy: FsyncPolicy) -> io::Result<Self> {
213        Ok(WalManager { buffer: Vec::new() })
214    }
215
216    /// Append an entry to the in-memory log (same framing as the file writer).
217    pub fn write(&mut self, entry: &WalEntry) -> io::Result<()> {
218        self.buffer.extend_from_slice(&entry.to_bytes());
219        Ok(())
220    }
221
222    /// #170 group-commit parity: identical to [`write`](Self::write) on wasm —
223    /// the in-memory log has no fsync to defer.
224    pub fn write_buffered(&mut self, entry: &WalEntry) -> io::Result<()> {
225        self.write(entry)
226    }
227
228    /// No-op flush — there is no disk to sync to on wasm.
229    pub fn flush(&mut self) -> io::Result<()> {
230        Ok(())
231    }
232
233    /// Replay every entry from the in-memory log in order, torn-tail-safe.
234    ///
235    /// Mirrors [`WalReader::read_all`]: parses framed entries from the buffer and
236    /// stops at the first incomplete/corrupt frame, returning the valid prefix.
237    pub fn replay<F>(&mut self, mut callback: F) -> io::Result<Vec<WalEntry>>
238    where
239        F: FnMut(&WalEntry) -> io::Result<()>,
240    {
241        let mut entries = Vec::new();
242        let mut offset = 0;
243        while offset < self.buffer.len() {
244            match WalEntry::from_bytes(&self.buffer[offset..]) {
245                Ok((entry, size)) => {
246                    entries.push(entry);
247                    offset += size;
248                }
249                Err(_) => break,
250            }
251        }
252        for entry in &entries {
253            callback(entry)?;
254        }
255        Ok(entries)
256    }
257
258    /// Clear the in-memory log.
259    pub fn truncate(&mut self) -> io::Result<()> {
260        self.buffer.clear();
261        Ok(())
262    }
263
264    /// Truncate the in-memory log to a specific byte `offset` (MVCC Tier 1
265    /// transaction rollback).  A no-op if `offset >=` the current length.
266    pub fn truncate_to(&mut self, offset: u64) -> io::Result<()> {
267        let offset = offset as usize;
268        if offset < self.buffer.len() {
269            self.buffer.truncate(offset);
270        }
271        Ok(())
272    }
273
274    /// Returns `true` if the in-memory log holds no bytes.
275    pub fn is_empty(&self) -> io::Result<bool> {
276        Ok(self.buffer.is_empty())
277    }
278
279    /// Returns the in-memory log size in bytes.
280    pub fn size(&self) -> io::Result<u64> {
281        Ok(self.buffer.len() as u64)
282    }
283}