Trait FileSystem 

pub trait FileSystem: Send + Sync {
    // Required methods
    fn read_file<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 Path,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn write_file<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        path: &'life1 Path,
        content: &'life2 [u8],
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn append_file<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        path: &'life1 Path,
        content: &'life2 [u8],
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn mkdir<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 Path,
        recursive: bool,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn remove<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 Path,
        recursive: bool,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn stat<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 Path,
    ) -> Pin<Box<dyn Future<Output = Result<Metadata>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn read_dir<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 Path,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<DirEntry>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn exists<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 Path,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn rename<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        from: &'life1 Path,
        to: &'life2 Path,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn copy<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        from: &'life1 Path,
        to: &'life2 Path,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn symlink<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        target: &'life1 Path,
        link: &'life2 Path,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn read_link<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 Path,
    ) -> Pin<Box<dyn Future<Output = Result<PathBuf>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn chmod<'life0, 'life1, 'async_trait>(
        &'life0 self,
        path: &'life1 Path,
        mode: u32,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided methods
    fn usage(&self) -> FsUsage { ... }
    fn limits(&self) -> FsLimits { ... }
}

Async virtual filesystem trait.

This trait defines the interface for all filesystem implementations in BashKit. Implement this trait to create custom storage backends.

Thread Safety

All implementations must be Send + Sync to support concurrent access from multiple tasks. Use interior mutability patterns (e.g., RwLock, Mutex) for mutable state.

Implementing FileSystem

To create a custom filesystem, implement all methods in this trait. See examples/custom_filesystem_impl.rs for a complete implementation.

use bashkit::{async_trait, FileSystem, Result};

pub struct MyFileSystem { /* ... */ }

#[async_trait]
impl FileSystem for MyFileSystem {
    async fn read_file(&self, path: &Path) -> Result<Vec<u8>> {
        // Your implementation
    }
    // ... implement all other methods
}

Using Custom Filesystems

Pass your filesystem to Bash::builder():

use bashkit::Bash;
use std::sync::Arc;

let custom_fs = Arc::new(MyFileSystem::new());
let mut bash = Bash::builder().fs(custom_fs).build();

Built-in Implementations

BashKit provides three implementations:

• InMemoryFs - HashMap-based in-memory storage
• OverlayFs - Copy-on-write layered filesystem
• MountableFs - Multiple mount points

Required Methods

fn read_file<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read a file’s contents as bytes.

Errors

Returns an error if:

• The file does not exist (NotFound)
• The path is a directory
• I/O error occurs

fn write_file<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, path: &'life1 Path, content: &'life2 [u8], ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Write contents to a file, creating it if necessary.

If the file exists, its contents are replaced. If it doesn’t exist, a new file is created (parent directory must exist).

Errors

Returns an error if:

• The parent directory does not exist
• The path is a directory
• I/O error occurs

fn append_file<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, path: &'life1 Path, content: &'life2 [u8], ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Append contents to a file, creating it if necessary.

Errors

Returns an error if:

• The path is a directory
• I/O error occurs

fn mkdir<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, recursive: bool, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Create a directory.

Arguments

• path - The directory path to create
• recursive - If true, create parent directories as needed (like mkdir -p)

Errors

Returns an error if:

• recursive is false and parent directory doesn’t exist
• Directory already exists (when not recursive)

fn remove<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, recursive: bool, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Remove a file or directory.

Arguments

• path - The path to remove
• recursive - If true and path is a directory, remove all contents (like rm -r)

Errors

Returns an error if:

• The path does not exist
• Path is a non-empty directory and recursive is false

fn stat<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = Result<Metadata>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get file or directory metadata.

Returns information about the file including type, size, permissions, and timestamps.

Errors

Returns an error if the path does not exist.

fn read_dir<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = Result<Vec<DirEntry>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

List directory contents.

Returns a list of entries (files, directories, symlinks) in the directory.

Errors

Returns an error if:

• The path does not exist
• The path is not a directory

fn exists<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Check if a path exists.

Returns true if the path exists (file, directory, or symlink).

fn rename<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, from: &'life1 Path, to: &'life2 Path, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Rename or move a file or directory.

Errors

Returns an error if:

• The source path does not exist
• The destination parent directory does not exist

fn copy<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, from: &'life1 Path, to: &'life2 Path, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Copy a file.

Errors

Returns an error if:

• The source file does not exist
• The source is a directory

fn symlink<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, target: &'life1 Path, link: &'life2 Path, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Create a symbolic link.

Creates a symlink at link that points to target.

Arguments

• target - The path the symlink will point to
• link - The path where the symlink will be created

fn read_link<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = Result<PathBuf>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read a symbolic link’s target.

Errors

Returns an error if:

• The path does not exist
• The path is not a symlink

fn chmod<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, mode: u32, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Change file permissions.

Arguments

• path - The file path
• mode - Unix permission mode (e.g., 0o644, 0o755)

Errors

Returns an error if the path does not exist.

Provided Methods

fn usage(&self) -> FsUsage

Get current filesystem usage statistics.

Returns total bytes used, file count, and directory count. Used by du and df builtins.

Default Implementation

Returns zeros. Implementations should override for accurate stats.

fn limits(&self) -> FsLimits

Get filesystem limits.

Returns the configured limits for this filesystem. Used by df builtin to show available space.

Default Implementation

Returns unlimited limits.

Implementors

impl FileSystem for InMemoryFs

impl FileSystem for MountableFs

impl FileSystem for OverlayFs