vvv_engine/vfs/mod.rs
1//! Virtual file system: the only way the engine touches files.
2//!
3//! Tests run against [`MemoryVfs`]; the CLI runs against [`DiskVfs`]; a plan
4//! that has to be planned *against* (the next step of a batch) is applied to
5//! an [`Overlay`] first. Because every read and write goes through the trait,
6//! the planners never know which.
7
8mod disk;
9mod memory;
10mod overlay;
11
12use std::path::{Path, PathBuf};
13
14pub use disk::DiskVfs;
15pub use memory::MemoryVfs;
16pub use overlay::Overlay;
17
18#[derive(Debug, thiserror::Error)]
19pub enum VfsError {
20 #[error("file not found: {0}")]
21 NotFound(PathBuf),
22 #[error("{path}: not valid UTF-8")]
23 InvalidUtf8 { path: PathBuf },
24 #[error("{path}: {source}")]
25 Io {
26 path: PathBuf,
27 #[source]
28 source: std::io::Error,
29 },
30}
31
32/// A cheap witness of a file's state: modification time and size on disk, a
33/// version counter in memory. Two equal stamps mean the contents could not
34/// have changed, which is what lets a warm corpus skip the read. Like `make`
35/// and `git`, it trusts the clock: an edit that keeps the length and lands
36/// within the same timestamp tick is invisible until the next one. Writes are
37/// never trusted to a stamp — `Plan::apply` checks content fingerprints.
38#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
39pub struct Stamp {
40 modified: u128,
41 len: u64,
42}
43
44impl Stamp {
45 pub fn new(modified: u128, len: u64) -> Self {
46 Self { modified, len }
47 }
48}
49
50pub trait Vfs: Send + Sync {
51 fn read(&self, path: &Path) -> Result<String, VfsError>;
52 /// The file's current [`Stamp`], without reading it.
53 fn stamp(&self, path: &Path) -> Result<Stamp, VfsError>;
54 /// Write a whole file, creating parent directories as needed.
55 fn write(&self, path: &Path, contents: &str) -> Result<(), VfsError>;
56 fn exists(&self, path: &Path) -> bool;
57 /// Move a file, creating parent directories of `to` as needed.
58 fn rename(&self, from: &Path, to: &Path) -> Result<(), VfsError>;
59 /// Every regular file under `root`, in a deterministic order.
60 fn walk(&self, root: &Path) -> Result<Vec<PathBuf>, VfsError>;
61}