use super::fault::{IoPoint, StorageIo};
use crate::error::{Error, Result};
use crate::pager::PageId;
use crc32fast::Hasher;
use std::collections::HashMap;
use std::fs::{File, OpenOptions};
use std::io::{BufWriter, Read, Seek, SeekFrom, Write};
use std::path::{Path, PathBuf};
pub const WAL_MAGIC: [u8; 8] = *b"TAPIRWAL";
pub const WAL_VERSION: u32 = 1;
pub const WAL_HEADER_SIZE: usize = 32;
pub const WAL_FRAME_HEADER_SIZE: usize = 24;
pub const DEFAULT_CHECKPOINT_THRESHOLD: usize = 1000;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WalHeader {
pub magic: [u8; 8],
pub version: u32,
pub page_size: u32,
pub checkpoint_seq: u32,
pub salt_1: u32,
pub salt_2: u32,
pub header_crc32: u32,
}
impl WalHeader {
pub fn new(page_size: u32) -> Self {
let mut header = Self {
magic: WAL_MAGIC,
version: WAL_VERSION,
page_size,
checkpoint_seq: 1,
salt_1: 0x1A2B3C4D,
salt_2: 0x5E6F7A8B,
header_crc32: 0,
};
header.header_crc32 = header.calculate_crc();
header
}
pub fn calculate_crc(&self) -> u32 {
let mut hasher = Hasher::new();
hasher.update(&self.magic);
hasher.update(&self.version.to_le_bytes());
hasher.update(&self.page_size.to_le_bytes());
hasher.update(&self.checkpoint_seq.to_le_bytes());
hasher.update(&self.salt_1.to_le_bytes());
hasher.update(&self.salt_2.to_le_bytes());
hasher.finalize()
}
pub fn to_bytes(&self) -> [u8; WAL_HEADER_SIZE] {
let mut buf = [0u8; WAL_HEADER_SIZE];
buf[0..8].copy_from_slice(&self.magic);
buf[8..12].copy_from_slice(&self.version.to_le_bytes());
buf[12..16].copy_from_slice(&self.page_size.to_le_bytes());
buf[16..20].copy_from_slice(&self.checkpoint_seq.to_le_bytes());
buf[20..24].copy_from_slice(&self.salt_1.to_le_bytes());
buf[24..28].copy_from_slice(&self.salt_2.to_le_bytes());
buf[28..32].copy_from_slice(&self.header_crc32.to_le_bytes());
buf
}
pub fn from_bytes(slice: &[u8]) -> Result<Self> {
if slice.len() < WAL_HEADER_SIZE {
return Err(Error::Corrupted(
"WAL header slice too short (<32 bytes)".into(),
));
}
let mut magic = [0u8; 8];
magic.copy_from_slice(&slice[0..8]);
if magic != WAL_MAGIC {
return Err(Error::InvalidMagic);
}
let version = u32::from_le_bytes([slice[8], slice[9], slice[10], slice[11]]);
let page_size = u32::from_le_bytes([slice[12], slice[13], slice[14], slice[15]]);
let checkpoint_seq = u32::from_le_bytes([slice[16], slice[17], slice[18], slice[19]]);
let salt_1 = u32::from_le_bytes([slice[20], slice[21], slice[22], slice[23]]);
let salt_2 = u32::from_le_bytes([slice[24], slice[25], slice[26], slice[27]]);
let header_crc32 = u32::from_le_bytes([slice[28], slice[29], slice[30], slice[31]]);
let header = Self {
magic,
version,
page_size,
checkpoint_seq,
salt_1,
salt_2,
header_crc32,
};
if header.version != WAL_VERSION
|| !header.page_size.is_power_of_two()
|| !(512..=65536).contains(&header.page_size)
{
return Err(Error::Corrupted(
"Unsupported WAL version or page size".into(),
));
}
let expected_crc = header.calculate_crc();
if header.header_crc32 != expected_crc {
return Err(Error::PageCorrupted(0, expected_crc, header.header_crc32));
}
Ok(header)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WalFrameHeader {
pub page_id: PageId,
pub db_size_in_pages: u32,
pub commit_seq: u32,
pub salt_1: u32,
pub salt_2: u32,
pub frame_crc32: u32,
}
impl WalFrameHeader {
pub fn calculate_crc(&self, page_data: &[u8]) -> u32 {
let mut hasher = Hasher::new();
hasher.update(&self.page_id.to_le_bytes());
hasher.update(&self.db_size_in_pages.to_le_bytes());
hasher.update(&self.commit_seq.to_le_bytes());
hasher.update(&self.salt_1.to_le_bytes());
hasher.update(&self.salt_2.to_le_bytes());
hasher.update(page_data);
hasher.finalize()
}
pub fn to_bytes(&self) -> [u8; WAL_FRAME_HEADER_SIZE] {
let mut buf = [0u8; WAL_FRAME_HEADER_SIZE];
buf[0..4].copy_from_slice(&self.page_id.to_le_bytes());
buf[4..8].copy_from_slice(&self.db_size_in_pages.to_le_bytes());
buf[8..12].copy_from_slice(&self.commit_seq.to_le_bytes());
buf[12..16].copy_from_slice(&self.salt_1.to_le_bytes());
buf[16..20].copy_from_slice(&self.salt_2.to_le_bytes());
buf[20..24].copy_from_slice(&self.frame_crc32.to_le_bytes());
buf
}
pub fn from_bytes(slice: &[u8]) -> Result<Self> {
if slice.len() < WAL_FRAME_HEADER_SIZE {
return Err(Error::Corrupted(
"WAL frame header slice too short (<24 bytes)".into(),
));
}
let page_id = u32::from_le_bytes([slice[0], slice[1], slice[2], slice[3]]);
let db_size_in_pages = u32::from_le_bytes([slice[4], slice[5], slice[6], slice[7]]);
let commit_seq = u32::from_le_bytes([slice[8], slice[9], slice[10], slice[11]]);
let salt_1 = u32::from_le_bytes([slice[12], slice[13], slice[14], slice[15]]);
let salt_2 = u32::from_le_bytes([slice[16], slice[17], slice[18], slice[19]]);
let frame_crc32 = u32::from_le_bytes([slice[20], slice[21], slice[22], slice[23]]);
Ok(Self {
page_id,
db_size_in_pages,
commit_seq,
salt_1,
salt_2,
frame_crc32,
})
}
}
#[derive(Debug, Clone)]
struct InMemoryFrame {
header: WalFrameHeader,
page_data: Vec<u8>,
}
#[derive(Debug)]
pub struct Wal {
header: WalHeader,
writer: Option<BufWriter<File>>,
_path: Option<PathBuf>,
page_size: usize,
index: HashMap<PageId, usize>,
frames: Vec<InMemoryFrame>,
current_commit_seq: u32,
io: StorageIo,
io_failed: bool,
checkpoint_error: Option<String>,
}
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct StorageHealth {
pub reopen_required: bool,
pub checkpoint_error: Option<String>,
pub wal_frames: usize,
}
pub(crate) type CommittedWalSnapshot = (u32, HashMap<PageId, Vec<u8>>);
impl Wal {
pub fn open<P: AsRef<Path>>(wal_path: P, page_size: u32) -> Result<Self> {
let path = wal_path.as_ref().to_path_buf();
let exists = path.exists();
let mut file = OpenOptions::new()
.read(true)
.write(true)
.create(true)
.truncate(false)
.open(&path)?;
let header = if exists && file.metadata()?.len() >= WAL_HEADER_SIZE as u64 {
let mut buf = [0u8; WAL_HEADER_SIZE];
file.seek(SeekFrom::Start(0))?;
file.read_exact(&mut buf)?;
WalHeader::from_bytes(&buf)?
} else {
let header = WalHeader::new(page_size);
file.seek(SeekFrom::Start(0))?;
file.write_all(&header.to_bytes())?;
file.sync_data()?;
header
};
if header.page_size != page_size {
return Err(Error::Corrupted(
"WAL page size does not match the database".into(),
));
}
let mut wal = Self {
header,
writer: None,
_path: Some(path),
page_size: page_size as usize,
index: HashMap::new(),
frames: Vec::new(),
current_commit_seq: 0,
io: StorageIo::default(),
io_failed: false,
checkpoint_error: None,
};
wal.rebuild_index_from_file(&mut file)?;
file.seek(SeekFrom::End(0))?;
wal.writer = Some(BufWriter::with_capacity(128 * 1024, file));
wal.discard_uncommitted_tail()?;
Ok(wal)
}
pub fn open_in_memory(page_size: u32) -> Self {
Self {
header: WalHeader::new(page_size),
writer: None,
_path: None,
page_size: page_size as usize,
index: HashMap::new(),
frames: Vec::new(),
current_commit_seq: 0,
io: StorageIo::default(),
io_failed: false,
checkpoint_error: None,
}
}
pub fn frame_count(&self) -> usize {
self.frames.len()
}
pub fn health(&self) -> StorageHealth {
StorageHealth {
reopen_required: self.io_failed,
checkpoint_error: self.checkpoint_error.clone(),
wal_frames: self.frames.len(),
}
}
pub(crate) fn requires_reopen(&self) -> bool {
self.io_failed
}
#[cfg(not(target_arch = "wasm32"))]
pub(crate) fn storage_io(&self) -> StorageIo {
self.io.clone()
}
#[cfg(feature = "fault-injection")]
pub fn set_io_fault(&self, plan: Option<super::fault::IoFaultPlan>) -> Result<()> {
self.io.configure(plan)
}
pub(crate) fn read_committed_page(path: &Path, wanted: PageId) -> Result<Option<Vec<u8>>> {
let mut file = File::open(path)?;
let length = file.metadata()?.len();
if length < WAL_HEADER_SIZE as u64 {
return Ok(None);
}
let mut bytes = [0; WAL_HEADER_SIZE];
file.read_exact(&mut bytes)?;
let header = WalHeader::from_bytes(&bytes)?;
let mut payload = vec![0; header.page_size as usize];
let mut pending = None;
let mut committed = None;
while file.stream_position()? + WAL_FRAME_HEADER_SIZE as u64 + payload.len() as u64
<= length
{
let mut raw = [0; WAL_FRAME_HEADER_SIZE];
file.read_exact(&mut raw)?;
let frame = WalFrameHeader::from_bytes(&raw)?;
file.read_exact(&mut payload)?;
if frame.salt_1 != header.salt_1
|| frame.salt_2 != header.salt_2
|| frame.page_id == 0
|| frame.frame_crc32 != frame.calculate_crc(&payload)
{
break;
}
if frame.page_id == wanted {
pending = Some(payload.clone());
}
if frame.db_size_in_pages > 0 {
committed = pending.clone();
}
}
Ok(committed)
}
pub(crate) fn read_file_fingerprint(path: &Path) -> Result<(u64, u32, u32, u32)> {
let mut file = match File::open(path) {
Ok(f) => f,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok((0, 0, 0, 0)),
Err(e) => return Err(e.into()),
};
let len = file.metadata()?.len();
if len < WAL_HEADER_SIZE as u64 {
return Ok((len, 0, 0, 0));
}
let mut bytes = [0u8; WAL_HEADER_SIZE];
file.read_exact(&mut bytes)?;
let header = WalHeader::from_bytes(&bytes)?;
Ok((len, header.checkpoint_seq, header.salt_1, header.salt_2))
}
pub(crate) fn read_all_committed_pages(path: &Path) -> Result<Option<CommittedWalSnapshot>> {
let mut file = match File::open(path) {
Ok(f) => f,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(e) => return Err(e.into()),
};
let length = file.metadata()?.len();
if length < WAL_HEADER_SIZE as u64 {
return Ok(None);
}
let mut bytes = [0u8; WAL_HEADER_SIZE];
file.read_exact(&mut bytes)?;
let header = WalHeader::from_bytes(&bytes)?;
let mut payload = vec![0u8; header.page_size as usize];
let mut pending: HashMap<PageId, Vec<u8>> = HashMap::new();
let mut committed: HashMap<PageId, Vec<u8>> = HashMap::new();
let mut committed_db_size: u32 = 0;
while file.stream_position()? + WAL_FRAME_HEADER_SIZE as u64 + payload.len() as u64
<= length
{
let mut raw = [0u8; WAL_FRAME_HEADER_SIZE];
if file.read_exact(&mut raw).is_err() {
break;
}
let frame = match WalFrameHeader::from_bytes(&raw) {
Ok(f) => f,
Err(_) => break,
};
if file.read_exact(&mut payload).is_err() {
break;
}
if frame.salt_1 != header.salt_1
|| frame.salt_2 != header.salt_2
|| frame.page_id == 0
|| frame.frame_crc32 != frame.calculate_crc(&payload)
{
break;
}
pending.insert(frame.page_id, payload.clone());
if frame.db_size_in_pages > 0 {
for (pid, data) in pending.drain() {
committed.insert(pid, data);
}
committed_db_size = frame.db_size_in_pages;
}
}
if committed_db_size == 0 || committed.is_empty() {
Ok(None)
} else {
Ok(Some((committed_db_size, committed)))
}
}
pub fn has_page(&self, page_id: PageId) -> bool {
self.index.contains_key(&page_id)
}
pub fn export_frames(&self) -> Vec<(PageId, Vec<u8>)> {
self.frames
.iter()
.map(|f| (f.header.page_id, f.page_data.clone()))
.collect()
}
fn rebuild_index_from_file(&mut self, file: &mut File) -> Result<()> {
let file_len = file.metadata()?.len();
let frame_size = (WAL_FRAME_HEADER_SIZE + self.page_size) as u64;
let mut offset = WAL_HEADER_SIZE as u64;
let mut frame_idx = 0;
while offset + frame_size <= file_len {
file.seek(SeekFrom::Start(offset))?;
let mut header_buf = [0u8; WAL_FRAME_HEADER_SIZE];
file.read_exact(&mut header_buf)?;
let frame_header = WalFrameHeader::from_bytes(&header_buf)?;
let mut page_data = vec![0u8; self.page_size];
file.read_exact(&mut page_data)?;
let expected_crc = frame_header.calculate_crc(&page_data);
if frame_header.frame_crc32 != expected_crc
|| frame_header.page_id == 0
|| frame_header.salt_1 != self.header.salt_1
|| frame_header.salt_2 != self.header.salt_2
{
break;
}
if frame_header.commit_seq > self.current_commit_seq {
self.current_commit_seq = frame_header.commit_seq;
}
self.index.insert(frame_header.page_id, frame_idx);
self.frames.push(InMemoryFrame {
header: frame_header,
page_data,
});
offset += frame_size;
frame_idx += 1;
}
file.set_len(offset)?;
Ok(())
}
fn discard_uncommitted_tail(&mut self) -> Result<()> {
let committed = self
.frames
.iter()
.rposition(|f| f.header.db_size_in_pages > 0)
.map_or(0, |i| i + 1);
self.rollback_to(committed)
}
pub fn read_page(&self, page_id: PageId) -> Option<Vec<u8>> {
let &frame_idx = self.index.get(&page_id)?;
self.frames.get(frame_idx).map(|f| f.page_data.clone())
}
pub fn write_frame(
&mut self,
page_id: PageId,
page_data: &[u8],
is_commit: bool,
db_size_in_pages: u32,
) -> Result<()> {
if self.io_failed {
return Err(Error::TransactionError(
"WAL requires reopen or successful rollback after I/O failure".into(),
));
}
if page_data.len() != self.page_size {
return Err(Error::Corrupted("Page data size mismatch in WAL".into()));
}
let commit_seq = if is_commit {
self.current_commit_seq
.checked_add(1)
.ok_or_else(|| Error::TransactionError("WAL commit sequence exhausted".into()))?
} else {
self.current_commit_seq
};
let mut frame_header = WalFrameHeader {
page_id,
db_size_in_pages: if is_commit { db_size_in_pages } else { 0 },
commit_seq,
salt_1: self.header.salt_1,
salt_2: self.header.salt_2,
frame_crc32: 0,
};
frame_header.frame_crc32 = frame_header.calculate_crc(page_data);
let written = (|| -> Result<()> {
if let Some(writer) = &mut self.writer {
self.io
.write(IoPoint::WalWrite, writer, &frame_header.to_bytes())?;
self.io.write(IoPoint::WalWrite, writer, page_data)?;
if is_commit {
self.io.before(IoPoint::WalFlush)?;
writer.flush()?;
self.io.before(IoPoint::WalSync)?;
writer.get_mut().sync_data()?;
}
}
Ok(())
})();
if let Err(error) = written {
self.io_failed = true;
return Err(error);
}
self.current_commit_seq = commit_seq;
let frame_idx = self.frames.len();
self.index.insert(page_id, frame_idx);
self.frames.push(InMemoryFrame {
header: frame_header,
page_data: page_data.to_vec(),
});
Ok(())
}
pub fn sync(&mut self) -> Result<()> {
let result = (|| -> Result<()> {
if let Some(writer) = &mut self.writer {
self.io.before(IoPoint::WalFlush)?;
writer.flush()?;
self.io.before(IoPoint::WalSync)?;
writer.get_mut().sync_data()?;
}
Ok(())
})();
if result.is_err() {
self.io_failed = true;
}
result
}
pub fn checkpoint(
&mut self,
base_file: &mut Option<File>,
base_in_memory: &mut HashMap<PageId, Vec<u8>>,
) -> Result<usize> {
let result = if self.io_failed {
Err(Error::TransactionError(
"WAL requires reopen before checkpoint".into(),
))
} else {
self.checkpoint_inner(base_file, base_in_memory)
};
self.checkpoint_error = result.as_ref().err().map(ToString::to_string);
result
}
fn checkpoint_inner(
&mut self,
base_file: &mut Option<File>,
base_in_memory: &mut HashMap<PageId, Vec<u8>>,
) -> Result<usize> {
if self
.frames
.last()
.is_some_and(|f| f.header.db_size_in_pages == 0)
{
return Err(Error::TransactionError(
"Cannot checkpoint an uncommitted WAL tail".into(),
));
}
let page_size = self.page_size;
let num_pages_to_flush = self.index.len();
if num_pages_to_flush == 0 {
return Ok(0);
}
let mut sorted_page_ids: Vec<PageId> = self.index.keys().copied().collect();
sorted_page_ids.sort_unstable();
for page_id in sorted_page_ids {
let frame_idx = self.index[&page_id];
let page_data = &self.frames[frame_idx].page_data;
if let Some(file) = base_file {
let offset = (page_id as u64 - 1) * page_size as u64;
file.seek(SeekFrom::Start(offset))?;
self.io.write(IoPoint::CheckpointWrite, file, page_data)?;
}
if base_file.is_none() {
base_in_memory.insert(page_id, page_data.clone());
}
}
if let Some(file) = base_file {
self.io.before(IoPoint::CheckpointSync)?;
file.sync_all()?;
}
self.header.checkpoint_seq += 1;
self.header.header_crc32 = self.header.calculate_crc();
let reset = (|| -> Result<()> {
if let Some(writer) = &mut self.writer {
self.io.before(IoPoint::WalFlush)?;
writer.flush()?;
let file = writer.get_mut();
self.io.before(IoPoint::WalTruncate)?;
file.set_len(0)?;
file.seek(SeekFrom::Start(0))?;
self.io
.write(IoPoint::WalReset, file, &self.header.to_bytes())?;
self.io.before(IoPoint::WalSync)?;
file.sync_all()?;
file.seek(SeekFrom::End(0))?;
}
Ok(())
})();
if let Err(error) = reset {
self.io_failed = true;
return Err(error);
}
self.index.clear();
self.frames.clear();
Ok(num_pages_to_flush)
}
pub fn recover(
&mut self,
base_file: &mut Option<File>,
base_in_memory: &mut HashMap<PageId, Vec<u8>>,
) -> Result<usize> {
self.discard_uncommitted_tail()?;
if self.frames.is_empty() {
return Ok(0);
}
let mut last_commit_idx = None;
for (idx, frame) in self.frames.iter().enumerate() {
if frame.header.db_size_in_pages > 0 {
last_commit_idx = Some(idx);
}
}
let max_safe_frame = match last_commit_idx {
Some(idx) => idx,
None => {
self.index.clear();
self.frames.clear();
return Ok(0);
}
};
let mut recovered_count = 0;
for frame in &self.frames[..=max_safe_frame] {
let page_id = frame.header.page_id;
let page_data = &frame.page_data;
if let Some(file) = base_file {
let offset = (page_id as u64 - 1) * self.page_size as u64;
file.seek(SeekFrom::Start(offset))?;
self.io.write(IoPoint::CheckpointWrite, file, page_data)?;
}
if base_file.is_none() {
base_in_memory.insert(page_id, page_data.clone());
}
recovered_count += 1;
}
if let Some(file) = base_file {
self.io.before(IoPoint::CheckpointSync)?;
file.sync_all()?;
}
Ok(recovered_count)
}
pub fn rollback_to(&mut self, frame_count: usize) -> Result<()> {
let frame_count = frame_count.min(self.frames.len());
let truncate = (|| -> Result<()> {
if let Some(writer) = &mut self.writer {
let offset = WAL_HEADER_SIZE as u64
+ frame_count as u64 * (WAL_FRAME_HEADER_SIZE + self.page_size) as u64;
if !self.io_failed
&& writer.buffer().is_empty()
&& writer.get_ref().metadata()?.len() == offset
&& frame_count == self.frames.len()
{
return Ok(());
}
self.io.before(IoPoint::WalFlush)?;
writer.flush()?;
let file = writer.get_mut();
self.io.before(IoPoint::WalTruncate)?;
file.set_len(offset)?;
self.io.before(IoPoint::WalSync)?;
file.sync_data()?;
file.seek(SeekFrom::End(0))?;
}
Ok(())
})();
if let Err(error) = truncate {
self.io_failed = true;
return Err(error);
}
self.io_failed = false;
self.frames.truncate(frame_count);
self.index.clear();
for (i, frame) in self.frames.iter().enumerate() {
self.index.insert(frame.header.page_id, i);
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_wal_header_roundtrip() {
let header = WalHeader::new(4096);
let bytes = header.to_bytes();
let parsed = WalHeader::from_bytes(&bytes).expect("Parse header");
assert_eq!(header, parsed);
}
#[test]
fn test_wal_frame_header_crc_validation() {
let page_data = vec![0xABu8; 4096];
let mut frame_header = WalFrameHeader {
page_id: 42,
db_size_in_pages: 10,
commit_seq: 1,
salt_1: 0x11223344,
salt_2: 0x55667788,
frame_crc32: 0,
};
frame_header.frame_crc32 = frame_header.calculate_crc(&page_data);
assert_eq!(
frame_header.frame_crc32,
frame_header.calculate_crc(&page_data)
);
let mut corrupted = page_data.clone();
corrupted[100] ^= 0x01;
assert_ne!(
frame_header.frame_crc32,
frame_header.calculate_crc(&corrupted)
);
}
#[test]
fn test_in_memory_wal_write_and_checkpoint() {
let mut wal = Wal::open_in_memory(4096);
let mut in_memory_pages = HashMap::new();
let page1 = vec![1u8; 4096];
let page2 = vec![2u8; 4096];
wal.write_frame(1, &page1, false, 0).expect("Write frame 1");
wal.write_frame(2, &page2, true, 2).expect("Commit frame 2");
assert_eq!(wal.frame_count(), 2);
assert!(wal.has_page(1));
assert!(wal.has_page(2));
assert_eq!(wal.read_page(1).unwrap(), page1);
assert_eq!(wal.read_page(2).unwrap(), page2);
let mut base_file = None;
let flushed = wal
.checkpoint(&mut base_file, &mut in_memory_pages)
.expect("Checkpoint");
assert_eq!(flushed, 2);
assert_eq!(wal.frame_count(), 0);
assert_eq!(in_memory_pages.get(&1).unwrap(), &page1);
assert_eq!(in_memory_pages.get(&2).unwrap(), &page2);
let page2_v2 = vec![9u8; 4096];
wal.write_frame(2, &page2_v2, true, 2)
.expect("Overwrite frame 2");
let flushed2 = wal
.checkpoint(&mut base_file, &mut in_memory_pages)
.expect("Second checkpoint");
assert_eq!(flushed2, 1);
assert_eq!(in_memory_pages.get(&2).unwrap(), &page2_v2);
}
}