Trait FileSystem 

pub trait FileSystem: FileSystemExt {
    // 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 method
    fn as_search_capable(&self) -> Option<&dyn SearchCapable> { ... }
}

Async virtual filesystem trait.

This trait defines the core interface for all filesystem implementations in Bashkit. It contains only the essential POSIX-like operations. Optional methods for resource tracking and special file types live in FileSystemExt, which is a supertrait — so all FileSystem implementors must also implement FileSystemExt (usually just impl FileSystemExt for T {} to accept the defaults).

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 and add an empty FileSystemExt impl (or override specific extension methods). See examples/custom_filesystem_impl.rs for a complete implementation.

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

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

#[async_trait]
impl FileSystemExt for 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
• Path already exists as a file or symlink (always fails)
• Path already exists as a directory (fails unless recursive=true)

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 as_search_capable(&self) -> Option<&dyn SearchCapable>

Returns a reference to this filesystem as a SearchCapable implementation, if supported.

Builtins like grep call this to check for optimized search support. Returns None by default — override in implementations that provide indexed search.

Implementors

impl FileSystem for InMemoryFs

impl FileSystem for MountableFs

impl FileSystem for OverlayFs

impl<B: FsBackend + 'static> FileSystem for PosixFs<B>