//! Watching the project for changes on disk. //! //! Two backends sit behind one API: //! - **Native** (default): operating-system notifications through the //! `notify` crate (ReadDirectoryChangesW, inotify, FSEvents). A //! notification only marks its directory as dirty; once no notification //! has arrived for [`WatchOptions::interval`] (100 ms by default, at most //! ten intervals after the first one) the dirty directories are rescanned. //! - **Polling** (fallback): every interval all watched directories are //! rescanned. Used when the native watcher cannot start for the root //! (network drives, exhausted inotify limits) or when //! [`WatchBackend::Polling`] is requested, and for single directories the //! native watcher refuses. //! //! Either way, events come from comparing kind, size and modification time //! of each entry with the previous scan, so both backends report the same //! events. 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 debounce window are coalesced: 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. If the native watcher reports an error or lost events, all //! watched directories are rescanned. //! - 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, BTreeSet, 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, RecvTimeoutError, Sender}; use std::sync::{Arc, Mutex, MutexGuard, PoisonError}; use std::thread::{self, JoinHandle}; use std::time::{Duration, Instant, SystemTime}; use notify::{RecommendedWatcher, RecursiveMode, Watcher as _}; use crate::VfsError; use crate::path::check_relative; use crate::project::{EntryKind, MAX_CHILDREN, Project, kind_of}; use crate::rules::{EntryRole, is_hidden}; /// Longest debounce, in intervals, while notifications keep arriving. const MAX_DEBOUNCE_INTERVALS: u32 = 10; /// Which backend [`Project::watch_with`] uses. #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] pub enum WatchBackend { /// Native notifications, falling back to polling if they fail to start. #[default] Auto, /// Polling only. Polling, } /// Options for [`Project::watch_with`]. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct WatchOptions { /// Debounce window, and the time between scans when polling. pub interval: Duration, /// The backend to use. pub backend: WatchBackend, } impl Default for WatchOptions { fn default() -> Self { WatchOptions { interval: Duration::from_millis(100), backend: WatchBackend::Auto, } } } /// 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, /// Wakes the thread when the watcher is dropped. signals: Sender, /// The background thread, joined on drop. thread: Option>, } /// 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, /// Every watched directory, keyed by project-relative path. dirs: Mutex>, /// The native watcher, if it started. native: Mutex>, } /// One watched directory. #[derive(Debug)] struct Watched { /// Its last scan. snapshot: Snapshot, /// The native watcher covers it; otherwise it is polled. native: bool, } /// Messages to the background thread. #[derive(Debug)] enum Signal { /// Something changed at these absolute paths. Paths(Vec), /// The native watcher lost events or failed; rescan everything. Rescan, /// The watcher was dropped. Stop, } /// What the next scan has to look at. #[derive(Default)] struct Work { /// Natively watched directories with notifications, project-relative. dirty: BTreeSet, /// Rescan every directory. full: bool, } /// Entries of one directory by name. type Snapshot = HashMap; /// 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, } /// 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, } impl Project { /// Starts watching with default options. /// /// # Errors /// See [`Project::watch_with`]. pub fn watch(&self) -> Result<(Watcher, Receiver), VfsError> { self.watch_with(WatchOptions::default()) } /// Starts watching the project root; events arrive on the returned /// channel. Changes made after this returns are reported. A native /// watcher that fails to start is not an error: the watcher polls /// instead (see [`Watcher::is_native`]). /// /// # 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), VfsError> { let (signals, signal_receiver) = mpsc::channel(); let native = match options.backend { WatchBackend::Auto => start_native(self.root(), signals.clone()), WatchBackend::Polling => None, }; let snapshot = 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(), Watched { snapshot, native: native.is_some(), }, ); let shared = Arc::new(Shared { project: self.clone(), stop: AtomicBool::new(false), dirs: Mutex::new(dirs), native: Mutex::new(native), }); 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, &signal_receiver, &sender, options.interval)) .map_err(|err| VfsError::WatchUnavailable { message: format!("cannot start the watcher thread: {err}"), })?; Ok(( Watcher { shared, signals, thread: Some(thread), }, receiver, )) } } /// Starts a native watcher on `root` that forwards notifications as /// [`Signal`]s; `None` if the platform refuses. A send to a stopped thread /// fails and is ignored: nobody is left to care about the notification. fn start_native(root: &Path, signals: Sender) -> Option { let handler = move |result: notify::Result| { let signal = match result { Ok(event) if event.need_rescan() => Signal::Rescan, Ok(event) => Signal::Paths(event.paths), Err(_) => Signal::Rescan, }; let _thread_gone = signals.send(signal); }; let mut watcher = notify::recommended_watcher(handler).ok()?; watcher.watch(root, RecursiveMode::NonRecursive).ok()?; Some(watcher) } 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. If the /// native watcher refuses the directory, it is polled instead. /// /// # 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) -> Result { 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 native = self .shared .lock_native() .as_mut() .is_some_and(|watcher| watcher.watch(&abs, RecursiveMode::NonRecursive).is_ok()); let snapshot = match scan(&abs) { Ok(snapshot) => snapshot, Err(err) => { self.shared.unwatch_native(&abs); return Err(VfsError::io(&abs, err)); } }; self.shared .lock() .entry(dir) .or_insert(Watched { snapshot, native }); Ok(true) } /// Stops watching the directory `dir` (project-relative). Unknown /// directories are ignored. pub fn unwatch_dir(&self, dir: impl AsRef) { let Ok(dir) = check_relative(dir.as_ref()) else { return; }; let removed = self.shared.lock().remove(&dir); if removed.is_some_and(|watched| watched.native) { self.shared .unwatch_native(&self.shared.project.root().join(&dir)); } } /// The watched directories, project-relative, sorted. pub fn watched_dirs(&self) -> Vec { self.shared.lock().keys().cloned().collect() } /// Whether the project root is watched natively (`false`: polling). pub fn is_native(&self) -> bool { self.shared .lock() .get(Path::new("")) .is_some_and(|watched| watched.native) } } impl Drop for Watcher { /// Stops the native watcher, then stops and joins the thread. A failed /// wake-up send means the thread already ended, and 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); let native = self.shared.lock_native().take(); drop(native); let _thread_gone = self.signals.send(Signal::Stop); if let Some(thread) = self.thread.take() { let _thread_result = thread.join(); } } } impl Shared { /// Locks the watched directories. A poisoned lock is recovered: /// entries are only replaced whole, so they are consistent even after a /// panic. fn lock(&self) -> MutexGuard<'_, BTreeMap> { self.dirs.lock().unwrap_or_else(PoisonError::into_inner) } /// Locks the native watcher, recovering a poisoned lock like /// [`Shared::lock`]. fn lock_native(&self) -> MutexGuard<'_, Option> { self.native.lock().unwrap_or_else(PoisonError::into_inner) } /// Removes the native watch on the absolute directory `abs`. Failure is /// ignored: the directory may already be gone, which ends its watch /// anyway. fn unwatch_native(&self, abs: &Path) { if let Some(watcher) = self.lock_native().as_mut() { let _already_gone = watcher.unwatch(abs); } } } impl Work { /// Records a signal; `false` for [`Signal::Stop`]. fn add(&mut self, signal: Signal, project: &Project) -> bool { match signal { Signal::Paths(paths) => { for path in paths { if let Some(rel) = project.relative(&path) { if let Some(parent) = rel.parent() { self.dirty.insert(parent.to_path_buf()); } self.dirty.insert(rel); } } true } Signal::Rescan => { self.full = true; true } Signal::Stop => false, } } } /// Body of the background thread: wait for notifications (debounced) or /// the polling interval, scan, send; until stopped, until the receiver is /// dropped or until the root fails. fn run(shared: &Shared, signals: &Receiver, sender: &Sender, interval: Duration) { loop { let mut work = Work::default(); match signals.recv_timeout(interval) { Ok(signal) => { if !work.add(signal, &shared.project) || !debounce(shared, signals, interval, &mut work) { return; } } Err(RecvTimeoutError::Timeout) => {} Err(RecvTimeoutError::Disconnected) => return, } if shared.stop.load(Ordering::SeqCst) { return; } let (events, failed) = poll(shared, &work); for event in events { if sender.send(event).is_err() { return; } } if failed { return; } } } /// Collects further signals until none arrives for `interval`, or for at /// most [`MAX_DEBOUNCE_INTERVALS`] intervals. Returns `false` if the thread /// must stop. fn debounce( shared: &Shared, signals: &Receiver, interval: Duration, work: &mut Work, ) -> bool { let deadline = Instant::now() + interval * MAX_DEBOUNCE_INTERVALS; loop { let left = deadline.saturating_duration_since(Instant::now()); if left.is_zero() { return true; } match signals.recv_timeout(interval.min(left)) { Ok(signal) => { if !work.add(signal, &shared.project) { return false; } } Err(RecvTimeoutError::Timeout) => return true, Err(RecvTimeoutError::Disconnected) => return false, } } } /// Rescans the polled directories and the dirty native ones (all of them /// for a full rescan) and returns the events, plus whether watching failed /// for good. The root is checked on every call, so its loss is noticed /// even when no notification reports it. fn poll(shared: &Shared, work: &Work) -> (Vec, bool) { let root = shared.project.root(); let mut dirs = shared.lock(); let mut root_error = match fs::metadata(root) { Ok(meta) if meta.is_dir() => None, Ok(_) => Some("not a directory".to_string()), Err(err) => Some(err.to_string()), }; let mut changes = Changes::default(); let mut gone = Vec::new(); if root_error.is_none() { for (dir, watched) in dirs.iter_mut() { if watched.native && !work.full && !work.dirty.contains(dir) { continue; } match scan(&root.join(dir)) { Ok(new) => { diff(dir, &watched.snapshot, &new, &mut changes); watched.snapshot = new; } Err(err) if dir.as_os_str().is_empty() => { root_error = Some(err.to_string()); break; } Err(_) => gone.push((dir.clone(), watched.native)), } } } if let Some(err) = root_error { dirs.clear(); drop(dirs); let native = shared.lock_native().take(); drop(native); let failure = VfsError::WatchUnavailable { message: format!("cannot read {}: {err}", root.display()), }; return (vec![VfsEvent::Failed(failure)], true); } for (dir, _) in &gone { dirs.remove(dir); } drop(dirs); for (dir, native) in gone { if native { shared.unwatch_native(&root.join(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 { 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 { let Changes { mut created, mut removed, mut modified, } = changes; let mut removed_by_stamp: HashMap> = 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 = 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 }