vortex_fs/
traits.rs

1//! VortexFs trait — the filesystem abstraction boundary.
2
3/// Error type for virtual filesystem operations.
4#[derive(Debug, Clone, PartialEq, Eq)]
5pub enum VortexFsError {
6    /// File or directory not found.
7    NotFound(String),
8    /// Permission denied (EACCES).
9    PermissionDenied(String),
10    /// Disk full (ENOSPC).
11    DiskFull(String),
12    /// I/O error (EIO).
13    IoError(String),
14    /// File already exists.
15    AlreadyExists(String),
16    /// Not a directory.
17    NotADirectory(String),
18    /// Is a directory (tried to read as file).
19    IsADirectory(String),
20    /// Directory not empty (tried to remove).
21    NotEmpty(String),
22    /// Torn write — partial write succeeded then failed.
23    TornWrite {
24        path: String,
25        bytes_written: u64,
26        intended: u64,
27    },
28    /// Data corruption injected.
29    Corrupted(String),
30}
31
32impl std::fmt::Display for VortexFsError {
33    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
34        match self {
35            VortexFsError::NotFound(p) => write!(f, "not found: {p}"),
36            VortexFsError::PermissionDenied(p) => write!(f, "permission denied: {p}"),
37            VortexFsError::DiskFull(p) => write!(f, "disk full: {p}"),
38            VortexFsError::IoError(p) => write!(f, "I/O error: {p}"),
39            VortexFsError::AlreadyExists(p) => write!(f, "already exists: {p}"),
40            VortexFsError::NotADirectory(p) => write!(f, "not a directory: {p}"),
41            VortexFsError::IsADirectory(p) => write!(f, "is a directory: {p}"),
42            VortexFsError::NotEmpty(p) => write!(f, "not empty: {p}"),
43            VortexFsError::TornWrite {
44                path,
45                bytes_written,
46                intended,
47            } => {
48                write!(
49                    f,
50                    "torn write on {path}: wrote {bytes_written}/{intended} bytes"
51                )
52            }
53            VortexFsError::Corrupted(p) => write!(f, "data corrupted: {p}"),
54        }
55    }
56}
57
58impl std::error::Error for VortexFsError {}
59
60/// Result type alias for filesystem operations.
61pub type VortexFsResult<T> = std::result::Result<T, VortexFsError>;
62
63/// File type (regular file or directory).
64#[derive(Debug, Clone, Copy, PartialEq, Eq)]
65pub enum FileType {
66    File,
67    Directory,
68}
69
70/// Metadata about a file or directory.
71#[derive(Debug, Clone)]
72pub struct FileMetadata {
73    /// File type.
74    pub file_type: FileType,
75    /// Size in bytes (0 for directories).
76    pub size: u64,
77}
78
79/// The filesystem abstraction boundary.
80///
81/// In production: implement with [`RealFs`](crate::RealFs) (pass-through to `std::fs`).
82/// In simulation: implement with [`SimFs`](crate::SimFs) (in-memory + fault injection).
83pub trait VortexFs {
84    /// Read the entire contents of a file.
85    fn read_file(&self, path: &str) -> VortexFsResult<Vec<u8>>;
86
87    /// Write data to a file (creates or overwrites).
88    fn write_file(&mut self, path: &str, data: &[u8]) -> VortexFsResult<()>;
89
90    /// Append data to a file (creates if not exists).
91    fn append_file(&mut self, path: &str, data: &[u8]) -> VortexFsResult<()>;
92
93    /// Remove a file.
94    fn remove_file(&mut self, path: &str) -> VortexFsResult<()>;
95
96    /// Rename a file or directory.
97    fn rename(&mut self, from: &str, to: &str) -> VortexFsResult<()>;
98
99    /// Create a directory (and all parent directories).
100    fn create_dir_all(&mut self, path: &str) -> VortexFsResult<()>;
101
102    /// Remove an empty directory.
103    fn remove_dir(&mut self, path: &str) -> VortexFsResult<()>;
104
105    /// List the entries in a directory.
106    fn read_dir(&self, path: &str) -> VortexFsResult<Vec<String>>;
107
108    /// Get metadata about a file or directory.
109    fn metadata(&self, path: &str) -> VortexFsResult<FileMetadata>;
110
111    /// Check if a path exists.
112    fn exists(&self, path: &str) -> bool;
113
114    /// Flush / fsync a file (no-op for in-memory, real sync for production).
115    fn fsync(&mut self, path: &str) -> VortexFsResult<()>;
116}
vortex_fs/traits.rs

vortex_fs/
traits.rs
