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/// Watches workspace roots and reports which one changed.
76pub struct Watcher {
77    inner: Mutex<notify::RecommendedWatcher>,
78    roots: Arc<Mutex<Vec<PathBuf>>>,
79}
80
81impl Watcher {
82    /// Start watching `roots`, reporting on `tx`.
83    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        // The debounce timer: report a root once it is due (see [`Pending::take_ready`]).
88        {
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                    // Attribute the event to the root it happened under. Nothing is filtered
112                    // by path here: what is synced is `SyncFilter`'s decision, made later on
113                    // content — the marker directory holds sync-id and config, which sync.
114                    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            // A root that cannot be watched is logged, not fatal: the others must keep
127            // working, and the next `scan` will pick this one up anyway.
128            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    /// Start watching one more root.
140    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    /// Stop watching one root.
150    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    /// Opening a file is not a change. inotify reports every open, and a scan opens
180    /// every file: counting those made each scan schedule the next one, so an idle
181    /// workspace was rescanned forever (issue #179).
182    #[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    /// A steady stream of changes must not postpone the report for ever: the debounce
197    /// waits for quiet, but only up to a bound. Without one, a host receiving a peer's
198    /// files held back its own edit until the stream stopped (issue #179).
199    #[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        // Checked once per `step`, so the first check at or past the bound may be up to
217        // one step late.
218        assert!(
219            reported_at <= MAX_DEBOUNCE + step,
220            "reported only after {reported_at:?}"
221        );
222    }
223
224    /// The real-filesystem half of [`an_access_event_does_not_make_a_root_due`]. Linux
225    /// only: inotify is the backend that reports opens; on Windows and macOS a read raises
226    /// no event at all, so the test could not fail there.
227    #[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        // Anything the setup itself raised has been reported and drained.
238        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        // Nothing more within another debounce window plus slack.
274        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}