blockworx_store/

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};

/// 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<()> {
    let target = resolve(path);
    let temp = temp_path(&target)?;
    write_and_replace(&temp, &target, contents).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]) -> 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.
        file.sync_all()?;
    }
    std::fs::rename(temp, target)?;
    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. Nor has a browser, which has no
/// filesystem at all.
#[cfg(not(unix))]
#[expect(clippy::unnecessary_wraps, reason = "the unix arm can fail")]
fn sync_dir(_dir: &Path) -> std::io::Result<()> {
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::temp::TempDir;

    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.json");

        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.json");
        write_atomically(&doc, b"content").unwrap();

        let leftovers: Vec<_> = std::fs::read_dir(dir.path())
            .unwrap()
            .map(|e| e.unwrap().file_name())
            .filter(|name| name != "doc.json")
            .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.json");
        write_atomically(&doc, b"the good version").unwrap();

        let blocker = dir.join(".doc.json.tmp");
        std::fs::create_dir(&blocker).unwrap();
        // Proves the precondition: this is the path the write would have used.
        // Canonicalized on both sides — the platform temp directory is a
        // symlink on macOS, and `resolve` follows it.
        assert_eq!(
            temp_path(&resolve(&doc)).unwrap(),
            std::fs::canonicalize(&blocker).unwrap(),
        );

        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.json");
        let link = dir.join("link.json");
        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");
    }
}