M1.2: vfs with ignore rules, polling watcher and safe file IO

- Project::open canonicalises the root (no \?\ prefix on Windows where
  safe); typed errors for missing and non-directory paths.
- Lazy children(dir): dirs first, case-insensitive; kind, ignored flag
  and role (vendor/ library, node_modules/ excluded, .git hidden).
- Ignore rules via the ignore crate: .gitignore, .ignore,
  .git/info/exclude, global git excludes, with git precedence.
- Watcher: std-only polling (100 ms, watched dirs only) with
  create/modify/remove/rename events and a Failed event on root loss.
  notify is CC0-1.0 and fails cargo deny; owner decision pending.
- read_text with a 32 MiB cap, UTF-8 + BOM, typed InvalidUtf8 and
  UnsupportedEncoding; write_atomic via temp file + rename, keeping
  permissions and refusing read-only files.
- 28 tests on temp dirs (30 on Unix: permission and symlink write tests).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-14 19:23:54 +02:00
parent faadb05eb3
commit 5d49b57b9c
16 changed files with 2058 additions and 4 deletions

416
crates/vfs/src/watch.rs Normal file
View file

@ -0,0 +1,416 @@
//! Watching the project for changes on disk.
//!
//! The watcher polls: a background thread re-reads the watched directories
//! every [`WatchOptions::interval`] (100 ms by default) and compares kind,
//! size and modification time of each entry with the previous scan. It needs
//! no dependency; native notifications (the `notify` crate) wait on a licence
//! decision and would sit behind the same API.
//!
//! Behaviour:
//! - Only watched directories are scanned, non-recursively. The root is
//! watched from the start; callers add the directories the user expanded
//! with [`Watcher::watch_dir`]. Directories that are hidden (`.git`),
//! ignored or excluded (`node_modules`) are refused, so no events come
//! from inside them, and `.git` entries are never reported.
//! - Changes within one interval are coalesced (debounced): several writes
//! give one [`VfsEvent::Modified`], a file created and deleted again gives
//! nothing. An entry that disappears while one with the same kind, size
//! and modification time appears in the same scan is reported as
//! [`VfsEvent::Renamed`].
//! - Directories report creation, removal and renames of their children,
//! but not [`VfsEvent::Modified`] for themselves.
//! - A watched directory that disappears stops being watched (its parent
//! reports the removal if watched). If the root cannot be read the watcher
//! sends [`VfsEvent::Failed`] and stops: the project keeps working without
//! watching.
//! - A change that keeps size and modification time is not seen; modern file
//! systems record modification times finely enough for this to be rare.
use std::collections::{BTreeMap, HashMap};
use std::ffi::OsString;
use std::fs;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::mpsc::{self, Receiver, Sender};
use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
use std::thread::{self, JoinHandle};
use std::time::{Duration, SystemTime};
use crate::VfsError;
use crate::path::check_relative;
use crate::project::{EntryKind, MAX_CHILDREN, Project, kind_of};
use crate::rules::{EntryRole, is_hidden};
/// Options for [`Project::watch_with`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct WatchOptions {
/// Time between scans; also the debounce window.
pub interval: Duration,
}
impl Default for WatchOptions {
fn default() -> Self {
WatchOptions {
interval: Duration::from_millis(100),
}
}
}
/// A change on disk. Paths are relative to the project root.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum VfsEvent {
/// An entry appeared.
Created {
/// The new entry.
path: PathBuf,
/// Its kind.
kind: EntryKind,
},
/// A file's contents changed.
Modified {
/// The file.
path: PathBuf,
},
/// An entry disappeared.
Removed {
/// The removed entry.
path: PathBuf,
},
/// An entry was moved within the watched directories.
Renamed {
/// The old path.
from: PathBuf,
/// The new path.
to: PathBuf,
},
/// Watching stopped; no further events follow.
Failed(VfsError),
}
/// A running watcher. Dropping it stops the background thread.
#[derive(Debug)]
pub struct Watcher {
/// State shared with the thread.
shared: Arc<Shared>,
/// The polling thread, joined on drop.
thread: Option<JoinHandle<()>>,
}
/// State shared between the [`Watcher`] handle and its thread.
#[derive(Debug)]
struct Shared {
/// The project being watched.
project: Project,
/// Set to ask the thread to stop.
stop: AtomicBool,
/// Last scan of every watched directory, keyed by project-relative path.
dirs: Mutex<BTreeMap<PathBuf, Snapshot>>,
}
/// Entries of one directory by name.
type Snapshot = HashMap<OsString, Stamp>;
/// What a scan remembers about an entry.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
struct Stamp {
/// Entry kind.
kind: EntryKind,
/// Size in bytes.
len: u64,
/// Modification time, if the platform reports one.
modified: Option<SystemTime>,
}
/// Changes found by one scan, before rename pairing.
#[derive(Default)]
struct Changes {
/// Entries that appeared.
created: Vec<(PathBuf, Stamp)>,
/// Entries that disappeared.
removed: Vec<(PathBuf, Stamp)>,
/// Files whose stamp changed.
modified: Vec<PathBuf>,
}
impl Project {
/// Starts watching with default options.
///
/// # Errors
/// See [`Project::watch_with`].
pub fn watch(&self) -> Result<(Watcher, Receiver<VfsEvent>), VfsError> {
self.watch_with(WatchOptions::default())
}
/// Starts watching the project root; events arrive on the returned
/// channel. Changes made after this returns are reported.
///
/// # Errors
/// [`VfsError::WatchUnavailable`] if the root cannot be scanned or the
/// thread cannot be started. The project stays usable; callers carry on
/// without watching and show the error.
pub fn watch_with(
&self,
options: WatchOptions,
) -> Result<(Watcher, Receiver<VfsEvent>), VfsError> {
let root = scan(self.root()).map_err(|err| VfsError::WatchUnavailable {
message: format!("cannot read {}: {err}", self.root().display()),
})?;
let mut dirs = BTreeMap::new();
dirs.insert(PathBuf::new(), root);
let shared = Arc::new(Shared {
project: self.clone(),
stop: AtomicBool::new(false),
dirs: Mutex::new(dirs),
});
let (sender, receiver) = mpsc::channel();
let thread_shared = Arc::clone(&shared);
let thread = thread::Builder::new()
.name("lutra-vfs-watch".into())
.spawn(move || run(&thread_shared, &sender, options.interval))
.map_err(|err| VfsError::WatchUnavailable {
message: format!("cannot start the watcher thread: {err}"),
})?;
Ok((
Watcher {
shared,
thread: Some(thread),
},
receiver,
))
}
}
impl Watcher {
/// Starts watching the directory `dir` (project-relative). Returns
/// `false` without watching if the directory is hidden, ignored or
/// excluded; watching an already watched directory is a no-op.
///
/// # Errors
/// [`VfsError::OutsideProject`] for an escaping path, [`VfsError::NotFound`]
/// or [`VfsError::Io`] if the directory cannot be read.
pub fn watch_dir(&self, dir: impl AsRef<Path>) -> Result<bool, VfsError> {
let dir = check_relative(dir.as_ref())?;
let status = self.shared.project.status(&dir)?;
if status.hidden || status.ignored || status.role == EntryRole::Excluded {
return Ok(false);
}
if self.shared.lock().contains_key(&dir) {
return Ok(true);
}
let abs = self.shared.project.root().join(&dir);
let snapshot = scan(&abs).map_err(|err| VfsError::io(&abs, err))?;
self.shared.lock().entry(dir).or_insert(snapshot);
Ok(true)
}
/// Stops watching the directory `dir` (project-relative). Unknown
/// directories are ignored.
pub fn unwatch_dir(&self, dir: impl AsRef<Path>) {
if let Ok(dir) = check_relative(dir.as_ref()) {
self.shared.lock().remove(&dir);
}
}
/// The watched directories, project-relative, sorted.
pub fn watched_dirs(&self) -> Vec<PathBuf> {
self.shared.lock().keys().cloned().collect()
}
}
impl Drop for Watcher {
/// Stops and joins the polling thread. A panic inside the thread is not
/// propagated: the watcher is going away and has nothing left to report.
fn drop(&mut self) {
self.shared.stop.store(true, Ordering::SeqCst);
if let Some(thread) = self.thread.take() {
thread.thread().unpark();
let _thread_result = thread.join();
}
}
}
impl Shared {
/// Locks the snapshots. A poisoned lock is recovered: snapshots are only
/// replaced whole, so they are consistent even after a panic.
fn lock(&self) -> MutexGuard<'_, BTreeMap<PathBuf, Snapshot>> {
self.dirs.lock().unwrap_or_else(PoisonError::into_inner)
}
}
/// Body of the polling thread: scan, diff, send, until stopped, until the
/// receiver is dropped or until the root fails.
fn run(shared: &Shared, sender: &Sender<VfsEvent>, interval: Duration) {
loop {
thread::park_timeout(interval);
if shared.stop.load(Ordering::SeqCst) {
return;
}
let (events, failed) = poll(shared);
for event in events {
if sender.send(event).is_err() {
return;
}
}
if failed {
return;
}
}
}
/// Rescans every watched directory and returns the events, plus whether
/// watching failed for good.
fn poll(shared: &Shared) -> (Vec<VfsEvent>, bool) {
let root = shared.project.root();
let mut dirs = shared.lock();
let mut changes = Changes::default();
let mut gone = Vec::new();
let mut root_error = None;
for (dir, old) in dirs.iter_mut() {
match scan(&root.join(dir)) {
Ok(new) => {
diff(dir, old, &new, &mut changes);
*old = new;
}
Err(err) if dir.as_os_str().is_empty() => {
root_error = Some(err);
break;
}
Err(_) => gone.push(dir.clone()),
}
}
if let Some(err) = root_error {
dirs.clear();
let failure = VfsError::WatchUnavailable {
message: format!("cannot read {}: {err}", root.display()),
};
return (vec![VfsEvent::Failed(failure)], true);
}
for dir in gone {
dirs.remove(&dir);
}
(pair_renames(changes), false)
}
/// Reads the entries of `dir`, skipping `.git` and stopping after
/// [`MAX_CHILDREN`] entries.
///
/// # Errors
/// The I/O error of opening the directory; entries that vanish or cannot be
/// inspected while reading are skipped.
fn scan(dir: &Path) -> std::io::Result<Snapshot> {
let mut snapshot = Snapshot::new();
for item in fs::read_dir(dir)? {
if snapshot.len() >= MAX_CHILDREN {
break;
}
let Ok(item) = item else {
continue;
};
let name = item.file_name();
if is_hidden(&name) {
continue;
}
let Ok(meta) = fs::metadata(item.path()) else {
continue;
};
let stamp = Stamp {
kind: kind_of(meta.file_type()),
len: meta.len(),
modified: meta.modified().ok(),
};
snapshot.insert(name, stamp);
}
Ok(snapshot)
}
/// Adds the differences between two scans of `dir` to `changes`.
fn diff(dir: &Path, old: &Snapshot, new: &Snapshot, changes: &mut Changes) {
for (name, stamp) in new {
match old.get(name) {
None => changes.created.push((dir.join(name), *stamp)),
Some(before) if before.kind != stamp.kind => {
changes.removed.push((dir.join(name), *before));
changes.created.push((dir.join(name), *stamp));
}
Some(before) if before != stamp && stamp.kind == EntryKind::File => {
changes.modified.push(dir.join(name));
}
Some(_) => {}
}
}
for (name, stamp) in old {
if !new.contains_key(name) {
changes.removed.push((dir.join(name), *stamp));
}
}
}
/// Turns raw changes into events, pairing a removal and a creation with the
/// same stamp into a rename when that stamp is unique on both sides.
/// Events are ordered removals, renames, creations, modifications, each
/// sorted by path.
fn pair_renames(changes: Changes) -> Vec<VfsEvent> {
let Changes {
mut created,
mut removed,
mut modified,
} = changes;
let mut removed_by_stamp: HashMap<Stamp, Vec<usize>> = HashMap::new();
for (index, (_, stamp)) in removed.iter().enumerate() {
if stamp.modified.is_some() {
removed_by_stamp.entry(*stamp).or_default().push(index);
}
}
let mut created_by_stamp: HashMap<Stamp, usize> = HashMap::new();
for (_, stamp) in &created {
*created_by_stamp.entry(*stamp).or_default() += 1;
}
let mut renamed = Vec::new();
let mut paired_removed = vec![false; removed.len()];
let mut paired_created = vec![false; created.len()];
for (index, (to, stamp)) in created.iter().enumerate() {
let Some(candidates) = removed_by_stamp.get(stamp) else {
continue;
};
let [from_index] = candidates.as_slice() else {
continue;
};
if created_by_stamp.get(stamp) != Some(&1) {
continue;
}
let Some((from, _)) = removed.get(*from_index) else {
continue;
};
renamed.push(VfsEvent::Renamed {
from: from.clone(),
to: to.clone(),
});
if let Some(flag) = paired_removed.get_mut(*from_index) {
*flag = true;
}
if let Some(flag) = paired_created.get_mut(index) {
*flag = true;
}
}
let mut keep = paired_removed.iter().map(|paired| !paired);
removed.retain(|_| keep.next().unwrap_or(true));
let mut keep = paired_created.iter().map(|paired| !paired);
created.retain(|_| keep.next().unwrap_or(true));
removed.sort_by(|a, b| a.0.cmp(&b.0));
created.sort_by(|a, b| a.0.cmp(&b.0));
modified.sort();
let mut events =
Vec::with_capacity(removed.len() + renamed.len() + created.len() + modified.len());
events.extend(
removed
.into_iter()
.map(|(path, _)| VfsEvent::Removed { path }),
);
events.extend(renamed);
events.extend(created.into_iter().map(|(path, stamp)| VfsEvent::Created {
path,
kind: stamp.kind,
}));
events.extend(modified.into_iter().map(|path| VfsEvent::Modified { path }));
events
}