sapphire_framework_server/sync/
watch.rs1use std::collections::HashMap;
4use std::path::{Path, PathBuf};
5use std::sync::{Arc, Mutex};
6use std::time::{Duration, Instant};
7
8use notify::{RecursiveMode, Watcher as _};
9use tokio::sync::mpsc;
10
11use crate::error::{Error, Result};
12
13pub const DEBOUNCE: Duration = Duration::from_millis(300);
15
16pub const MAX_DEBOUNCE: Duration = Duration::from_secs(1);
19
20#[derive(Debug, Default)]
25struct Pending {
26 roots: HashMap<PathBuf, Window>,
27}
28
29#[derive(Debug)]
31struct Window {
32 first: Instant,
33 last: Instant,
34}
35
36impl Pending {
37 fn note(&mut self, root: &Path, kind: ¬ify::EventKind, now: Instant) {
44 if matches!(kind, notify::EventKind::Access(_)) {
45 return;
46 }
47 self.roots
48 .entry(root.to_owned())
49 .and_modify(|window| window.last = now)
50 .or_insert(Window {
51 first: now,
52 last: now,
53 });
54 }
55
56 fn take_ready(&mut self, now: Instant) -> Vec<PathBuf> {
59 let ready: Vec<PathBuf> = self
60 .roots
61 .iter()
62 .filter(|(_, window)| {
63 now.duration_since(window.last) >= DEBOUNCE
64 || now.duration_since(window.first) >= MAX_DEBOUNCE
65 })
66 .map(|(root, _)| root.clone())
67 .collect();
68 for root in &ready {
69 self.roots.remove(root);
70 }
71 ready
72 }
73}
74
75#[derive(Debug)]
82struct Root {
83 path: PathBuf,
84 resolved: PathBuf,
85}
86
87impl Root {
88 fn new(path: &Path) -> Root {
89 Root {
90 path: path.to_owned(),
91 resolved: std::fs::canonicalize(path).unwrap_or_else(|_| path.to_owned()),
92 }
93 }
94
95 fn contains(&self, path: &Path) -> bool {
96 path.starts_with(&self.path) || path.starts_with(&self.resolved)
97 }
98}
99
100pub struct Watcher {
102 inner: Mutex<notify::RecommendedWatcher>,
103 roots: Arc<Mutex<Vec<Root>>>,
104}
105
106impl Watcher {
107 pub fn start(roots: Vec<PathBuf>, tx: mpsc::Sender<PathBuf>) -> Result<Watcher> {
109 let known: Arc<Mutex<Vec<Root>>> =
110 Arc::new(Mutex::new(roots.iter().map(|r| Root::new(r)).collect()));
111 let pending: Arc<Mutex<Pending>> = Arc::new(Mutex::new(Pending::default()));
112
113 {
115 let pending = Arc::clone(&pending);
116 tokio::spawn(async move {
117 let mut ticker = tokio::time::interval(DEBOUNCE / 3);
118 loop {
119 ticker.tick().await;
120 let ready = pending.lock().expect("pending").take_ready(Instant::now());
121 for root in ready {
122 if tx.send(root).await.is_err() {
123 return;
124 }
125 }
126 }
127 });
128 }
129
130 let handler_roots = Arc::clone(&known);
131 let handler_pending = Arc::clone(&pending);
132 let mut watcher =
133 notify::recommended_watcher(move |event: notify::Result<notify::Event>| {
134 let Ok(event) = event else { return };
135 let roots = handler_roots.lock().expect("roots");
136 for path in event.paths {
137 if let Some(root) = roots.iter().find(|r| r.contains(&path)) {
141 handler_pending.lock().expect("pending").note(
142 &root.path,
143 &event.kind,
144 Instant::now(),
145 );
146 }
147 }
148 })
149 .map_err(|e| Error::Sync(e.to_string()))?;
150
151 for root in &roots {
152 if let Err(err) = watcher.watch(root, RecursiveMode::Recursive) {
155 tracing::warn!(root = %root.display(), "could not watch: {err}");
156 }
157 }
158
159 Ok(Watcher {
160 inner: Mutex::new(watcher),
161 roots: known,
162 })
163 }
164
165 pub fn watch(&self, root: &Path) -> Result<()> {
167 self.roots.lock().expect("roots").push(Root::new(root));
168 self.inner
169 .lock()
170 .expect("watcher")
171 .watch(root, RecursiveMode::Recursive)
172 .map_err(|e| Error::Sync(e.to_string()))
173 }
174
175 pub fn unwatch(&self, root: &Path) {
177 self.roots.lock().expect("roots").retain(|r| r.path != root);
178 let _ = self.inner.lock().expect("watcher").unwatch(root);
179 }
180}
181
182#[cfg(test)]
183mod tests {
184 use super::*;
185
186 async fn recv(rx: &mut tokio::sync::mpsc::Receiver<PathBuf>) -> Option<PathBuf> {
187 tokio::time::timeout(std::time::Duration::from_secs(5), rx.recv())
188 .await
189 .ok()
190 .flatten()
191 }
192
193 fn access() -> notify::EventKind {
194 notify::EventKind::Access(notify::event::AccessKind::Open(
195 notify::event::AccessMode::Any,
196 ))
197 }
198
199 fn modify() -> notify::EventKind {
200 notify::EventKind::Modify(notify::event::ModifyKind::Data(
201 notify::event::DataChange::Any,
202 ))
203 }
204
205 #[test]
209 fn an_access_event_does_not_make_a_root_due() {
210 let root = Path::new("/ws");
211 let t0 = Instant::now();
212 let mut pending = Pending::default();
213
214 pending.note(root, &access(), t0);
215
216 assert!(
217 pending.take_ready(t0 + DEBOUNCE * 10).is_empty(),
218 "a read must not be reported as an edit"
219 );
220 }
221
222 #[test]
226 fn a_steady_stream_of_changes_is_still_reported() {
227 let root = Path::new("/ws");
228 let t0 = Instant::now();
229 let mut pending = Pending::default();
230 let step = DEBOUNCE / 2;
231
232 let mut reported_at = None;
233 for n in 0..20 {
234 let now = t0 + step * n;
235 pending.note(root, &modify(), now);
236 if !pending.take_ready(now).is_empty() {
237 reported_at = Some(now - t0);
238 break;
239 }
240 }
241 let reported_at = reported_at.expect("the root was never reported");
242 assert!(
245 reported_at <= MAX_DEBOUNCE + step,
246 "reported only after {reported_at:?}"
247 );
248 }
249
250 #[cfg(target_os = "linux")]
254 #[tokio::test(flavor = "multi_thread")]
255 async fn reading_a_file_is_not_reported() {
256 let tmp = tempfile::tempdir().unwrap();
257 let root = tmp.path().join("ws");
258 std::fs::create_dir_all(&root).unwrap();
259 std::fs::write(root.join("note.md"), "content").unwrap();
260
261 let (tx, mut rx) = tokio::sync::mpsc::channel(16);
262 let _watcher = Watcher::start(vec![root.clone()], tx).unwrap();
263 tokio::time::sleep(DEBOUNCE * 2).await;
265 while rx.try_recv().is_ok() {}
266
267 let _ = std::fs::read_to_string(root.join("note.md")).unwrap();
268 let reported = tokio::time::timeout(DEBOUNCE * 3, rx.recv()).await;
269 assert!(reported.is_err(), "a read was reported: {reported:?}");
270 }
271
272 #[tokio::test(flavor = "multi_thread")]
273 async fn a_file_created_outside_the_server_is_reported() {
274 let tmp = tempfile::tempdir().unwrap();
275 let root = tmp.path().join("ws");
276 std::fs::create_dir_all(&root).unwrap();
277
278 let (tx, mut rx) = tokio::sync::mpsc::channel(16);
279 let _watcher = Watcher::start(vec![root.clone()], tx).unwrap();
280
281 std::fs::write(root.join("new.md"), "content").unwrap();
282 assert_eq!(recv(&mut rx).await.as_deref(), Some(root.as_path()));
283 }
284
285 #[tokio::test(flavor = "multi_thread")]
286 async fn a_burst_of_writes_produces_one_report() {
287 let tmp = tempfile::tempdir().unwrap();
288 let root = tmp.path().join("ws");
289 std::fs::create_dir_all(&root).unwrap();
290
291 let (tx, mut rx) = tokio::sync::mpsc::channel(64);
292 let _watcher = Watcher::start(vec![root.clone()], tx).unwrap();
293
294 for n in 0..20 {
295 std::fs::write(root.join(format!("f{n}.md")), "x").unwrap();
296 }
297 assert!(recv(&mut rx).await.is_some());
298
299 let extra = tokio::time::timeout(DEBOUNCE * 3, rx.recv()).await;
301 assert!(
302 extra.is_err(),
303 "the burst should have coalesced, got {extra:?}"
304 );
305 }
306
307 #[tokio::test(flavor = "multi_thread")]
308 async fn events_inside_the_marker_directory_are_reported_too() {
309 let tmp = tempfile::tempdir().unwrap();
310 let root = tmp.path().join("ws");
311 std::fs::create_dir_all(root.join(".test-app")).unwrap();
312
313 let (tx, mut rx) = tokio::sync::mpsc::channel(16);
314 let _watcher = Watcher::start(vec![root.clone()], tx).unwrap();
315
316 std::fs::write(root.join(".test-app").join("config.toml"), "x = 1").unwrap();
317 assert!(
318 recv(&mut rx).await.is_some(),
319 "the marker directory holds sync-id and config, which are synced"
320 );
321 }
322
323 #[tokio::test(flavor = "multi_thread")]
324 async fn a_watched_root_that_disappears_does_not_kill_the_watcher() {
325 let tmp = tempfile::tempdir().unwrap();
326 let going = tmp.path().join("going");
327 let staying = tmp.path().join("staying");
328 std::fs::create_dir_all(&going).unwrap();
329 std::fs::create_dir_all(&staying).unwrap();
330
331 let (tx, mut rx) = tokio::sync::mpsc::channel(16);
332 let _watcher = Watcher::start(vec![going.clone(), staying.clone()], tx).unwrap();
333
334 std::fs::remove_dir_all(&going).unwrap();
335 tokio::time::sleep(DEBOUNCE * 2).await;
336 while rx.try_recv().is_ok() {}
337
338 std::fs::write(staying.join("still-here.md"), "x").unwrap();
339 assert_eq!(
340 recv(&mut rx).await.as_deref(),
341 Some(staying.as_path()),
342 "one lost root must not stop the others being watched"
343 );
344 }
345
346 #[tokio::test(flavor = "multi_thread")]
347 async fn a_root_added_later_is_watched() {
348 let tmp = tempfile::tempdir().unwrap();
349 let first = tmp.path().join("first");
350 let second = tmp.path().join("second");
351 std::fs::create_dir_all(&first).unwrap();
352 std::fs::create_dir_all(&second).unwrap();
353
354 let (tx, mut rx) = tokio::sync::mpsc::channel(16);
355 let watcher = Watcher::start(vec![first], tx).unwrap();
356 watcher.watch(&second).unwrap();
357
358 std::fs::write(second.join("a.md"), "x").unwrap();
359 assert_eq!(recv(&mut rx).await.as_deref(), Some(second.as_path()));
360 }
361}