dodot-lib 5.10.0

mod os;

pub use os::OsFs;

use std::path::{Path, PathBuf};

use crate::Result;

/// Metadata about a filesystem entry.
#[derive(Debug, Clone)]
pub struct FsMetadata {
    pub is_file: bool,
    pub is_dir: bool,
    pub is_symlink: bool,
    pub len: u64,
    /// Unix permission mode (e.g. `0o755`).
    pub mode: u32,
    /// Which entry this is and when it last changed — what a caller
    /// compares to ask whether a path still holds what it left there.
    ///
    /// See [`FileId`].
    pub id: FileId,
}

/// A filesystem entry's identity and version: the device and inode
/// numbers `stat(2)` reports, plus the entry's ctime.
///
/// A path answers "what is here now", and that answer changes under a
/// caller whenever another process writes the same path. This answers
/// "is this still the entry I left here", which is what a recovery
/// step needs before it moves or removes something it believes it
/// created.
///
/// All four numbers, because none of the three parts is sufficient
/// alone:
///
/// - Inode numbers are unique only within a filesystem, so `dev` comes
///   with `ino` — a mount appearing at a path is enough for one inode
///   number to name a different file than it did a moment earlier.
/// - A freed inode number is handed straight back out: removing a file
///   and writing a fresh one at the same path commonly lands on the
///   *same* `ino` on ext4 and tmpfs, so identity alone reads a
///   replaced file as the original. The ctime of the replacement is
///   its creation, which is later than the one recorded, and that is
///   what separates the two.
///
/// The comparison is not free of races — another process can still
/// act between the read and the move — but it turns "assume it is
/// ours" into "check that it is", which is the difference between
/// silently destroying a concurrent writer's file and leaving it
/// alone. Note what a match means, too: the entry has not been
/// replaced *and* nothing has touched its metadata since. A `chmod`
/// by another process reads as "not the same state", which fails
/// toward leaving the path alone.
///
/// A `rename` changes the ctime of the entry it moves, so a caller
/// recording an entry it renames reads the id at its destination, and
/// uses the pre-rename `dev`/`ino` to prove the destination is still
/// that entry rather than something that raced it there.
///
/// The [`Default`] is the zeros a filesystem stub reports when it
/// models no identity at all. Two such stubs compare equal, so a
/// caller that decides anything on identity has to run against a real
/// filesystem to be testing what it thinks it is.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct FileId {
    pub dev: u64,
    pub ino: u64,
    /// Seconds and nanoseconds of the entry's last status change.
    pub ctime: i64,
    pub ctime_nsec: i64,
}

impl FileId {
    /// Whether both ids name the same filesystem entry, disregarding
    /// when it last changed.
    ///
    /// This is the question a caller asks across its own `rename`,
    /// which carries the entry over but stamps it with a new ctime.
    /// Everywhere else the full comparison is the one that answers
    /// "is this still what I left here", because a reused inode
    /// number passes this one.
    pub fn same_entry(&self, other: &FileId) -> bool {
        self.dev == other.dev && self.ino == other.ino
    }
}

/// A single directory entry returned by [`Fs::read_dir`].
#[derive(Debug, Clone)]
pub struct DirEntry {
    pub path: PathBuf,
    pub name: String,
    pub is_dir: bool,
    pub is_file: bool,
    pub is_symlink: bool,
}

/// Filesystem abstraction.
///
/// All dodot code accesses the filesystem through this trait so that:
/// - Tests can use isolated temp directories with a real implementation
/// - Every `io::Error` is wrapped with the path that caused it
///
/// Use `&dyn Fs` (trait objects) throughout the codebase. The operations
/// are I/O-bound so dynamic dispatch costs nothing meaningful, and generics
/// would infect every type signature.
pub trait Fs: Send + Sync {
    /// Returns metadata for the path, following symlinks.
    fn stat(&self, path: &Path) -> Result<FsMetadata>;

    /// Returns metadata for the path without following symlinks.
    fn lstat(&self, path: &Path) -> Result<FsMetadata>;

    /// Opens the file for reading in a streaming fashion.
    ///
    /// Errors that occur while opening the file are returned through this
    /// method's [`Result`] and include path context. Once opened, the
    /// returned reader is a raw [`std::io::Read`], so any later `read()`
    /// errors are reported as plain [`std::io::Error`] values and are not
    /// automatically wrapped with the path.
    fn open_read(&self, path: &Path) -> Result<Box<dyn std::io::Read + Send + Sync>>;

    /// Reads the entire file into bytes.
    fn read_file(&self, path: &Path) -> Result<Vec<u8>>;

    /// Reads the entire file as a UTF-8 string.
    fn read_to_string(&self, path: &Path) -> Result<String>;

    /// Writes `contents` to `path`, creating or truncating the file.
    fn write_file(&self, path: &Path, contents: &[u8]) -> Result<()>;

    /// Writes `contents` to `path`, creating or truncating the file
    /// **with `mode` applied at creation time** (not via a follow-up
    /// `chmod`). Used by whole-file secret preprocessors so the
    /// rendered plaintext never lives at the umask-default mode,
    /// even briefly — closing the race window between
    /// `write_file` (lands at e.g. 0644 on a typical 022 umask)
    /// and `set_permissions` (tightens to 0600). See
    /// `secrets.lex` §4.3.
    ///
    /// The default impl is the racy `write_file` +
    /// `set_permissions` pair; `OsFs` overrides it to apply the
    /// mode via `OpenOptions::mode` instead.
    fn write_file_with_mode(&self, path: &Path, contents: &[u8], mode: u32) -> Result<()> {
        self.write_file(path, contents)?;
        self.set_permissions(path, mode)
    }

    /// Writes `contents` to `path` through a temp sibling renamed into
    /// place, so a concurrent reader never sees a partial file.
    ///
    /// `write_file` truncates in place: a reader that opens the file
    /// mid-write gets a prefix of it, cut at an arbitrary byte. That
    /// is fine for files nothing reads concurrently, but wrong for
    /// any artifact with a live reader — the shell init script and
    /// the Homebrew cache are both sourced/read by *every shell the
    /// user opens* while `dodot up` may be rewriting them. Use this
    /// method for any such file.
    ///
    /// The temp is a sibling (same directory ⇒ same filesystem ⇒ the
    /// rename is atomic on POSIX) named by pid plus a process-global
    /// counter, so no two live writers — threads or processes — can
    /// ever select the same temp. Any failure after the temp is
    /// created (a failed write or rename — plus a failed chmod in
    /// [`Fs::write_atomic_with_mode`]) removes it rather than
    /// abandoning it; only a crash mid-write can leave a temp
    /// behind, and never a torn target.
    ///
    /// Note the trade-off: the rename replaces the *directory entry*,
    /// so `path` gets a fresh inode. Do not use this on files the
    /// user may hold as a hard link or that must stay a symlink —
    /// e.g. rc files, which are commonly symlinks into a dotfiles
    /// repo that a rename would silently replace with a regular file.
    ///
    /// The temp name is unique but predictable, and creation does not
    /// use `O_EXCL`: this is a primitive for directories the user
    /// owns (the datastore, `$XDG_*` paths), not for shared,
    /// world-writable directories like `/tmp`, where a predictable
    /// name would open a symlink pre-creation attack.
    fn write_atomic(&self, path: &Path, contents: &[u8]) -> Result<()> {
        let tmp = temp_sibling(path);
        if let Err(e) = self.write_file(&tmp, contents) {
            let _ = self.remove_file(&tmp);
            return Err(e);
        }
        if let Err(e) = self.rename(&tmp, path) {
            let _ = self.remove_file(&tmp);
            return Err(e);
        }
        Ok(())
    }

    /// [`Fs::write_atomic`], with `mode` applied to the temp file
    /// **before** the rename — the visible file carries the intended
    /// mode from its first instant, never a umask-default one. Used
    /// for the init script, which is documented (and tested) as
    /// executable.
    fn write_atomic_with_mode(&self, path: &Path, contents: &[u8], mode: u32) -> Result<()> {
        let tmp = temp_sibling(path);
        if let Err(e) = self.write_file_with_mode(&tmp, contents, mode) {
            let _ = self.remove_file(&tmp);
            return Err(e);
        }
        if let Err(e) = self.rename(&tmp, path) {
            let _ = self.remove_file(&tmp);
            return Err(e);
        }
        Ok(())
    }

    /// Creates `path` and all parent directories.
    fn mkdir_all(&self, path: &Path) -> Result<()>;

    /// Creates `path` as a new directory, failing with
    /// [`std::io::ErrorKind::AlreadyExists`] if anything is there
    /// already. Parent directories must exist.
    ///
    /// The exclusive counterpart to [`Fs::mkdir_all`], which treats an
    /// existing directory as success. A caller that needs the
    /// directory to be *its own* — a staging area no other process is
    /// also writing into — creates it with this and reads
    /// `AlreadyExists` as "choose another name", never as success.
    /// Creation and the existence test are one operation, so two
    /// processes racing for the same name cannot both win.
    fn mkdir_exclusive(&self, path: &Path) -> Result<()>;

    /// Creates a symbolic link at `link` pointing to `original`.
    fn symlink(&self, original: &Path, link: &Path) -> Result<()>;

    /// Reads the target of a symbolic link.
    fn readlink(&self, path: &Path) -> Result<PathBuf>;

    /// Removes a file or symlink (not a directory).
    fn remove_file(&self, path: &Path) -> Result<()>;

    /// Removes a directory and all of its contents.
    fn remove_dir_all(&self, path: &Path) -> Result<()>;

    /// Removes a directory only if it is empty, failing with
    /// [`std::io::ErrorKind::DirectoryNotEmpty`] if it is not.
    ///
    /// The kernel decides emptiness inside the same operation that
    /// removes, which is what a cleanup needs: "list it, see nothing,
    /// then `remove_dir_all`" deletes whatever another process put
    /// there between the two calls. A caller undoing its own work asks
    /// here so that a directory which has since picked up someone
    /// else's content survives.
    fn remove_dir_empty(&self, path: &Path) -> Result<()>;

    /// Returns `true` if `path` exists (follows symlinks).
    fn exists(&self, path: &Path) -> bool;

    /// Returns `true` if `path` is a symlink (does not follow).
    fn is_symlink(&self, path: &Path) -> bool;

    /// Returns `true` if `path` is a directory (follows symlinks).
    fn is_dir(&self, path: &Path) -> bool;

    /// Lists entries in a directory, sorted by name.
    fn read_dir(&self, path: &Path) -> Result<Vec<DirEntry>>;

    /// Renames (moves) `from` to `to`, replacing `to` if it exists —
    /// POSIX `rename` semantics, including replacing an empty
    /// directory or a symlink.
    fn rename(&self, from: &Path, to: &Path) -> Result<()>;

    /// Renames `from` to `to` unless `to` exists, in which case it
    /// fails with [`std::io::ErrorKind::AlreadyExists`] and leaves
    /// both paths as they were.
    ///
    /// Because [`Fs::rename`] replaces its destination, "test that
    /// `to` is free, then rename" still overwrites a destination that
    /// appeared between the two calls — an empty directory or a
    /// symlink is enough. Here the kernel makes that decision in the
    /// same operation that moves the file: `renameat2` with
    /// `RENAME_NOREPLACE` on Linux, `renamex_np` with `RENAME_EXCL` on
    /// macOS.
    fn rename_noreplace(&self, from: &Path, to: &Path) -> Result<()>;

    /// Copies a file from `from` to `to`.
    fn copy_file(&self, from: &Path, to: &Path) -> Result<()>;

    /// Sets file permissions (Unix mode).
    fn set_permissions(&self, path: &Path, mode: u32) -> Result<()>;

    /// Returns the modification time of `path` (follows symlinks).
    /// Used by `dodot refresh` to compare deployed-side mtimes against
    /// source-side mtimes when deciding whether to touch the source.
    ///
    /// **Default implementation panics.** Override in `Fs` impls that
    /// need mtime support (currently `OsFs`).
    fn modified(&self, _path: &Path) -> Result<std::time::SystemTime> {
        unimplemented!("Fs::modified is only implemented by OsFs")
    }

    /// Sets the modification time of `path` to `time`. Used by
    /// `dodot refresh` to copy the deployed file's mtime onto the
    /// template source so git's stat-cache invalidates and the next
    /// `git status` re-reads the file (invoking the clean filter on
    /// repos that have it installed).
    ///
    /// **Default implementation panics.** Override in `Fs` impls that
    /// need mtime support (currently `OsFs`).
    fn set_modified(&self, _path: &Path, _time: std::time::SystemTime) -> Result<()> {
        unimplemented!("Fs::set_modified is only implemented by OsFs")
    }
}

/// `true` when `e` is the "something is already there" refusal of
/// [`Fs::mkdir_exclusive`] or [`Fs::rename_noreplace`].
///
/// Both report it as an [`std::io::ErrorKind::AlreadyExists`], the
/// first in [`DodotError::Fs`](crate::DodotError::Fs) and the second
/// in [`DodotError::FsBetween`](crate::DodotError::FsBetween), which
/// names both ends of a rename because either can be the one at fault.
/// Callers that retry under another name, or turn the collision into
/// their own message, ask here rather than matching the variants
/// themselves.
pub(crate) fn is_already_exists(e: &crate::DodotError) -> bool {
    let source = match e {
        crate::DodotError::Fs { source, .. } => source,
        crate::DodotError::FsBetween { source, .. } => source,
        _ => return false,
    };
    source.kind() == std::io::ErrorKind::AlreadyExists
}

/// A dotted temp path in `path`'s own directory, for the write-then-
/// rename in [`Fs::write_atomic`]. Same directory means same
/// filesystem, which is what makes the rename atomic. The suffix is
/// the pid plus a process-global counter: pids are unique among live
/// processes and the counter within this one, so two live writers —
/// threads or processes — can never select the same temp; uniqueness
/// is structural, not probabilistic. (After pid reuse a name can
/// recur, but only colliding with a stale leftover of a dead process
/// that nothing holds open — truncating it is harmless.)
fn temp_sibling(path: &Path) -> PathBuf {
    static SEQ: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
    let parent = path.parent().unwrap_or(Path::new("."));
    let name = path.file_name().unwrap_or_default().to_string_lossy();
    let seq = SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    parent.join(format!(".dodot-{name}.{}-{seq:x}.tmp", std::process::id()))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::DodotError;
    use std::collections::HashSet;
    use std::sync::Barrier;
    use tempfile::TempDir;

    #[test]
    fn temp_sibling_never_repeats_across_threads_and_calls() {
        // The atomicity guarantee rests on no two live writers ever
        // selecting the same temp. Hammer temp_sibling from parallel
        // threads and assert every returned path is distinct.
        let path = Path::new("/some/dir/file.txt");
        let mut seen = HashSet::new();
        std::thread::scope(|s| {
            let handles: Vec<_> = (0..8)
                .map(|_| s.spawn(|| (0..1000).map(|_| temp_sibling(path)).collect::<Vec<_>>()))
                .collect();
            for h in handles {
                for p in h.join().unwrap() {
                    assert!(seen.insert(p), "temp_sibling returned a duplicate path");
                }
            }
        });
    }

    #[test]
    fn concurrent_writers_to_one_target_leave_one_complete_file_and_no_temps() {
        // Racing write_atomic calls must each go through a private
        // temp: whichever rename lands last wins whole — the target
        // is exactly one writer's full payload, never an interleaving
        // — and every loser's temp is gone (consumed by its rename).
        const WRITERS: u8 = 8;
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("target.bin");
        let payloads: Vec<Vec<u8>> = (0..WRITERS).map(|i| vec![i; 64 * 1024]).collect();
        let barrier = Barrier::new(WRITERS as usize);
        std::thread::scope(|s| {
            for payload in &payloads {
                s.spawn(|| {
                    barrier.wait();
                    OsFs::new().write_atomic(&target, payload).unwrap();
                });
            }
        });
        let survivor = std::fs::read(&target).unwrap();
        assert!(
            payloads.contains(&survivor),
            "target must be exactly one writer's full payload"
        );
        let leftovers: Vec<String> = std::fs::read_dir(dir.path())
            .unwrap()
            .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
            .filter(|name| name.ends_with(".tmp"))
            .collect();
        assert!(
            leftovers.is_empty(),
            "temp siblings left behind: {leftovers:?}"
        );
    }

    /// Delegates to [`OsFs`], injecting a failure into one operation —
    /// for proving the write-atomic methods clean up their temp on
    /// every post-creation error path, not just a failed rename.
    ///
    /// The injected `write_file` failure lands the bytes first and
    /// *then* errors, mimicking the interesting real-world shape
    /// (ENOSPC mid-write): the temp exists on disk when the error
    /// surfaces, so returning it unremoved would leak it.
    struct FaultFs {
        inner: OsFs,
        fail_write: bool,
        fail_chmod: bool,
    }

    impl FaultFs {
        fn injected(&self, path: &Path) -> DodotError {
            DodotError::Fs {
                path: path.to_path_buf(),
                source: std::io::Error::other("injected fault"),
            }
        }
    }

    impl Fs for FaultFs {
        fn stat(&self, path: &Path) -> Result<FsMetadata> {
            self.inner.stat(path)
        }
        fn lstat(&self, path: &Path) -> Result<FsMetadata> {
            self.inner.lstat(path)
        }
        fn open_read(&self, path: &Path) -> Result<Box<dyn std::io::Read + Send + Sync>> {
            self.inner.open_read(path)
        }
        fn read_file(&self, path: &Path) -> Result<Vec<u8>> {
            self.inner.read_file(path)
        }
        fn read_to_string(&self, path: &Path) -> Result<String> {
            self.inner.read_to_string(path)
        }
        fn write_file(&self, path: &Path, contents: &[u8]) -> Result<()> {
            self.inner.write_file(path, contents)?;
            if self.fail_write {
                return Err(self.injected(path));
            }
            Ok(())
        }
        fn set_permissions(&self, path: &Path, mode: u32) -> Result<()> {
            if self.fail_chmod {
                return Err(self.injected(path));
            }
            self.inner.set_permissions(path, mode)
        }
        fn mkdir_all(&self, path: &Path) -> Result<()> {
            self.inner.mkdir_all(path)
        }
        fn mkdir_exclusive(&self, path: &Path) -> Result<()> {
            self.inner.mkdir_exclusive(path)
        }
        fn symlink(&self, original: &Path, link: &Path) -> Result<()> {
            self.inner.symlink(original, link)
        }
        fn readlink(&self, path: &Path) -> Result<PathBuf> {
            self.inner.readlink(path)
        }
        fn remove_file(&self, path: &Path) -> Result<()> {
            self.inner.remove_file(path)
        }
        fn remove_dir_all(&self, path: &Path) -> Result<()> {
            self.inner.remove_dir_all(path)
        }
        fn remove_dir_empty(&self, path: &Path) -> Result<()> {
            self.inner.remove_dir_empty(path)
        }
        fn exists(&self, path: &Path) -> bool {
            self.inner.exists(path)
        }
        fn is_symlink(&self, path: &Path) -> bool {
            self.inner.is_symlink(path)
        }
        fn is_dir(&self, path: &Path) -> bool {
            self.inner.is_dir(path)
        }
        fn read_dir(&self, path: &Path) -> Result<Vec<DirEntry>> {
            self.inner.read_dir(path)
        }
        fn rename(&self, from: &Path, to: &Path) -> Result<()> {
            self.inner.rename(from, to)
        }
        fn rename_noreplace(&self, from: &Path, to: &Path) -> Result<()> {
            self.inner.rename_noreplace(from, to)
        }
        fn copy_file(&self, from: &Path, to: &Path) -> Result<()> {
            self.inner.copy_file(from, to)
        }
    }

    fn tmp_leftovers(dir: &Path) -> Vec<String> {
        std::fs::read_dir(dir)
            .unwrap()
            .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
            .filter(|name| name.ends_with(".tmp"))
            .collect()
    }

    #[test]
    fn write_atomic_removes_the_temp_when_the_write_fails() {
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("target.txt");
        let fs = FaultFs {
            inner: OsFs::new(),
            fail_write: true,
            fail_chmod: false,
        };
        assert!(fs.write_atomic(&target, b"data").is_err());
        assert!(!target.exists(), "target must not appear on a failed write");
        let leftovers = tmp_leftovers(dir.path());
        assert!(
            leftovers.is_empty(),
            "temp siblings left behind: {leftovers:?}"
        );
    }

    #[test]
    fn write_atomic_with_mode_removes_the_temp_when_the_chmod_fails() {
        // The chmod happens after the temp is fully written — the
        // temp is guaranteed on disk when the error surfaces, so
        // this pins the cleanup, not just error propagation.
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("target.sh");
        let fs = FaultFs {
            inner: OsFs::new(),
            fail_write: false,
            fail_chmod: true,
        };
        assert!(fs
            .write_atomic_with_mode(&target, b"#!/bin/sh\n", 0o755)
            .is_err());
        assert!(!target.exists(), "target must not appear on a failed chmod");
        let leftovers = tmp_leftovers(dir.path());
        assert!(
            leftovers.is_empty(),
            "temp siblings left behind: {leftovers:?}"
        );
    }
}