Struct DirFS 

pub struct DirFS { /* private fields */ }

Implementations

impl DirFS

A virtual filesystem (VFS) implementation that maps to a real directory on the host system.

DirFS provides an isolated, path‑normalized view of a portion of the filesystem, rooted at a designated absolute path (root). It maintains an internal state of valid paths and supports standard operations:

• Navigate via cd() (change working directory).
• Create directories (mkdir()) and files (mkfile()).
• Remove entries (rm()).
• Check existence (exists()).
• Read and write content (read() / write() / append()).

Key features:

• Path normalization: Automatically resolves ., .., and trailing slashes.
• State consistency: Tracks all valid VFS paths to ensure operations reflect the actual VFS structure.
• Isolated root: All operations are confined to the root directory; no access to parent paths.
• Auto‑cleanup: Optionally removes created parent directories on drop (when is_auto_clean = true).
• Cross‑platform: Uses std::path::Path for portable path handling.

Usage notes:

• DirFS does not follow symlinks; rm() removes the link, not the target.
• Permissions are not automatically adjusted; ensure root is writable.
• Not thread‑safe in current version (wrap in Mutex if needed).
• Errors are returned via anyhow::Result with descriptive messages.

Example:

use vfs_kit::{DirFS, FsBackend};

let tmp = std::env::temp_dir();
let root = tmp.join("my_vfs");

let mut fs = DirFS::new(root).unwrap();
fs.mkdir("/docs").unwrap();
fs.mkfile("/docs/note.txt", Some(b"Hello")).unwrap();
assert!(fs.exists("/docs/note.txt"));

fs.rm("/docs/note.txt").unwrap();

pub fn new<P: AsRef<Path>>(root: P) -> Result<Self>

Creates a new DirFs instance with the root directory at path. Checks permissions to create and write into path.

• path is an absolute host path. If path is not absolute, error returns.

pub fn set_auto_clean(&mut self, clean: bool)

Changes auto-clean flag. If auto-clean flag is true all created in vfs artifacts will be removed on drop.

Trait Implementations

impl Drop for DirFS

fn drop(&mut self)

Executes the destructor for this type.

impl FsBackend for DirFS

fn root(&self) -> &Path

Returns root path related to the host file system.

fn cwd(&self) -> &Path

Returns current working directory related to the vfs root.

fn cd<P: AsRef<Path>>(&mut self, path: P) -> Result<()>

Changes the current working directory.

• path can be in relative or absolute form, but in both cases it must exist. An error is returned if the specified path does not exist.

fn exists<P: AsRef<Path>>(&self, path: P) -> bool

Checks if a path exists in the vfs. The path can be:

• absolute (starting with ‘/’),
• relative (relative to the vfs cwd),
• contain ‘..’ or ‘.’.

fn mkdir<P: AsRef<Path>>(&mut self, path: P) -> Result<()>

Creates directory and all it parents (if needed).

• path - inner vfs path.

fn mkfile<P: AsRef<Path>>( &mut self, file_path: P, content: Option<&[u8]>, ) -> Result<()>

Creates new file in vfs.

• file_path must be inner vfs path. It must contain the name of the file, optionally preceded by existing parent directory. If the parent directory does not exist, an error is returned.

fn read<P: AsRef<Path>>(&self, path: P) -> Result<Vec<u8>>

Reads the entire contents of a file into a byte vector.

• path is the inner VFS path.

Returns

• Ok(Vec<u8>) - File content as a byte vector if successful.
• Err(anyhow::Error) - If any of the following occurs:
  • File does not exist in VFS (file does not exist: ...)
  • Path points to a directory (... is a directory)
  • Permission issues when accessing the host file
  • I/O errors during reading

Notes

• Does not follow symbolic links on the host filesystem (reads the link itself).
• Returns an empty vector for empty files.

fn write<P: AsRef<Path>>(&self, path: P, content: &[u8]) -> Result<()>

Writes bytes to an existing file, replacing its entire contents.

• path - Path to the file.
• content - Byte slice (&[u8]) to write to the file.

Returns

• Ok(()) - If the write operation succeeded.
• Err(anyhow::Error) - If any of the following occurs:
  • File does not exist in VFS (file does not exist: ...)
  • Path points to a directory (... is a directory)
  • Permission issues when accessing the host file
  • I/O errors during writing (e.g., disk full, invalid path)

Behavior

• Overwrites completely: The entire existing content is replaced.
• No file creation: File must exist (use mkfile() first).
• Atomic operation: Uses std::fs::write() which replaces the file in one step.
• Permissions: The file retains its original permissions (no chmod is performed).

fn append<P: AsRef<Path>>(&self, path: P, content: &[u8]) -> Result<()>

Appends bytes to the end of an existing file, preserving its old contents.

Arguments

• path - Path to the existing file.
• content - Byte slice (&[u8]) to append to the file.

Returns

• Ok(()) - If the append operation succeeded.
• Err(anyhow::Error) - If any of the following occurs:
  • File does not exist in VFS (file does not exist: ...)
  • Path points to a directory (... is a directory)
  • Permission issues when accessing the host file
  • I/O errors during writing (e.g., disk full, invalid path)

Behavior

• Appends only: Existing content is preserved; new bytes are added at the end.
• No parent creation: Parent directories must exist (use mkdir() first if needed).
• File creation: Does NOT create the file if it doesn’t exist (returns error).
• Permissions: The file retains its original permissions.

fn rm<P: AsRef<Path>>(&mut self, path: P) -> Result<()>

Removes a file or directory at the specified path.

• path: can be absolute (starting with ‘/’) or relative to the current working directory (cwd).
• If the path is a directory, all its contents are removed recursively.

Returns:

• Ok(()) on successful removal.
• Err(_) if:
  • the path does not exist in the VFS;
  • there are insufficient permissions;
  • a filesystem error occurs.

fn cleanup(&mut self) -> bool

Removes all artifacts (dirs and files) in vfs, but preserve its root.