Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.
use futures::{Stream, StreamExt as _};
use gpui::{BackgroundExecutor, Task};
use notify::{Event, EventKind};
use parking_lot::Mutex;
use std::{
collections::{BTreeSet, HashMap},
ops::DerefMut,
path::Path,
pin::Pin,
sync::{Arc, LazyLock},
time::{Duration, Instant},
};
use util::{ResultExt, paths::SanitizedPath};
use crate::{Fs, PathEvent, PathEventKind, Watcher};
mod diagnostics;
pub use diagnostics::{
WatchDiagnosticEvent, WatchRecording, WatchRoot, WatchSnapshot, WatcherSnapshot,
};
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize)]
pub enum OsWatcherKind {
Native,
Poll,
}
impl OsWatcherKind {
/// Poll watches and native macOS/Windows watches cover their whole subtree;
/// native Linux (inotify) watches cover one directory.
fn is_recursive(self) -> bool {
self == Self::Poll || cfg!(any(target_os = "windows", target_os = "macos"))
}
}
pub(crate) async fn watch(
fs: Arc<dyn Fs>,
native_watcher: Arc<OsWatcher>,
poll_watcher: Arc<OsWatcher>,
executor: BackgroundExecutor,
path: &Path,
latency: Duration,
) -> (
Pin<Box<dyn Send + Stream<Item = Vec<PathEvent>>>>,
Arc<dyn Watcher>,
) {
let (tx, rx) = async_channel::unbounded();
let pending_paths: Arc<Mutex<Vec<PathEvent>>> = Default::default();
let watcher: Arc<dyn Watcher> = Arc::new(FsWatcher::new(
native_watcher,
poll_watcher,
fs.clone(),
executor.clone(),
tx,
pending_paths.clone(),
));
if let Err(e) = watcher.add(path) {
log::warn!("Failed to watch {}:\n{e}", path.display());
}
// Check if path is a symlink and follow the target parent
if let Some(mut target) = fs.read_link(path).await.ok() {
log::trace!("watch symlink {path:?} -> {target:?}");
// Check if symlink target is relative path, if so make it absolute
if target.is_relative()
&& let Some(parent) = path.parent()
{
target = parent.join(target);
if let Ok(canonical) = fs.canonicalize(&target).await {
target = SanitizedPath::new(&canonical).as_path().to_path_buf();
}
}
watcher.add(&target).ok();
// Skipped for poll watchers: PollWatcher::watch() recursively scans
// at registration, blocking on large virtual filesystem mounts
if let Some(parent) = target.parent()
&& !fs.requires_poll_watcher(parent)
{
watcher.add(parent).log_err();
}
}
(
Box::pin(rx.filter_map({
let watcher = watcher.clone();
move |_| {
let _ = watcher.clone();
let pending_paths = pending_paths.clone();
let executor = executor.clone();
async move {
if !latency.is_zero() {
executor.timer(latency).await;
}
let paths = std::mem::take(&mut *pending_paths.lock());
log::debug!("pending path events: {:?}", paths);
(!paths.is_empty()).then_some(paths)
}
}
})),
watcher,
)
}
pub struct FsWatcher {
native_watcher: Arc<OsWatcher>,
poll_watcher: Arc<OsWatcher>,
fs: Arc<dyn Fs>,
executor: BackgroundExecutor,
tx: async_channel::Sender<()>,
pending_path_events: Arc<Mutex<Vec<PathEvent>>>,
registrations: Arc<Mutex<HashMap<WatchKey, FsWatcherRegistration>>>,
pending_registrations: Arc<Mutex<HashMap<Arc<std::path::Path>, Task<()>>>>,
}
#[derive(Clone)]
struct FsWatcherRegistration {
id: WatcherRegistrationId,
os_watcher: Arc<OsWatcher>,
}
impl FsWatcher {
pub(crate) fn new(
native_watcher: Arc<OsWatcher>,
poll_watcher: Arc<OsWatcher>,
fs: Arc<dyn Fs>,
executor: BackgroundExecutor,
tx: async_channel::Sender<()>,
pending_path_events: Arc<Mutex<Vec<PathEvent>>>,
) -> Self {
Self {
native_watcher,
poll_watcher,
fs,
executor,
tx,
pending_path_events,
registrations: Default::default(),
pending_registrations: Default::default(),
}
}
fn add_existing_path(&self, path: Arc<Path>) -> anyhow::Result<()> {
let case_insensitive = !self.fs.is_path_case_sensitive(&path);
let key = WatchKey::for_registration(SanitizedPath::new(&path), case_insensitive);
let existing = self.registrations.lock().get(&key).cloned();
if let Some(existing) = existing {
log::trace!("path to watch is already registered: {path:?}");
return existing.os_watcher.rewatch_if_stale(
&mut existing.os_watcher.state.lock(),
SanitizedPath::new(&path),
&key,
);
}
match register_existing_path(
&self.native_watcher,
&self.poll_watcher,
self.fs.as_ref(),
path.clone(),
case_insensitive,
self.tx.clone(),
self.pending_path_events.clone(),
)? {
Some(registration) => {
self.registrations.lock().insert(key, registration);
}
None => {
// Registration was skipped (e.g. the native watch-limit cooldown
// is active). Retry in the background rather than silently leaving
// the path unwatched forever.
log::warn!("watch registration for {path:?} was skipped; retrying in background");
self.add_pending_path(path);
}
}
Ok(())
}
fn add_pending_path(&self, path: Arc<Path>) {
let mut pending_registrations = self.pending_registrations.lock();
if pending_registrations.contains_key(path.as_ref()) {
return;
}
let task = self.executor.spawn(poll_path_until_created(
self.native_watcher.clone(),
self.poll_watcher.clone(),
self.fs.clone(),
self.executor.clone(),
path.clone(),
self.tx.clone(),
self.pending_path_events.clone(),
self.registrations.clone(),
self.pending_registrations.clone(),
));
pending_registrations.insert(path, task);
}
}
impl Drop for FsWatcher {
fn drop(&mut self) {
self.pending_registrations.lock().clear();
let mut registrations = HashMap::new();
{
let old = &mut self.registrations.lock();
std::mem::swap(old.deref_mut(), &mut registrations);
}
for (_, registration) in registrations {
registration.os_watcher.remove(registration.id);
}
}
}
impl Watcher for FsWatcher {
fn add(&self, path: &std::path::Path) -> anyhow::Result<()> {
log::trace!("watcher add: {path:?}");
let path: Arc<Path> = path.into();
if path_covered_by_recursive_registration(
&self.registrations.lock(),
SanitizedPath::new(&path),
) {
log::trace!("path to watch is covered by an existing registration: {path:?}");
return Ok(());
}
if self
.pending_registrations
.lock()
.contains_key(path.as_ref())
{
log::trace!("path to watch is already pending: {path:?}");
return Ok(());
}
if !self.fs.path_exists(&path) {
self.add_pending_path(path);
return Ok(());
}
self.add_existing_path(path)
}
fn remove(&self, path: &std::path::Path) -> anyhow::Result<()> {
log::trace!("remove watched path: {path:?}");
self.pending_registrations.lock().remove(path);
let sanitized = SanitizedPath::new(path);
let registration = {
let mut registrations = self.registrations.lock();
registrations
.remove(&WatchKey::exact(sanitized))
.or_else(|| registrations.remove(&WatchKey::folded(sanitized)))
};
if let Some(registration) = registration {
registration.os_watcher.remove(registration.id);
}
Ok(())
}
}
/// Whether a recursive registration on a strict ancestor of `path` already covers
/// it. Both key spellings are probed so a folded registration still matches; only
/// poll watches and native macOS/Windows watches are recursive.
fn path_covered_by_recursive_registration(
registrations: &HashMap<WatchKey, FsWatcherRegistration>,
path: &SanitizedPath,
) -> bool {
path.as_path().ancestors().skip(1).any(|ancestor| {
let ancestor = SanitizedPath::unchecked_new(ancestor);
[WatchKey::exact(ancestor), WatchKey::folded(ancestor)]
.iter()
.any(|key| {
registrations
.get(key)
.is_some_and(|registration| registration.os_watcher.is_recursive())
})
})
}
/// Detect whether a path requires polling instead of native file watching.
///
/// Returns `true` for filesystem types where inotify/FSEvents/ReadDirectoryChanges
/// silently fail to deliver events: 9P (WSL drvfs), NFS, CIFS/SMB, FUSE (sshfs), etc.
///
/// Can be overridden with the `ZED_FILE_WATCHER_MODE` environment variable:
/// - `native` — always use native OS watcher
/// - `poll` — always use polling
/// - `auto` (default) — auto-detect based on filesystem type
pub fn requires_poll_watcher(path: &Path) -> bool {
match std::env::var("ZED_FILE_WATCHER_MODE")
.as_deref()
.unwrap_or("auto")
{
"native" => return false,
"poll" => return true,
_ => {}
}
#[cfg(target_os = "linux")]
{
return detect_requires_poll_watcher_linux(path);
}
#[cfg(not(target_os = "linux"))]
{
let _ = path;
false
}
}
fn register_existing_path(
native_watcher: &Arc<OsWatcher>,
poll_watcher: &Arc<OsWatcher>,
fs: &dyn Fs,
path: Arc<Path>,
case_insensitive: bool,
tx: async_channel::Sender<()>,
pending_path_events: Arc<Mutex<Vec<PathEvent>>>,
) -> anyhow::Result<Option<FsWatcherRegistration>> {
let os_watcher = if fs.requires_poll_watcher(path.as_ref()) {
log::info!(
"Using poll watcher ({}ms interval) for {}",
poll_interval().as_millis(),
path.display()
);
telemetry::event!("fs_watcher_poll", path = path.display().to_string());
poll_watcher
} else {
native_watcher
};
let root_path = SanitizedPath::new_arc(path.as_ref());
let path_for_callback = path.clone();
let Some(registration_id) =
os_watcher.add(path, case_insensitive, move |event: ¬ify::Event| {
log::trace!("watcher received event: {event:?}");
push_notify_event(
&tx,
&pending_path_events,
&root_path,
case_insensitive,
path_for_callback.as_ref(),
event,
);
})?
else {
return Ok(None);
};
Ok(Some(FsWatcherRegistration {
id: registration_id,
os_watcher: os_watcher.clone(),
}))
}
#[cfg(target_os = "linux")]
fn detect_requires_poll_watcher_linux(path: &Path) -> bool {
use std::ffi::CString;
use std::os::unix::ffi::OsStrExt;
let c_path = match CString::new(path.as_os_str().as_bytes()) {
Ok(p) => p,
Err(_) => return false,
};
let mut stat: libc::statfs = unsafe { std::mem::zeroed() };
if unsafe { libc::statfs(c_path.as_ptr(), &mut stat) } != 0 {
return false;
}
const V9FS_MAGIC: u64 = 0x0102_1997;
const NFS_SUPER_MAGIC: u64 = 0x0000_6969;
const CIFS_MAGIC: u64 = 0xFF53_4D42;
const SMB_SUPER_MAGIC: u64 = 0x0000_517B;
const SMB2_MAGIC: u64 = 0xFE53_4D42;
const FUSE_SUPER_MAGIC: u64 = 0x6573_5546;
let fs_type = (stat.f_type as u64) & 0xFFFF_FFFF;
if fs_type == FUSE_SUPER_MAGIC && is_virtiofs(path) {
return false;
}
if fs_type == V9FS_MAGIC
|| fs_type == NFS_SUPER_MAGIC
|| fs_type == CIFS_MAGIC
|| fs_type == SMB_SUPER_MAGIC
|| fs_type == SMB2_MAGIC
|| fs_type == FUSE_SUPER_MAGIC
{
log::info!(
"Detected network/virtual filesystem (type 0x{:x}) at {}, using poll watcher",
fs_type,
path.display()
);
return true;
}
if is_wsl_drvfs_path(path) {
log::info!(
"Detected WSL drvfs mount at {}, using poll watcher",
path.display()
);
return true;
}
false
}
#[cfg(target_os = "linux")]
fn is_virtiofs(path: &Path) -> bool {
let Ok(mountinfo) = std::fs::read_to_string("/proc/self/mountinfo") else {
return false;
};
let mut best_mount = None;
for line in mountinfo.lines() {
let fields = line.split(' ').collect::<Vec<_>>();
let Some(separator) = fields.iter().position(|field| *field == "-") else {
continue;
};
let (Some(mount_point), Some(fs_type)) = (fields.get(4), fields.get(separator + 1)) else {
continue;
};
let mount_point = mount_point
.replace("\\040", " ")
.replace("\\011", "\t")
.replace("\\012", "\n")
.replace("\\134", "\\");
if path.starts_with(&mount_point)
&& best_mount.is_none_or(|(length, _)| mount_point.len() > length)
{
best_mount = Some((mount_point.len(), *fs_type));
}
}
best_mount.is_some_and(|(_, fs_type)| fs_type == "virtiofs" || fs_type == "fuse.virtiofs")
}
#[cfg(target_os = "linux")]
fn is_wsl_drvfs_path(path: &Path) -> bool {
if std::env::var_os("WSL_DISTRO_NAME").is_none() {
if let Ok(version) = std::fs::read_to_string("/proc/version") {
let version = version.to_lowercase();
if !version.contains("microsoft") && !version.contains("wsl") {
return false;
}
} else {
return false;
}
}
let Some(path) = path.to_str() else {
return false;
};
if !path.starts_with("/mnt/") || path.len() < 6 {
return false;
}
let after_mnt = &path[5..];
after_mnt.starts_with(|c: char| c.is_ascii_alphabetic())
&& (after_mnt.len() == 1 || after_mnt.as_bytes()[1] == b'/')
}
/// Whether the volume backing `path` does case-insensitive name lookups, used to
/// pick exact vs. folded matching.
#[cfg(target_os = "macos")]
pub(crate) fn case_insensitive_path(path: &Path) -> bool {
use std::os::unix::ffi::OsStrExt as _;
// `pathconf(_PC_CASE_SENSITIVE)` returns 1 (sensitive), 0 (insensitive), or -1
// on error; default errors to insensitive (the APFS/HFS+ default).
let Ok(c_path) = std::ffi::CString::new(path.as_os_str().as_bytes()) else {
return true;
};
// SAFETY: We just initialized c_path, so it's a valid pointer
unsafe { libc::pathconf(c_path.as_ptr(), libc::_PC_CASE_SENSITIVE) == 0 }
}
#[cfg(target_os = "linux")]
pub(crate) fn case_insensitive_path(_path: &Path) -> bool {
// use std::os::unix::ffi::OsStrExt as _;
// // Only ext4/f2fs casefold (`+F`) dirs are insensitive, reported by `statx` via
// // STATX_ATTR_CASEFOLD; any failure (e.g. pre-4.11 ENOSYS) means case-sensitive.
// const STATX_ATTR_CASEFOLD: u64 = 0x0000_2000;
// let Ok(c_path) = std::ffi::CString::new(path.as_os_str().as_bytes()) else {
// return false;
// };
// let mut buf = std::mem::MaybeUninit::<libc::statx>::zeroed();
// // SAFETY: c_path is still valid, buffer has been zeroed
// if unsafe { libc::statx(libc::AT_FDCWD, c_path.as_ptr(), 0, 0, buf.as_mut_ptr()) } != 0 {
// return false;
// }
// // SAFETY: libc statx initialized this buffer, otherwise we would've returned on a error
// // in that function call
// let buf = unsafe { buf.assume_init() };
// buf.stx_attributes_mask & STATX_ATTR_CASEFOLD != 0
// && buf.stx_attributes & STATX_ATTR_CASEFOLD != 0
false
}
#[cfg(target_os = "windows")]
pub(crate) fn case_insensitive_path(_path: &Path) -> bool {
// todo(windows): Windows defaults to case in sensitive, but
// they can mark specific directories as case sensitive. Mainly
// for WSL use cases
true
}
#[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
pub(crate) fn case_insensitive_path(_path: &Path) -> bool {
// Other BSDs default to case-sensitive local filesystems.
false
}
/// Whether `path` is `root` or sits beneath it, folding case on case-insensitive
/// volumes so a differently-cased spelling still matches.
fn path_is_under(path: &SanitizedPath, root: &SanitizedPath, case_insensitive: bool) -> bool {
if case_insensitive {
let path = path.as_path().to_string_lossy().to_lowercase();
let root = root.as_path().to_string_lossy().to_lowercase();
Path::new(&path).starts_with(Path::new(&root))
} else {
path.starts_with(root)
}
}
/// Lookup key for a watch path, shared by add, remove, and dispatch so they all
/// agree on whether two spellings denote the same directory.
///
/// On case-sensitive volumes the exact (sanitized) path is the key, so genuinely
/// distinct directories stay distinct. On case-insensitive volumes the folded
/// (lowercased) spelling is the key, so any casing of a directory collides.
///
/// The two variants are distinct map keys, so a case-sensitive registration can
/// never be hit by a folded lookup (or vice versa); dispatch can therefore probe
/// both forms of an event path without risking a cross-rule false match.
///
/// Folded keys use path-component spelling so separators and `.` components
/// agree with exact path equality. macOS also normalizes Unicode before folding.
#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
enum WatchKey {
Exact(Arc<Path>),
Folded(Arc<str>),
}
impl WatchKey {
fn exact(path: &SanitizedPath) -> Self {
Self::Exact(Arc::from(path.as_path()))
}
fn folded(path: &SanitizedPath) -> Self {
// Event ancestors omit trailing separators, even when registration paths include them.
let normalized_path = path.as_path().components().collect::<std::path::PathBuf>();
let lossy = normalized_path.to_string_lossy();
// macOS (APFS/HFS+) compares names normalization-insensitively (NFC vs
// NFD), and FSEvents can report NFD while a config/LSP supplies NFC, so
// normalize before folding case. Windows (NTFS) and Linux are
// normalization-sensitive, so there we only fold case.
#[cfg(target_os = "macos")]
let folded = {
use unicode_normalization::UnicodeNormalization as _;
lossy.chars().nfc().collect::<String>().to_lowercase()
};
#[cfg(not(target_os = "macos"))]
let folded = lossy.to_lowercase();
Self::Folded(folded.into())
}
fn for_registration(path: &SanitizedPath, case_insensitive: bool) -> Self {
if case_insensitive {
Self::folded(path)
} else {
Self::exact(path)
}
}
}
async fn poll_path_until_created(
native_watcher: Arc<OsWatcher>,
poll_watcher: Arc<OsWatcher>,
fs: Arc<dyn Fs>,
executor: BackgroundExecutor,
path: Arc<Path>,
tx: async_channel::Sender<()>,
pending_path_events: Arc<Mutex<Vec<PathEvent>>>,
registrations: Arc<Mutex<HashMap<WatchKey, FsWatcherRegistration>>>,
pending_registrations: Arc<Mutex<HashMap<Arc<Path>, Task<()>>>>,
) {
loop {
executor.timer(poll_interval()).await;
if !pending_registrations.lock().contains_key(path.as_ref()) {
return;
}
if !fs.path_exists(&path) {
continue;
}
// Probe case sensitivity now that the path exists, rather than at add
// time when it didn't.
let case_insensitive = if fs.is_fake() {
!fs.is_path_case_sensitive(&path)
} else {
smol::unblock({
let path = path.clone();
let fs = fs.clone();
move || !fs.is_path_case_sensitive(&path)
})
.await
};
let key = WatchKey::for_registration(SanitizedPath::new(&path), case_insensitive);
if registrations.lock().contains_key(&key) {
pending_registrations.lock().remove(path.as_ref());
return;
}
let register = {
let path = path.clone();
let tx = tx.clone();
let pending_path_events = pending_path_events.clone();
let fs = fs.clone();
let native_watcher = native_watcher.clone();
let poll_watcher = poll_watcher.clone();
move || {
register_existing_path(
&native_watcher,
&poll_watcher,
fs.as_ref(),
path,
case_insensitive,
tx,
pending_path_events,
)
}
};
let registration = if fs.is_fake() {
register()
} else {
smol::unblock(register).await
};
match registration {
Ok(Some(registration)) => {
{
let mut pending_registrations = pending_registrations.lock();
if pending_registrations.remove(path.as_ref()).is_none() {
registration.os_watcher.remove(registration.id);
return;
}
registrations.lock().insert(key, registration);
}
enqueue_path_events(
&tx,
&pending_path_events,
vec![
PathEvent {
path: path.to_path_buf(),
kind: Some(PathEventKind::Created),
},
PathEvent {
path: path.to_path_buf(),
kind: Some(PathEventKind::Rescan),
},
],
);
return;
}
Ok(None) => {}
Err(error) => {
log::warn!("failed to watch newly-created path {path:?}: {error}; retrying");
}
}
}
}
fn enqueue_path_events(
tx: &smol::channel::Sender<()>,
pending_path_events: &Arc<Mutex<Vec<PathEvent>>>,
mut path_events: Vec<PathEvent>,
) {
if path_events.is_empty() {
return;
}
path_events.sort();
let mut pending_paths = pending_path_events.lock();
if pending_paths.is_empty() {
tx.try_send(()).ok();
}
coalesce_pending_rescans(&mut pending_paths, &mut path_events);
util::extend_sorted(&mut *pending_paths, path_events, usize::MAX, |a, b| {
a.path.cmp(&b.path)
});
}
fn push_notify_event(
tx: &smol::channel::Sender<()>,
pending_path_events: &Arc<Mutex<Vec<PathEvent>>>,
root_path: &SanitizedPath,
case_insensitive: bool,
watched_root: &Path,
event: ¬ify::Event,
) {
let kind = match event.kind {
EventKind::Create(_) => Some(PathEventKind::Created),
EventKind::Modify(_) => Some(PathEventKind::Changed),
EventKind::Remove(_) => Some(PathEventKind::Removed),
_ => None,
};
let mut path_events = event
.paths
.iter()
.filter_map(|event_path| {
let event_path = SanitizedPath::new(event_path);
path_is_under(event_path, root_path, case_insensitive).then(|| PathEvent {
path: event_path.as_path().to_path_buf(),
kind,
})
})
.collect::<Vec<_>>();
if event.need_rescan() {
// A rescan event names the subtrees that lost sync (FSEvents
// `MustScanSubDirs`); only a pathless one (inotify queue overflow) means
// the whole watched root is suspect.
if path_events.is_empty() {
path_events.push(PathEvent {
path: watched_root.to_path_buf(),
kind: Some(PathEventKind::Rescan),
});
} else {
for path_event in &mut path_events {
path_event.kind = Some(PathEventKind::Rescan);
}
}
}
log::trace!("path_events: {:?}", path_events);
enqueue_path_events(tx, pending_path_events, path_events);
}
fn coalesce_pending_rescans(pending_paths: &mut Vec<PathEvent>, path_events: &mut Vec<PathEvent>) {
if !path_events
.iter()
.any(|event| event.kind == Some(PathEventKind::Rescan))
{
return;
}
let mut new_rescan_paths: Vec<std::path::PathBuf> = path_events
.iter()
.filter(|e| e.kind == Some(PathEventKind::Rescan))
.map(|e| e.path.clone())
.collect();
new_rescan_paths.sort_unstable();
let mut deduped_rescans: Vec<std::path::PathBuf> = Vec::with_capacity(new_rescan_paths.len());
for path in new_rescan_paths {
if deduped_rescans
.iter()
.any(|ancestor| path != *ancestor && path.starts_with(ancestor))
{
continue;
}
deduped_rescans.push(path);
}
deduped_rescans.retain(|new_path| {
!pending_paths
.iter()
.any(|pending| is_covered_rescan(pending.kind, new_path, &pending.path))
});
if !deduped_rescans.is_empty() {
pending_paths.retain(|pending| {
!deduped_rescans.iter().any(|rescan_path| {
pending.path == *rescan_path
|| is_covered_rescan(pending.kind, &pending.path, rescan_path)
})
});
}
path_events.retain(|event| {
event.kind != Some(PathEventKind::Rescan) || deduped_rescans.contains(&event.path)
});
}
fn path_depth(path: &SanitizedPath) -> usize {
path.as_path().components().count()
}
fn is_covered_rescan(kind: Option<PathEventKind>, path: &Path, ancestor: &Path) -> bool {
kind == Some(PathEventKind::Rescan) && path != ancestor && path.starts_with(ancestor)
}
#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash)]
pub struct WatcherRegistrationId(u32);
struct WatcherRegistrationState {
callback: Arc<dyn Fn(¬ify::Event) + Send + Sync>,
key: WatchKey,
}
struct PathRegistrationState {
path: Arc<SanitizedPath>,
/// Empty while a backend watch is retained for covered descendants that
/// could not get their own backend watch.
watcher_ids: Vec<WatcherRegistrationId>,
coverage: Coverage,
stale: bool,
}
enum Coverage {
/// Has its own backend watch. On recursive backends, that watch also
/// serves the descendant registrations listed here by [`path_depth`] and
/// key, so promotion proceeds shallowest first without re-sorting.
Watched {
covered: BTreeSet<(usize, WatchKey)>,
},
/// Served by the recursive backend watch of this ancestor registration.
CoveredBy(WatchKey),
}
/// The registered watch paths for one backend, keyed by [`WatchKey`] so that
/// add (dedup), remove, and dispatch share a single notion of path identity.
#[derive(Default)]
struct WatchPaths(HashMap<WatchKey, PathRegistrationState>);
impl WatchPaths {
fn contains(&self, key: &WatchKey) -> bool {
self.0.contains_key(key)
}
fn get_mut(&mut self, key: &WatchKey) -> Option<&mut PathRegistrationState> {
self.0.get_mut(key)
}
/// The nearest strict ancestor whose recursive backend watch covers `path`.
/// Only poll watches and native macOS/Windows watches are recursive.
fn covering_ancestor(&self, path: &SanitizedPath, recursive: bool) -> Option<WatchKey> {
if !recursive {
return None;
}
path.as_path().ancestors().skip(1).find_map(|ancestor| {
let ancestor = SanitizedPath::unchecked_new(ancestor);
[WatchKey::exact(ancestor), WatchKey::folded(ancestor)]
.into_iter()
.find(|key| {
self.0.get(key).is_some_and(|registration| {
matches!(registration.coverage, Coverage::Watched { .. })
})
})
})
}
fn covered_by_mut(&mut self, key: &WatchKey) -> Option<&mut BTreeSet<(usize, WatchKey)>> {
match &mut self.0.get_mut(key)?.coverage {
Coverage::Watched { covered } => Some(covered),
Coverage::CoveredBy(_) => None,
}
}
/// Collects the watcher ids of every registration whose directory is an
/// ancestor of (or equal to) `path`. Both exact and folded keys are probed,
/// so a real-cased event path matches a folded registration and vice versa.
fn watcher_ids_covering(&self, path: &SanitizedPath, ids: &mut Vec<WatcherRegistrationId>) {
for ancestor in path.as_path().ancestors() {
let ancestor = SanitizedPath::unchecked_new(ancestor);
if let Some(registration) = self.0.get(&WatchKey::exact(ancestor)) {
ids.extend_from_slice(®istration.watcher_ids);
}
if let Some(registration) = self.0.get(&WatchKey::folded(ancestor)) {
ids.extend_from_slice(®istration.watcher_ids);
}
}
}
}
struct WatcherState {
watchers: HashMap<WatcherRegistrationId, WatcherRegistrationState>,
paths: WatchPaths,
cooldown_until: Option<Instant>,
last_registration: WatcherRegistrationId,
}
impl WatcherState {
fn is_native_watch_limit_cooldown_active(&self) -> bool {
self.cooldown_until
.is_some_and(|cooldown_until| cooldown_until > Instant::now())
}
fn start_native_watch_limit_cooldown(&mut self, path: &Path) {
let should_log = !self.is_native_watch_limit_cooldown_active();
self.cooldown_until = Some(Instant::now() + *NATIVE_WATCH_LIMIT_COOLDOWN);
if should_log {
log::warn!(
"OS file watch limit reached while watching {path:?}; skipping new native file watcher registrations for {} seconds",
NATIVE_WATCH_LIMIT_COOLDOWN.as_secs()
);
}
}
}
pub(crate) trait WatchBackend: Send {
fn watch(&mut self, path: &Path, mode: notify::RecursiveMode) -> notify::Result<()>;
fn unwatch(&mut self, path: &Path) -> notify::Result<()>;
}
impl<T: notify::Watcher + Send> WatchBackend for T {
fn watch(&mut self, path: &Path, mode: notify::RecursiveMode) -> notify::Result<()> {
notify::Watcher::watch(self, path, mode)
}
fn unwatch(&mut self, path: &Path) -> notify::Result<()> {
notify::Watcher::unwatch(self, path)
}
}
pub struct OsWatcher {
kind: OsWatcherKind,
recursive: bool,
state: Arc<Mutex<WatcherState>>,
// Hold state across backend mutations. Callbacks don't acquire state or
// invert the lock order.
backend: Mutex<Option<Box<dyn WatchBackend>>>,
event_tx: async_channel::Sender<notify::Result<notify::Event>>,
_dispatch_task: Task<()>,
diagnostics: Arc<diagnostics::DiagnosticRecorder>,
// Closing the event channel can wake the dispatch task. Keep its scheduler
// alive through channel and task teardown, even when our owner drops first.
_executor: BackgroundExecutor,
}
impl OsWatcher {
/// Watches with notify's backend of `kind`, created lazily on first use so
/// that a failure to start it can be reported by `ensure_backend`.
pub fn new(kind: OsWatcherKind, executor: BackgroundExecutor) -> Arc<Self> {
Self::with_backend(kind, executor, None)
}
/// Watches with the given backend in place of notify's; `event_sink` is how
/// that backend reports events, standing in for notify's `EventHandler`.
pub(crate) fn with_backend(
kind: OsWatcherKind,
executor: BackgroundExecutor,
backend: Option<Box<dyn WatchBackend>>,
) -> Arc<Self> {
let (event_tx, event_rx) = async_channel::unbounded();
let state = Arc::new(Mutex::new(WatcherState {
watchers: Default::default(),
paths: Default::default(),
cooldown_until: None,
last_registration: Default::default(),
}));
let dispatch_task = executor.spawn({
let state = state.clone();
async move {
let mut rescan_history = diagnostics::RescanHistory::default();
while let Ok(first) = event_rx.recv().await {
dispatch_batch(kind, &state, &mut rescan_history, first, &event_rx);
}
}
});
Arc::new(Self {
kind,
recursive: kind.is_recursive(),
state,
backend: Mutex::new(backend),
event_tx,
_dispatch_task: dispatch_task,
diagnostics: Default::default(),
_executor: executor,
})
}
/// The callback a substitute backend uses to report events, standing
/// in for the `EventHandler` notify would have been constructed with.
pub(crate) fn event_sink(
&self,
) -> impl Fn(notify::Result<notify::Event>) + Send + Sync + 'static {
let event_tx = self.event_tx.clone();
let diagnostics = self.diagnostics.clone();
let kind = self.kind;
move |event| {
diagnostics.record(|| match &event {
Ok(event) => WatchDiagnosticEvent::from_notify_event(kind, event),
Err(error) => WatchDiagnosticEvent::new(
kind,
"error",
&error.paths,
format!("{error:?}"),
false,
),
});
enqueue(&event_tx, event);
}
}
pub(crate) fn is_recursive(&self) -> bool {
self.recursive
}
#[must_use]
fn add(
&self,
path: Arc<std::path::Path>,
case_insensitive: bool,
cb: impl Fn(¬ify::Event) + Send + Sync + 'static,
) -> anyhow::Result<Option<WatcherRegistrationId>> {
let path = SanitizedPath::from_arc(path);
let key = WatchKey::for_registration(&path, case_insensitive);
let mut state = self.state.lock();
let new_coverage = if state.paths.contains(&key) {
self.rewatch_if_stale(&mut state, &path, &key)?;
None
} else if let Some(ancestor) = state.paths.covering_ancestor(&path, self.recursive) {
Some(Coverage::CoveredBy(ancestor))
} else {
if self.kind == OsWatcherKind::Native && state.is_native_watch_limit_cooldown_active() {
self.diagnostics.record(|| {
WatchDiagnosticEvent::new(
self.kind,
"watch_skipped",
&[path.as_path().to_owned()],
"Native watch limit cooldown is active; registration will be retried"
.into(),
false,
)
});
return Ok(None);
}
match self.watch(path.as_path()) {
Ok(()) => {}
Err(error)
if self.kind == OsWatcherKind::Native && is_max_files_watch_error(&error) =>
{
state.start_native_watch_limit_cooldown(path.as_path());
return Ok(None);
}
Err(error) => return Err(error),
}
Some(Coverage::Watched {
covered: BTreeSet::new(),
})
};
let id = state.last_registration;
state.last_registration = WatcherRegistrationId(id.0 + 1);
let registration_state = WatcherRegistrationState {
callback: Arc::new(cb),
key: key.clone(),
};
state.watchers.insert(id, registration_state);
match new_coverage {
None => {
if let Some(registration) = state.paths.get_mut(&key) {
registration.watcher_ids.push(id);
}
}
Some(coverage) => {
if let Coverage::CoveredBy(ancestor) = &coverage
&& let Some(covered) = state.paths.covered_by_mut(ancestor)
{
covered.insert((path_depth(&path), key.clone()));
}
state.paths.0.insert(
key,
PathRegistrationState {
path,
watcher_ids: vec![id],
coverage,
stale: false,
},
);
}
}
Ok(Some(id))
}
fn rewatch_if_stale(
&self,
state: &mut WatcherState,
path: &SanitizedPath,
key: &WatchKey,
) -> anyhow::Result<()> {
let Some(path_state) = state.paths.get_mut(key) else {
return Ok(());
};
if !path_state.stale {
return Ok(());
}
log::trace!("rewatching stale path: {path:?}");
// A renamed directory's watch survives under the old path; unwatch it
// so the backend won't skip installation as a duplicate.
self.unwatch(path.as_path()).log_err();
self.watch(path.as_path())?;
path_state.stale = false;
Ok(())
}
#[cfg(test)]
fn dispatch(&self, event: notify::Result<notify::Event>) {
dispatch(self.kind, &self.state, event);
}
#[cfg(test)]
fn dispatch_batch(
&self,
first: notify::Result<notify::Event>,
event_rx: &async_channel::Receiver<notify::Result<notify::Event>>,
) {
dispatch_batch(
self.kind,
&self.state,
&mut diagnostics::RescanHistory::default(),
first,
event_rx,
);
}
pub fn remove(&self, id: WatcherRegistrationId) {
let mut state = self.state.lock();
let Some(registration) = state.watchers.remove(&id) else {
return;
};
let key = registration.key;
let Some(path_state) = state.paths.get_mut(&key) else {
return;
};
path_state.watcher_ids.retain(|&existing| existing != id);
if !path_state.watcher_ids.is_empty() {
return;
}
match &path_state.coverage {
Coverage::Watched { .. } => self.release_watch(&mut state, key),
Coverage::CoveredBy(ancestor) => {
let ancestor = ancestor.clone();
let covered_entry = (path_depth(&path_state.path), key);
state.paths.0.remove(&covered_entry.1);
let Some(ancestor_state) = state.paths.get_mut(&ancestor) else {
return;
};
let retained = ancestor_state.watcher_ids.is_empty();
let Coverage::Watched { covered } = &mut ancestor_state.coverage else {
return;
};
// A retained watch stopped at its shallowest covered registration,
// so only that registration leaving can unblock its release.
let blocked_release = covered.first() == Some(&covered_entry);
covered.remove(&covered_entry);
if retained && blocked_release {
self.release_watch(&mut state, ancestor);
}
}
}
}
/// Unwatches the unused backend watch at `key` once every registration it
/// covers is served by another watch.
///
/// Replacements are installed shallowest first, so one can cover deeper
/// registrations. If one cannot be installed, the watch is retained for
/// the registrations still covered by it, and is reconsidered when the one
/// that could not be promoted is removed.
fn release_watch(&self, state: &mut WatcherState, key: WatchKey) {
// Exclude this watch from coverage checks while it stays installed.
let Some(mut released) = state.paths.0.remove(&key) else {
return;
};
let mut pending = match &mut released.coverage {
Coverage::Watched { covered } => std::mem::take(covered),
Coverage::CoveredBy(_) => {
state.paths.0.insert(key, released);
return;
}
};
while let Some((depth, covered_key)) = pending.pop_first() {
let Some(covered_path) = state
.paths
.0
.get(&covered_key)
.map(|registration| registration.path.clone())
else {
continue;
};
let coverage = match state.paths.covering_ancestor(&covered_path, self.recursive) {
Some(ancestor) => {
if let Some(covered) = state.paths.covered_by_mut(&ancestor) {
covered.insert((depth, covered_key.clone()));
}
Coverage::CoveredBy(ancestor)
}
None if self.watch_replacement(state, &covered_path) => Coverage::Watched {
covered: BTreeSet::new(),
},
None => {
pending.insert((depth, covered_key));
released.coverage = Coverage::Watched { covered: pending };
state.paths.0.insert(key, released);
return;
}
};
if let Some(registration) = state.paths.get_mut(&covered_key) {
registration.coverage = coverage;
registration.stale = false;
}
}
// Forget the watch even if unwatching fails: notify can report failure
// after dropping the watch (FSEvents restarts its stream afterwards), so
// a later registration of this path must install a fresh watch.
self.unwatch(released.path.as_path()).log_err();
}
fn watch_replacement(&self, state: &mut WatcherState, path: &SanitizedPath) -> bool {
if self.kind == OsWatcherKind::Native && state.is_native_watch_limit_cooldown_active() {
return false;
}
match self.watch(path.as_path()) {
Ok(()) => true,
Err(error) => {
if self.kind == OsWatcherKind::Native && is_max_files_watch_error(&error) {
state.start_native_watch_limit_cooldown(path.as_path());
}
log::error!(
"failed to restore watch for {path:?}; retaining its covering watch: {error:#}"
);
false
}
}
}
fn watch(&self, path: &Path) -> anyhow::Result<()> {
self.ensure_backend()?;
let result = self
.backend
.lock()
.as_mut()
.expect("watcher backend initialized")
.watch(
path,
if self.recursive {
notify::RecursiveMode::Recursive
} else {
notify::RecursiveMode::NonRecursive
},
);
self.diagnostics.record(|| {
WatchDiagnosticEvent::new(
self.kind,
if result.is_ok() {
"watch"
} else {
"watch_error"
},
&[path.to_owned()],
match &result {
Ok(()) => format!("recursive={}", self.recursive),
Err(error) => format!("{error:?}"),
},
false,
)
});
result?;
Ok(())
}
fn unwatch(&self, path: &Path) -> anyhow::Result<()> {
let watcher = self
.backend
.lock()
.as_mut()
.map(|watcher| watcher.unwatch(path));
self.diagnostics.record(|| {
WatchDiagnosticEvent::new(
self.kind,
if matches!(&watcher, Some(Err(_))) {
"unwatch_error"
} else {
"unwatch"
},
&[path.to_owned()],
match &watcher {
Some(Err(error)) => format!("{error:?}"),
_ => String::new(),
},
false,
)
});
match watcher {
// inotify auto-removes a watch when its directory is deleted, so a
// later unwatch races that and fails with a benign error. Either way
// the path is no longer watched, which is all we wanted.
Some(Err(error)) if !matches!(error.kind, notify::ErrorKind::WatchNotFound) => {
Err(error.into())
}
_ => Ok(()),
}
}
pub(crate) fn ensure_backend(&self) -> anyhow::Result<()> {
// The lock is held across creation: with a check-then-insert under two
// separate lock acquisitions, concurrent callers could each create a
// watcher and the loser's insert would silently drop the winner's
// watcher along with every path registered on it.
let mut backend = self.backend.lock();
if backend.is_none() {
*backend = Some(match self.kind {
OsWatcherKind::Native => {
// CORE excludes Access events, which Zed discards anyway. Without this,
// the default mask subscribes to inotify OPEN/CLOSE_* on Linux, so every
// file read in a watched directory would queue events, increasing the
// risk of queue overflows (and thus full rescans) under read-heavy
// workloads like grep or language server indexing.
let config =
notify::Config::default().with_event_kinds(notify::EventKindMask::CORE);
Box::new(
<notify::RecommendedWatcher as notify::Watcher>::new(
self.event_sink(),
config,
)
.inspect_err(|error| self.record_backend_error(error))?,
)
}
OsWatcherKind::Poll => {
let config = notify::Config::default().with_poll_interval(*POLL_INTERVAL);
Box::new(
notify::PollWatcher::new(self.event_sink(), config)
.inspect_err(|error| self.record_backend_error(error))?,
)
}
});
}
Ok(())
}
fn record_backend_error(&self, error: ¬ify::Error) {
self.diagnostics.record(|| {
WatchDiagnosticEvent::new(
self.kind,
"backend_error",
&error.paths,
format!("{error:?}"),
false,
)
});
}
}
fn dispatch(
kind: OsWatcherKind,
state: &Mutex<WatcherState>,
event: notify::Result<notify::Event>,
) {
let event = match event {
Ok(event) => event,
Err(error) => {
log::warn!("{kind:?} watcher error: {error}");
return;
}
};
log::trace!("handle {kind:?} watcher event: {event:?}");
let callbacks = {
let mut state = state.lock();
// Invalidate before callbacks can trigger a scan.
if !kind.is_recursive() && event.need_rescan() {
// Overflow may have dropped removal events.
for path_state in state.paths.0.values_mut() {
path_state.stale = true;
}
} else if !kind.is_recursive()
&& matches!(
event.kind,
EventKind::Remove(_) | EventKind::Modify(notify::event::ModifyKind::Name(_))
)
{
for path in &event.paths {
let path = SanitizedPath::new(path);
for event_key in [WatchKey::exact(path), WatchKey::folded(path)] {
let Some(path_state) = state.paths.get_mut(&event_key) else {
continue;
};
path_state.stale = true;
if !matches!(event.kind, EventKind::Modify(_)) {
continue;
}
// Descendant watches follow the directory without their own rename events.
for (key, path_state) in &mut state.paths.0 {
let descendant = match (key, &event_key) {
(WatchKey::Exact(key), WatchKey::Exact(event_key)) => {
key.starts_with(event_key)
}
(WatchKey::Folded(key), WatchKey::Folded(event_key)) => {
Path::new(key.as_ref()).starts_with(Path::new(event_key.as_ref()))
}
_ => false,
};
if descendant {
path_state.stale = true;
}
}
}
}
}
if event.need_rescan() {
state
.watchers
.values()
.map(|registration| registration.callback.clone())
.collect::<Vec<_>>()
} else {
let mut ids = Vec::new();
for path in &event.paths {
let sanitized = SanitizedPath::new(path);
state.paths.watcher_ids_covering(sanitized, &mut ids);
}
ids.sort_unstable_by_key(|id| id.0);
ids.dedup();
ids.into_iter()
.filter_map(|id| state.watchers.get(&id))
.map(|registration| registration.callback.clone())
.collect::<Vec<_>>()
}
};
for callback in callbacks {
callback(&event);
}
}
fn dispatch_batch(
kind: OsWatcherKind,
state: &Mutex<WatcherState>,
rescan_history: &mut diagnostics::RescanHistory,
first: notify::Result<notify::Event>,
event_rx: &async_channel::Receiver<notify::Result<notify::Event>>,
) {
// A single backend overflow can enqueue many pathless rescan markers, each
// of which rescans every watched root, so one covers the entire
// drained batch. Rescans that name paths only cover those subtrees and are
// all dispatched; ordinary events still run.
let mut rescan_dispatched = false;
for event in std::iter::once(first).chain(std::iter::from_fn(|| event_rx.try_recv().ok())) {
if event
.as_ref()
.is_ok_and(|event| event.need_rescan() && event.paths.is_empty())
{
if rescan_dispatched {
continue;
}
rescan_dispatched = true;
}
// Log writes can block, so keep them off the native watcher reader.
if let Ok(event) = &event
&& let Some(report) = rescan_history.record(event)
{
log::error!("{kind:?} filesystem watcher requested rescan: {report}");
}
dispatch(kind, state, event);
}
}
fn enqueue(
event_tx: &async_channel::Sender<notify::Result<notify::Event>>,
event: notify::Result<notify::Event>,
) {
if matches!(
event,
Ok(Event {
kind: EventKind::Access(_),
..
})
) {
return;
}
// A failed send only happens once the dispatch thread has shut down, at
// which point there's nothing left to dispatch to.
event_tx.try_send(event).ok();
}
fn is_max_files_watch_error(error: &anyhow::Error) -> bool {
error
.downcast_ref::<notify::Error>()
.is_some_and(|error| matches!(&error.kind, notify::ErrorKind::MaxFilesWatch))
}
static POLL_INTERVAL: LazyLock<Duration> = LazyLock::new(|| {
let poll_ms: u64 = std::env::var("ZED_FILE_WATCHER_POLL_MS")
.ok()
.and_then(|value| value.parse().ok())
.unwrap_or(2000)
.clamp(500, 30000);
Duration::from_millis(poll_ms)
});
static NATIVE_WATCH_LIMIT_COOLDOWN: LazyLock<Duration> = LazyLock::new(|| {
let cooldown_seconds: u64 = std::env::var("ZED_NATIVE_WATCH_LIMIT_COOLDOWN_SECONDS")
.ok()
.and_then(|value| value.parse().ok())
.unwrap_or(5)
.clamp(0, 300);
Duration::from_secs(cooldown_seconds)
});
pub fn poll_interval() -> Duration {
*POLL_INTERVAL
}
#[cfg(test)]
mod tests {
use super::*;
use std::{collections::HashSet, path::PathBuf};
fn rescan(path: &str) -> PathEvent {
PathEvent {
path: PathBuf::from(path),
kind: Some(PathEventKind::Rescan),
}
}
fn changed(path: &str) -> PathEvent {
PathEvent {
path: PathBuf::from(path),
kind: Some(PathEventKind::Changed),
}
}
#[derive(Default)]
struct FakeWatchBackend {
watched_paths: HashSet<PathBuf>,
watch_calls: Vec<PathBuf>,
unwatch_calls: Vec<PathBuf>,
operations: Vec<(&'static str, PathBuf)>,
fail_with_watch_limit: bool,
failed_paths: HashSet<PathBuf>,
failed_unwatch_paths: HashSet<PathBuf>,
}
struct SharedFakeWatchBackend(Arc<Mutex<FakeWatchBackend>>);
impl WatchBackend for SharedFakeWatchBackend {
fn watch(&mut self, path: &Path, _mode: notify::RecursiveMode) -> notify::Result<()> {
let path = path.to_path_buf();
let mut backend = self.0.lock();
backend.watch_calls.push(path.clone());
backend.operations.push(("watch", path.clone()));
if backend.fail_with_watch_limit {
return Err(notify::Error::new(notify::ErrorKind::MaxFilesWatch));
}
if backend.failed_paths.contains(&path) {
return Err(notify::Error::generic("injected watch failure"));
}
backend.watched_paths.insert(path);
Ok(())
}
fn unwatch(&mut self, path: &Path) -> notify::Result<()> {
let path = path.to_path_buf();
let mut backend = self.0.lock();
backend.unwatch_calls.push(path.clone());
backend.operations.push(("unwatch", path.clone()));
if !backend.watched_paths.remove(&path) {
return Err(notify::Error::watch_not_found());
}
// Like FSEvents failing to restart its stream after removing the path.
if backend.failed_unwatch_paths.contains(&path) {
return Err(notify::Error::generic("injected unwatch failure"));
}
Ok(())
}
}
#[test]
fn watcher_retains_scheduler_until_teardown() {
let dispatcher = Arc::new(gpui::TestDispatcher::new(0));
let scheduler = Arc::downgrade(dispatcher.scheduler());
let executor = BackgroundExecutor::new(dispatcher.clone());
let watcher = OsWatcher::new(OsWatcherKind::Native, executor.clone());
executor.run_until_parked();
drop(executor);
drop(dispatcher);
assert!(scheduler.upgrade().is_some());
drop(watcher);
assert!(scheduler.upgrade().is_none());
}
fn test_os_watcher(
kind: OsWatcherKind,
backend: Option<Arc<Mutex<FakeWatchBackend>>>,
) -> OsWatcher {
// Tests call `dispatch` directly to exercise dispatch synchronously,
// rather than going through the OS watcher callbacks, so nothing is ever
// sent on this channel; the receiver can just be dropped.
let (event_tx, _event_rx) = async_channel::unbounded();
OsWatcher {
kind,
recursive: kind.is_recursive(),
state: Arc::new(Mutex::new(WatcherState {
watchers: Default::default(),
paths: Default::default(),
cooldown_until: None,
last_registration: Default::default(),
})),
backend: Mutex::new(
backend.map(|watcher| {
Box::new(SharedFakeWatchBackend(watcher)) as Box<dyn WatchBackend>
}),
),
event_tx,
_dispatch_task: Task::ready(()),
diagnostics: Default::default(),
_executor: BackgroundExecutor::new(Arc::new(gpui::TestDispatcher::new(0))),
}
}
struct TestCase {
name: &'static str,
pending_paths: Vec<PathEvent>,
path_events: Vec<PathEvent>,
expected_pending_paths: Vec<PathEvent>,
expected_path_events: Vec<PathEvent>,
}
#[test]
fn covered_child_registration_is_promoted_before_parent_is_unwatched() {
let backend = Arc::new(Mutex::new(FakeWatchBackend::default()));
let watcher = test_os_watcher(OsWatcherKind::Poll, Some(backend.clone()));
let parent = Arc::<Path>::from(Path::new("/repo"));
let child = Arc::<Path>::from(Path::new("/repo/foo.csproj"));
let parent_registration = watcher
.add(parent.as_ref().into(), false, |_| {})
.expect("add parent watch")
.expect("parent watch registered");
let child_registration = watcher
.add(child.as_ref().into(), false, |_| {})
.expect("add covered child watch")
.expect("child watch registered");
watcher.remove(parent_registration);
assert_eq!(
backend.lock().watched_paths,
HashSet::from([child.to_path_buf()])
);
assert_eq!(
backend.lock().operations,
[
("watch", parent.to_path_buf()),
("watch", child.to_path_buf()),
("unwatch", parent.to_path_buf()),
]
);
watcher.remove(child_registration);
let backend = backend.lock();
assert_eq!(
backend.watch_calls,
&[parent.to_path_buf(), child.to_path_buf()]
);
assert_eq!(
backend.unwatch_calls,
&[parent.to_path_buf(), child.to_path_buf()]
);
assert!(backend.watched_paths.is_empty());
assert!(watcher.state.lock().paths.0.is_empty());
}
#[test]
fn promoted_ancestor_covers_deeper_subscribers() {
let backend = Arc::new(Mutex::new(FakeWatchBackend::default()));
let watcher = test_os_watcher(OsWatcherKind::Poll, Some(backend.clone()));
let root = watcher
.add(Path::new("/repo").into(), true, |_| {})
.expect("watch root")
.expect("registered root");
// Several deeper subscribers make an unordered promotion unlikely to
// reach the shallowest one first by chance.
let deep = (0..8)
.map(|index| {
watcher
.add(
PathBuf::from(format!("/repo/child/deep{index}")).into(),
true,
|_| {},
)
.expect("watch deep")
.expect("registered deep")
})
.collect::<Vec<_>>();
let child = watcher
.add(Path::new("/repo/child").into(), true, |_| {})
.expect("watch child")
.expect("registered child");
watcher.remove(root);
assert_eq!(
backend.lock().watched_paths,
HashSet::from([PathBuf::from("/repo/child")])
);
assert_eq!(backend.lock().watch_calls.len(), 2);
watcher.remove(child);
assert_eq!(backend.lock().watched_paths.len(), deep.len());
for deep in deep {
watcher.remove(deep);
}
assert!(backend.lock().watched_paths.is_empty());
assert!(watcher.state.lock().paths.0.is_empty());
}
#[test]
fn failed_promotion_retains_coverage_without_retaining_removed_callback() {
let backend = Arc::new(Mutex::new(FakeWatchBackend::default()));
let watcher = test_os_watcher(OsWatcherKind::Poll, Some(backend.clone()));
let (parent_fired, parent_callback) = fired_count();
let (child_fired, child_callback) = fired_count();
let parent = watcher
.add(Path::new("/repo").into(), false, parent_callback)
.expect("watch parent")
.expect("registered parent");
let child = watcher
.add(Path::new("/repo/child").into(), false, child_callback)
.expect("watch child")
.expect("registered child");
backend
.lock()
.failed_paths
.insert(PathBuf::from("/repo/child"));
watcher.remove(parent);
assert_eq!(
backend.lock().watched_paths,
HashSet::from([PathBuf::from("/repo")])
);
watcher.dispatch(Ok(modify_event("/repo/child/file")));
assert_eq!(*parent_fired.lock(), 0);
assert_eq!(*child_fired.lock(), 1);
watcher.remove(child);
assert!(backend.lock().watched_paths.is_empty());
assert!(watcher.state.lock().paths.0.is_empty());
}
#[cfg(target_os = "macos")]
#[test]
fn native_child_delivery_survives_parent_removal() {
let directory = tempfile::tempdir().expect("temporary directory");
let root = directory.path().canonicalize().expect("canonical root");
let child = root.join("child");
std::fs::create_dir(&child).expect("create child");
let executor = BackgroundExecutor::new(Arc::new(gpui::TestDispatcher::new(0)));
let watcher = OsWatcher::new(OsWatcherKind::Native, executor.clone());
let parent = watcher
.add(root.as_path().into(), false, |_| {})
.expect("watch parent")
.expect("registered parent");
let (sender, receiver) = std::sync::mpsc::channel();
watcher
.add(child.as_path().into(), false, move |event| {
sender.send(event.clone()).expect("receiver alive");
})
.expect("watch child")
.expect("registered child");
std::thread::sleep(Duration::from_millis(500));
for phase in ["before", "after"] {
if phase == "after" {
watcher.remove(parent);
}
let file = child.join(phase);
std::fs::write(&file, b"probe").expect("write probe");
let deadline = Instant::now() + Duration::from_secs(5);
loop {
executor.run_until_parked();
if receiver.try_iter().any(|event| event.paths.contains(&file)) {
break;
}
assert!(Instant::now() < deadline, "missing {phase} event");
std::thread::sleep(Duration::from_millis(20));
}
}
}
#[test]
fn partial_promotion_releases_retained_parent_when_failed_subscriber_leaves() {
let backend = Arc::new(Mutex::new(FakeWatchBackend::default()));
let watcher = test_os_watcher(OsWatcherKind::Poll, Some(backend.clone()));
let registrations = [
"/repo",
"/repo/a",
"/repo/other/deep",
"/unrelated",
"/repo/other/deep/deeper",
]
.map(|path| {
watcher
.add(Path::new(path).into(), false, |_| {})
.expect("watch")
.expect("registered")
});
backend
.lock()
.failed_paths
.insert(PathBuf::from("/repo/other/deep"));
watcher.remove(registrations[0]);
assert_eq!(
backend.lock().watched_paths,
HashSet::from([
PathBuf::from("/repo"),
PathBuf::from("/repo/a"),
PathBuf::from("/unrelated")
])
);
// Only removing the registration that blocked promotion retries it.
let watch_calls = backend.lock().watch_calls.len();
watcher.remove(registrations[3]);
watcher.remove(registrations[1]);
watcher.remove(registrations[4]);
assert_eq!(backend.lock().watch_calls.len(), watch_calls);
assert_eq!(
backend.lock().watched_paths,
HashSet::from([PathBuf::from("/repo")])
);
watcher.remove(registrations[2]);
assert!(backend.lock().watched_paths.is_empty());
assert!(watcher.state.lock().paths.0.is_empty());
}
#[test]
fn failed_unwatch_is_not_trusted_when_path_is_registered_again() {
for kind in [OsWatcherKind::Native, OsWatcherKind::Poll] {
let backend = Arc::new(Mutex::new(FakeWatchBackend::default()));
let watcher = test_os_watcher(kind, Some(backend.clone()));
let path = PathBuf::from("/repo");
backend.lock().failed_unwatch_paths.insert(path.clone());
let registration = watcher
.add(path.as_path().into(), false, |_| {})
.expect("watch")
.expect("registered");
watcher.remove(registration);
assert!(backend.lock().watched_paths.is_empty());
assert!(watcher.state.lock().paths.0.is_empty());
let registration = watcher
.add(path.as_path().into(), false, |_| {})
.expect("watch again")
.expect("registered again");
assert_eq!(backend.lock().watch_calls, [path.clone(), path.clone()]);
assert_eq!(backend.lock().watched_paths, HashSet::from([path.clone()]));
// The backend already dropped this watch, as inotify does when a
// watched directory is deleted.
backend.lock().watched_paths.clear();
watcher.remove(registration);
assert!(watcher.state.lock().paths.0.is_empty());
}
}
#[gpui::test]
async fn pending_path_is_registered_once_created(cx: &mut gpui::TestAppContext) {
let temp_dir = tempfile::tempdir().expect("create temp dir");
let path = temp_dir.path().join("file.txt");
let (tx, rx) = async_channel::unbounded();
let pending_path_events: Arc<Mutex<Vec<PathEvent>>> = Default::default();
let watcher = FsWatcher::new(
OsWatcher::new(OsWatcherKind::Native, cx.executor()),
OsWatcher::new(OsWatcherKind::Poll, cx.executor()),
crate::RealFs::new(None, cx.executor()),
cx.executor(),
tx,
pending_path_events.clone(),
);
watcher
.add(&path)
.expect("add path that does not exist yet");
assert!(
watcher
.pending_registrations
.lock()
.contains_key(path.as_path())
);
assert!(watcher.registrations.lock().is_empty());
std::fs::write(&path, b"contents").expect("create path");
// poll_path_until_created stats the path on smol's blocking pool, which
// the deterministic executor cannot drive; park until the poll task
// signals the event channel.
cx.executor().allow_parking();
cx.executor().advance_clock(poll_interval());
rx.recv().await.expect("receive watcher event");
assert!(
!watcher
.pending_registrations
.lock()
.contains_key(path.as_path())
);
let case_insensitive = case_insensitive_path(&path);
let key = WatchKey::for_registration(SanitizedPath::new(&path), case_insensitive);
assert!(watcher.registrations.lock().contains_key(&key));
// poll_path_until_created also enqueues a Rescan for the same path, but
// enqueue_path_events -> util::extend_sorted dedups by path, so only Created survives.
assert_eq!(
pending_path_events.lock().clone(),
vec![PathEvent {
path: path.clone(),
kind: Some(PathEventKind::Created),
}]
);
}
#[test]
fn native_watch_limit_cools_down_subsequent_native_registrations() {
let native_backend = Arc::new(Mutex::new(FakeWatchBackend {
fail_with_watch_limit: true,
..Default::default()
}));
let watcher = test_os_watcher(OsWatcherKind::Native, Some(native_backend.clone()));
let first_path = Arc::<Path>::from(Path::new("/repo/first"));
let second_path = Arc::<Path>::from(Path::new("/repo/second"));
let first_registration = watcher
.add(first_path.clone(), false, |_| {})
.expect("native watch limit is handled");
let second_registration = watcher
.add(second_path, false, |_| {})
.expect("native watch limit backoff is handled");
assert!(first_registration.is_none());
assert!(second_registration.is_none());
let native_backend = native_backend.lock();
assert_eq!(native_backend.watch_calls, &[first_path.to_path_buf()]);
}
#[cfg(not(any(target_os = "windows", target_os = "macos")))]
#[test]
fn removed_or_renamed_path_is_rewatched_once() {
let dir = PathBuf::from("/Repo/Dir");
let subdir = PathBuf::from("/Repo/Dir/Subdir");
let removal = notify::Event {
paths: vec![dir.clone()],
..notify::Event::new(EventKind::Remove(notify::event::RemoveKind::Folder))
};
let overflow = notify::Event::new(EventKind::Other).set_flag(notify::event::Flag::Rescan);
let rename = |path: &str| notify::Event {
paths: vec![PathBuf::from(path)],
..notify::Event::new(EventKind::Modify(notify::event::ModifyKind::Name(
notify::event::RenameMode::From,
)))
};
for (event, case_insensitive, rewatched) in [
(removal, false, &dir),
(overflow, false, &dir),
(rename("/Repo/Dir"), false, &subdir),
(rename("/repo/dir"), true, &subdir),
] {
let backend = Arc::new(Mutex::new(FakeWatchBackend::default()));
let watcher = test_os_watcher(OsWatcherKind::Native, Some(backend.clone()));
for path in [&dir, &dir, &subdir] {
watcher
.add(path.as_path().into(), case_insensitive, |_| {})
.expect("add watch")
.expect("watch registered");
}
watcher.dispatch(Ok(event));
let rewatched = SanitizedPath::new(rewatched);
let key = WatchKey::for_registration(rewatched, case_insensitive);
watcher
.rewatch_if_stale(&mut watcher.state.lock(), rewatched, &key)
.expect("rewatch");
let backend = backend.lock();
assert_eq!(
backend.watch_calls,
&[
dir.clone(),
subdir.clone(),
rewatched.as_path().to_path_buf()
]
);
assert_eq!(backend.unwatch_calls, &[rewatched.as_path().to_path_buf()]);
}
}
fn modify_event(path: &str) -> notify::Event {
notify::Event {
paths: vec![PathBuf::from(path)],
..notify::Event::new(EventKind::Modify(notify::event::ModifyKind::Any))
}
}
fn recording_watcher() -> (OsWatcher, Arc<Mutex<Vec<String>>>) {
let backend = Arc::new(Mutex::new(FakeWatchBackend::default()));
let watcher = test_os_watcher(OsWatcherKind::Native, Some(backend));
let fired = Arc::new(Mutex::new(Vec::new()));
for dir in ["/repo/a", "/repo/a/nested", "/repo/b"] {
let fired = fired.clone();
let label = dir.to_owned();
watcher
.add(Arc::<Path>::from(Path::new(dir)), false, move |_| {
fired.lock().push(label.clone());
})
.expect("add watch")
.expect("watch registered");
}
(watcher, fired)
}
#[test]
fn event_dispatches_only_to_registrations_covering_its_path() {
let (watcher, fired) = recording_watcher();
watcher.dispatch(Ok(modify_event("/repo/a/file.txt")));
// Only the directory containing the file resolves; siblings stay untouched.
assert_eq!(*fired.lock(), vec!["/repo/a".to_owned()]);
}
#[test]
fn event_dispatches_to_every_ancestor_registration() {
let (watcher, fired) = recording_watcher();
watcher.dispatch(Ok(modify_event("/repo/a/nested/file.txt")));
// Both the directory containing the file and the ancestor watching it
// resync, each exactly once, matching the previous broadcast-and-filter
// behavior.
let mut got = fired.lock().clone();
got.sort();
assert_eq!(got, vec!["/repo/a".to_owned(), "/repo/a/nested".to_owned()]);
}
fn fired_count() -> (
Arc<Mutex<usize>>,
impl Fn(¬ify::Event) + Send + Sync + 'static,
) {
let fired = Arc::new(Mutex::new(0usize));
let cb = {
let fired = fired.clone();
move |_: ¬ify::Event| *fired.lock() += 1
};
(fired, cb)
}
#[test]
fn equivalent_path_spellings_share_watch_delivery_and_lifetime() {
for case_insensitive in [false, true] {
for spelling in ["/repo/project/", "/repo//project", "/repo/./project"] {
let backend = Arc::new(Mutex::new(FakeWatchBackend::default()));
let watcher = test_os_watcher(OsWatcherKind::Native, Some(backend.clone()));
let (first_fired, first_callback) = fired_count();
let first = watcher
.add(Path::new(spelling).into(), case_insensitive, first_callback)
.expect("add alternate spelling")
.expect("registered alternate spelling");
watcher.dispatch(Ok(modify_event("/repo/project/file.txt")));
assert_eq!(
*first_fired.lock(),
1,
"{spelling}, folded={case_insensitive}"
);
let (second_fired, second_callback) = fired_count();
let second = watcher
.add(
Path::new("/repo/project").into(),
case_insensitive,
second_callback,
)
.expect("add ordinary spelling")
.expect("registered ordinary spelling");
assert_eq!(backend.lock().watch_calls.len(), 1);
watcher.dispatch(Ok(modify_event("/repo/project/file.txt")));
assert_eq!(*first_fired.lock(), 2);
assert_eq!(*second_fired.lock(), 1);
watcher.remove(first);
assert!(backend.lock().unwatch_calls.is_empty());
watcher.dispatch(Ok(modify_event("/repo/project/file.txt")));
assert_eq!(*first_fired.lock(), 2);
assert_eq!(*second_fired.lock(), 2);
watcher.remove(second);
assert_eq!(backend.lock().unwatch_calls.len(), 1);
assert!(backend.lock().watched_paths.is_empty());
}
}
}
#[test]
fn folded_keys_preserve_root_and_parent_component_identity() {
for path in ["/", "/repo/../project", "./project", "project"] {
let ordinary = Path::new(path);
let with_separator = PathBuf::from(format!("{path}/"));
assert_eq!(ordinary, with_separator);
assert_eq!(
WatchKey::folded(SanitizedPath::new(ordinary)),
WatchKey::folded(SanitizedPath::new(&with_separator)),
);
}
for (left, right) in [
("/", ""),
("/repo/../project", "/project"),
("./project", "project"),
] {
assert_ne!(
WatchKey::folded(SanitizedPath::new(Path::new(left))),
WatchKey::folded(SanitizedPath::new(Path::new(right))),
);
}
}
#[test]
fn watch_key_folds_case_but_keeps_exact_distinct() {
let mixed = SanitizedPath::new(Path::new("/Repo/Proj"));
let lower = SanitizedPath::new(Path::new("/repo/proj"));
// Folded keys collide regardless of casing; exact keys do not.
assert_eq!(WatchKey::folded(mixed), WatchKey::folded(lower));
assert_ne!(WatchKey::exact(mixed), WatchKey::exact(lower));
// Exact and folded live in different key spaces even for the same path.
assert_ne!(WatchKey::exact(mixed), WatchKey::folded(mixed));
}
#[cfg(target_os = "macos")]
#[test]
fn watch_key_folds_unicode_normalization_on_macos() {
// "Café" precomposed (NFC) vs decomposed (NFD) are different byte
// sequences but the same directory on a normalization-insensitive volume.
let nfc = Path::new("/repo/Caf\u{00e9}");
let nfd = Path::new("/repo/Cafe\u{0301}");
assert_ne!(nfc, nfd);
assert_eq!(
WatchKey::folded(SanitizedPath::new(nfc)),
WatchKey::folded(SanitizedPath::new(nfd)),
);
}
#[test]
fn case_insensitive_registration_matches_differently_cased_event() {
let (fired, cb) = fired_count();
let watcher = test_os_watcher(OsWatcherKind::Native, Some(Default::default()));
watcher
.add(Path::new("/Repo/Project").into(), true, cb)
.expect("add")
.expect("registered");
// Event arrives lowercased (as TSGO/macOS may report it).
watcher.dispatch(Ok(modify_event("/repo/project/file.txt")));
assert_eq!(*fired.lock(), 1);
}
#[test]
fn case_insensitive_registration_survives_case_only_rename() {
let (fired, cb) = fired_count();
let watcher = test_os_watcher(OsWatcherKind::Native, Some(Default::default()));
watcher
.add(Path::new("/Repo/Proj").into(), true, cb)
.expect("add")
.expect("registered");
// The watched directory was renamed to a different casing; events now
// arrive under the new spelling.
watcher.dispatch(Ok(modify_event("/Repo/PROJ/file.txt")));
assert_eq!(*fired.lock(), 1);
}
#[test]
fn case_sensitive_registration_ignores_differently_cased_event() {
let (fired, cb) = fired_count();
let watcher = test_os_watcher(OsWatcherKind::Native, Some(Default::default()));
watcher
.add(Path::new("/Repo/proj").into(), false, cb)
.expect("add")
.expect("registered");
// On a case-sensitive volume these are genuinely different directories.
watcher.dispatch(Ok(modify_event("/Repo/PROJ/file.txt")));
assert_eq!(*fired.lock(), 0);
}
#[test]
fn differently_cased_adds_dedupe_on_case_insensitive_volume() {
let backend = Arc::new(Mutex::new(FakeWatchBackend::default()));
let watcher = test_os_watcher(OsWatcherKind::Native, Some(backend.clone()));
watcher
.add(Path::new("/Repo/Proj").into(), true, |_| {})
.expect("add")
.expect("registered");
watcher
.add(Path::new("/repo/proj").into(), true, |_| {})
.expect("add")
.expect("registered");
// The second, differently-cased spelling reuses the same OS watch.
assert_eq!(backend.lock().watch_calls.len(), 1);
}
#[test]
fn recursive_parent_covers_differently_cased_child() {
let backend = Arc::new(Mutex::new(FakeWatchBackend::default()));
let watcher = test_os_watcher(OsWatcherKind::Poll, Some(backend.clone()));
watcher
.add(Path::new("/Repo").into(), true, |_| {})
.expect("add")
.expect("registered");
watcher
.add(Path::new("/repo/child").into(), true, |_| {})
.expect("add");
// The child is covered by the recursive parent despite the case mismatch.
assert_eq!(backend.lock().watch_calls, vec![PathBuf::from("/Repo")]);
}
#[test]
fn rescan_event_broadcasts_to_all_registrations_of_the_same_backend() {
let (watcher, fired) = recording_watcher();
let rescan = notify::Event::new(EventKind::Other).set_flag(notify::event::Flag::Rescan);
watcher.dispatch(Ok(rescan));
// A pathless rescan may have missed events anywhere, so every registration
// of that backend resyncs, regardless of which directory it watches.
let mut got = fired.lock().clone();
got.sort();
assert_eq!(
got,
vec![
"/repo/a".to_owned(),
"/repo/a/nested".to_owned(),
"/repo/b".to_owned(),
]
);
}
#[test]
fn queued_rescans_are_coalesced_without_dropping_normal_events() {
let (watcher, fired) = recording_watcher();
let (event_tx, event_rx) = async_channel::unbounded();
let rescan = || notify::Event::new(EventKind::Other).set_flag(notify::event::Flag::Rescan);
event_tx.try_send(Ok(rescan())).unwrap();
event_tx
.try_send(Ok(modify_event("/repo/a/file.txt")))
.unwrap();
watcher.dispatch_batch(Ok(rescan()), &event_rx);
let mut got = fired.lock().clone();
got.sort();
assert_eq!(
got,
vec![
"/repo/a".to_owned(),
"/repo/a".to_owned(),
"/repo/a/nested".to_owned(),
"/repo/b".to_owned(),
]
);
}
#[test]
fn queued_rescans_naming_distinct_paths_are_all_dispatched() {
let (watcher, fired) = recording_watcher();
let (event_tx, event_rx) = async_channel::unbounded();
let rescan_of = |path: &str| {
notify::Event::new(EventKind::Other)
.set_flag(notify::event::Flag::Rescan)
.add_path(PathBuf::from(path))
};
event_tx.try_send(Ok(rescan_of("/repo/b"))).unwrap();
watcher.dispatch_batch(Ok(rescan_of("/repo/a/nested")), &event_rx);
// Each named rescan only covers its own subtree once it reaches the
// callbacks, so collapsing the second one would lose /repo/b's resync.
// Both are broadcast to every registration of the backend.
let mut got = fired.lock().clone();
got.sort();
assert_eq!(
got,
vec![
"/repo/a".to_owned(),
"/repo/a".to_owned(),
"/repo/a/nested".to_owned(),
"/repo/a/nested".to_owned(),
"/repo/b".to_owned(),
"/repo/b".to_owned(),
]
);
}
#[test]
#[cfg(target_os = "windows")]
fn event_dispatches_when_reported_path_has_verbatim_prefix() {
// `notify` (and Windows APIs generally) can report a changed path using the
// verbatim `\\?\` long-path form even when the directory was registered
// without it.
let backend = Arc::new(Mutex::new(FakeWatchBackend::default()));
let watcher = test_os_watcher(OsWatcherKind::Native, Some(backend));
let fired = Arc::new(Mutex::new(Vec::new()));
{
let fired = fired.clone();
watcher
.add(
Arc::<Path>::from(Path::new("C:\\repo\\src")),
false,
move |_| fired.lock().push(()),
)
.expect("add watch")
.expect("watch registered");
}
watcher.dispatch(Ok(modify_event("\\\\?\\C:\\repo\\src\\main.rs")));
assert_eq!(fired.lock().len(), 1);
}
#[test]
fn test_coalesce_pending_rescans() {
let test_cases = [
TestCase {
name: "coalesces descendant rescans under pending ancestor",
pending_paths: vec![rescan("/root")],
path_events: vec![rescan("/root/child"), rescan("/root/child/grandchild")],
expected_pending_paths: vec![rescan("/root")],
expected_path_events: vec![],
},
TestCase {
name: "new ancestor rescan replaces pending descendant rescans",
pending_paths: vec![
changed("/other"),
rescan("/root/child"),
rescan("/root/child/grandchild"),
],
path_events: vec![rescan("/root")],
expected_pending_paths: vec![changed("/other")],
expected_path_events: vec![rescan("/root")],
},
TestCase {
name: "same path rescan replaces pending non-rescan event",
pending_paths: vec![changed("/root")],
path_events: vec![rescan("/root")],
expected_pending_paths: vec![],
expected_path_events: vec![rescan("/root")],
},
TestCase {
name: "unrelated rescans are preserved",
pending_paths: vec![rescan("/root-a")],
path_events: vec![rescan("/root-b")],
expected_pending_paths: vec![rescan("/root-a")],
expected_path_events: vec![rescan("/root-b")],
},
TestCase {
name: "batch ancestor rescan replaces descendant rescan",
pending_paths: vec![],
path_events: vec![rescan("/root/child"), rescan("/root")],
expected_pending_paths: vec![],
expected_path_events: vec![rescan("/root")],
},
];
for test_case in test_cases {
let mut pending_paths = test_case.pending_paths;
let mut path_events = test_case.path_events;
coalesce_pending_rescans(&mut pending_paths, &mut path_events);
assert_eq!(
pending_paths, test_case.expected_pending_paths,
"pending_paths mismatch for case: {}",
test_case.name
);
assert_eq!(
path_events, test_case.expected_path_events,
"path_events mismatch for case: {}",
test_case.name
);
}
}
}