Trait FileSystem 

pub trait FileSystem: Send + Sync {
    // Required methods
    fn read_file(&self, path: &Path) -> Result<Vec<u8>>;
    fn read_range(
        &self,
        path: &Path,
        offset: u64,
        len: usize,
    ) -> Result<Vec<u8>>;
    fn write_file(&self, path: &Path, data: &[u8]) -> Result<()>;
    fn create_file(&self, path: &Path) -> Result<Box<dyn FileWriter>>;
    fn open_file(&self, path: &Path) -> Result<Box<dyn FileReader>>;
    fn open_file_for_write(&self, path: &Path) -> Result<Box<dyn FileWriter>>;
    fn open_file_for_append(&self, path: &Path) -> Result<Box<dyn FileWriter>>;
    fn set_file_length(&self, path: &Path, len: u64) -> Result<()>;
    fn rename(&self, from: &Path, to: &Path) -> Result<()>;
    fn copy(&self, from: &Path, to: &Path) -> Result<u64>;
    fn remove_file(&self, path: &Path) -> Result<()>;
    fn remove_dir(&self, path: &Path) -> Result<()>;
    fn metadata(&self, path: &Path) -> Result<FileMetadata>;
    fn symlink_metadata(&self, path: &Path) -> Result<FileMetadata>;
    fn is_dir(&self, path: &Path) -> Result<bool>;
    fn is_file(&self, path: &Path) -> Result<bool>;
    fn set_permissions(
        &self,
        path: &Path,
        permissions: &FilePermissions,
    ) -> Result<()>;
    fn read_dir(&self, path: &Path) -> Result<Vec<DirEntry>>;
    fn create_dir(&self, path: &Path) -> Result<()>;
    fn create_dir_all(&self, path: &Path) -> Result<()>;
    fn canonicalize(&self, path: &Path) -> Result<PathBuf>;
    fn current_uid(&self) -> u32;
    fn search_file(
        &self,
        path: &Path,
        pattern: &str,
        opts: &FileSearchOptions,
        cursor: &mut FileSearchCursor,
    ) -> Result<Vec<SearchMatch>>;
    fn sudo_write(
        &self,
        path: &Path,
        data: &[u8],
        mode: u32,
        uid: u32,
        gid: u32,
    ) -> Result<()>;

    // Provided methods
    fn count_line_feeds_in_range(
        &self,
        path: &Path,
        offset: u64,
        len: usize,
    ) -> Result<usize> { ... }
    fn write_patched(
        &self,
        src_path: &Path,
        dst_path: &Path,
        ops: &[WriteOp<'_>],
    ) -> Result<()> { ... }
    fn exists(&self, path: &Path) -> bool { ... }
    fn metadata_if_exists(&self, path: &Path) -> Option<FileMetadata> { ... }
    fn is_writable(&self, path: &Path) -> bool { ... }
    fn is_owner(&self, path: &Path) -> bool { ... }
    fn temp_path_for(&self, path: &Path) -> PathBuf { ... }
    fn unique_temp_path(&self, dest_path: &Path) -> PathBuf { ... }
    fn remote_connection_info(&self) -> Option<&str> { ... }
    fn is_remote_connected(&self) -> bool { ... }
    fn home_dir(&self) -> Result<PathBuf> { ... }
}

Unified trait for all filesystem operations

This trait provides both file content I/O and directory operations. Implementations can be:

• StdFileSystem: Native filesystem using std::fs
• VirtualFileSystem: In-memory for WASM/browser
• Custom backends for remote agents, network filesystems, etc.

All methods are synchronous. For async UI operations, use spawn_blocking.

Required Methods

fn read_file(&self, path: &Path) -> Result<Vec<u8>>

Read entire file into memory

fn read_range(&self, path: &Path, offset: u64, len: usize) -> Result<Vec<u8>>

Read a range of bytes from a file (for lazy loading large files)

fn write_file(&self, path: &Path, data: &[u8]) -> Result<()>

Write data to file atomically (temp file + rename)

fn create_file(&self, path: &Path) -> Result<Box<dyn FileWriter>>

Create a file for writing, returns a writer handle

fn open_file(&self, path: &Path) -> Result<Box<dyn FileReader>>

Open a file for reading, returns a reader handle

fn open_file_for_write(&self, path: &Path) -> Result<Box<dyn FileWriter>>

Open a file for writing in-place (truncating, preserves ownership on Unix)

fn open_file_for_append(&self, path: &Path) -> Result<Box<dyn FileWriter>>

Open a file for appending (creates if doesn’t exist)

fn set_file_length(&self, path: &Path, len: u64) -> Result<()>

Set file length (truncate or extend with zeros)

fn rename(&self, from: &Path, to: &Path) -> Result<()>

Rename/move a file or directory atomically

fn copy(&self, from: &Path, to: &Path) -> Result<u64>

Copy a file (fallback when rename fails across filesystems)

fn remove_file(&self, path: &Path) -> Result<()>

Remove a file

fn remove_dir(&self, path: &Path) -> Result<()>

Remove an empty directory

fn metadata(&self, path: &Path) -> Result<FileMetadata>

Get file/directory metadata

fn symlink_metadata(&self, path: &Path) -> Result<FileMetadata>

Get symlink metadata (doesn’t follow symlinks)

fn is_dir(&self, path: &Path) -> Result<bool>

Check if path is a directory

fn is_file(&self, path: &Path) -> Result<bool>

Check if path is a file

fn set_permissions( &self, path: &Path, permissions: &FilePermissions, ) -> Result<()>

Set file permissions

fn read_dir(&self, path: &Path) -> Result<Vec<DirEntry>>

List entries in a directory (non-recursive)

fn create_dir(&self, path: &Path) -> Result<()>

Create a directory

fn create_dir_all(&self, path: &Path) -> Result<()>

Create a directory and all parent directories

fn canonicalize(&self, path: &Path) -> Result<PathBuf>

Get canonical (absolute, normalized) path

fn current_uid(&self) -> u32

Get the current user’s UID (Unix only, returns 0 on other platforms)

fn search_file( &self, path: &Path, pattern: &str, opts: &FileSearchOptions, cursor: &mut FileSearchCursor, ) -> Result<Vec<SearchMatch>>

Search a file on disk for a pattern, returning one batch of matches.

Call repeatedly with the same cursor until cursor.done is true. Each call searches one chunk; the cursor tracks position and line numbers across calls.

The search runs where the data lives: StdFileSystem reads and scans locally; RemoteFileSystem sends a stateless RPC to the remote agent. Only matches cross the network.

For searching an already-open buffer with unsaved edits, use TextBuffer::search_scan_all which reads from the piece tree.

fn sudo_write( &self, path: &Path, data: &[u8], mode: u32, uid: u32, gid: u32, ) -> Result<()>

Write file using sudo (for root-owned files).

This writes the file with elevated privileges, preserving the specified permissions and ownership. Used when normal write fails due to permissions.

• path: Destination file path
• data: File contents to write
• mode: File permissions (e.g., 0o644)
• uid: Owner user ID
• gid: Owner group ID

Provided Methods

fn count_line_feeds_in_range( &self, path: &Path, offset: u64, len: usize, ) -> Result<usize>

Count \n bytes in a file range without returning the data.

Used by the line-feed scanner to count newlines in unloaded chunks. Remote filesystem implementations can override this to count on the server side, avoiding the transfer of chunk bytes over the network.

The default implementation reads the range and counts locally.

fn write_patched( &self, src_path: &Path, dst_path: &Path, ops: &[WriteOp<'_>], ) -> Result<()>

Write a file using a patch recipe (optimized for remote filesystems).

This allows saving edited files by specifying which parts to copy from the original and which parts are new content. For remote filesystems, this avoids transferring unchanged portions over the network.

Arguments

• src_path - The original file to read from (for Copy operations)
• dst_path - The destination file (often same as src_path)
• ops - The sequence of operations to build the new file

The default implementation flattens all operations into memory and calls write_file. Remote implementations can override this to send the recipe and let the remote host do the reconstruction.

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

Check if path exists

fn metadata_if_exists(&self, path: &Path) -> Option<FileMetadata>

Check if path exists, returns metadata if it does

fn is_writable(&self, path: &Path) -> bool

Check if the current user has write permission to the given path.

On Unix, this considers file ownership, group membership (including supplementary groups), and the relevant permission bits. On other platforms it falls back to the standard readonly check.

Returns false if the path doesn’t exist or metadata can’t be read.

fn is_owner(&self, path: &Path) -> bool

Check if the current user is the owner of the file

fn temp_path_for(&self, path: &Path) -> PathBuf

Get a temporary file path for atomic writes

fn unique_temp_path(&self, dest_path: &Path) -> PathBuf

Get a unique temporary file path (using timestamp and PID)

fn remote_connection_info(&self) -> Option<&str>

Get remote connection info if this is a remote filesystem

Returns Some("user@host") for remote filesystems, None for local. Used to display remote connection status in the UI.

fn is_remote_connected(&self) -> bool

Check if a remote filesystem is currently connected.

Returns true for local filesystems (always “connected”) and for remote filesystems with a healthy connection. Returns false when the remote connection has been lost (e.g., timeout, SSH disconnect).

fn home_dir(&self) -> Result<PathBuf>

Get the home directory for this filesystem

For local filesystems, returns the local home directory. For remote filesystems, returns the remote home directory.

Implementors

impl FileSystem for SlowFileSystem

impl FileSystem for RemoteFileSystem

impl FileSystem for NoopFileSystem

impl FileSystem for StdFileSystem