Trait Filesystem 

pub trait Filesystem: Send {
    // Required methods
    fn root(&mut self) -> Result<FileEntry, FilesystemError>;
    fn list_directory(
        &mut self,
        entry: &FileEntry,
    ) -> Result<Vec<FileEntry>, FilesystemError>;
    fn read_file(
        &mut self,
        entry: &FileEntry,
        max_bytes: usize,
    ) -> Result<Vec<u8>, FilesystemError>;
    fn volume_label(&self) -> Option<&str>;
    fn fs_type(&self) -> &str;
    fn total_size(&self) -> u64;
    fn used_size(&self) -> u64;

    // Provided methods
    fn allocation_unit(&self) -> Option<u64> { ... }
    fn last_data_byte(&mut self) -> Result<u64, FilesystemError> { ... }
    fn defragmented_minimum_size(&mut self) -> Result<u64, FilesystemError> { ... }
    fn fragmentation_stats(
        &mut self,
    ) -> Option<Result<FragmentationStats, FilesystemError>> { ... }
    fn write_file_to(
        &mut self,
        entry: &FileEntry,
        writer: &mut dyn Write,
    ) -> Result<u64, FilesystemError> { ... }
    fn write_resource_fork_to(
        &mut self,
        _entry: &FileEntry,
        _writer: &mut dyn Write,
    ) -> Result<u64, FilesystemError> { ... }
    fn resource_fork_size(&mut self, _entry: &FileEntry) -> u64 { ... }
    fn blessed_system_folder(&mut self) -> Option<(u64, String)> { ... }
    fn fsck(&mut self) -> Option<Result<FsckResult, FilesystemError>> { ... }
    fn set_show_deleted(&mut self, _on: bool) -> bool { ... }
    fn journal_detail(
        &mut self,
    ) -> Result<Option<Box<dyn Any + Send>>, FilesystemError> { ... }
    fn validate_name(&self, name: &str) -> Result<(), FilesystemError> { ... }
    fn uses_colon_paths(&self) -> bool { ... }
    fn case_insensitive_lookup(&self) -> bool { ... }
    fn supports_xattrs(&self) -> bool { ... }
    fn list_xattrs(
        &mut self,
        _entry: &FileEntry,
    ) -> Result<Vec<Xattr>, FilesystemError> { ... }
}

Trait for browsing a filesystem within a partition.

Required Methods

fn root(&mut self) -> Result<FileEntry, FilesystemError>

Get the root directory entry.

fn list_directory( &mut self, entry: &FileEntry, ) -> Result<Vec<FileEntry>, FilesystemError>

List the contents of a directory.

fn read_file( &mut self, entry: &FileEntry, max_bytes: usize, ) -> Result<Vec<u8>, FilesystemError>

Read file contents (up to max_bytes).

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

Volume label, if available.

fn fs_type(&self) -> &str

Filesystem type name (e.g., “FAT16”, “FAT32”).

fn total_size(&self) -> u64

Total filesystem size in bytes.

fn used_size(&self) -> u64

Used space in bytes.

Provided Methods

fn allocation_unit(&self) -> Option<u64>

Allocation unit (cluster / block) size in bytes, when the filesystem has a single fixed one. The cross-image copy preflight uses this to project real on-disk consumption — many small files each round up to one unit, so summing raw byte sizes badly underestimates usage on large-cluster volumes. None means “unknown”; the copy engine then falls back to a 512-byte floor.

fn last_data_byte(&mut self) -> Result<u64, FilesystemError>

Returns the minimum number of bytes from the partition start needed to capture all filesystem data without moving any data on disk — i.e. the position of the last allocated byte. Used for smart backup trimming.

Default implementation returns total_size() (no trimming).

fn defragmented_minimum_size(&mut self) -> Result<u64, FilesystemError>

Returns the minimum partition size that could host all live filesystem data after a defragmenting clone (data packed from offset 0).

For most filesystems this is identical to last_data_byte() — there is no clone-shrink path. HFS+ overrides this because a fragmented volume’s in-place trim point hugs the partition tail even when most blocks are free. See docs/hfsplus_enhancements.md Phase 1.

Callers should treat the value as an approximate target: the actual clone may need a small additional margin for fresh B-tree headers and alignment.

fn fragmentation_stats( &mut self, ) -> Option<Result<FragmentationStats, FilesystemError>>

Returns per-fork fragmentation statistics for this volume, or None when the filesystem can’t compute them (e.g. cluster-allocation filesystems whose CompactReader already repacks during the backup stream so “fragmentation” doesn’t translate into a backup-time decision the user can make).

Only HFS+/HFS implement this today; FAT/NTFS/exFAT return None because the packing CompactReader inherently emits a defragmented layout for them, and the UI doesn’t surface a defrag toggle on those rows.

fn write_file_to( &mut self, entry: &FileEntry, writer: &mut dyn Write, ) -> Result<u64, FilesystemError>

Stream file data to a writer. Returns the number of bytes written.

All built-in filesystems (FAT/exFAT/NTFS/ext/btrfs/HFS/HFS+/ProDOS) override this with an extent-by-extent implementation that doesn’t allocate the full file. The default falls back to loading the entire file into RAM via read_file(entry, usize::MAX); new filesystems should override unless their files are bounded by design.

fn write_resource_fork_to( &mut self, _entry: &FileEntry, _writer: &mut dyn Write, ) -> Result<u64, FilesystemError>

Write resource fork data to a writer. Returns the number of bytes written. Default returns Ok(0) (no resource fork).

fn resource_fork_size(&mut self, _entry: &FileEntry) -> u64

Returns the resource fork size for a file entry. Default returns 0.

fn blessed_system_folder(&mut self) -> Option<(u64, String)>

Returns the CNID and name of the blessed (bootable) system folder, if set. Only meaningful for HFS/HFS+.

fn fsck(&mut self) -> Option<Result<FsckResult, FilesystemError>>

Run filesystem integrity check. Returns None if not supported for this filesystem type. Override in implementations that support fsck.

fn set_show_deleted(&mut self, _on: bool) -> bool

List deleted-but-readable entries alongside live ones; false when unsupported.

fn journal_detail( &mut self, ) -> Result<Option<Box<dyn Any + Send>>, FilesystemError>

Decode the journal into per-transaction detail for a history viewer; Ok(None) if unjournaled. The value is the filesystem’s own detail type (HFS+: JournalDetail), for the caller to downcast.

fn validate_name(&self, name: &str) -> Result<(), FilesystemError>

Validate that name is legal for a new file or directory on this filesystem. Returns Err(InvalidData) with a human-readable reason when the name violates length, character, or encoding rules.

Default implementation accepts any non-empty name; filesystems that support editing should override this with their actual rules so that GUI callers can validate at staging time rather than at apply time.

fn uses_colon_paths(&self) -> bool

True when this filesystem reserves : as its native path separator (classic Mac HFS / HFS+), so : can never appear in a catalog name.

When this is true, rb-cli accepts an in-image path written with : separators (e.g. :System Folder:Apple Menu Items), which lets a literal / be an ordinary filename byte — the only way to address a name like Oxyd b/w unambiguously, since classic-Mac volumes allow / in names.

Default false: / is the only separator, and a literal / inside a component must be written \/ (with \\ for a literal backslash).

fn case_insensitive_lookup(&self) -> bool

Whether name lookup falls back to case-insensitive matching, the way the native OS resolves paths on this filesystem; an exact match wins first.

fn supports_xattrs(&self) -> bool

Whether this filesystem stores POSIX extended attributes (user.*, security.*, …). True on ext / XFS / SquashFS; false on filesystems with no xattr concept (Minix, EFS, FAT, HFS). The UI uses this to show or hide the xattr section rather than probing every file.

fn list_xattrs( &mut self, _entry: &FileEntry, ) -> Result<Vec<Xattr>, FilesystemError>

Read the extended attributes on entry. Default: none. Override on xattr-bearing filesystems. Returning an empty list is normal — most files carry no xattrs even where the filesystem supports them.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors