obj_core/platform/

mod.rs

//! Platform layer (L0).
//!
//! This module owns the file-system primitives the pager and WAL
//! build on: opening a database file, positioned reads and writes at
//! fixed page boundaries, length queries, truncation, removal, and the
//! durability primitive [`FileHandle::sync_data`].
//!
//! # `unsafe` policy
//!
//! Power-of-ten Rule 8 confines `unsafe` to this submodule (and to
//! `libobj`). All positioned-I/O and durability calls go through the
//! `rustix` crate, which provides audited safe wrappers. The
//! cross-process locking submodule [`lock`] reaches for `libc::fcntl`
//! / `LockFileEx` directly because `rustix` does not expose POSIX
//! OFD-lock variants; every `unsafe` block in that submodule
//! carries a `// SAFETY:` comment per Rule 8. This `mod.rs` itself
//! contains no `unsafe` blocks and is `#![deny(unsafe_code)]`; the
//! lint is scoped to the file rather than the module tree so the
//! `lock` submodule can re-introduce its (audited) `unsafe`
//! blocks.

#![deny(unsafe_code)]

#[cfg(any(test, feature = "fault-injection"))]
pub mod fault;

pub mod lock;

pub use crate::platform::lock::{ReaderLock, WriterLock};

use std::fs::{File, OpenOptions};
use std::io;
use std::path::Path;

use rustix::fs::FileExt as _;

use crate::error::{Error, Result};

/// File-backend abstraction the pager and WAL build on.
///
/// `FileBackend` is the common subset of [`FileHandle`] operations
/// that fault-injection harnesses and the production type both expose
/// (Rule 9). Production code never holds `dyn FileBackend`; both
/// [`crate::pager::Pager`] and [`crate::wal::Wal`] are generic over
/// `F: FileBackend` so the dispatch stays monomorphised.
///
/// New methods added to this trait MUST mirror an existing
/// [`FileHandle`] method exactly. Adding a method that does not exist
/// on the production type would let the harness perform syscalls
/// production code cannot — a forbidden divergence (the harness
/// must be a strict superset of legal behaviour, never a separate
/// kingdom).
pub trait FileBackend: Sized {
    /// Length of the file in bytes. See [`FileHandle::len`].
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] on syscall failure.
    fn len(&self) -> Result<u64>;

    /// `true` iff the file has zero length.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] on syscall failure.
    fn is_empty(&self) -> Result<bool> {
        Ok(self.len()? == 0)
    }

    /// Positioned read. See [`FileHandle::read_exact_at`].
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] on syscall failure or harness-injected
    /// short read.
    fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<()>;

    /// Positioned write. See [`FileHandle::write_all_at`].
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] on syscall failure.
    fn write_all_at(&self, buf: &[u8], offset: u64) -> Result<()>;

    /// Truncate or extend the file. See [`FileHandle::set_len`].
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] on syscall failure.
    fn set_len(&self, new_len: u64) -> Result<()>;

    /// See [`FileHandle::sync_data`].
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] on syscall failure.
    fn sync_data(&self, mode: SyncMode) -> Result<()>;

    /// See [`FileHandle::sync_all`].
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] on syscall failure.
    fn sync_all(&self) -> Result<()>;
}

/// Durability mode for [`FileHandle::sync_data`].
///
/// `SyncMode` is the user-visible knob that selects the cross-platform
/// fsync primitive `obj` calls after a WAL commit. The contract for
/// each variant is documented in `docs/format.md` § `SyncMode`.
///
/// The default is [`SyncMode::Full`]: a `commit` that returns
/// `Ok(())` is durable across a system-wide power loss. `Normal` is
/// the throughput-tuned middle ground; `Off` skips the syscall and is
/// only safe for tests and benchmarks.
///
/// Power-of-ten Rule 5: a three-state enum is far cheaper to audit
/// than three `bool` knobs, and the variants are exhaustive at every
/// `match`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SyncMode {
    /// Strongest durability. Survives system-wide power loss.
    ///
    /// Maps to `fcntl(F_FULLFSYNC)` on macOS (forces the drive cache
    /// to flush), `FlushFileBuffers` on Windows, and `fdatasync` on
    /// Linux / BSDs. macOS's plain `fsync` is **not** sufficient
    /// here — it does not flush the drive cache; `F_FULLFSYNC` does.
    /// This is the standard wisdom for safety-critical macOS storage.
    #[default]
    Full,

    /// Process-crash and kernel-panic durability; may lose data on a
    /// sudden power loss if the drive's write cache has not been
    /// flushed by the time the OS acknowledges the call.
    ///
    /// Maps to `fsync` on Unix and `FlushFileBuffers` on Windows. On
    /// Windows there is no weaker primitive than `FlushFileBuffers`,
    /// so `Normal` and `Full` are equivalent there.
    Normal,

    /// No durability call. The OS may write the data eventually, but
    /// `obj` does not ask it to. Use only for tests and benchmarks
    /// where data loss is acceptable.
    Off,
}

/// A handle to a database file capable of positioned reads and writes
/// at page boundaries.
///
/// `FileHandle` is intentionally minimal — it exposes only the
/// operations the pager (L1) and WAL (L2) need. Higher layers must
/// never reach past it into `std::fs` directly; routing every syscall
/// through this type is how the project keeps Rule 8 enforceable.
#[derive(Debug)]
pub struct FileHandle {
    file: File,
}

impl FileHandle {
    /// Open `path` for read-write access, creating it if it does not
    /// exist. The new file is empty; the caller is responsible for
    /// writing the file header.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] if the file cannot be opened or created
    /// (permission denied, missing parent directory, etc.).
    pub fn open_or_create<P: AsRef<Path>>(path: P) -> Result<Self> {
        let file = OpenOptions::new()
            .read(true)
            .write(true)
            .create(true)
            .truncate(false)
            .open(path)?;
        Ok(Self { file })
    }

    /// Open `path` for read-write access, failing if the file
    /// already exists (`O_CREAT | O_EXCL` on POSIX, `CREATE_NEW` on
    /// Windows). Used by M11 #92 hot-backup to guarantee the
    /// destination is never overwritten.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] if the file already exists, the parent
    /// directory does not exist, or any other syscall failure
    /// occurs.
    pub fn create_new<P: AsRef<Path>>(path: P) -> Result<Self> {
        let file = OpenOptions::new()
            .read(true)
            .write(true)
            .create_new(true)
            .open(path)?;
        Ok(Self { file })
    }

    /// Length of the file in bytes.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] if the metadata syscall fails.
    pub fn len(&self) -> Result<u64> {
        let meta = self.file.metadata()?;
        Ok(meta.len())
    }

    /// `true` if the file is zero-length (i.e. just created).
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] if the metadata syscall fails.
    pub fn is_empty(&self) -> Result<bool> {
        Ok(self.len()? == 0)
    }

    /// Positioned read. Fills `buf` from byte offset `offset`.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] on syscall failure or on short read
    /// (e.g. file shorter than `offset + buf.len()`).
    pub fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<()> {
        // `FileExt::read_exact_at` is `rustix`'s audited wrapper around
        // `pread`. It does not require `unsafe`.
        self.file.read_exact_at(buf, offset).map_err(Error::from)
    }

    /// Positioned write. Writes `buf` to byte offset `offset`.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] on syscall failure or on short write.
    pub fn write_all_at(&self, buf: &[u8], offset: u64) -> Result<()> {
        self.file.write_all_at(buf, offset).map_err(Error::from)
    }

    /// Truncate or extend the file to `new_len` bytes.
    ///
    /// Used by the pager when the freelist is exhausted and a fresh
    /// page must be appended.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] on syscall failure.
    pub fn set_len(&self, new_len: u64) -> Result<()> {
        self.file.set_len(new_len).map_err(Error::from)
    }

    /// Force file contents and metadata to disk. Used at close.
    ///
    /// Power-of-ten Rule 7: the underlying call returns
    /// `io::Result<()>` and is propagated explicitly.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] on syscall failure.
    pub fn sync_all(&self) -> Result<()> {
        self.file.sync_all().map_err(Error::from)
    }

    /// Force file data (and on `Full`, the drive cache) to persistent
    /// storage according to `mode`. See [`SyncMode`] for the exact
    /// per-variant durability promise.
    ///
    /// On `SyncMode::Off` this call is a no-op.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Io`] on syscall failure.
    pub fn sync_data(&self, mode: SyncMode) -> Result<()> {
        match mode {
            SyncMode::Off => Ok(()),
            SyncMode::Normal => sync_data_normal(&self.file),
            SyncMode::Full => sync_data_full(&self.file),
        }
    }
}

impl FileBackend for FileHandle {
    fn len(&self) -> Result<u64> {
        FileHandle::len(self)
    }
    fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<()> {
        FileHandle::read_exact_at(self, buf, offset)
    }
    fn write_all_at(&self, buf: &[u8], offset: u64) -> Result<()> {
        FileHandle::write_all_at(self, buf, offset)
    }
    fn set_len(&self, new_len: u64) -> Result<()> {
        FileHandle::set_len(self, new_len)
    }
    fn sync_data(&self, mode: SyncMode) -> Result<()> {
        FileHandle::sync_data(self, mode)
    }
    fn sync_all(&self) -> Result<()> {
        FileHandle::sync_all(self)
    }
}

// --------------------------------------------------------------------
// Per-platform sync primitives. Kept as small free functions so the
// platform switch is one match-arm per variant rather than threading
// `cfg` attributes through `FileHandle::sync_data`.
// --------------------------------------------------------------------

/// `Normal` durability — `fsync` on Unix, `FlushFileBuffers` on
/// Windows. Survives process / kernel crash but may lose data on a
/// sudden power loss if the drive cache has not been flushed.
fn sync_data_normal(file: &File) -> Result<()> {
    // `std::fs::File::sync_all` invokes `fsync(2)` on Unix and
    // `FlushFileBuffers` on Windows. Both flush the OS page cache;
    // neither, on macOS, flushes the drive cache (that is `Full`'s
    // job via `F_FULLFSYNC`). Using `sync_all` here keeps the
    // platform switch in one place and avoids reimplementing the
    // `fsync` syscall ourselves.
    file.sync_all().map_err(Error::from)
}

/// `Full` durability — flush the drive cache where the platform
/// distinguishes it from the OS cache. See [`SyncMode::Full`] for
/// the per-OS mapping.
#[cfg(target_vendor = "apple")]
fn sync_data_full(file: &File) -> Result<()> {
    // macOS: plain `fsync` does NOT flush the drive cache. The
    // documented way to do that is `fcntl(F_FULLFSYNC)`, which the
    // `rustix` crate exposes safely. See
    // <https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fcntl.2.html>.
    rustix::fs::fcntl_fullfsync(file).map_err(|e| Error::Io(io::Error::from(e)))
}

/// `Full` durability on non-Apple Unix targets: `fdatasync(2)` is
/// sufficient (the on-disk data is flushed, metadata changes that do
/// not affect the data — like mtime — are not).
#[cfg(all(unix, not(target_vendor = "apple")))]
fn sync_data_full(file: &File) -> Result<()> {
    rustix::fs::fdatasync(file).map_err(|e| Error::Io(io::Error::from(e)))
}

/// `Full` durability on Windows: `FlushFileBuffers` is the strongest
/// primitive; `std::fs::File::sync_all` invokes it.
#[cfg(windows)]
fn sync_data_full(file: &File) -> Result<()> {
    file.sync_all().map_err(Error::from)
}

/// Delete the file at `path` if it exists.
///
/// Used by `Pager::close()` to remove the WAL sidecar after a clean
/// shutdown. Missing-file is intentionally **not** an error; the
/// post-condition is "no file at `path`", and that is satisfied either
/// by deletion or by absence.
///
/// # Errors
///
/// Returns [`Error::Io`] on any failure other than `NotFound`.
pub fn remove_file_if_exists<P: AsRef<Path>>(path: P) -> Result<()> {
    match std::fs::remove_file(path) {
        Ok(()) => Ok(()),
        Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(()),
        Err(e) => Err(Error::Io(e)),
    }
}

impl From<io::ErrorKind> for Error {
    fn from(kind: io::ErrorKind) -> Self {
        Error::Io(io::Error::from(kind))
    }
}

#[cfg(test)]
mod tests {
    use super::{FileHandle, SyncMode};
    use tempfile::TempDir;

    fn write_and_sync(mode: SyncMode) {
        let dir = TempDir::new().expect("tempdir");
        let path = dir.path().join("sync.bin");
        let h = FileHandle::open_or_create(&path).expect("open");
        h.set_len(4096).expect("set_len");
        h.write_all_at(&[0xABu8; 4096], 0).expect("write");
        h.sync_data(mode).expect("sync_data must succeed");
    }

    #[test]
    fn sync_data_full_returns_ok() {
        write_and_sync(SyncMode::Full);
    }

    #[test]
    fn sync_data_normal_returns_ok() {
        write_and_sync(SyncMode::Normal);
    }

    #[test]
    fn sync_data_off_is_noop() {
        write_and_sync(SyncMode::Off);
    }

    #[test]
    fn default_is_full() {
        assert_eq!(SyncMode::default(), SyncMode::Full);
    }
}