Crate anyfs_backend

Expand description

§anyfs-backend

Core traits and types for the AnyFS pluggable virtual filesystem standard.

This crate provides the foundational API that filesystem backends implement. It contains only trait definitions and types — no concrete implementations. Implementations live in the anyfs crate.

§Quick Start

Most users only need Fs — it covers 90% of use cases.

A typical usage pattern with any backend that implements Fs:

use anyfs_backend::Fs;
use std::path::Path;

// Generic function that works with any Fs implementation
fn work_with_files<B: Fs>(backend: &B) -> Result<(), anyfs_backend::FsError> {
    let data = backend.read(Path::new("/input.txt"))?;
    backend.write(Path::new("/output.txt"), &data)?;
    backend.create_dir_all(Path::new("/archive/2024"))?;
    for entry in backend.read_dir(Path::new("/"))? {
        println!("{}", entry?.name);
    }
    Ok(())
}

See the anyfs crate for concrete backend implementations.

§Core Types

Type	Purpose
`Fs`	Basic filesystem trait — read, write, and directory operations
`FsFull`	Extended filesystem — adds links, permissions, sync, stats
`FsFuse`	FUSE-mountable — adds inode-based operations
`FsPosix`	Full POSIX — adds handles, locks, extended attributes
`FsError`	Comprehensive error type with context
`Metadata`	File/directory metadata (size, type, times, permissions)
`DirEntry`	Single directory listing entry

§Which Trait Should I Use?

Fs — When you need basic file operations.

Use for: Config files, data serialization, file processing, simple I/O
Methods: read, write, create_dir, read_dir, exists, metadata
Coverage: 90% of use cases

FsFull — When you need filesystem features beyond basic I/O.

Use for: Backup tools, file managers, archive extraction
Adds: symlink, hard_link, set_permissions, sync, statfs
Includes: Everything in Fs

FsFuse — When building a FUSE filesystem.

Use for: Userspace mounts, virtual drives, network filesystems
Adds: path_to_inode, inode_to_path, lookup, metadata_by_inode
Includes: Everything in FsFull

FsPosix — When you need full POSIX semantics.

Use for: Database storage, lock-based coordination, xattr metadata
Adds: open/close handles, lock/unlock, get_xattr/set_xattr
Includes: Everything in FsFuse

§Complete Trait Reference

§Component Traits (What You Implement)

Trait	Provides	Key Methods	When to Use
`FsRead`	Read operations	`read`, `exists`, `metadata`	Always (core)
`FsWrite`	Write operations	`write`, `remove_file`, `rename`	Always (core)
`FsDir`	Directory ops	`read_dir`, `create_dir`	Always (core)
`FsLink`	Symlinks/hardlinks	`symlink`, `hard_link`	Backup tools
`FsPermissions`	Permission mgmt	`set_permissions`	File managers
`FsSync`	Disk sync	`sync`, `sync_path`	Databases
`FsStats`	FS statistics	`statfs`	Disk monitoring
`FsInode`	Inode ↔ path	`path_to_inode`, `lookup`	FUSE filesystems
`FsHandles`	File handles	`open`, `read_at`, `write_at`	Random access
`FsLock`	File locking	`lock`, `unlock`	Multi-process
`FsXattr`	Extended attrs	`get_xattr`, `set_xattr`	Metadata storage
`FsPath`	Path resolution	`canonicalize`	Symlink handling

§Composite Traits (What You Use in Bounds)

Trait	Combines	Typical Consumer
`Fs`	`FsRead + FsWrite + FsDir`	Generic file code
`FsFull`	`Fs + FsLink + FsPermissions + FsSync + FsStats`	File managers
`FsFuse`	`FsFull + FsInode`	FUSE implementations
`FsPosix`	`FsFuse + FsHandles + FsLock + FsXattr`	Databases, POSIX apps

§Trait Hierarchy

Layer 1 (Core):     FsRead + FsWrite + FsDir = Fs
                                              ↓
Layer 2 (Extended): Fs + FsLink + FsPermissions + FsSync + FsStats = FsFull
                                              ↓
Layer 3 (FUSE):     FsFull + FsInode = FsFuse
                                              ↓
Layer 4 (POSIX):    FsFuse + FsHandles + FsLock + FsXattr = FsPosix

All composite traits (Fs, FsFull, FsFuse, FsPosix) have blanket implementations. Just implement the component traits and you get the composite trait for free.

§Error Handling

All operations return Result<T, FsError>. Errors include context:

use anyfs_backend::FsError;
use std::path::PathBuf;

// Errors include the path that caused the problem
let err = FsError::NotFound { path: PathBuf::from("/missing.txt") };
assert_eq!(err.to_string(), "not found: /missing.txt");

// Permission errors include the operation
let err = FsError::PermissionDenied {
    path: PathBuf::from("/secret"),
    operation: "read",
};
assert_eq!(err.to_string(), "read: permission denied: /secret");

§Thread Safety

All traits require Send + Sync. Methods take &self (not &mut self), enabling safe concurrent access. Backends use interior mutability internally.

You can safely share a backend across threads using Arc<B> and spawn concurrent operations without explicit locking at the call site.

§Feature Flags

Feature	Description
`serde`	Enable serialization for `Metadata`, `DirEntry`, `Permissions`, etc.

§Crate Organization

This crate (anyfs-backend) contains only traits and types.

For concrete implementations, see the anyfs crate which provides:

MemoryBackend — In-memory filesystem
NativeBackend — Wrapper around std::fs
OverlayBackend — UnionFS-style layering
FileStorage — Type-erased filesystem wrapper
Middleware (encryption, compression, caching, etc.)

Structs§

DirEntry: A single entry from a directory listing.
Handle: Opaque file handle for POSIX-style I/O operations.
Metadata: Complete metadata for a filesystem entry.
OpenFlags: Flags for opening a file.
Permissions: Unix-style permission bits.
ReadDirIter: Iterator over directory entries.
StatFs: Filesystem-level statistics.

Enums§

FileType: The type of a filesystem entry.
FsError: Comprehensive filesystem error type.
LockType: Type of file lock.

Constants§

ROOT_INODE: The root directory inode number (FUSE convention).

Traits§

Fs: Basic filesystem — covers 90% of use cases.
FsDir: Directory operations for a virtual filesystem.
FsExt: Extension methods for any filesystem backend.
FsFull: Full filesystem with all std::fs features.
FsFuse: FUSE-mountable filesystem.
FsHandles: Handle-based file operations for POSIX compatibility.
FsInode: Inode-based filesystem operations for FUSE mounting.
FsLink: Symlink and hard link operations.
FsLock: File locking operations for POSIX compatibility.
FsPath: Path canonicalization with a default implementation.
FsPermissions: Permission management operations.
FsPosix: Full POSIX-compatible filesystem.
FsRead: Read operations for a virtual filesystem.
FsStats: Filesystem statistics operations.
FsSync: Filesystem synchronization operations.
FsWrite: Write operations for a virtual filesystem.
FsXattr: Extended attribute operations for POSIX compatibility.
Layer: A layer that wraps a backend to add functionality.
LayerExt: Extension trait for fluent layer composition.
PathResolver: Strategy trait for path resolution algorithms.
SelfResolving: Marker trait for backends that handle their own path resolution.