feat(fs): add .path(path).read_link()

README.md

@@ -2,25 +2,9 @@
 
 Provides injectable Filesystem and Network resources to make code more testable.
 
-#### std::fs alternatives
+### Filesystem
 
-- [ ] `std::fs::canonicalize` - `path(path).canonicalize()` - Returns the canonical, absolute form of a path with all intermediate components normalized and symbolic links resolved.
-- [x] `std::fs::copy` - `file(path).copy(target)` - Copies the contents of one file to another. This function will also copy the permission bits of the original file to the destination file.
-- [x] `std::fs::create_dir` - `dir(path).create()` - Creates a new, empty directory at the provided path
-- [x] `std::fs::create_dir_all` - `dir(path).create_all()` - Recursively create a directory and all of its parent components if they are missing.
-- [x] `std::fs::hard_link` - `file(path).hard_link(other)` - Creates a new hard link on the filesystem.
-- [x] `std::fs::metadata` - `path(path).metadata()` - Given a path, query the file system to get information about a file, directory, etc.
-- [x] `std::fs::read` - `file(path).reader().bytes()` - Read the entire contents of a file into a bytes vector.
-- [x] `std::fs::read_dir` - `dir(path).read()` - Returns an iterator over the entries within a directory.
-- [ ] `std::fs::read_link` - `link(path).read()` - Reads a symbolic link, returning the file that the link points to.
-- [x] `std::fs::read_to_string` - `file(path).reader().to_string()` - Read the entire contents of a file into a string.
-- [x] `std::fs::remove_dir` - `dir(path).remove()` - Removes an empty directory.
-- [x] `std::fs::remove_dir_all` - `dir(path).remove_all()` - Removes a directory at this path, after removing all its contents. Use carefully!
-- [x] `std::fs::remove_file` - `file(path).remove()` - Removes a file from the filesystem.
-- [x] `std::fs::rename` - `path(path).rename()` - Rename a file or directory to a new name, replacing the original file if to already exists.
-- [ ] `std::fs::set_permissions` - `path(path).set_permissions()` - Changes the permissions found on a file or a directory.
-- [ ] `std::fs::symlink_metadata` - `link(path).metadata()` - Query the metadata about a file without following symlinks.
-- [x] `std::fs::write` - `file(path).write()` - Write a slice as the entire contents of a file.
+Documentation is [here](https://docs.rs/kxio/latest/kxio/fs/).
 
 ### Network
 

src/fs/dir.rs

@@ -3,7 +3,7 @@ use crate::fs::{DirItem, DirItemIterator, Result};
 
 use super::{DirHandle, Error, FileHandle, PathHandle, PathMarker};
 
-impl<'base, 'path> DirHandle<'base, 'path> {
+impl DirHandle {
     /// Creates a new, empty directory at the path
     ///
     /// Wrapper for [std::fs::create_dir]
@@ -93,12 +93,10 @@ impl<'base, 'path> DirHandle<'base, 'path> {
         std::fs::remove_dir_all(self.as_pathbuf()).map_err(Error::Io)
     }
 }
-impl<'base, 'path> TryFrom<PathHandle<'base, 'path, PathMarker>> for FileHandle<'base, 'path> {
+impl TryFrom<PathHandle<PathMarker>> for FileHandle {
     type Error = crate::fs::Error;
 
-    fn try_from(
-        path: PathHandle<'base, 'path, PathMarker>,
-    ) -> std::result::Result<Self, Self::Error> {
+    fn try_from(path: PathHandle<PathMarker>) -> std::result::Result<Self, Self::Error> {
         match path.as_file() {
             Ok(Some(dir)) => Ok(dir.clone()),
             Ok(None) => Err(crate::fs::Error::NotADirectory {
@@ -108,12 +106,10 @@ impl<'base, 'path> TryFrom<PathHandle<'base, 'path, PathMarker>> for FileHandle<
         }
     }
 }
-impl<'base, 'path> TryFrom<PathHandle<'base, 'path, PathMarker>> for DirHandle<'base, 'path> {
+impl TryFrom<PathHandle<PathMarker>> for DirHandle {
     type Error = crate::fs::Error;
 
-    fn try_from(
-        path: PathHandle<'base, 'path, PathMarker>,
-    ) -> std::result::Result<Self, Self::Error> {
+    fn try_from(path: PathHandle<PathMarker>) -> std::result::Result<Self, Self::Error> {
         match path.as_dir() {
             Ok(Some(dir)) => Ok(dir.clone()),
             Ok(None) => Err(crate::fs::Error::NotADirectory {

src/fs/file.rs

@@ -3,7 +3,7 @@ use crate::fs::Result;
 
 use super::{reader::Reader, Error, FileHandle};
 
-impl<'base, 'path> FileHandle<'base, 'path> {
+impl FileHandle {
     /// Returns a [Reader] for the file.
     ///
     /// ```
@@ -54,7 +54,7 @@ impl<'base, 'path> FileHandle<'base, 'path> {
     /// # Ok(())
     /// # }
     /// ```
-    pub fn copy(&self, dest: &FileHandle<'base, 'path>) -> Result<u64> {
+    pub fn copy(&self, dest: &FileHandle) -> Result<u64> {
         self.check_error()?;
         std::fs::copy(self.as_pathbuf(), dest.as_pathbuf()).map_err(Error::Io)
     }
@@ -94,7 +94,7 @@ impl<'base, 'path> FileHandle<'base, 'path> {
     /// #    Ok(())
     /// # }
     /// ```
-    pub fn hard_link(&self, dest: &FileHandle<'base, 'path>) -> Result<()> {
+    pub fn hard_link(&self, dest: &FileHandle) -> Result<()> {
         self.check_error()?;
         std::fs::hard_link(self.as_pathbuf(), dest.as_pathbuf()).map_err(Error::Io)
     }

src/fs/mod.rs

@@ -26,6 +26,36 @@
 //! # Ok(())
 //! # }
 //! ```
+//!
+//! # Standard library equivalents
+//!
+//! Given a `FileSystem` `fs`:
+//!
+//! ```no_run
+//! let fs = kxio::fs::temp().expect("temp fs"); // for testing
+//! // or
+//! # let pathbuf = fs.base().join("foo").to_path_buf();
+//! let fs = kxio::fs::new(pathbuf);
+//! ```
+//!
+//! - [x] `std::fs::canonicalize` - `fs.path(path).canonicalize()` - Returns the canonical, absolute form of a path with all intermediate components normalized and symbolic links resolved.
+//! - [x] `std::fs::copy` - `fs.file(path).copy(target)` - Copies the contents of one file to another. This function will also copy the permission bits of the original file to the destination file.
+//! - [x] `std::fs::create_dir` - `fs.dir(path).create()` - Creates a new, empty directory at the provided path
+//! - [x] `std::fs::create_dir_all` - `fs.dir(path).create_all()` - Recursively create a directory and all of its parent components if they are missing.
+//! - [x] `std::fs::hard_link` - `fs.file(path).hard_link(other)` - Creates a new hard link on the filesystem.
+//! - [x] `std::fs::metadata` - `fs.path(path).metadata()` - Given a path, query the file system to get information about a file, directory, etc.
+//! - [x] `std::fs::read` - `fs.file(path).reader().bytes()` - Read the entire contents of a file into a bytes vector.
+//! - [x] `std::fs::read_dir` - `fs.dir(path).read()` - Returns an iterator over the entries within a directory.
+//! - [x] `std::fs::read_link` - `fs.path(path).read_link()` - Reads a symbolic link, returning the file that the link points to.
+//! - [x] `std::fs::read_to_string` - `fs.file(path).reader().to_string()` - Read the entire contents of a file into a string.
+//! - [x] `std::fs::remove_dir` - `fs.dir(path).remove()` - Removes an empty directory.
+//! - [x] `std::fs::remove_dir_all` - `fs.dir(path).remove_all()` - Removes a directory at this path, after removing all its contents. Use carefully!
+//! - [x] `std::fs::remove_file` - `fs.file(path).remove()` - Removes a file from the filesystem.
+//! - [x] `std::fs::rename` - `fs.path(path).rename()` - Rename a file or directory to a new name, replacing the original file if to already exists.
+//! - [x] `std::fs::set_permissions` - `fs.path(path).set_permissions(perms)` - Changes the permissions found on a file or a directory.
+//! - [x] `std::fs::symlink_metadata` - `fs.path(path).symlink_metadata()` - Query the metadata about a file without following symlinks.
+//! - [x] `std::fs::write` - `fs.file(path).write()` - Write a slice as the entire contents of a file.
+//!
 use std::path::PathBuf;
 
 mod dir;

src/fs/path.rs

@@ -30,19 +30,22 @@ impl PathType for DirMarker {}
 ///
 /// It can be a simple path, or it can be a file or a directory.
 #[derive(Clone, Debug)]
-pub struct PathReal<'base, 'path, T: PathType> {
-    base: &'base Path,
-    path: &'path Path,
+pub struct PathReal<T: PathType> {
+    base: PathBuf,
+    path: PathBuf,
     _phanton: PhantomData<T>,
     pub(super) error: Option<Error>,
 }
-impl<'base, 'path, T: PathType> PathReal<'base, 'path, T> {
-    pub(super) fn new(base: &'base Path, path: &'path Path) -> Self {
+impl<T: PathType> PathReal<T> {
+    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);
         Self {
             base,
             path,
             _phanton: PhantomData::<T>,
-            error: PathReal::<T>::validate(base, path),
+            error,
         }
     }
 
@@ -59,7 +62,7 @@ impl<'base, 'path, T: PathType> PathReal<'base, 'path, T> {
     /// # }
     /// ```
     pub fn as_pathbuf(&self) -> PathBuf {
-        self.base.join(self.path)
+        self.base.join(&self.path)
     }
 
     pub(super) fn put(&mut self, error: Error) {
@@ -172,10 +175,10 @@ impl<'base, 'path, T: PathType> PathReal<'base, 'path, T> {
     /// #    Ok(())
     /// # }
     /// ```
-    pub fn as_dir(&self) -> Result<Option<DirHandle<'base, 'path>>> {
+    pub fn as_dir(&self) -> Result<Option<DirHandle>> {
         self.check_error()?;
         if self.as_pathbuf().is_dir() {
-            Ok(Some(PathReal::new(self.base, self.path)))
+            Ok(Some(PathReal::new(&self.base, &self.path)))
         } else {
             Ok(None)
         }
@@ -195,10 +198,10 @@ impl<'base, 'path, T: PathType> PathReal<'base, 'path, T> {
     /// #    Ok(())
     /// # }
     /// ```
-    pub fn as_file(&self) -> Result<Option<FileHandle<'base, 'path>>> {
+    pub fn as_file(&self) -> Result<Option<FileHandle>> {
         self.check_error()?;
         if self.as_pathbuf().is_file() {
-            Ok(Some(PathReal::new(self.base, self.path)))
+            Ok(Some(PathReal::new(&self.base, &self.path)))
         } else {
             Ok(None)
         }
@@ -221,7 +224,7 @@ impl<'base, 'path, T: PathType> PathReal<'base, 'path, T> {
     /// #    Ok(())
     /// # }
     /// ```
-    pub fn rename(&self, dest: &PathHandle<'base, 'path, T>) -> Result<()> {
+    pub fn rename(&self, dest: &PathHandle<T>) -> Result<()> {
         self.check_error()?;
         std::fs::rename(self.as_pathbuf(), dest.as_pathbuf()).map_err(Error::Io)
     }
@@ -261,7 +264,7 @@ impl<'base, 'path, T: PathType> PathReal<'base, 'path, T> {
     /// #    Ok(())
     /// # }
     /// ```
-    pub fn soft_link(&self, link: &PathReal<'_, '_, PathMarker>) -> Result<()> {
+    pub fn soft_link(&self, link: &PathReal<PathMarker>) -> Result<()> {
         self.check_error()?;
         std::os::unix::fs::symlink(self.as_pathbuf(), link.as_pathbuf()).map_err(Error::Io)
     }
@@ -283,19 +286,84 @@ impl<'base, 'path, T: PathType> PathReal<'base, 'path, T> {
         self.check_error()?;
         Ok(self.as_pathbuf().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(())
+    /// # }
+    /// ```
+    pub fn canonicalize(&self) -> Result<PathBuf> {
+        self.check_error()?;
+        self.as_pathbuf().canonicalize().map_err(Error::Io)
     }
-impl<'base, 'path> From<PathHandle<'base, 'path, PathMarker>> for PathBuf {
+
+    /// 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(())
+    /// # }
+    /// ```
+    pub fn symlink_metadata(&self) -> Result<std::fs::Metadata> {
+        self.check_error()?;
+        std::fs::symlink_metadata(self.as_pathbuf()).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(())
+    /// # }
+    /// ```
+    pub fn set_permissions(&self, perms: std::fs::Permissions) -> Result<()> {
+        self.check_error()?;
+        std::fs::set_permissions(self.as_pathbuf(), perms).map_err(Error::Io)
+    }
+
+    pub fn read_link(&self) -> Result<PathReal<PathMarker>> {
+        self.check_error()?;
+        let read_path = std::fs::read_link(self.as_pathbuf()).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<'base, 'path> From<DirHandle<'base, 'path>> for PathHandle<'base, 'path, PathMarker> {
-    fn from(dir: DirHandle<'base, 'path>) -> Self {
+impl From<DirHandle> for PathHandle<PathMarker> {
+    fn from(dir: DirHandle) -> Self {
         PathReal::new(dir.base, dir.path)
     }
 }
-impl<'base, 'path> From<FileHandle<'base, 'path>> for PathHandle<'base, 'path, PathMarker> {
-    fn from(file: FileHandle<'base, 'path>) -> Self {
+impl From<FileHandle> for PathHandle<PathMarker> {
+    fn from(file: FileHandle) -> Self {
         PathReal::new(file.base, file.path)
     }
 }

src/fs/system.rs

@@ -15,13 +15,13 @@ pub struct FileSystem {
 }
 
 /// Represents a directory path in the filesystem.
-pub type DirHandle<'base, 'path> = PathReal<'base, 'path, DirMarker>;
+pub type DirHandle = PathReal<DirMarker>;
 
 /// Represents a file path in the filesystem.
-pub type FileHandle<'base, 'path> = PathReal<'base, 'path, FileMarker>;
+pub type FileHandle = PathReal<FileMarker>;
 
 /// Represents a path in the filesystem.
-pub type PathHandle<'base, 'path, T> = PathReal<'base, 'path, T>;
+pub type PathHandle<T> = PathReal<T>;
 
 impl FileSystem {
     pub const fn new(base: PathBuf) -> Self {
@@ -55,8 +55,8 @@ impl FileSystem {
     /// # Ok(())
     /// # }
     /// ```
-    pub fn dir<'base, 'path>(&'base self, path: &'path Path) -> DirHandle<'base, 'path> {
-        let mut dir = PathReal::new(self.base(), path);
+    pub fn dir(&self, path: &Path) -> DirHandle {
+        let mut dir = PathReal::new(&self.base, path);
 
         if dir.error.is_none() {
             if let Ok(exists) = dir.exists() {
@@ -90,8 +90,8 @@ impl FileSystem {
     /// # Ok(())
     /// # }
     /// ```
-    pub fn file<'base, 'path>(&'base self, path: &'path Path) -> FileHandle<'base, 'path> {
-        let mut file = PathReal::new(self.base(), path);
+    pub fn file(&self, path: &Path) -> FileHandle {
+        let mut file = PathReal::new(&self.base, path);
 
         if file.error.is_none() {
             if let Ok(exists) = file.exists() {
@@ -124,11 +124,8 @@ impl FileSystem {
     /// # Ok(())
     /// # }
     /// ```
-    pub fn path<'base, 'path>(
-        &'base self,
-        path: &'path Path,
-    ) -> PathHandle<'base, 'path, PathMarker> {
-        PathReal::new(self.base(), path)
+    pub fn path(&self, path: &Path) -> PathHandle<PathMarker> {
+        PathReal::new(&self.base, path)
     }
 
     fn validate(&self, path: &Path) -> Result<()> {

tests/fs.rs

@@ -7,6 +7,67 @@ type TestResult = Result<(), fs::Error>;
 mod path {
     use super::*;
 
+    mod set_permissions {
+        use super::*;
+
+        #[test]
+        fn should_set_permissions() -> TestResult {
+            let fs = fs::temp().expect("temp fs");
+            let path = fs.base().join("foo");
+            let file = fs.file(&path);
+            file.write("bar").expect("write");
+            let md = file.metadata().expect("metadata");
+            assert!(md.is_file());
+
+            let mut perms = md.permissions();
+            perms.set_readonly(true);
+
+            let path = fs.path(&path);
+            path.set_permissions(perms).expect("set_permissions");
+
+            let md = file.metadata().expect("metadata");
+            assert!(md.is_file());
+            assert!(md.permissions().readonly());
+
+            Ok(())
+        }
+    }
+    mod read_link {
+        use super::*;
+
+        #[test]
+        fn should_read_link() -> TestResult {
+            let fs = fs::temp().expect("temp fs");
+
+            let file_path = fs.base().join("foo");
+            let file = fs.file(&file_path);
+            file.write("bar").expect("write");
+
+            let link_path = fs.base().join("bar");
+            let link = fs.path(&link_path);
+            file.soft_link(&link).expect("soft_link");
+
+            let read_link = link.read_link().expect("read_link");
+            assert_eq!(read_link.as_pathbuf(), file_path);
+
+            Ok(())
+        }
+
+        #[test]
+        fn should_fail_on_path_traversal() -> TestResult {
+            let fs = fs::temp().expect("temp fs");
+            let path = fs.base().join("..").join("foo");
+            let_assert!(
+                Err(fs::Error::PathTraversal {
+                    base: _base,
+                    path: _path
+                }) = fs.path(&path).read_link()
+            );
+
+            Ok(())
+        }
+    }
+
     mod metadata {
         use super::*;
 
@@ -418,6 +479,61 @@ mod file {
             Ok(())
         }
     }
+    mod symlink_metadata {
+        use super::*;
+
+        #[test]
+        fn should_return_metadata_for_a_file() -> TestResult {
+            let fs = fs::temp().expect("temp fs");
+            let path = fs.base().join("foo");
+            let file = fs.file(&path);
+            file.write("bar").expect("write");
+            let md = file.symlink_metadata().expect("metadata");
+            assert!(md.is_file());
+            Ok(())
+        }
+
+        #[test]
+        fn should_return_metadata_for_a_dir() -> TestResult {
+            let fs = fs::temp().expect("temp fs");
+            let path = fs.base().join("foo");
+            let dir = fs.dir(&path);
+            dir.create().expect("create");
+            let md = dir.symlink_metadata().expect("metadata");
+            assert!(md.is_dir());
+            Ok(())
+        }
+
+        #[test]
+        fn should_return_metadata_for_a_symlink() -> TestResult {
+            let fs = fs::temp().expect("temp fs");
+            let file_path = fs.base().join("foo");
+            let file = fs.file(&file_path);
+            file.write("bar").expect("write");
+
+            let link_path = fs.base().join("bar");
+            let link = fs.path(&link_path);
+            file.soft_link(&link).expect("soft_link");
+
+            let md = link.symlink_metadata().expect("metadata");
+            assert!(md.is_symlink());
+            Ok(())
+        }
+
+        #[test]
+        fn should_fail_on_path_traversal() -> TestResult {
+            let fs = fs::temp().expect("temp fs");
+            let path = fs.base().join("..").join("foo");
+            let_assert!(
+                Err(fs::Error::PathTraversal {
+                    base: _base,
+                    path: _path
+                }) = fs.file(&path).symlink_metadata()
+            );
+
+            Ok(())
+        }
+    }
     mod reader {
         use super::*;
         mod to_string {
@@ -661,3 +777,31 @@ mod dir {
         }
     }
 }
+mod canonicalize {
+    use std::path::Path;
+
+    use super::*;
+
+    #[test]
+    fn should_resolve_symlinks() -> TestResult {
+        let fs = fs::temp().expect("temp fs");
+
+        let file_path = fs.base().join("foo");
+        let file = fs.file(&file_path);
+        file.write("bar").expect("write");
+
+        let link_path = fs.base().join("link");
+        let link = fs.path(&link_path);
+        file.soft_link(&link).expect("create");
+        let canonical = link.canonicalize().expect("canonicalize");
+        let canonical = if canonical.starts_with("/private") {
+            // INFO: macos puts all temp files under /private
+            Path::new("/").join(canonical.strip_prefix("/private").unwrap())
+        } else {
+            canonical
+        };
+        assert_eq!(canonical, file_path);
+
+        Ok(())
+    }
+}