WIP: docs(fs): add some documentation

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kxio"
-version = "1.1.2"
+version = "1.2.0"
 edition = "2021"
 authors = ["Paul Campbell <pcampbell@kemitix.net>"]
 description = "Provides injectable Filesystem and Network resources to make code more testable"
@@ -33,8 +33,12 @@ thiserror = "1.0"
 tempfile = "3.10"
 path-clean = "1.0"
 
-# error handling
-derive_more = { version = "1.0.0-beta.6", features = ["from", "display"] }
+# boilerplate
+derive_more = { version = "1.0.0-beta.6", features = [
+  "from",
+  "display",
+  "constructor",
+] }
 
 [dev-dependencies]
 # testing

src/fs/dir_item.rs

@@ -0,0 +1,37 @@
+use std::{
+    fs::{DirEntry, ReadDir},
+    path::PathBuf,
+};
+
+#[derive(Debug, PartialEq, Eq, PartialOrd, Ord)]
+pub enum DirItem {
+    File(PathBuf),
+    Dir(PathBuf),
+    SymLink(PathBuf),
+    Fifo(PathBuf),
+    Unsupported(PathBuf),
+}
+
+#[derive(Debug, derive_more::Constructor)]
+pub struct DirItemIterator(ReadDir);
+impl Iterator for DirItemIterator {
+    type Item = super::Result<DirItem>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.0.next().map(map_dir_item)
+    }
+}
+
+fn map_dir_item(item: std::io::Result<DirEntry>) -> super::Result<DirItem> {
+    let item = item?;
+    let file_type = item.file_type()?;
+    if file_type.is_dir() {
+        Ok(DirItem::Dir(item.path()))
+    } else if file_type.is_file() {
+        Ok(DirItem::File(item.path()))
+    } else if file_type.is_symlink() {
+        Ok(DirItem::SymLink(item.path()))
+    } else {
+        Ok(DirItem::Unsupported(item.path()))
+    }
+}

src/fs/like.rs

@@ -1,3 +1,5 @@
+use crate::fs::DirItem;
+
 use super::Result;
 
 use std::path::{Path, PathBuf};
@@ -36,6 +38,9 @@ pub trait FileSystemLike {
     /// ```
     fn dir_create_all(&self, path: &Path) -> Result<()>;
 
+    /// Reads the items in a directory and returns them as an iterator.
+    fn dir_read(&self, path: &Path) -> Result<Box<dyn Iterator<Item = Result<DirItem>>>>;
+
     /// Reads a file into a [String]. Will attempt to read the whole file into memory in one go.
     ///
     /// ```no_run

src/fs/mod.rs

@@ -8,6 +8,10 @@ pub mod like;
 mod real;
 mod temp;
 
+mod dir_item;
+pub use dir_item::DirItem;
+pub use dir_item::DirItemIterator;
+
 #[derive(Debug, From, derive_more::Display)]
 pub enum Error {
     Io(std::io::Error),
@@ -17,6 +21,11 @@ pub enum Error {
         base: PathBuf,
         path: PathBuf,
     },
+
+    #[display("Path must be a directory: {path:?}")]
+    NotADirectory {
+        path: PathBuf,
+    },
 }
 impl std::error::Error for Error {}
 

src/fs/real.rs

@@ -1,5 +1,7 @@
 use std::path::{Path, PathBuf};
 
+use crate::fs::{DirItem, DirItemIterator};
+
 pub const fn new(base: PathBuf) -> RealFileSystem {
     RealFileSystem { base }
 }
@@ -24,6 +26,20 @@ impl super::FileSystemLike for RealFileSystem {
         std::fs::create_dir_all(path).map_err(Into::into)
     }
 
+    fn dir_read(
+        &self,
+        path: &Path,
+    ) -> super::Result<Box<dyn Iterator<Item = super::Result<DirItem>>>> {
+        self.validate(path)?;
+        if !self.path_is_dir(path)? {
+            return Err(super::Error::NotADirectory {
+                path: path.to_path_buf(),
+            });
+        }
+        let read_dir = std::fs::read_dir(path)?;
+        Ok(Box::new(DirItemIterator::new(read_dir)))
+    }
+
     fn file_read_to_string(&self, path: &Path) -> super::Result<String> {
         self.validate(path)?;
         std::fs::read_to_string(path).map_err(Into::into)

src/tests/fs.rs

@@ -107,6 +107,57 @@ mod dir_create_all {
     }
 }
 
+mod dir_dir_read {
+    use crate::fs::DirItem;
+
+    use super::*;
+
+    #[test]
+    fn should_return_dir_items() -> TestResult {
+        let fs = fs::temp()?;
+        let file1 = fs.base().join("file-1");
+        let dir = fs.base().join("dir");
+        let file2 = dir.join("file-2");
+        fs.file_write(&file1, "file-1")?;
+        fs.dir_create(&dir)?;
+        fs.file_write(&file2, "file-2")?;
+
+        let items = fs
+            .dir_read(fs.base())?
+            .filter_map(|i| i.ok())
+            .collect::<Vec<_>>();
+
+        assert_eq!(items.len(), 2);
+        assert!(items.contains(&DirItem::File(file1)));
+        assert!(items.contains(&DirItem::Dir(dir)));
+
+        Ok(())
+    }
+    #[test]
+    fn should_fail_on_not_a_dir() -> TestResult {
+        let fs = fs::temp()?;
+        let path = fs.base().join("file");
+        fs.file_write(&path, "contents")?;
+
+        let_assert!(Err(fs::Error::NotADirectory { path: _path }) = fs.dir_read(&path));
+
+        Ok(())
+    }
+    #[test]
+    fn should_fail_on_path_traversal() -> TestResult {
+        let fs = fs::temp()?;
+        let path = fs.base().join("..").join("foo");
+        let_assert!(
+            Err(fs::Error::PathTraversal {
+                base: _base,
+                path: _path
+            }) = fs.dir_read(&path)
+        );
+
+        Ok(())
+    }
+}
+
 mod path_exists {
     use super::*;
     #[test]