Compare commits

...

10 commits

7 changed files with 434 additions and 58 deletions

View file

@ -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.
- [ ] `std::fs::hard_link` - `link(path)create()` - Creates a new hard link on the filesystem.
- [ ] `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

View file

@ -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 {

View file

@ -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)
}
@ -76,4 +76,26 @@ impl<'base, 'path> FileHandle<'base, 'path> {
self.check_error()?;
std::fs::remove_file(self.as_pathbuf()).map_err(Error::Io)
}
/// Creates a hard link on the filesystem.
///
/// Wrapper for [std::fs::hard_link]
///
/// ```
/// # 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.hard_link(&dst)?;
/// # Ok(())
/// # }
/// ```
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)
}
}

View file

@ -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;

View file

@ -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,23 +224,146 @@ 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)
}
/// 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)
}
/// 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(())
/// # }
/// ```
pub fn metadata(&self) -> Result<std::fs::Metadata> {
self.check_error()?;
std::fs::metadata(self.as_pathbuf()).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(())
/// # }
/// ```
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)
}
/// 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(())
/// # }
/// ```
pub fn is_link(&self) -> Result<bool> {
self.check_error()?;
Ok(self.as_pathbuf().is_symlink())
}
/// 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<'base, 'path> From<PathHandle<'base, 'path, PathMarker>> for PathBuf {
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)
}
}

View file

@ -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<()> {

View file

@ -7,6 +7,97 @@ 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::*;
#[test]
fn should_return_metadata() -> 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());
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).metadata()
);
Ok(())
}
}
mod path_of {
use super::*;
@ -269,6 +360,57 @@ mod path {
mod file {
use super::*;
// // test for reading the symlink metadata
// #[test]
// fn symlink_metadata() -> 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("symlink metadata");
// assert!(md.is_file());
// Ok(())
// }
#[test]
fn create_soft_link() -> TestResult {
let fs = fs::temp().expect("temp fs");
let file_path = fs.base().join("foo");
let file = fs.file(&file_path);
file.write("content").expect("write");
let link_path = fs.base().join("bar");
let link = fs.path(&link_path);
file.soft_link(&link).expect("soft_link");
let exists = link.exists().expect("exists");
assert!(exists);
let is_link = link.is_link().expect("is_link");
assert!(is_link);
Ok(())
}
#[test]
fn create_hard_link() -> TestResult {
let fs = fs::temp().expect("temp fs");
let file_path = fs.base().join("foo");
let file = fs.file(&file_path);
file.write("content").expect("write");
let link_path = fs.base().join("bar");
let link = fs.file(&link_path);
file.hard_link(&link).expect("hard_link");
let exists = link.exists().expect("exists");
assert!(exists);
Ok(())
}
#[test]
/// Write to a file, read it, verify it exists, is a file and has the expected contents
fn write_read_file_exists() -> TestResult {
@ -337,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 {
@ -580,3 +777,27 @@ 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("soft_link");
let canonical = link.canonicalize().expect("canonicalize");
// macos puts all temp files under /private
let canonical = Path::new("/").join(canonical.strip_prefix("/private").unwrap());
assert_eq!(canonical, file_path);
Ok(())
}
}