local-store 0.2.0

//! Atomic file I/O helpers shared across storage types.
//!
//! Provides `get_temp_path`, `atomic_rename`, and `cleanup_temp_files` as
//! free functions so that `FileStorage`, `DirStorage`, and `AsyncDirStorage`
//! can all delegate to a single implementation instead of duplicating the
//! logic in each `impl` block.

use crate::errors::{IoOperationKind, StoreError};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::Duration;

/// Per-process monotonic counter appended to temporary file names so that
/// concurrent writers inside one process never share a temporary path.
static TMP_SEQ: AtomicU64 = AtomicU64::new(0);

/// Minimum age before an orphaned temporary file is removed by
/// [`cleanup_temp_files`].
///
/// Files younger than this are considered potentially in-flight (another
/// thread or process may still be writing them) and are left untouched.
pub const TMP_CLEANUP_MIN_AGE: Duration = Duration::from_secs(60);

/// Compute the path to a unique temporary file for `target_path`.
///
/// The temporary file is placed in the same directory as `target_path` so
/// that the subsequent rename stays on the same filesystem.
///
/// Format: `<parent>/.<filename>.tmp.<pid>-<seq>`
///
/// `<seq>` is a per-process monotonic counter, so concurrent writers in the
/// same process each get a distinct temporary file.
///
/// # Errors
///
/// `StoreError::IoError` if `target_path` has no parent directory or no
/// file-name component.
pub fn get_temp_path(target_path: &Path) -> Result<PathBuf, StoreError> {
    let parent = target_path.parent().ok_or_else(|| StoreError::IoError {
        operation: IoOperationKind::Create,
        path: target_path.display().to_string(),
        context: Some("path has no parent directory".to_string()),
        error: "cannot determine parent for temporary file".to_string(),
    })?;

    let file_name = target_path.file_name().ok_or_else(|| StoreError::IoError {
        operation: IoOperationKind::Create,
        path: target_path.display().to_string(),
        context: Some("path has no file name".to_string()),
        error: "cannot determine filename for temporary file".to_string(),
    })?;

    let tmp_name = format!(
        ".{}.tmp.{}-{}",
        file_name.to_string_lossy(),
        std::process::id(),
        TMP_SEQ.fetch_add(1, Ordering::Relaxed)
    );
    Ok(parent.join(tmp_name))
}

/// Fsync the parent directory of `target_path` so that a preceding rename is
/// durable across power loss (POSIX requires a directory fsync to persist
/// directory-entry changes).
///
/// No-op on non-Unix platforms, where directory handles cannot be synced the
/// same way.
///
/// # Errors
///
/// `StoreError::IoError { operation: Sync, … }` if the directory cannot be
/// opened or synced.
pub fn sync_parent_dir(target_path: &Path) -> Result<(), StoreError> {
    #[cfg(unix)]
    if let Some(parent) = target_path.parent() {
        if !parent.as_os_str().is_empty() {
            let map_err = |e: std::io::Error| StoreError::IoError {
                operation: IoOperationKind::Sync,
                path: parent.display().to_string(),
                context: Some("parent directory".to_string()),
                error: e.to_string(),
            };
            let dir = std::fs::File::open(parent).map_err(map_err)?;
            dir.sync_all().map_err(map_err)?;
        }
    }
    #[cfg(not(unix))]
    let _ = target_path;
    Ok(())
}

/// Rename `tmp_path` to `target_path` atomically, retrying up to
/// `retry_count` times with a 10 ms delay between attempts.
///
/// # Errors
///
/// `StoreError::IoError { operation: Rename, … }` after all retries are
/// exhausted.
pub fn atomic_rename(
    tmp_path: &Path,
    target_path: &Path,
    retry_count: usize,
) -> Result<(), StoreError> {
    let mut last_error = None;

    for attempt in 0..retry_count {
        match std::fs::rename(tmp_path, target_path) {
            Ok(()) => return Ok(()),
            Err(e) => {
                last_error = Some(e);
                if attempt + 1 < retry_count {
                    std::thread::sleep(std::time::Duration::from_millis(10));
                }
            }
        }
    }

    Err(StoreError::IoError {
        operation: IoOperationKind::Rename,
        path: target_path.display().to_string(),
        context: Some(format!("after {} retries", retry_count)),
        error: last_error
            .map(|e| e.to_string())
            .unwrap_or_else(|| "unknown error after retries".to_string()),
    })
}

/// Remove orphaned `.<filename>.tmp.*` files in the same directory as
/// `target_path`.
///
/// Only files older than [`TMP_CLEANUP_MIN_AGE`] are removed: a younger file
/// may belong to a concurrent writer (another thread or process) that has not
/// yet renamed it into place.
///
/// Errors are silently ignored (best-effort cleanup).
pub fn cleanup_temp_files(target_path: &Path) -> std::io::Result<()> {
    cleanup_temp_files_with_min_age(target_path, TMP_CLEANUP_MIN_AGE)
}

/// [`cleanup_temp_files`] with an explicit minimum age threshold.
///
/// Files whose modification time is younger than `min_age` (or cannot be
/// determined) are left untouched.
///
/// Errors are silently ignored (best-effort cleanup).
pub fn cleanup_temp_files_with_min_age(
    target_path: &Path,
    min_age: Duration,
) -> std::io::Result<()> {
    let parent = match target_path.parent() {
        Some(p) => p,
        None => return Ok(()),
    };

    let file_name = match target_path.file_name() {
        Some(f) => f.to_string_lossy().into_owned(),
        None => return Ok(()),
    };

    let prefix = format!(".{}.tmp.", file_name);

    if let Ok(entries) = std::fs::read_dir(parent) {
        for entry in entries.flatten() {
            if let Ok(name) = entry.file_name().into_string() {
                if name.starts_with(&prefix) && is_older_than(&entry.path(), min_age) {
                    let _ = std::fs::remove_file(entry.path());
                }
            }
        }
    }

    Ok(())
}

/// Best-effort check that a file's mtime is at least `min_age` in the past.
///
/// Returns `false` when metadata or mtime is unavailable, or when the mtime
/// lies in the future — deleting is skipped in all uncertain cases.
fn is_older_than(path: &Path, min_age: Duration) -> bool {
    std::fs::metadata(path)
        .and_then(|m| m.modified())
        .ok()
        .and_then(|mtime| mtime.elapsed().ok())
        .map(|age| age >= min_age)
        .unwrap_or(false)
}

// ============================================================================
// Async variants
// ============================================================================

#[cfg(feature = "async")]
pub mod async_io {
    //! Async variants of the atomic I/O helpers.
    //!
    //! `get_temp_path` is synchronous and shared with the sync module;
    //! call `super::get_temp_path(target_path)` from async callers.

    use crate::errors::{IoOperationKind, StoreError};
    use std::path::Path;

    /// Rename `tmp_path` to `target_path` atomically (async), retrying up to
    /// `retry_count` times with a 10 ms `tokio::time::sleep` between attempts.
    ///
    /// # Errors
    ///
    /// `StoreError::IoError { operation: Rename, … }` after all retries are
    /// exhausted.
    pub async fn atomic_rename(
        tmp_path: &Path,
        target_path: &Path,
        retry_count: usize,
    ) -> Result<(), StoreError> {
        let mut last_error = None;

        for attempt in 0..retry_count {
            match tokio::fs::rename(tmp_path, target_path).await {
                Ok(()) => return Ok(()),
                Err(e) => {
                    last_error = Some(e);
                    if attempt + 1 < retry_count {
                        tokio::time::sleep(tokio::time::Duration::from_millis(10)).await;
                    }
                }
            }
        }

        Err(StoreError::IoError {
            operation: IoOperationKind::Rename,
            path: target_path.display().to_string(),
            context: Some(format!("after {} retries (async)", retry_count)),
            error: last_error
                .map(|e| e.to_string())
                .unwrap_or_else(|| "unknown error after retries".to_string()),
        })
    }

    /// Remove orphaned `.<filename>.tmp.*` files in the same directory as
    /// `target_path` (async).
    ///
    /// Only files older than [`super::TMP_CLEANUP_MIN_AGE`] are removed: a
    /// younger file may belong to a concurrent writer (another thread or
    /// process) that has not yet renamed it into place.
    ///
    /// Errors are silently ignored (best-effort cleanup).
    pub async fn cleanup_temp_files(target_path: &Path) -> std::io::Result<()> {
        cleanup_temp_files_with_min_age(target_path, super::TMP_CLEANUP_MIN_AGE).await
    }

    /// [`cleanup_temp_files`] with an explicit minimum age threshold (async).
    ///
    /// Files whose modification time is younger than `min_age` (or cannot be
    /// determined) are left untouched.
    ///
    /// Errors are silently ignored (best-effort cleanup).
    pub async fn cleanup_temp_files_with_min_age(
        target_path: &Path,
        min_age: std::time::Duration,
    ) -> std::io::Result<()> {
        let parent = match target_path.parent() {
            Some(p) => p,
            None => return Ok(()),
        };

        let file_name = match target_path.file_name() {
            Some(f) => f.to_string_lossy().into_owned(),
            None => return Ok(()),
        };

        let prefix = format!(".{}.tmp.", file_name);

        let mut entries = match tokio::fs::read_dir(parent).await {
            Ok(e) => e,
            Err(_) => return Ok(()),
        };

        while let Ok(Some(entry)) = entries.next_entry().await {
            if let Ok(name) = entry.file_name().into_string() {
                if name.starts_with(&prefix) && super::is_older_than(&entry.path(), min_age) {
                    let _ = tokio::fs::remove_file(entry.path()).await;
                }
            }
        }

        Ok(())
    }

    /// Fsync the parent directory of `target_path` (async) so that a
    /// preceding rename is durable across power loss.
    ///
    /// No-op on non-Unix platforms, where directory handles cannot be synced
    /// the same way.
    ///
    /// # Errors
    ///
    /// `StoreError::IoError { operation: Sync, … }` if the directory cannot
    /// be opened or synced.
    pub async fn sync_parent_dir(target_path: &Path) -> Result<(), StoreError> {
        #[cfg(unix)]
        if let Some(parent) = target_path.parent() {
            if !parent.as_os_str().is_empty() {
                let map_err = |e: std::io::Error| StoreError::IoError {
                    operation: IoOperationKind::Sync,
                    path: parent.display().to_string(),
                    context: Some("parent directory (async)".to_string()),
                    error: e.to_string(),
                };
                let dir = tokio::fs::File::open(parent).await.map_err(map_err)?;
                dir.sync_all().await.map_err(map_err)?;
            }
        }
        #[cfg(not(unix))]
        let _ = target_path;
        Ok(())
    }
}

// ============================================================================
// Tests
// ============================================================================

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

    #[test]
    fn test_get_temp_path_format() {
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("config.toml");
        let tmp = get_temp_path(&target).unwrap();
        let name = tmp.file_name().unwrap().to_string_lossy();
        assert!(
            name.starts_with(".config.toml.tmp."),
            "tmp name should start with .<filename>.tmp., got: {}",
            name
        );
        assert_eq!(tmp.parent().unwrap(), dir.path());
    }

    #[test]
    fn test_get_temp_path_no_parent_errors() {
        // A path with no parent (root-relative bare name has parent "").
        // Use a path that genuinely has no parent component.
        let bare = std::path::PathBuf::from("/");
        // "/" has no file_name, so this should error.
        let result = get_temp_path(&bare);
        assert!(result.is_err(), "root path should produce an error");
    }

    #[test]
    fn test_atomic_rename_success() {
        let dir = TempDir::new().unwrap();
        let src = dir.path().join("src.tmp");
        let dst = dir.path().join("dst.toml");
        fs::write(&src, "data").unwrap();
        atomic_rename(&src, &dst, 3).unwrap();
        assert!(dst.exists());
        assert!(!src.exists());
        assert_eq!(fs::read_to_string(&dst).unwrap(), "data");
    }

    #[test]
    fn test_atomic_rename_fails_when_src_missing() {
        let dir = TempDir::new().unwrap();
        let src = dir.path().join("nonexistent.tmp");
        let dst = dir.path().join("dst.toml");
        let result = atomic_rename(&src, &dst, 1);
        assert!(result.is_err(), "should fail when src does not exist");
        if let Err(StoreError::IoError { operation, .. }) = result {
            assert_eq!(operation, IoOperationKind::Rename);
        } else {
            panic!("expected StoreError::IoError(Rename)");
        }
    }

    #[test]
    fn test_get_temp_path_unique_per_call() {
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("config.toml");
        let tmp1 = get_temp_path(&target).unwrap();
        let tmp2 = get_temp_path(&target).unwrap();
        assert_ne!(
            tmp1, tmp2,
            "concurrent writers must never share a temp path"
        );
    }

    #[test]
    fn test_cleanup_temp_files_removes_matching() {
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("data.toml");

        let stale1 = dir.path().join(".data.toml.tmp.11111-0");
        let stale2 = dir.path().join(".data.toml.tmp.22222-0");
        let other = dir.path().join("other.toml");
        fs::write(&stale1, "s1").unwrap();
        fs::write(&stale2, "s2").unwrap();
        fs::write(&other, "keep").unwrap();

        // min_age = 0 so the freshly created files qualify as orphans.
        cleanup_temp_files_with_min_age(&target, Duration::ZERO).unwrap();

        assert!(!stale1.exists(), "stale1 should be removed");
        assert!(!stale2.exists(), "stale2 should be removed");
        assert!(other.exists(), "other.toml should be kept");
    }

    #[test]
    fn test_cleanup_temp_files_keeps_fresh_files() {
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("data.toml");

        // Simulates another writer's in-flight temp file.
        let in_flight = dir.path().join(".data.toml.tmp.33333-0");
        fs::write(&in_flight, "in-flight").unwrap();

        cleanup_temp_files(&target).unwrap();

        assert!(
            in_flight.exists(),
            "files younger than TMP_CLEANUP_MIN_AGE must be kept"
        );
    }

    #[test]
    fn test_cleanup_temp_files_no_matches_is_ok() {
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("config.toml");
        // No .tmp files — should not error.
        cleanup_temp_files(&target).unwrap();
    }
}