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:
parent
faadb05eb3
commit
5d49b57b9c
16 changed files with 2058 additions and 4 deletions
416
crates/vfs/src/watch.rs
Normal file
416
crates/vfs/src/watch.rs
Normal 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
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue