kxio 3.2.0

//
use std::{
    fmt::Display,
    marker::PhantomData,
    path::{Path, PathBuf},
};

use crate::fs::{Error, Result};

use super::{DirHandle, FileHandle, PathHandle};

/// Marker trait for the type of [PathReal].
pub trait PathType {}

/// Path marker for the type of [PathReal].
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct PathMarker;
impl PathType for PathMarker {}

/// File marker for the type of [PathReal].
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct FileMarker;
impl PathType for FileMarker {}

/// Dir marker for the type of [PathReal].
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct DirMarker;
impl PathType for DirMarker {}

/// Represents a path in the filesystem.
///
/// It can be a simple path, or it can be a file or a directory.
#[derive(Clone, Debug, Default)]
pub struct PathReal<T: PathType> {
    base: PathBuf,
    path: PathBuf,
    _phanton: PhantomData<T>,
    pub(super) error: Option<Error>,
}
impl<T: PathType> PathReal<T> {
    #[tracing::instrument(skip_all)]
    pub(super) fn new(base: impl Into<PathBuf>, path: impl Into<PathBuf>) -> Self {
        let base: PathBuf = base.into();
        let path: PathBuf = path.into();
        let error = PathReal::<T>::validate(&base, &path);
        tracing::debug!(?base, ?path, ?error, "new");
        Self {
            base,
            path,
            _phanton: PhantomData::<T>,
            error,
        }
    }

    /// Returns a [PathBuf] for the path.
    ///
    /// ```
    /// # use kxio::fs::Result;
    /// # fn main() -> Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let path = fs.base().join("foo");
    /// let path = fs.path(&path);
    /// let pathbuf = path.as_pathbuf();
    /// #    Ok(())
    /// # }
    /// ```
    pub fn as_pathbuf(&self) -> PathBuf {
        self.base.join(&self.path)
    }

    // only stores the first error, subsequent errors are dropped
    pub(super) fn put(&mut self, error: Error) {
        if self.error.is_none() {
            self.error.replace(error);
        }
    }

    fn validate(base: &Path, path: &Path) -> Option<Error> {
        match PathReal::<PathMarker>::clean_path(path) {
            Err(error) => Some(error),
            Ok(path) => {
                if !path.starts_with(base) {
                    return Some(Error::PathTraversal {
                        base: base.to_path_buf(),
                        path,
                    });
                }
                None
            }
        }
    }

    #[tracing::instrument]
    fn clean_path(path: &Path) -> Result<PathBuf> {
        use path_clean::PathClean;
        let abs_path = if path.is_absolute() {
            tracing::debug!("is absolute");
            path.to_path_buf()
        } else {
            tracing::debug!("std::env::current_dir");
            std::env::current_dir().expect("current_dir").join(path)
        }
        .clean();
        tracing::debug!(?abs_path);
        Ok(abs_path)
    }

    #[tracing::instrument(skip_all)]
    pub(super) fn check_error(&self) -> Result<()> {
        if let Some(error) = &self.error {
            tracing::warn!(?error, "error");
            Err(error.clone())
        } else {
            Ok(())
        }
    }

    /// Returns true if the path exists.
    ///
    /// N.B. If you have the path used to create the file or directory, you
    /// should use [std::path::Path::exists] instead.
    ///
    /// ```
    /// # use kxio::fs::Result;
    /// # fn main() -> Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let path = fs.base().join("foo");
    /// let dir = fs.dir(&path);
    /// #    dir.create()?;
    /// if dir.exists()? { /* ... */ }
    /// #    Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn exists(&self) -> Result<bool> {
        self.check_error()?;
        let path = self.as_pathbuf();
        tracing::debug!(?path, "PathBuf::exists");
        Ok(path.exists())
    }

    /// Returns true if the path is a directory.
    ///
    /// ```
    /// # use kxio::fs::Result;
    /// # fn main() -> Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let path = fs.base().join("foo");
    /// #    fs.dir(&path).create()?;
    /// if path.is_dir() { /* ... */ }
    /// #    Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn is_dir(&self) -> Result<bool> {
        self.check_error()?;
        let path = self.as_pathbuf();
        tracing::debug!(?path, "PathBuf::is_dir");
        Ok(path.is_dir())
    }

    /// Returns true if the path is a file.
    ///
    /// ```
    /// # use kxio::fs::Result;
    /// # fn main() -> Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let path = fs.base().join("foo");
    /// #    fs.dir(&path).create()?;
    /// if path.is_file() { /* ... */ }
    /// #    Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn is_file(&self) -> Result<bool> {
        self.check_error()?;
        let path = self.as_pathbuf();
        tracing::debug!(?path, "PathBuf::is_file");
        Ok(path.is_file())
    }

    /// Returns the path as a directory if it exists and is a directory, otherwise
    /// it will return None.
    ///
    /// ```
    /// # use kxio::fs::Result;
    /// # fn main() -> Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let path = fs.base().join("foo");
    /// #    fs.dir(&path).create()?;
    /// let file = fs.path(&path);
    /// if let Ok(Some(dir)) = file.as_dir() { /* ... */ }
    /// #    Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn as_dir(&self) -> Result<Option<DirHandle>> {
        self.check_error()?;
        let path = self.as_pathbuf();
        let is_dir = path.is_dir();
        tracing::debug!(?path, ?is_dir, "PathBuf::is_dir");
        if is_dir {
            Ok(Some(PathReal::new(&self.base, &self.path)))
        } else {
            Ok(None)
        }
    }

    /// Returns the path as a file if it exists and is a file, otherwise
    /// it will return None.
    ///
    /// ```
    /// # use kxio::fs::Result;
    /// # fn main() -> Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let path = fs.base().join("foo");
    /// #    fs.dir(&path).create()?;
    /// let file = fs.path(&path);
    /// if let Ok(Some(file)) = file.as_file() { /* ... */ }
    /// #    Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn as_file(&self) -> Result<Option<FileHandle>> {
        self.check_error()?;
        let path = self.as_pathbuf();
        let is_file = path.is_file();
        tracing::debug!(?path, ?is_file, "PathBuf::is_file");
        if is_file {
            Ok(Some(PathReal::new(&self.base, &self.path)))
        } else {
            Ok(None)
        }
    }

    /// Renames a path.
    ///
    /// Wrapper for [std::fs::rename]
    ///
    /// ```
    /// # use kxio::fs::Result;
    /// # fn main() -> Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let src_path = fs.base().join("foo");
    /// let src = fs.file(&src_path);
    /// # src.write("bar")?;
    /// let dst_path = fs.base().join("bar");
    /// let dst = fs.file(&dst_path);
    /// src.rename(&dst)?;
    /// #    Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn rename(&self, dest: &PathHandle<T>) -> Result<()> {
        self.check_error()?;
        let from = self.as_pathbuf();
        let to = dest.as_pathbuf();
        tracing::debug!(?from, ?to, "std::fs::rename");
        std::fs::rename(from, to).map_err(Error::Io)
    }

    /// Returns the metadata for a path.
    ///
    /// Wrapper for [std::fs::metadata]
    ///
    /// ```
    /// # fn try_main() -> kxio::fs::Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let path = fs.base().join("foo");
    /// let file = fs.file(&path);
    /// let metadata = file.metadata()?;
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn metadata(&self) -> Result<std::fs::Metadata> {
        self.check_error()?;
        let path = self.as_pathbuf();
        tracing::debug!(?path, "std::fs::metadata");
        std::fs::metadata(path).map_err(Error::Io)
    }

    /// Creates a symbolic link to a path.
    ///
    /// Wrapper for [std::os::unix::fs::symlink]
    ///
    /// ```
    /// # use kxio::fs::Result;
    /// # fn main() -> Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let src_path = fs.base().join("foo");
    /// let src = fs.file(&src_path);
    /// # src.write("bar")?;
    /// let link_path = fs.base().join("bar");
    /// let link = fs.path(&link_path);
    /// src.soft_link(&link)?;
    /// #    Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn soft_link(&self, link: &PathReal<PathMarker>) -> Result<()> {
        self.check_error()?;
        let original = self.as_pathbuf();
        let link = link.as_pathbuf();
        tracing::debug!(?original, ?link, "std::os::unix::fs::symlink");
        std::os::unix::fs::symlink(original, link).map_err(Error::Io)
    }

    /// Returns true if the path is a symbolic link.
    ///
    /// ```
    /// # use kxio::fs::Result;
    /// # fn main() -> Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let path = fs.base().join("foo");
    /// let dir = fs.dir(&path);
    /// # dir.create()?;
    /// if dir.is_link()? { /* ... */ }
    /// #    Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn is_link(&self) -> Result<bool> {
        self.check_error()?;
        let path = self.as_pathbuf();
        tracing::debug!(?path, "PathBuf::is_symlink");
        Ok(path.is_symlink())
    }

    /// Returns the canonical, absolute form of the path with all intermediate
    /// components normalized and symbolic links resolved.
    ///
    /// ```
    /// # use kxio::fs::Result;
    /// # fn main() -> Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let path = fs.base().join("foo");
    /// #    fs.dir(&path).create()?;
    /// let dir = fs.path(&path);
    /// let canonical = dir.canonicalize()?;
    /// #    Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn canonicalize(&self) -> Result<PathBuf> {
        self.check_error()?;
        let path = self.as_pathbuf();
        tracing::debug!(?path, "PathBuf::canonicalize");
        path.canonicalize().map_err(Error::Io)
    }

    /// Returns the metadata for a path without following symlinks.
    ///
    /// Wrapper for [std::fs::symlink_metadata]
    ///
    /// ```
    /// # fn try_main() -> kxio::fs::Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let path = fs.base().join("foo");
    /// let file = fs.file(&path);
    /// let metadata = file.symlink_metadata()?;
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn symlink_metadata(&self) -> Result<std::fs::Metadata> {
        self.check_error()?;
        let path = self.as_pathbuf();
        tracing::debug!(?path, "std::fs::symlink_metadata");
        std::fs::symlink_metadata(path).map_err(Error::Io)
    }

    /// Sets the permissions of a file or directory.
    ///
    /// Wrapper for [std::fs::set_permissions]
    ///
    /// ```
    /// # use kxio::fs::Result;
    /// # use std::os::unix::fs::PermissionsExt;
    /// # fn main() -> Result<()> {
    /// let fs = kxio::fs::temp()?;
    /// let path = fs.base().join("foo");
    /// let file = fs.file(&path);
    /// # file.write("bar")?;
    /// file.set_permissions(std::fs::Permissions::from_mode(0o755))?;
    /// #    Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn set_permissions(&self, perms: std::fs::Permissions) -> Result<()> {
        self.check_error()?;
        let path = self.as_pathbuf();
        tracing::debug!(?path, ?perms, "std::fs::set_permissions");
        std::fs::set_permissions(path, perms).map_err(Error::Io)
    }

    #[tracing::instrument(skip_all)]
    pub fn read_link(&self) -> Result<PathReal<PathMarker>> {
        self.check_error()?;
        let path = self.as_pathbuf();
        tracing::debug!(?path, "std::fs::read_link");
        let read_path = std::fs::read_link(path).map_err(Error::Io)?;
        let path = read_path.strip_prefix(&self.base).unwrap().to_path_buf();
        Ok(PathReal::new(&self.base, &path))
    }
}
impl From<PathHandle<PathMarker>> for PathBuf {
    fn from(path: PathReal<PathMarker>) -> Self {
        path.base.join(path.path)
    }
}
impl From<DirHandle> for PathHandle<PathMarker> {
    fn from(dir: DirHandle) -> Self {
        PathReal::new(dir.base, dir.path)
    }
}
impl From<FileHandle> for PathHandle<PathMarker> {
    fn from(file: FileHandle) -> Self {
        PathReal::new(file.base, file.path)
    }
}

impl Display for PathReal<PathMarker> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.as_pathbuf().display())
    }
}