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
75pub struct Watcher {
77 inner: Mutex<notify::RecommendedWatcher>,
78 roots: Arc<Mutex<Vec<PathBuf>>>,
79}
80
81impl Watcher {
82 pub fn start(roots: Vec<PathBuf>, tx: mpsc::Sender<PathBuf>) -> Result<Watcher> {
84 let known = Arc::new(Mutex::new(roots.clone()));
85 let pending: Arc<Mutex<Pending>> = Arc::new(Mutex::new(Pending::default()));
86
87 {
89 let pending = Arc::clone(&pending);
90 tokio::spawn(async move {
91 let mut ticker = tokio::time::interval(DEBOUNCE / 3);
92 loop {
93 ticker.tick().await;
94 let ready = pending.lock().expect("pending").take_ready(Instant::now());
95 for root in ready {
96 if tx.send(root).await.is_err() {
97 return;
98 }
99 }
100 }
101 });
102 }
103
104 let handler_roots = Arc::clone(&known);
105 let handler_pending = Arc::clone(&pending);
106 let mut watcher =
107 notify::recommended_watcher(move |event: notify::Result<notify::Event>| {
108 let Ok(event) = event else { return };
109 let roots = handler_roots.lock().expect("roots").clone();
110 for path in event.paths {
111 if let Some(root) = roots.iter().find(|r| path.starts_with(r)) {
115 handler_pending.lock().expect("pending").note(
116 root,
117 &event.kind,
118 Instant::now(),
119 );
120 }
121 }
122 })
123 .map_err(|e| Error::Sync(e.to_string()))?;
124
125 for root in &roots {
126 if let Err(err) = watcher.watch(root, RecursiveMode::Recursive) {
129 tracing::warn!(root = %root.display(), "could not watch: {err}");
130 }
131 }
132
133 Ok(Watcher {
134 inner: Mutex::new(watcher),
135 roots: known,
136 })
137 }
138
139 pub fn watch(&self, root: &Path) -> Result<()> {
141 self.roots.lock().expect("roots").push(root.to_owned());
142 self.inner
143 .lock()
144 .expect("watcher")
145 .watch(root, RecursiveMode::Recursive)
146 .map_err(|e| Error::Sync(e.to_string()))
147 }
148
149 pub fn unwatch(&self, root: &Path) {
151 self.roots.lock().expect("roots").retain(|r| r != root);
152 let _ = self.inner.lock().expect("watcher").unwatch(root);
153 }
154}
155
156#[cfg(test)]
157mod tests {
158 use super::*;
159
160 async fn recv(rx: &mut tokio::sync::mpsc::Receiver<PathBuf>) -> Option<PathBuf> {
161 tokio::time::timeout(std::time::Duration::from_secs(5), rx.recv())
162 .await
163 .ok()
164 .flatten()
165 }
166
167 fn access() -> notify::EventKind {
168 notify::EventKind::Access(notify::event::AccessKind::Open(
169 notify::event::AccessMode::Any,
170 ))
171 }
172
173 fn modify() -> notify::EventKind {
174 notify::EventKind::Modify(notify::event::ModifyKind::Data(
175 notify::event::DataChange::Any,
176 ))
177 }
178
179 #[test]
183 fn an_access_event_does_not_make_a_root_due() {
184 let root = Path::new("/ws");
185 let t0 = Instant::now();
186 let mut pending = Pending::default();
187
188 pending.note(root, &access(), t0);
189
190 assert!(
191 pending.take_ready(t0 + DEBOUNCE * 10).is_empty(),
192 "a read must not be reported as an edit"
193 );
194 }
195
196 #[test]
200 fn a_steady_stream_of_changes_is_still_reported() {
201 let root = Path::new("/ws");
202 let t0 = Instant::now();
203 let mut pending = Pending::default();
204 let step = DEBOUNCE / 2;
205
206 let mut reported_at = None;
207 for n in 0..20 {
208 let now = t0 + step * n;
209 pending.note(root, &modify(), now);
210 if !pending.take_ready(now).is_empty() {
211 reported_at = Some(now - t0);
212 break;
213 }
214 }
215 let reported_at = reported_at.expect("the root was never reported");
216 assert!(
219 reported_at <= MAX_DEBOUNCE + step,
220 "reported only after {reported_at:?}"
221 );
222 }
223
224 #[cfg(target_os = "linux")]
228 #[tokio::test(flavor = "multi_thread")]
229 async fn reading_a_file_is_not_reported() {
230 let tmp = tempfile::tempdir().unwrap();
231 let root = tmp.path().join("ws");
232 std::fs::create_dir_all(&root).unwrap();
233 std::fs::write(root.join("note.md"), "content").unwrap();
234
235 let (tx, mut rx) = tokio::sync::mpsc::channel(16);
236 let _watcher = Watcher::start(vec![root.clone()], tx).unwrap();
237 tokio::time::sleep(DEBOUNCE * 2).await;
239 while rx.try_recv().is_ok() {}
240
241 let _ = std::fs::read_to_string(root.join("note.md")).unwrap();
242 let reported = tokio::time::timeout(DEBOUNCE * 3, rx.recv()).await;
243 assert!(reported.is_err(), "a read was reported: {reported:?}");
244 }
245
246 #[tokio::test(flavor = "multi_thread")]
247 async fn a_file_created_outside_the_server_is_reported() {
248 let tmp = tempfile::tempdir().unwrap();
249 let root = tmp.path().join("ws");
250 std::fs::create_dir_all(&root).unwrap();
251
252 let (tx, mut rx) = tokio::sync::mpsc::channel(16);
253 let _watcher = Watcher::start(vec![root.clone()], tx).unwrap();
254
255 std::fs::write(root.join("new.md"), "content").unwrap();
256 assert_eq!(recv(&mut rx).await.as_deref(), Some(root.as_path()));
257 }
258
259 #[tokio::test(flavor = "multi_thread")]
260 async fn a_burst_of_writes_produces_one_report() {
261 let tmp = tempfile::tempdir().unwrap();
262 let root = tmp.path().join("ws");
263 std::fs::create_dir_all(&root).unwrap();
264
265 let (tx, mut rx) = tokio::sync::mpsc::channel(64);
266 let _watcher = Watcher::start(vec![root.clone()], tx).unwrap();
267
268 for n in 0..20 {
269 std::fs::write(root.join(format!("f{n}.md")), "x").unwrap();
270 }
271 assert!(recv(&mut rx).await.is_some());
272
273 let extra = tokio::time::timeout(DEBOUNCE * 3, rx.recv()).await;
275 assert!(
276 extra.is_err(),
277 "the burst should have coalesced, got {extra:?}"
278 );
279 }
280
281 #[tokio::test(flavor = "multi_thread")]
282 async fn events_inside_the_marker_directory_are_reported_too() {
283 let tmp = tempfile::tempdir().unwrap();
284 let root = tmp.path().join("ws");
285 std::fs::create_dir_all(root.join(".test-app")).unwrap();
286
287 let (tx, mut rx) = tokio::sync::mpsc::channel(16);
288 let _watcher = Watcher::start(vec![root.clone()], tx).unwrap();
289
290 std::fs::write(root.join(".test-app").join("config.toml"), "x = 1").unwrap();
291 assert!(
292 recv(&mut rx).await.is_some(),
293 "the marker directory holds sync-id and config, which are synced"
294 );
295 }
296
297 #[tokio::test(flavor = "multi_thread")]
298 async fn a_watched_root_that_disappears_does_not_kill_the_watcher() {
299 let tmp = tempfile::tempdir().unwrap();
300 let going = tmp.path().join("going");
301 let staying = tmp.path().join("staying");
302 std::fs::create_dir_all(&going).unwrap();
303 std::fs::create_dir_all(&staying).unwrap();
304
305 let (tx, mut rx) = tokio::sync::mpsc::channel(16);
306 let _watcher = Watcher::start(vec![going.clone(), staying.clone()], tx).unwrap();
307
308 std::fs::remove_dir_all(&going).unwrap();
309 tokio::time::sleep(DEBOUNCE * 2).await;
310 while rx.try_recv().is_ok() {}
311
312 std::fs::write(staying.join("still-here.md"), "x").unwrap();
313 assert_eq!(
314 recv(&mut rx).await.as_deref(),
315 Some(staying.as_path()),
316 "one lost root must not stop the others being watched"
317 );
318 }
319
320 #[tokio::test(flavor = "multi_thread")]
321 async fn a_root_added_later_is_watched() {
322 let tmp = tempfile::tempdir().unwrap();
323 let first = tmp.path().join("first");
324 let second = tmp.path().join("second");
325 std::fs::create_dir_all(&first).unwrap();
326 std::fs::create_dir_all(&second).unwrap();
327
328 let (tx, mut rx) = tokio::sync::mpsc::channel(16);
329 let watcher = Watcher::start(vec![first], tx).unwrap();
330 watcher.watch(&second).unwrap();
331
332 std::fs::write(second.join("a.md"), "x").unwrap();
333 assert_eq!(recv(&mut rx).await.as_deref(), Some(second.as_path()));
334 }
335}