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}