obj_core/

backup.rs

//! Hot backup primitives (M11 #92).
//!
//! [`backup_pager_to_path`] is the obj-core entry point the obj
//! crate's `Db::backup_to` dispatches through. The function takes a
//! `&Pager<F>` (the caller has already pinned a [`ReaderSnapshot`])
//! and writes a self-contained `.obj` file at `dest`. Writers may
//! continue against the source pager throughout; their post-snapshot
//! commits do not appear in the destination.
//!
//! See `docs/format.md` § Hot backup for the algorithm this module
//! implements.
//!
//! # Power-of-ten posture
//!
//! - **Rule 2.** The page-copy loop is bounded by
//!   `source.page_count()`; the WAL-overlay loop is bounded by the
//!   snapshot's frozen-view size (which is itself bounded by
//!   `source.page_count()`).
//! - **Rule 4.** The driver is short; per-phase helpers
//!   (`copy_main_file`, `overlay_frozen_view`, `patch_destination_header`)
//!   factor the work.
//! - **Rule 7.** No `unwrap` / `expect` in the production path.
//!   Every syscall is `?`-propagated. On any mid-backup error the
//!   destination file is removed best-effort so a half-written
//!   backup does not linger.

#![forbid(unsafe_code)]

use std::path::Path;

use crate::error::{Error, Result};
use crate::pager::header::{decode_header, encode_header, FileHeader};
use crate::pager::page::{Page, PageId, PAGE_SIZE};
use crate::pager::{Pager, ReaderSnapshot};
use crate::platform::{remove_file_if_exists, FileBackend, FileHandle, SyncMode};

/// Build a self-contained `.obj` file at `dest` carrying the state
/// of `source` as of `snapshot.pinned_lsn()`.
///
/// `snapshot` MUST have been taken against `source` and not yet
/// dropped; the pin keeps the source's WAL frames at-or-below the
/// pinned LSN from being reclaimed while the backup runs.
///
/// # Algorithm
///
/// 1. Refuse to overwrite an existing `dest` (`create_new`).
/// 2. Copy main-file pages `0..source.page_count()` byte-for-byte.
/// 3. Overlay every frame in the snapshot's frozen WAL view onto
///    the destination at its page-id offset.
/// 4. If the snapshot's frozen view carries a page-0 header frame,
///    overlay that on top of the main-file copy of page 0.
/// 5. Patch the destination header: zero `wal_salt`, recompute the
///    header CRC32C.
/// 6. `sync_data(SyncMode::Full)` on the destination.
///
/// On any mid-backup error the destination file is removed best-
/// effort so a half-written backup does not linger.
///
/// # Errors
///
/// - [`Error::BackupDestinationExists`] if `dest` already exists.
/// - [`Error::BackupNotSupportedForMemoryPager`] if `source` is an
///   in-memory pager.
/// - [`Error::Io`] on any syscall failure during the copy.
/// - [`Error::InvalidFormat`] / [`Error::Corruption`] propagated
///   from the source header decode (the source's header bytes are
///   re-encoded with the WAL-staged values applied).
pub fn backup_pager_to_path<F: FileBackend>(
    source: &Pager<F>,
    snapshot: &ReaderSnapshot<F>,
    dest: impl AsRef<Path>,
) -> Result<()> {
    let dest_path = dest.as_ref().to_path_buf();
    if source.is_memory_backed() {
        return Err(Error::BackupNotSupportedForMemoryPager);
    }
    if dest_path.exists() {
        return Err(Error::BackupDestinationExists { path: dest_path });
    }
    let result = run_backup(source, snapshot, &dest_path);
    if result.is_err() {
        // Best-effort cleanup; ignore the result so the original
        // error is the one the caller sees.
        let _ = remove_file_if_exists(&dest_path);
    }
    result
}

fn run_backup<F: FileBackend>(
    source: &Pager<F>,
    snapshot: &ReaderSnapshot<F>,
    dest_path: &Path,
) -> Result<()> {
    let dest_handle = FileHandle::create_new(dest_path)?;
    let page_count = source.page_count();
    dest_handle.set_len(
        page_count
            .checked_mul(PAGE_SIZE as u64)
            .ok_or(Error::InvalidArgument("backup: file size overflow"))?,
    )?;
    copy_main_file(source, &dest_handle, page_count)?;
    overlay_frozen_view(snapshot, &dest_handle, page_count)?;
    overlay_frozen_header(snapshot, &dest_handle)?;
    patch_destination_header(&dest_handle)?;
    dest_handle.sync_data(SyncMode::Full)?;
    Ok(())
}

/// Copy every page in `0..page_count` from the source pager's main
/// file to `dest`. Reads bypass the WAL overlay — that's the
/// snapshot's job in [`overlay_frozen_view`].
///
/// Power-of-ten Rule 2: bounded by `page_count`; Rule 3: a single
/// page-sized scratch buffer is reused across the loop.
fn copy_main_file<F: FileBackend>(
    source: &Pager<F>,
    dest: &FileHandle,
    page_count: u64,
) -> Result<()> {
    // Page 0 first — it's the header, copied as-is here and patched
    // below in `patch_destination_header`.
    let mut buf = Page::zeroed();
    let page_size_u64 = PAGE_SIZE as u64;
    let mut id_raw: u64 = 0;
    while id_raw < page_count {
        let off = id_raw
            .checked_mul(page_size_u64)
            .ok_or(Error::InvalidArgument("backup: byte-offset overflow"))?;
        if id_raw == 0 {
            source.read_main_file_page_zero(buf.as_bytes_mut())?;
        } else {
            let pid = PageId::new(id_raw)
                .ok_or(Error::InvalidArgument("backup: zero page id (impossible)"))?;
            let page = source.read_main_file_page(pid)?;
            buf.as_bytes_mut().copy_from_slice(page.as_bytes());
        }
        dest.write_all_at(buf.as_bytes(), off)?;
        id_raw = id_raw
            .checked_add(1)
            .ok_or(Error::InvalidArgument("backup: page id overflow"))?;
    }
    Ok(())
}

/// Overlay the snapshot's frozen WAL view onto `dest`. After this
/// returns, every page-id `<= page_count` whose body the snapshot
/// would observe via [`ReaderSnapshot::read_page`] carries that
/// observed body in `dest`.
fn overlay_frozen_view<F: FileBackend>(
    snapshot: &ReaderSnapshot<F>,
    dest: &FileHandle,
    page_count: u64,
) -> Result<()> {
    let page_size_u64 = PAGE_SIZE as u64;
    for (pid, page) in snapshot.frozen_pages() {
        if pid.get() >= page_count {
            // The snapshot pinned a frame for a page id that no
            // longer exists in the source (post-snapshot truncate
            // is impossible in M11, but defensive). Skip it.
            continue;
        }
        let off = pid
            .get()
            .checked_mul(page_size_u64)
            .ok_or(Error::InvalidArgument("backup: byte-offset overflow"))?;
        dest.write_all_at(page.as_bytes(), off)?;
    }
    Ok(())
}

/// Overlay the snapshot's frozen page-0 header (if any) on top of
/// `dest`. This places the WAL-staged catalog root / freelist head /
/// page count into the destination's header BEFORE
/// [`patch_destination_header`] zeros the WAL salt.
fn overlay_frozen_header<F: FileBackend>(
    snapshot: &ReaderSnapshot<F>,
    dest: &FileHandle,
) -> Result<()> {
    if let Some(header_page) = snapshot.frozen_header() {
        dest.write_all_at(header_page.as_bytes(), 0)?;
    }
    Ok(())
}

/// Re-encode the destination's page-0 header with `wal_salt` zeroed
/// and the header CRC recomputed. After this the destination is
/// self-consistent: a `Db::open(dest)` will see no WAL salt and
/// will create a fresh empty WAL on first open.
fn patch_destination_header(dest: &FileHandle) -> Result<()> {
    let mut page = Page::zeroed();
    dest.read_exact_at(page.as_bytes_mut(), 0)?;
    let mut header: FileHeader = decode_header(&page)?;
    header.wal_salt = [0u8; 16];
    encode_header(&header, &mut page);
    dest.write_all_at(page.as_bytes(), 0)?;
    Ok(())
}