blockworx/storage/

atomic.rs

//! Crash-safe file writes.
//!
//! Every write of something a user would mind losing goes through
//! [`write_atomically`]. `std::fs::write` truncates the target and then fills it,
//! so a crash, a kill, or a power cut partway through leaves a half-written file
//! where the previous good one used to be — and for the document save that is the
//! drawing itself.

use std::io::Write as _;
use std::path::{Path, PathBuf};

use super::Durability;

/// Write `contents` to `path` so that dying partway through leaves the previous
/// contents intact: the bytes land in a sibling temporary file, are flushed to
/// the storage device, and only then replace `path` with one atomic rename.
///
/// The target is never opened for writing, so there is no window in which it
/// holds a partial document.
pub fn write_atomically(path: &Path, contents: &[u8]) -> std::io::Result<()> {
    write_with(path, contents, Durability::Sync)
}

/// [`write_atomically`], with the choice of whether to wait for the storage
/// device. [`Durability::Relaxed`] still moves the file into place — it only
/// skips the flushes, which is the whole cost (see `todo.md` P0).
pub fn write_with(path: &Path, contents: &[u8], durability: Durability) -> std::io::Result<()> {
    let target = resolve(path);
    let temp = temp_path(&target)?;
    write_and_replace(&temp, &target, contents, durability).inspect_err(|_| {
        // A temp file left behind would be overwritten by the next attempt
        // anyway; removing it just keeps the directory tidy.
        let _ = std::fs::remove_file(&temp);
    })
}

/// Follow symlinks, so writing a symlinked document replaces what it points at —
/// the way `fs::write` does. Renaming onto the link would instead replace the
/// link with a regular file and quietly detach it from its target.
fn resolve(path: &Path) -> PathBuf {
    std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf())
}

/// A dot-prefixed sibling of `target`. It has to share the directory: `rename`
/// is only atomic within one filesystem.
fn temp_path(target: &Path) -> std::io::Result<PathBuf> {
    let name = target.file_name().ok_or_else(|| {
        std::io::Error::new(
            std::io::ErrorKind::InvalidInput,
            format!("{} names no file to write", target.display()),
        )
    })?;
    let mut temp = std::ffi::OsString::from(".");
    temp.push(name);
    temp.push(".tmp");
    Ok(target.with_file_name(temp))
}

fn write_and_replace(
    temp: &Path,
    target: &Path,
    contents: &[u8],
    durability: Durability,
) -> std::io::Result<()> {
    let mut file = std::fs::File::create(temp)?;
    file.write_all(contents)?;
    // Without this the rename can be recorded while the bytes are still in the
    // page cache, so a power cut yields an intact rename onto empty content.
    if durability == Durability::Sync {
        file.sync_all()?;
    }
    drop(file);
    std::fs::rename(temp, target)?;
    if durability == Durability::Sync {
        sync_dir(parent_dir(target))?;
    }
    Ok(())
}

/// The directory holding `target`. A bare relative filename has an empty parent,
/// which names nothing openable.
fn parent_dir(target: &Path) -> &Path {
    match target.parent() {
        Some(dir) if !dir.as_os_str().is_empty() => dir,
        _ => Path::new("."),
    }
}

/// Flush the directory entry itself, so the rename survives a power cut and not
/// just a process crash.
#[cfg(unix)]
fn sync_dir(dir: &Path) -> std::io::Result<()> {
    std::fs::File::open(dir)?.sync_all()
}

/// Windows has no directory handle to sync; `MoveFileEx` metadata ordering is
/// the filesystem's business there.
#[cfg(not(unix))]
fn sync_dir(_dir: &Path) -> std::io::Result<()> {
    Ok(())
}

#[cfg(test)]
pub mod tests {
    use super::*;

    /// A unique directory per test, removed on drop. Named for the test so a
    /// failure leaves an identifiable directory behind. Shared with the
    /// `storage::fs` and `storage::container` tests.
    pub struct TempDir(PathBuf);

    impl TempDir {
        /// # Panics
        ///
        /// If the directory cannot be created — in a test that is the
        /// assertion, not something to recover from.
        pub fn new(name: &str) -> Self {
            let dir = std::env::temp_dir().join(format!("blockworx-{}-{name}", std::process::id()));
            let _ = std::fs::remove_dir_all(&dir);
            std::fs::create_dir_all(&dir).unwrap();
            Self(dir)
        }

        pub fn join(&self, name: &str) -> PathBuf {
            self.0.join(name)
        }

        pub fn path(&self) -> &Path {
            &self.0
        }
    }

    impl Drop for TempDir {
        fn drop(&mut self) {
            let _ = std::fs::remove_dir_all(&self.0);
        }
    }

    fn read(path: &Path) -> String {
        std::fs::read_to_string(path).unwrap()
    }

    #[test]
    fn it_creates_and_then_overwrites() {
        let dir = TempDir::new("create-overwrite");
        let doc = dir.join("doc.kdl");

        write_atomically(&doc, b"first").unwrap();
        assert_eq!(read(&doc), "first");

        write_atomically(&doc, b"second").unwrap();
        assert_eq!(read(&doc), "second");
    }

    #[test]
    fn a_successful_write_leaves_no_temp_behind() {
        let dir = TempDir::new("no-temp");
        let doc = dir.join("doc.kdl");
        write_atomically(&doc, b"content").unwrap();

        let leftovers: Vec<_> = std::fs::read_dir(&dir.0)
            .unwrap()
            .map(|e| e.unwrap().file_name())
            .filter(|name| name != "doc.kdl")
            .collect();
        assert!(leftovers.is_empty(), "left {leftovers:?} behind");
    }

    /// The property the whole module exists for: a write that fails partway
    /// cannot have touched the target. The failure is forced by occupying the
    /// temp path with a directory, so `File::create` fails after the target
    /// already holds content worth keeping.
    #[test]
    fn a_failed_write_leaves_the_previous_contents_intact() {
        let dir = TempDir::new("failed-write");
        let doc = dir.join("doc.kdl");
        write_atomically(&doc, b"the good version").unwrap();

        let blocker = dir.join(".doc.kdl.tmp");
        std::fs::create_dir(&blocker).unwrap();
        // Proves the precondition: this is the path the write would have used.
        assert_eq!(temp_path(&resolve(&doc)).unwrap(), blocker);

        assert!(write_atomically(&doc, b"a doomed longer version").is_err());
        assert_eq!(read(&doc), "the good version");
    }

    #[test]
    fn a_path_naming_no_file_is_an_error() {
        assert!(write_atomically(Path::new(".."), b"x").is_err());
    }

    /// A symlinked document is written *through*, not replaced by a regular
    /// file — the behavior `fs::write` had and a bare rename would lose.
    #[cfg(unix)]
    #[test]
    fn writing_a_symlink_updates_its_target() {
        let dir = TempDir::new("symlink");
        let target = dir.join("real.kdl");
        let link = dir.join("link.kdl");
        write_atomically(&target, b"before").unwrap();
        std::os::unix::fs::symlink(&target, &link).unwrap();

        write_atomically(&link, b"after").unwrap();

        assert!(
            std::fs::symlink_metadata(&link).unwrap().is_symlink(),
            "the link itself was replaced"
        );
        assert_eq!(read(&target), "after");
    }
}