wowlab_fs/

directory.rs

//! Directory mutation and symlink-aware inspection.

use std::time::SystemTime;

use crate::{
    error::{Error, Operation, Result},
    path::{Path, PathBuf},
};

/// Kind of entry observed without following its final symlink.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum EntryKind {
    /// A regular file.
    File,
    /// A directory.
    Directory,
    /// A symbolic link.
    Symlink,
    /// A platform-specific entry kind.
    Other,
}

/// Snapshot of one filesystem entry.
#[derive(Clone, Debug)]
pub struct EntryInfo {
    path: PathBuf,
    kind: EntryKind,
    len: u64,
    modified: Option<SystemTime>,
}

impl EntryInfo {
    /// Return the entry path.
    #[must_use]
    pub fn path(&self) -> &Path {
        &self.path
    }

    /// Return the entry kind.
    #[must_use]
    pub const fn kind(&self) -> EntryKind {
        self.kind
    }

    /// Return the reported byte length.
    #[must_use]
    pub const fn len(&self) -> u64 {
        self.len
    }

    /// Report whether the entry has zero reported bytes.
    #[must_use]
    pub const fn is_empty(&self) -> bool {
        self.len == 0
    }

    /// Return the last-modified time when the platform provides it.
    #[must_use]
    pub const fn modified(&self) -> Option<SystemTime> {
        self.modified
    }
}

/// Create a directory and every missing ancestor.
///
/// # Errors
///
/// Returns a contextual error when the directory cannot be ensured.
pub fn ensure(path: &Path) -> Result<()> {
    std::fs::create_dir_all(path)
        .map_err(|source| Error::new(Operation::CreateDirectory, path, source))
}

/// Create exactly one directory.
///
/// # Errors
///
/// Returns a contextual error when the directory cannot be created.
pub fn create(path: &Path) -> Result<()> {
    std::fs::create_dir(path).map_err(|source| Error::new(Operation::CreateDirectory, path, source))
}

/// Inspect a path while following its final symlink.
///
/// A missing path is represented by `Ok(None)`.
///
/// # Errors
///
/// Returns a contextual error when metadata cannot be read.
pub fn inspect(path: &Path) -> Result<Option<EntryInfo>> {
    inspect_with(path, true)
}

/// Inspect a path without following its final symlink.
///
/// A missing path is represented by `Ok(None)`.
///
/// # Errors
///
/// Returns a contextual error when metadata cannot be read.
pub fn inspect_link(path: &Path) -> Result<Option<EntryInfo>> {
    inspect_with(path, false)
}

fn inspect_with(path: &Path, follow: bool) -> Result<Option<EntryInfo>> {
    let result = if follow {
        std::fs::metadata(path)
    } else {
        std::fs::symlink_metadata(path)
    };
    let metadata = match result {
        Ok(metadata) => metadata,
        Err(source) if source.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(source) => return Err(Error::new(Operation::Inspect, path, source)),
    };
    let file_type = metadata.file_type();
    let kind = if file_type.is_file() {
        EntryKind::File
    } else if file_type.is_dir() {
        EntryKind::Directory
    } else if file_type.is_symlink() {
        EntryKind::Symlink
    } else {
        EntryKind::Other
    };

    Ok(Some(EntryInfo {
        path: path.to_path_buf(),
        kind,
        len: metadata.len(),
        modified: metadata.modified().ok(),
    }))
}

/// Read and sort all immediate directory entries.
///
/// Entry kinds are captured without following final symlinks.
///
/// # Errors
///
/// Returns a contextual error for opening the directory or reading any entry.
pub fn entries(path: &Path) -> Result<Vec<EntryInfo>> {
    let entries = std::fs::read_dir(path)
        .map_err(|source| Error::new(Operation::ReadDirectory, path, source))?;
    let mut result = Vec::new();

    for entry in entries {
        let entry = entry.map_err(|source| Error::new(Operation::ReadDirectory, path, source))?;
        let entry_path = PathBuf::from(entry.path());
        let info = inspect_link(&entry_path)?.ok_or_else(|| {
            Error::new(
                Operation::Inspect,
                &entry_path,
                std::io::Error::new(
                    std::io::ErrorKind::NotFound,
                    "directory entry disappeared during inspection",
                ),
            )
        })?;

        result.push(info);
    }

    result.sort_by(|left, right| left.path.cmp(&right.path));

    Ok(result)
}

/// Remove a file when present.
///
/// Returns whether an entry was removed.
///
/// # Errors
///
/// Returns a contextual error for failures other than a missing path.
pub fn remove_file_if_exists(path: &Path) -> Result<bool> {
    match std::fs::remove_file(path) {
        Ok(()) => Ok(true),
        Err(source) if source.kind() == std::io::ErrorKind::NotFound => Ok(false),
        Err(source) => Err(Error::new(Operation::RemoveFile, path, source)),
    }
}

/// Remove an empty directory.
///
/// # Errors
///
/// Returns a contextual error when the directory cannot be removed.
pub fn remove_if_empty(path: &Path) -> Result<()> {
    std::fs::remove_dir(path).map_err(|source| Error::new(Operation::RemoveDirectory, path, source))
}

/// Remove a directory tree when present.
///
/// Returns whether an entry was removed.
///
/// # Errors
///
/// Returns a contextual error for failures other than a missing path.
pub fn remove_tree_if_exists(path: &Path) -> Result<bool> {
    match std::fs::remove_dir_all(path) {
        Ok(()) => Ok(true),
        Err(source) if source.kind() == std::io::ErrorKind::NotFound => Ok(false),
        Err(source) => Err(Error::new(Operation::RemoveDirectory, path, source)),
    }
}

/// Canonicalize a path through the host filesystem.
///
/// Prefer a confined resolver for untrusted relative paths.
///
/// # Errors
///
/// Returns a contextual error when the path cannot be resolved.
pub fn canonicalize(path: &Path) -> Result<PathBuf> {
    std::fs::canonicalize(path)
        .map(PathBuf::from)
        .map_err(|source| Error::new(Operation::Canonicalize, path, source))
}

/// Rename one entry.
///
/// # Errors
///
/// Returns a contextual error with both paths when the rename fails.
pub fn rename(from: &Path, to: &Path) -> Result<()> {
    std::fs::rename(from, to).map_err(|source| Error::between(Operation::Rename, from, to, source))
}