Skip to main content

sapphire_framework_server/sync/
watch.rs

1//! Noticing edits the app server did not make.
2
3use 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
13/// How long events are coalesced before a root is reported.
14pub const DEBOUNCE: Duration = Duration::from_millis(300);
15
16/// The longest a root waits for quiet: one that keeps changing is reported this long
17/// after its first unreported event anyway.
18pub const MAX_DEBOUNCE: Duration = Duration::from_secs(1);
19
20/// The roots with unreported events, and when each one's events arrived.
21///
22/// Kept apart from the `notify` callback and the ticker so the decision — which events
23/// count, and when a root is due — can be tested with made-up events and instants.
24#[derive(Debug, Default)]
25struct Pending {
26    roots: HashMap<PathBuf, Window>,
27}
28
29/// When one root's unreported events began, and when the latest arrived.
30#[derive(Debug)]
31struct Window {
32    first: Instant,
33    last: Instant,
34}
35
36impl Pending {
37    /// Record an event of `kind` under `root` at `now`.
38    ///
39    /// Access events are dropped: opening or closing a file changes nothing, and inotify
40    /// reports every one — including the opens of the scan this report triggers, which
41    /// would otherwise schedule the next scan, and the next, for as long as the server
42    /// runs. A write shows up as `Create` or `Modify` regardless.
43    fn note(&mut self, root: &Path, kind: &notify::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    /// Take every root that is due at `now`: quiet for [`DEBOUNCE`], or waiting
57    /// [`MAX_DEBOUNCE`] since its first event however busy it still is.
58    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/// A watched root, as the caller named it and as the OS may report it.
76///
77/// FSEvents (macOS) reports events under the resolved path: a root under `/var/...`
78/// sees its events arrive as `/private/var/...`. Matching only the name given would
79/// drop every event under a root reached through a symlink, so both forms are kept;
80/// the root is still reported under the name it was given.
81#[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
100/// Watches workspace roots and reports which one changed.
101pub struct Watcher {
102    inner: Mutex<notify::RecommendedWatcher>,
103    roots: Arc<Mutex<Vec<Root>>>,
104}
105
106impl Watcher {
107    /// Start watching `roots`, reporting on `tx`.
108    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        // The debounce timer: report a root once it is due (see [`Pending::take_ready`]).
114        {
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                    // Attribute the event to the root it happened under. Nothing is filtered
138                    // by path here: what is synced is `SyncFilter`'s decision, made later on
139                    // content — the marker directory holds sync-id and config, which sync.
140                    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            // A root that cannot be watched is logged, not fatal: the others must keep
153            // working, and the next `scan` will pick this one up anyway.
154            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    /// Start watching one more root.
166    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    /// Stop watching one root.
176    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    /// Opening a file is not a change. inotify reports every open, and a scan opens
206    /// every file: counting those made each scan schedule the next one, so an idle
207    /// workspace was rescanned forever (issue #179).
208    #[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    /// A steady stream of changes must not postpone the report for ever: the debounce
223    /// waits for quiet, but only up to a bound. Without one, a host receiving a peer's
224    /// files held back its own edit until the stream stopped (issue #179).
225    #[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        // Checked once per `step`, so the first check at or past the bound may be up to
243        // one step late.
244        assert!(
245            reported_at <= MAX_DEBOUNCE + step,
246            "reported only after {reported_at:?}"
247        );
248    }
249
250    /// The real-filesystem half of [`an_access_event_does_not_make_a_root_due`]. Linux
251    /// only: inotify is the backend that reports opens; on Windows and macOS a read raises
252    /// no event at all, so the test could not fail there.
253    #[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        // Anything the setup itself raised has been reported and drained.
264        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        // Nothing more within another debounce window plus slack.
300        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}