codetree 0.1.1

AI-native version control system for autonomous agents
Documentation
//! Crash-safe, race-safe file updates for repository state.
//!
//! Every persistent state file (refs, HEAD, index, locks.json, ops.json, ...)
//! is a whole-value document that must never be observed half-written and must
//! survive concurrent writers. This module provides the primitives:
//!
//! - [`write_atomic`]: replace a file's contents atomically. The data is
//!   written to a temporary sibling file and renamed over the target — readers
//!   see either the old or the new contents, never a torn write. Writers are
//!   serialized by an exclusive `<path>.lock` lockfile (git's convention), so
//!   last-writer-wins races cannot silently drop updates.
//! - [`with_file_lock`]: run a closure while holding the exclusive lockfile.
//!   Use this for read-modify-write cycles (e.g. locks.json) and for
//!   compare-and-swap ref updates; inside the closure, call [`write_locked`]
//!   to persist without re-taking the lock (the lock is *not* reentrant).
//!
//! A `<path>.lock` file left behind by a crashed process is detected by age
//! and force-broken after [`STALE_LOCK_AGE`], so a crash cannot wedge the
//! repository forever.

use crate::error::{Context, Result};
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};

/// How long a `<path>.lock` may sit untouched before it is presumed left
/// behind by a crashed process and force-broken. Real lock holders finish in
/// microseconds at these file sizes, so 30s is conservative.
pub const STALE_LOCK_AGE: Duration = Duration::from_secs(30);

/// Default bound on how long a writer waits for a contended lock.
const DEFAULT_LOCK_TIMEOUT: Duration = Duration::from_secs(5);

/// How often to re-poll for a contended lock.
const LOCK_POLL: Duration = Duration::from_millis(10);

/// Lockfile path for a target: `<path>.lock`.
fn lock_path(path: &Path) -> PathBuf {
    let mut name = path.as_os_str().to_os_string();
    name.push(".lock");
    PathBuf::from(name)
}

/// Temporary staging path for a target: a hidden dotfile sibling named
/// `.<name>.tmp.<pid>`. Being a sibling guarantees `rename` stays on one
/// filesystem (atomic); the dot prefix keeps staging files invisible to
/// directory listings (see `RefManager::list_branches`).
pub(crate) fn temp_sibling(path: &Path) -> PathBuf {
    let name = path
        .file_name()
        .map(|n| n.to_string_lossy().to_string())
        .unwrap_or_else(|| "state".to_string());
    path.with_file_name(format!(".{}.tmp.{}", name, std::process::id()))
}

/// Replace the contents of `path` with `data` atomically and with mutual
/// exclusion between writers. Creates parent directories as needed.
pub fn write_atomic(path: &Path, data: &[u8]) -> Result<()> {
    with_file_lock(path, DEFAULT_LOCK_TIMEOUT, || write_locked(path, data))
}

/// Write `data` to `path` via temp-file + rename, *without* taking the
/// lockfile. Only call this while already holding the lock via
/// [`with_file_lock`] — otherwise concurrent writers can interleave.
pub fn write_locked(path: &Path, data: &[u8]) -> Result<()> {
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent)
            .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
    }
    let tmp = temp_sibling(path);
    std::fs::write(&tmp, data)
        .with_context(|| format!("Failed to write staging file: {}", tmp.display()))?;
    std::fs::rename(&tmp, path)
        .with_context(|| format!("Failed to atomically replace: {}", path.display()))?;
    Ok(())
}

/// Run `f` while holding the exclusive `<path>.lock` lockfile for `path`.
///
/// Acquisition retries until `timeout`; a lockfile older than
/// [`STALE_LOCK_AGE`] is treated as abandoned by a crashed process and
/// force-broken. The lock is released when this function returns (including
/// on error paths) by removing the lockfile we created.
pub fn with_file_lock<T, F>(path: &Path, timeout: Duration, f: F) -> Result<T>
where
    F: FnOnce() -> Result<T>,
{
    let lock = lock_path(path);
    if let Some(parent) = lock.parent() {
        std::fs::create_dir_all(parent)
            .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
    }
    let deadline = Instant::now() + timeout;
    let mut held = false;
    while Instant::now() < deadline {
        match std::fs::OpenOptions::new()
            .write(true)
            .create_new(true)
            .open(&lock)
        {
            Ok(mut file) => {
                // Stamp our pid so release can verify ownership: a wedged
                // process recovering after its stale lock was broken by
                // another writer must not delete that writer's lock.
                use std::io::Write;
                let _ = writeln!(file, "{}", std::process::id());
                let _ = file.sync_all();
                held = true;
                break;
            }
            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
                if is_stale(&lock) {
                    // Best-effort break; another process may beat us to it,
                    // in which case create_new just fails again and we retry.
                    let _ = std::fs::remove_file(&lock);
                    continue;
                }
                std::thread::sleep(LOCK_POLL);
            }
            Err(e) => {
                return Err(e).with_context(|| format!("Failed to open lockfile: {}", lock.display()));
            }
        }
    }
    if !held {
        bail!(
            "Timed out after {:?} waiting for lock: {}",
            timeout,
            lock.display()
        );
    }
    let result = f();
    release_lockfile(&lock);
    result
}

/// Remove the lockfile only if it is still ours (pid-stamped). If another
/// process stale-broke our lock and took over, leave theirs alone.
fn release_lockfile(lock: &Path) {
    let mine = std::fs::read_to_string(lock)
        .ok()
        .map(|c| c.trim() == std::process::id().to_string())
        .unwrap_or(false);
    if mine {
        let _ = std::fs::remove_file(lock);
    }
}

/// True if the lockfile exists and has not been modified within
/// [`STALE_LOCK_AGE`] — i.e. it predates this attempt and looks abandoned.
fn is_stale(lock: &Path) -> bool {
    let Ok(meta) = std::fs::metadata(lock) else {
        return false;
    };
    let Ok(modified) = meta.modified() else {
        return false;
    };
    let Ok(age) = modified.elapsed() else {
        return false;
    };
    age >= STALE_LOCK_AGE
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::sync::Arc;
    use std::sync::atomic::{AtomicUsize, Ordering};
    use tempfile::TempDir;

    #[test]
    fn test_write_atomic_basic() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("state.json");
        write_atomic(&path, b"v1").unwrap();
        assert_eq!(std::fs::read(&path).unwrap(), b"v1");
        write_atomic(&path, b"v2-longer").unwrap();
        assert_eq!(std::fs::read(&path).unwrap(), b"v2-longer");
        // No staging or lock litter left behind.
        let leftovers: Vec<_> = std::fs::read_dir(tmp.path()).unwrap()
            .map(|e| e.unwrap().file_name().to_string_lossy().to_string())
            .filter(|n| n != "state.json")
            .collect();
        assert!(leftovers.is_empty(), "leftover files: {:?}", leftovers);
    }

    #[test]
    fn test_write_atomic_creates_parents() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("refs/heads/deep/branch");
        write_atomic(&path, b"abc").unwrap();
        assert_eq!(std::fs::read(&path).unwrap(), b"abc");
    }

    #[test]
    fn test_concurrent_writers_never_tear() {
        // 8 threads racing on one path; every write is a complete document.
        // Without temp+rename, a reader could observe interleaved bytes.
        let tmp = TempDir::new().unwrap();
        let path = Arc::new(tmp.path().join("contended"));
        write_atomic(&path, b"initial").unwrap();
        let mut handles = Vec::new();
        for i in 0..8u8 {
            let p = Arc::clone(&path);
            handles.push(std::thread::spawn(move || {
                for _ in 0..20 {
                    write_atomic(&p, &[b'a' + i; 512][..]).unwrap();
                }
            }));
        }
        for h in handles {
            h.join().unwrap();
        }
        let final_data = std::fs::read(&*path).unwrap();
        assert_eq!(final_data.len(), 512);
        // Every byte identical => the read observed one whole write, not a mix.
        assert!(final_data.iter().all(|&b| b == final_data[0]));
    }

    #[test]
    fn test_with_file_lock_serializes_access() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("rmw");
        let counter = Arc::new(AtomicUsize::new(0));
        let mut handles = Vec::new();
        for _ in 0..4 {
            let p = path.clone();
            let c = Arc::clone(&counter);
            handles.push(std::thread::spawn(move || {
                for _ in 0..25 {
                    with_file_lock(&p, Duration::from_secs(5), || {
                        // Read-modify-write cycle: must not interleave.
                        let cur = std::fs::read_to_string(&p)
                            .unwrap_or_default()
                            .trim()
                            .parse::<usize>()
                            .unwrap_or(0);
                        c.store(cur, Ordering::SeqCst);
                        write_locked(&p, format!("{}", cur + 1).as_bytes())?;
                        Ok(())
                    })
                    .unwrap();
                }
            }));
        }
        for h in handles {
            h.join().unwrap();
        }
        assert_eq!(std::fs::read_to_string(&path).unwrap().trim(), "100");
    }

    #[test]
    fn test_stale_lock_is_broken() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("stale");
        let lock = lock_path(&path);
        std::fs::write(&lock, b"").unwrap();

        // freshly created lock: still considered live -> times out fast
        let err = with_file_lock(&path, Duration::from_millis(50), || Ok(())).unwrap_err();
        assert!(err.to_string().contains("Timed out"));

        // backdate the lockfile: it must be broken and the write must succeed
        let old = std::time::SystemTime::now() - STALE_LOCK_AGE - Duration::from_secs(1);
        let file = std::fs::File::options().write(true).open(&lock).unwrap();
        file.set_modified(old).unwrap();
        drop(file);
        write_atomic(&path, b"recovered").unwrap();
        assert_eq!(std::fs::read(&path).unwrap(), b"recovered");
        assert!(!lock.exists());
    }

    #[test]
    fn test_lock_released_on_closure_error() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("err");
        let res: Result<()> = with_file_lock(&path, Duration::from_secs(1), || {
            bail!("inner failure")
        });
        assert!(res.is_err());
        // A failed closure must not leave the lock behind.
        assert!(!lock_path(&path).exists());
        // And a subsequent writer can proceed immediately.
        write_atomic(&path, b"ok").unwrap();
    }
}