Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
14.7 KB
Raw Blame
//! Atomic file writes.
//!
//! Every file the wiki owns is written via a tmp + rename + fsync dance.
//! Two payoffs: a crash mid-write never produces a torn file, and the
//! upcoming watcher (M1-D) can ignore "own writes" by inode tracking.
// The write primitive itself; every reporting wrapper is built on it.
#![allow(clippy::disallowed_methods)]

use std::fs::File;
use std::io::Write;
use std::path::Path;
use std::time::Duration;

use crate::error::{WikiError, WikiResult};

/// How many times a persist is retried when the failure is a transient
/// sharing violation, and the base of the linear backoff between attempts.
/// Worst case adds 10+20+30+40+50 = 150ms before the real error propagates.
const PERSIST_RETRY_ATTEMPTS: u32 = 5;
const PERSIST_RETRY_BASE_DELAY: Duration = Duration::from_millis(10);

/// Persist `tmp` over `path`, absorbing transient Windows sharing violations.
///
/// On Windows the rename can fail with `ERROR_SHARING_VIOLATION` (32) or
/// `ERROR_LOCK_VIOLATION` (33) when another process briefly holds the
/// just-created tempfile or the destination — most commonly an antivirus or
/// indexer scanning the new file, which is endemic on CI runners. The hold is
/// transient by nature, so a short bounded retry absorbs it; anything that
/// outlasts the budget is a real error and propagates unchanged. On
/// non-Windows platforms nothing is classified transient, so behaviour is
/// byte-for-byte what it was.
pub(crate) fn persist_with_retry(
    tmp: tempfile::NamedTempFile,
    path: &Path,
) -> Result<File, tempfile::PersistError> {
    persist_with_retry_impl(
        tmp,
        PERSIST_RETRY_ATTEMPTS,
        PERSIST_RETRY_BASE_DELAY,
        is_transient_sharing_violation,
        |tmp, path| tmp.persist(path),
        path,
    )
}

/// The retry loop with its collaborators injected, so the mechanics are
/// testable on every platform: tests fabricate `PersistError`s (its fields
/// are public) and supply their own transience predicate and zero delay,
/// while production supplies the Windows classifier and the real `persist`.
fn persist_with_retry_impl<F, P>(
    mut tmp: tempfile::NamedTempFile,
    attempts: u32,
    base_delay: Duration,
    transient: P,
    mut attempt_fn: F,
    path: &Path,
) -> Result<File, tempfile::PersistError>
where
    F: FnMut(tempfile::NamedTempFile, &Path) -> Result<File, tempfile::PersistError>,
    P: Fn(&std::io::Error) -> bool,
{
    let mut attempt = 0u32;
    loop {
        match attempt_fn(tmp, path) {
            Ok(file) => return Ok(file),
            Err(err) if attempt < attempts && transient(&err.error) => {
                attempt += 1;
                std::thread::sleep(base_delay * attempt);
                // `PersistError` hands the tempfile back, which is what makes
                // retrying possible at all: the staged bytes are still intact.
                tmp = err.file;
            }
            Err(err) => return Err(err),
        }
    }
}

/// `fs::rename`, retrying a transient sharing violation `attempts` times
/// with a linear backoff from `base_delay`. Off Windows nothing is transient.
///
/// # Errors
/// The final `fs::rename` error.
pub fn rename_with_retry(
    from: &Path,
    to: &Path,
    attempts: u32,
    base_delay: Duration,
) -> std::io::Result<()> {
    retry_transient(attempts, base_delay, is_transient_sharing_violation, || {
        std::fs::rename(from, to)
    })
}

/// Retry `attempt_fn` while `transient` says so, at most `attempts` times.
fn retry_transient<T, F, P>(
    attempts: u32,
    base_delay: Duration,
    transient: P,
    mut attempt_fn: F,
) -> std::io::Result<T>
where
    F: FnMut() -> std::io::Result<T>,
    P: Fn(&std::io::Error) -> bool,
{
    let mut attempt = 0u32;
    loop {
        match attempt_fn() {
            Ok(value) => return Ok(value),
            Err(err) if attempt < attempts && transient(&err) => {
                attempt += 1;
                std::thread::sleep(base_delay * attempt);
            }
            Err(err) => return Err(err),
        }
    }
}

/// Windows: sharing (32) and lock (33) violations are transient third-party
/// holds. Everything else — including `ACCESS_DENIED`, which is usually a
/// real permissions problem — propagates immediately. Elsewhere: nothing is
/// transient; raw code 32 on Unix is `EPIPE` and retrying a rename on it
/// would be noise on top of a real failure.
fn is_transient_sharing_violation(err: &std::io::Error) -> bool {
    if cfg!(windows) {
        matches!(err.raw_os_error(), Some(32) | Some(33))
    } else {
        false
    }
}

/// Atomically replace the file at `path` with `bytes`.
///
/// Steps: write to a `tempfile` in the same directory, `sync_data` the
/// tempfile, `persist` it over the destination, then best-effort `sync_all`
/// the parent directory so the rename hits stable storage.
///
/// Returns the inode number of the persisted file (used by the watcher to
/// skip its own writes).
///
/// # Errors
/// Propagates I/O and [`tempfile::PersistError`] failures.
pub fn write_atomic(path: &Path, bytes: &[u8]) -> WikiResult<u64> {
    let parent = path
        .parent()
        .ok_or_else(|| WikiError::Io(std::io::Error::other("path has no parent")))?;
    std::fs::create_dir_all(parent)?;

    let mut tmp = tempfile::Builder::new()
        .prefix(".ai-memory-tmp.")
        .tempfile_in(parent)?;
    tmp.write_all(bytes)?;
    tmp.as_file().sync_data()?;

    let persisted: File = persist_with_retry(tmp, path)?;
    persisted.sync_data()?;

    // Best-effort: fsync the parent so the rename is durable too.
    if let Ok(dir) = File::open(parent) {
        let _ = dir.sync_all();
    }

    Ok(inode_of(path).unwrap_or(0))
}

#[cfg(unix)]
fn inode_of(path: &Path) -> std::io::Result<u64> {
    use std::os::unix::fs::MetadataExt;
    Ok(std::fs::metadata(path)?.ino())
}

// The NTFS file index is the closest stable analog to a Unix inode and is
// what the watcher compares to skip its own writes. Unlike Unix, it isn't
// exposed via `Metadata`; it requires an open handle (`GetFileInformationByHandle`),
// hence the extra `File::open`. Non-NTFS volumes (FAT) report 0 — harmless:
// the caller's `.unwrap_or(0)` path already treats 0 as "no stable id".
#[cfg(windows)]
fn inode_of(path: &Path) -> std::io::Result<u64> {
    let file = std::fs::File::open(path)?;
    let info = winapi_util::file::information(&file)?;
    Ok(info.file_index())
}

#[cfg(not(any(unix, windows)))]
fn inode_of(_path: &Path) -> std::io::Result<u64> {
    Ok(0)
}

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

    fn staged(dir: &TempDir) -> tempfile::NamedTempFile {
        let mut tmp = tempfile::Builder::new().tempfile_in(dir.path()).unwrap();
        tmp.write_all(b"staged bytes").unwrap();
        tmp
    }

    fn sharing_violation(tmp: tempfile::NamedTempFile) -> tempfile::PersistError {
        tempfile::PersistError {
            error: std::io::Error::from_raw_os_error(32),
            file: tmp,
        }
    }

    /// A transient hold that clears must not surface: the retry absorbs the
    /// first failures and the bytes still land. This is the Windows-CI
    /// antivirus scenario, exercised on every platform by injecting the
    /// failure instead of hoping to reproduce a scanner's timing.
    #[test]
    fn a_transient_hold_is_absorbed_and_the_write_lands() {
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("page.md");
        let mut failures_left = 3;
        let result = persist_with_retry_impl(
            staged(&dir),
            5,
            Duration::ZERO,
            |_| true,
            |tmp, path| {
                if failures_left > 0 {
                    failures_left -= 1;
                    Err(sharing_violation(tmp))
                } else {
                    tmp.persist(path)
                }
            },
            &target,
        );
        assert!(result.is_ok(), "three transient failures must be absorbed");
        assert_eq!(std::fs::read(&target).unwrap(), b"staged bytes");
    }

    /// A hold that never clears is a real error: the budget bounds the wait
    /// and the final error propagates rather than looping forever.
    #[test]
    fn a_persistent_hold_exhausts_the_budget_and_propagates() {
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("page.md");
        let mut calls = 0u32;
        let result = persist_with_retry_impl(
            staged(&dir),
            5,
            Duration::ZERO,
            |_| true,
            |tmp, _| {
                calls += 1;
                Err(sharing_violation(tmp))
            },
            &target,
        );
        assert!(result.is_err());
        assert_eq!(calls, 6, "initial attempt plus five retries, then stop");
    }

    /// A non-transient error must NOT be retried: retrying a real failure
    /// only delays it and can mask its cause. The control for the whole
    /// mechanism — if the loop treated everything as transient, this fails.
    #[test]
    fn a_non_transient_error_propagates_immediately() {
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("page.md");
        let mut calls = 0u32;
        let result = persist_with_retry_impl(
            staged(&dir),
            5,
            Duration::ZERO,
            |_| false,
            |tmp, _| {
                calls += 1;
                Err(sharing_violation(tmp))
            },
            &target,
        );
        assert!(result.is_err());
        assert_eq!(calls, 1, "no retry when the predicate says non-transient");
    }

    /// Absorbs a transient hold, stops at the budget, never retries a real
    /// error.
    #[test]
    fn rename_retry_absorbs_transient_holds_within_its_budget() {
        let mut failures_left = 3;
        let mut calls = 0u32;
        let result = retry_transient(
            5,
            Duration::ZERO,
            |_| true,
            || {
                calls += 1;
                if failures_left > 0 {
                    failures_left -= 1;
                    Err(std::io::Error::from_raw_os_error(32))
                } else {
                    Ok(())
                }
            },
        );
        assert!(result.is_ok());
        assert_eq!(calls, 4, "three transient failures, then success");

        let mut calls = 0u32;
        let result: std::io::Result<()> = retry_transient(
            5,
            Duration::ZERO,
            |_| true,
            || {
                calls += 1;
                Err(std::io::Error::from_raw_os_error(32))
            },
        );
        assert!(result.is_err());
        assert_eq!(calls, 6, "initial attempt plus five retries, then stop");

        let mut calls = 0u32;
        let result: std::io::Result<()> = retry_transient(
            5,
            Duration::ZERO,
            |_| false,
            || {
                calls += 1;
                Err(std::io::Error::from_raw_os_error(32))
            },
        );
        assert!(result.is_err());
        assert_eq!(calls, 1, "no retry when the predicate says non-transient");
    }

    #[test]
    fn rename_with_retry_moves_the_file_and_reports_a_missing_source() {
        let dir = TempDir::new().unwrap();
        let from = dir.path().join("from");
        let to = dir.path().join("to");
        std::fs::write(&from, b"bytes").unwrap();
        rename_with_retry(&from, &to, 5, Duration::ZERO).unwrap();
        assert_eq!(std::fs::read(&to).unwrap(), b"bytes");
        let err = rename_with_retry(&from, &to, 5, Duration::ZERO).unwrap_err();
        assert_eq!(err.kind(), std::io::ErrorKind::NotFound);
    }

    /// A real sharing hold: a handle without `FILE_SHARE_DELETE`, as a
    /// scanner holds a file.
    #[cfg(windows)]
    #[test]
    fn rename_with_retry_outlasts_a_real_sharing_hold() {
        use std::os::windows::fs::OpenOptionsExt as _;
        const FILE_SHARE_READ: u32 = 1;

        let dir = TempDir::new().unwrap();
        let from = dir.path().join("held.exe");
        let to = dir.path().join("held.old");
        std::fs::write(&from, b"image").unwrap();
        let holder = std::fs::OpenOptions::new()
            .read(true)
            .share_mode(FILE_SHARE_READ)
            .open(&from)
            .unwrap();
        let err = std::fs::rename(&from, &to).unwrap_err();
        assert_eq!(err.raw_os_error(), Some(32), "the hold must be real: {err}");

        let release = std::thread::spawn(move || {
            std::thread::sleep(Duration::from_millis(300));
            drop(holder);
        });
        rename_with_retry(&from, &to, 20, Duration::from_millis(50)).unwrap();
        release.join().unwrap();
        assert_eq!(std::fs::read(&to).unwrap(), b"image");
    }

    /// Pins the production classifier per platform: on Unix nothing is
    /// transient (raw 32 is EPIPE there), so Unix persist behaviour is
    /// byte-for-byte unchanged by this fix. On Windows, 32 and 33 retry.
    #[test]
    fn the_classifier_matches_only_windows_sharing_codes() {
        let sharing = std::io::Error::from_raw_os_error(32);
        let lock = std::io::Error::from_raw_os_error(33);
        let denied = std::io::Error::from_raw_os_error(5);
        if cfg!(windows) {
            assert!(is_transient_sharing_violation(&sharing));
            assert!(is_transient_sharing_violation(&lock));
            assert!(
                !is_transient_sharing_violation(&denied),
                "ACCESS_DENIED is a real permissions problem, not a transient hold"
            );
        } else {
            assert!(
                !is_transient_sharing_violation(&sharing),
                "nothing is transient off Windows; unix behaviour is unchanged"
            );
        }
    }

    #[test]
    fn writes_atomically_and_creates_parents() {
        let tmp = TempDir::new().unwrap();
        let target = tmp.path().join("nested/dir/page.md");
        let ino = write_atomic(&target, b"hello").unwrap();
        assert!(target.is_file());
        assert_eq!(std::fs::read(&target).unwrap(), b"hello");
        if cfg!(unix) || cfg!(windows) {
            assert_ne!(ino, 0);
        }
    }

    #[test]
    fn overwrites_existing_file() {
        let tmp = TempDir::new().unwrap();
        let target = tmp.path().join("page.md");
        write_atomic(&target, b"first").unwrap();
        write_atomic(&target, b"second").unwrap();
        assert_eq!(std::fs::read(&target).unwrap(), b"second");
    }

    #[test]
    fn does_not_leave_tmp_files_on_success() {
        let tmp = TempDir::new().unwrap();
        let target = tmp.path().join("page.md");
        write_atomic(&target, b"x").unwrap();
        let leftover = std::fs::read_dir(tmp.path())
            .unwrap()
            .map(|e| e.unwrap().file_name())
            .any(|n| n.to_string_lossy().starts_with(".ai-memory-tmp."));
        assert!(!leftover, "tempfile leaked");
    }
}