use core::fmt;
use core::time::Duration;
use std::path::{Path, PathBuf};
use notify::{RecommendedWatcher, RecursiveMode};
use notify_debouncer_full::{DebounceEventResult, Debouncer, RecommendedCache, new_debouncer};
use tokio::sync::mpsc;
#[derive(Debug)]
pub struct WatchSource {
_debouncer: Debouncer<RecommendedWatcher, RecommendedCache>,
}
pub fn watch_tree(
root: &Path,
delay: Duration,
) -> Result<(WatchSource, mpsc::UnboundedReceiver<WatchBatch>), WatchError> {
let resolved = std::fs::canonicalize(root).map_err(|err| WatchError::Watch {
path: root.to_path_buf(),
reason: err.to_string(),
})?;
let root = resolved.as_path();
let (tx, rx) = mpsc::unbounded_channel();
let watched_root = root.to_path_buf();
let mut debouncer = new_debouncer(delay, None, move |result: DebounceEventResult| {
forward_batch(result, &watched_root, &tx);
})
.map_err(|err| WatchError::Backend {
reason: render_reason(&err),
})?;
debouncer
.watch(root, RecursiveMode::Recursive)
.map_err(|err| WatchError::Watch {
path: root.to_path_buf(),
reason: render_reason(&err),
})?;
Ok((
WatchSource {
_debouncer: debouncer,
},
rx,
))
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WatchBatch {
pub paths: Vec<PathBuf>,
pub rescan: bool,
}
fn forward_batch(result: DebounceEventResult, root: &Path, tx: &mpsc::UnboundedSender<WatchBatch>) {
match result {
Ok(events) => {
let mut paths: Vec<PathBuf> = Vec::new();
let mut rescan = false;
for debounced in events {
rescan |= debounced.event.need_rescan();
paths.extend(debounced.event.paths);
}
let _ = tx.send(WatchBatch { paths, rescan });
}
Err(errors) => {
for err in errors {
tracing::warn!(
root = %root.display(),
%err,
"filesystem watch error"
);
}
}
}
}
fn render_reason(err: ¬ify::Error) -> String {
let rendered = err.to_string();
match rendered.split_once(" about [") {
Some((message, _)) => message.to_string(),
None => rendered,
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum WatchError {
Backend {
reason: String,
},
Watch {
path: PathBuf,
reason: String,
},
}
impl fmt::Display for WatchError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Backend { reason } => {
write!(f, "could not create a filesystem watcher: {reason}")
}
Self::Watch { path, reason } => {
write!(f, "could not watch `{}`: {reason}", path.display())
}
}
}
}
impl core::error::Error for WatchError {}
#[cfg(test)]
mod tests {
use core::time::Duration;
use std::path::PathBuf;
use std::time::Instant;
use notify::event::{Flag, ModifyKind};
use notify::{Event, EventKind};
use notify_debouncer_full::DebouncedEvent;
use tokio::sync::mpsc::UnboundedReceiver;
use tokio::time::timeout;
use super::*;
use crate::watch::real_time::{NO_EVENT_WINDOW, SMOKE_DEADLINE, TEST_DELAY};
const _: () = assert!(
NO_EVENT_WINDOW.as_millis() >= TEST_DELAY.as_millis() * 4,
"NO_EVENT_WINDOW must stay at least 4x TEST_DELAY, or a quiet window \
proves nothing about a debounced event that has not landed yet"
);
fn canonical_root(dir: &tempfile::TempDir) -> PathBuf {
dir.path()
.canonicalize()
.expect("canonicalize tempdir root")
}
async fn batches_until(
rx: &mut UnboundedReceiver<WatchBatch>,
within: Duration,
wanted_desc: &str,
wanted: impl Fn(&WatchBatch) -> bool,
) -> Vec<WatchBatch> {
let deadline = Instant::now() + within;
let mut seen = Vec::new();
loop {
let remaining = deadline.saturating_duration_since(Instant::now());
match timeout(remaining, rx.recv()).await {
Ok(Some(batch)) => {
let matched = wanted(&batch);
seen.push(batch);
if matched {
return seen;
}
}
Ok(None) => {
panic!("watch source ended before {wanted_desc} arrived; got {seen:?}")
}
Err(_) => {
panic!("no batch carried {wanted_desc} within the deadline; got {seen:?}")
}
}
}
}
#[test]
fn a_rescan_marker_is_forwarded_as_a_rescan_rather_than_as_a_path() {
let root = PathBuf::from("/watched");
let (tx, mut rx) = mpsc::unbounded_channel();
let rescan = Event::new(EventKind::Other).set_flag(Flag::Rescan);
forward_batch(
Ok(vec![DebouncedEvent::new(rescan, Instant::now())]),
&root,
&tx,
);
assert_eq!(
rx.try_recv().expect("a rescan marker must produce a batch"),
WatchBatch {
paths: Vec::new(),
rescan: true,
}
);
let changed = root.join("src/main.rs");
let modified = Event::new(EventKind::Modify(ModifyKind::Any)).add_path(changed.clone());
forward_batch(
Ok(vec![DebouncedEvent::new(modified, Instant::now())]),
&root,
&tx,
);
assert_eq!(
rx.try_recv().expect("a path batch must be forwarded"),
WatchBatch {
paths: vec![changed],
rescan: false,
}
);
}
#[test]
fn a_rescan_marker_that_carries_a_path_is_still_a_rescan() {
let root = PathBuf::from("/watched");
let (tx, mut rx) = mpsc::unbounded_channel();
let rescan = Event::new(EventKind::Other)
.add_path(root.clone())
.set_flag(Flag::Rescan);
let changed = root.join("src/main.rs");
let modified = Event::new(EventKind::Modify(ModifyKind::Any)).add_path(changed.clone());
forward_batch(
Ok(vec![
DebouncedEvent::new(modified, Instant::now()),
DebouncedEvent::new(rescan, Instant::now()),
]),
&root,
&tx,
);
assert_eq!(
rx.try_recv().expect("a rescan marker must produce a batch"),
WatchBatch {
paths: vec![changed, root],
rescan: true,
}
);
}
const HOLD_TEST_DELAY: Duration = Duration::from_secs(1);
#[tokio::test]
async fn a_nonexistent_root_returns_a_watch_error_naming_the_path() {
let dir = tempfile::tempdir().unwrap();
let root = dir.path().join("does-not-exist");
let err = watch_tree(&root, TEST_DELAY).expect_err("a nonexistent root must fail to watch");
let WatchError::Watch { path, reason } = err else {
panic!("expected WatchError::Watch, got {err:?}");
};
assert_eq!(path, root);
assert!(!reason.is_empty(), "reason must not be empty");
assert!(
!reason.contains(" about ["),
"reason must not carry notify's own redundant path clause: {reason:?}"
);
}
#[test]
fn watch_error_display_does_not_repeat_the_path() {
let backend = WatchError::Backend {
reason: "boom".to_string(),
};
assert_eq!(
backend.to_string(),
"could not create a filesystem watcher: boom"
);
let watch = WatchError::Watch {
path: PathBuf::from("/x"),
reason: "No path was found.".to_string(),
};
assert_eq!(
watch.to_string(),
"could not watch `/x`: No path was found."
);
let _: &dyn core::error::Error = &backend;
let _: &dyn core::error::Error = &watch;
}
mod slow {
use super::*;
#[tokio::test]
async fn a_file_created_under_the_root_produces_a_batch_containing_it() {
let dir = tempfile::tempdir().unwrap();
let root = canonical_root(&dir);
let (_source, mut rx) = watch_tree(&root, TEST_DELAY).unwrap();
let file = root.join("created.txt");
std::fs::write(&file, b"hello").unwrap();
batches_until(&mut rx, SMOKE_DEADLINE, &format!("{file:?}"), |batch| {
batch.paths.contains(&file)
})
.await;
}
#[tokio::test]
async fn a_file_created_in_a_nested_subdirectory_also_produces_a_batch() {
let dir = tempfile::tempdir().unwrap();
let root = canonical_root(&dir);
let nested = root.join("a").join("b");
std::fs::create_dir_all(&nested).unwrap();
let (_source, mut rx) = watch_tree(&root, TEST_DELAY).unwrap();
let file = nested.join("created.txt");
std::fs::write(&file, b"hello").unwrap();
batches_until(&mut rx, SMOKE_DEADLINE, &format!("{file:?}"), |batch| {
batch.paths.contains(&file)
})
.await;
}
#[tokio::test]
async fn dropping_the_source_stops_delivery() {
let dir = tempfile::tempdir().unwrap();
let root = canonical_root(&dir);
let (source, mut rx) = watch_tree(&root, TEST_DELAY).unwrap();
let first = root.join("first.txt");
std::fs::write(&first, b"hello").unwrap();
batches_until(&mut rx, SMOKE_DEADLINE, &format!("{first:?}"), |batch| {
batch.paths.contains(&first)
})
.await;
drop(source);
let deadline = Instant::now() + SMOKE_DEADLINE;
loop {
let remaining = deadline.saturating_duration_since(Instant::now());
match timeout(remaining, rx.recv()).await {
Ok(None) => break,
Ok(Some(_)) => continue,
Err(_) => panic!(
"the watcher thread outlived its WatchSource by {SMOKE_DEADLINE:?}: \
the debouncer guard leaked"
),
}
}
}
#[tokio::test]
async fn writes_separated_by_more_than_delay_produce_two_batches() {
let dir = tempfile::tempdir().unwrap();
let root = canonical_root(&dir);
let (_source, mut rx) = watch_tree(&root, TEST_DELAY).unwrap();
let first = crate::testing::touch(&root, "first.txt").unwrap();
tokio::time::sleep(TEST_DELAY * 4).await;
let second = crate::testing::touch(&root, "second.txt").unwrap();
let batches = batches_until(&mut rx, SMOKE_DEADLINE, &format!("{second:?}"), |batch| {
batch.paths.contains(&second)
})
.await;
assert!(
!batches
.iter()
.any(|b| b.paths.contains(&first) && b.paths.contains(&second)),
"the two writes coalesced into one batch despite the gap \
exceeding `delay` — got {batches:?}"
);
assert!(
batches.iter().any(|b| b.paths.contains(&first)),
"expected {first:?} in an earlier batch than {second:?}, got {batches:?}"
);
}
#[tokio::test]
async fn no_batch_arrives_before_delay_has_elapsed() {
let dir = tempfile::tempdir().unwrap();
let root = canonical_root(&dir);
let (_source, mut rx) = watch_tree(&root, HOLD_TEST_DELAY).unwrap();
let started = Instant::now();
let file = crate::testing::touch(&root, "first.txt").unwrap();
let batches = batches_until(&mut rx, HOLD_TEST_DELAY * 4, &format!("{file:?}"), |b| {
b.paths.contains(&file)
})
.await;
assert!(
started.elapsed() >= HOLD_TEST_DELAY,
"a batch arrived after {:?}, inside `delay` ({HOLD_TEST_DELAY:?}) -- \
got {batches:?}",
started.elapsed()
);
}
#[tokio::test]
async fn a_path_deleted_while_watched_still_produces_a_batch() {
let dir = tempfile::tempdir().unwrap();
let root = canonical_root(&dir);
let file = crate::testing::touch(&root, "doomed.txt").unwrap();
let (_source, mut rx) = watch_tree(&root, TEST_DELAY).unwrap();
std::fs::remove_file(&file).unwrap();
batches_until(&mut rx, SMOKE_DEADLINE, &format!("{file:?}"), |batch| {
batch.paths.contains(&file)
})
.await;
}
#[cfg(unix)]
#[tokio::test]
async fn a_symlinked_root_delivers_the_resolved_path_not_the_one_passed_in() {
let target = tempfile::tempdir().unwrap();
let resolved_target = canonical_root(&target);
let link_parent = tempfile::tempdir().unwrap();
let link = link_parent.path().join("link-to-target");
std::os::unix::fs::symlink(&resolved_target, &link).unwrap();
let (_source, mut rx) = watch_tree(&link, TEST_DELAY).unwrap();
crate::testing::touch(&link, "through-the-link.txt").unwrap();
let resolved_file = resolved_target.join("through-the-link.txt");
let batches = batches_until(
&mut rx,
SMOKE_DEADLINE,
&format!("{resolved_file:?}"),
|batch| batch.paths.contains(&resolved_file),
)
.await;
for batch in &batches {
assert!(
!batch.paths.iter().any(|p| p.starts_with(&link)),
"expected no path under the symlink itself, got {batch:?}"
);
}
}
}
}