1//! The sections of an open notebook that no session holds, kept in sync as OneNote 2010
2//! keeps every section of an open notebook: queued edits publish and other clients' changes
3//! are noticed without the section being open.
4
5use crate::fs;
6use crate::{
7 EditStatus, Error, Remote, Replica, Result,
8 discover::{Entry, Listed},
9 session::{Observed, Section, SyncStatus, reached, sync_status},
10 worker::Signal,
11};
12use onestore::Stamp;
13use std::{
14 collections::{BTreeMap, BTreeSet},
15 io,
16 path::{Path, PathBuf},
17 sync::{
18 Arc, Mutex, Weak,
19 atomic::{AtomicBool, Ordering},
20 },
21 time::Duration,
22};
23use web_time::Instant;
24
25/// How long a section that could not be reached waits to be tried again; OneNote 2010
26/// retries a failing section about every 31 seconds.
27const RETRY: Duration = Duration::from_secs(31);
28/// Between one section's first check and the next's, so opening a notebook reads its files
29/// one after another rather than in a burst.
30const STAGGER: Duration = Duration::from_millis(100);
31
32/// How soon a section whose replica another holder had is checked again.
33const HELD: Duration = Duration::from_secs(1);
34
35/// How long a reported change settles before its section is checked, so the writes of one
36/// commit cost one check.
37const SETTLE: Duration = Duration::from_secs(1);
38
39/// Keeps each watched section in sync: a section is checked when a watch on the notebook's
40/// folder reports it changed, when it could not be reached, and otherwise every interval.
41/// On connecting, and when a watch reports a folder rather than a file, the folders are
42/// listed and only the sections listed otherwise than before are checked, as OneNote 2010
43/// reopens a notebook. A check costs one stamp read; a section whose replica has edits waiting,
44/// or whose file moved past the replica's base, has its replica opened for the synchronization
45/// steps that publish or rebase it, then closed again. A section without a replica gets one,
46/// its offline copy, where the notebook keeps them. A section a session holds is left to that
47/// session's worker, which the watch wakes. Dropping requests cancellation without waiting for
48/// the step in flight.
49pub struct Background(Arc<Shared>, Mutex<Option<crate::task::JoinHandle<()>>>);
50
51/// A section for `Background::watch`, as its notebook knows it.
52pub struct Known {
53 /// The catalog path.
54 pub path: String,
55 pub replica: Option<PathBuf>,
56 /// How the notebook's discovery last found the file: its listing, and its stamp then.
57 pub found: Option<(Listed, Stamp)>,
58 /// The file as that discovery read it, if it did, which the first check takes in place
59 /// of reading the file again while its stamp still matches.
60 pub image: Option<Vec<u8>>,
61}
62
63/// What the background thread and whatever reports changes to it share.
64pub(crate) struct Shared {
65 signal: Arc<Signal>,
66 watched: Mutex<Watched>,
67 /// Asked for by `discard`, once the thread stops.
68 discard: AtomicBool,
69 /// Hears every report of changed paths (`on_touched`).
70 listener: Mutex<Option<Listener>>,
71}
72
73/// Hears the catalog paths a report names.
74pub type Listener = Box<dyn Fn(&[String]) + Send + Sync>;
75
76/// A connection's report of its notebook folder's changes, from a watch armed on connecting.
77#[cfg_attr(not(any(feature = "smb", feature = "live")), allow(dead_code))]
78pub(crate) struct Reports {
79 shared: Weak<Shared>,
80 connection: u64,
81}
82
83#[derive(Default)]
84struct Watched {
85 sections: Vec<Watch>,
86 /// Sections or cached folders changed since `changed` was last asked.
87 changed: Vec<String>,
88 /// Folders a watch reported without naming the file, listed at `relist`.
89 folders: BTreeSet<String>,
90 relist: Option<Instant>,
91 /// Counts connections, so a watch that ended with an earlier one is not this one's.
92 connection: u64,
93 /// The current connection's watch ended, or none was connected: changes since went
94 /// unreported.
95 lost: bool,
96 /// The current connection's watch reports the folder's changes.
97 reported: bool,
98 /// How long a report settles, where not `SETTLE` (`Background::set_settle`).
99 settle: Option<Duration>,
100}
101
102struct Watch {
103 path: String,
104 replica: Option<PathBuf>,
105 /// The file's stamp when last read.
106 stamp: Option<Stamp>,
107 /// How the file was listed when its folder was last listed; the stamp was read since.
108 listed: Option<Listed>,
109 /// The folder's listing since `stamp` shows the file unchanged, so the next check need not
110 /// read it.
111 current: bool,
112 /// A watch reported the file changed since its folder's listing began.
113 reported: bool,
114 status: SyncStatus,
115 /// The file as discovery read it, until the next check takes it.
116 image: Option<Vec<u8>>,
117 /// When the section is next checked.
118 due: Instant,
119 held: Option<Held>,
120}
121
122#[derive(Clone)]
123struct Held {
124 worker: Weak<Signal>,
125 replica: Weak<Replica>,
126 observed: Weak<Mutex<Observed>>,
127}
128
129impl Background {
130 /// How often each section is checked while a watch reports its folder's changes, against
131 /// a report that went missing; OneNote 2010, watching, checks nothing on a timer.
132 pub const BACKSTOP: Duration = Duration::from_secs(60 * 60);
133 /// How often each section is checked where nothing reports its folder's changes.
134 pub const UNWATCHED: Duration = Duration::from_secs(15);
135
136 /// Starts the thread. `connect` answers how the connection reaches each section file and
137 /// lists each folder, both by catalog path, arming any watch that reports the folder's
138 /// changes through `Reports`, and whether one does; it runs again after a transport
139 /// failure. `copies` keeps an offline copy of every section.
140 pub(crate) fn start<R, B, L, LF>(
141 copies: bool,
142 mut connect: impl FnMut(Reports) -> io::Result<((B, L), bool)> + Send + 'static,
143 notify: impl Fn() + Send + 'static,
144 ) -> Result<Self>
145 where
146 R: Remote,
147 B: FnMut(&str, Option<&Path>) -> R,
148 L: FnMut(String) -> LF,
149 LF: Future<Output = io::Result<Vec<Entry>>>,
150 {
151 let (signal, receiver) = Signal::new();
152 let shared = Arc::new(Shared {
153 signal,
154 watched: Mutex::default(),
155 discard: AtomicBool::new(false),
156 listener: Mutex::default(),
157 });
158 let weak = Arc::downgrade(&shared);
159 let owner = Arc::clone(&shared);
160 let thread = crate::task::spawn("onestore-background", move || async move {
161 let signal = &owner.signal;
162 let mut bound: Option<(B, L)> = None;
163 let mut news = false;
164 while !signal.stopped.load(Ordering::Acquire) {
165 if signal.offline.load(Ordering::Acquire)
166 && !signal.requested.load(Ordering::Acquire)
167 {
168 // Working online again lists every folder again.
169 if let Ok(mut watched) = owner.watched.lock() {
170 watched.watching(false);
171 watched.lost = true;
172 }
173 bound = None;
174 crate::task::wait(&receiver, None).await;
175 continue;
176 }
177 let now = Instant::now();
178 let next = {
179 let Ok(mut watched) = owner.watched.lock() else {
180 return;
181 };
182 if std::mem::take(&mut watched.lost) {
183 bound = None;
184 watched.watching(false);
185 for watch in &mut watched.sections {
186 watch.due = now;
187 }
188 }
189 watched.next(now, bound.is_some())
190 };
191 let (path, replica, seen, current, image) = match next {
192 Next::Wait(wait) => {
193 signal.requested.store(false, Ordering::Release);
194 if std::mem::take(&mut news) {
195 notify();
196 }
197 crate::task::wait(&receiver, wait).await;
198 continue;
199 }
200 Next::Connect(connection) => {
201 let reports = Reports {
202 shared: weak.clone(),
203 connection: connection + 1,
204 };
205 let connected = connect(reports);
206 let folders = {
207 let Ok(mut watched) = owner.watched.lock() else {
208 return;
209 };
210 watched.connection += 1;
211 watched.lost = false;
212 match &connected {
213 Ok((_, reported)) => {
214 watched.watching(*reported);
215 Some(watched.rescanning())
216 }
217 Err(error) => {
218 let error = Error::RemoteIo(io::Error::new(
219 error.kind(),
220 error.to_string(),
221 ));
222 let retry = now + RETRY;
223 for watch in &mut watched.sections {
224 news |= watch.fail(&error, None);
225 watch.due = watch.due.max(retry);
226 }
227 watched.relist = watched.relist.map(|due| due.max(retry));
228 None
229 }
230 }
231 };
232 if let (Ok((mut files, _)), Some(folders)) = (connected, folders) {
233 let listings = list(&mut files.1, folders).await;
234 let Ok(mut watched) = owner.watched.lock() else {
235 return;
236 };
237 watched.listed(&listings, Some(copies), Instant::now());
238 bound = Some(files);
239 }
240 continue;
241 }
242 Next::List(folders) => {
243 let Some((_, list_folder)) = &mut bound else {
244 continue;
245 };
246 let listings = list(list_folder, folders).await;
247 let Ok(mut watched) = owner.watched.lock() else {
248 return;
249 };
250 watched.listed(&listings, None, Instant::now());
251 continue;
252 }
253 Next::Check {
254 path,
255 replica,
256 seen,
257 current,
258 image,
259 } => (path, replica, seen, current, image),
260 };
261 let Some((bind, _)) = &mut bound else {
262 continue;
263 };
264 let (queued, outcome) = step_async(
265 &mut bind(&path, replica.as_deref()),
266 replica.as_deref(),
267 seen.as_deref(),
268 current,
269 image,
270 copies,
271 )
272 .await;
273 if outcome.as_ref().is_err_and(disconnected) {
274 bound = None;
275 }
276 let Ok(mut watched) = owner.watched.lock() else {
277 return;
278 };
279 let interval = watched.interval();
280 let Watched {
281 sections, changed, ..
282 } = &mut *watched;
283 let Some(watch) = sections.iter_mut().find(|watch| watch.path == path) else {
284 continue;
285 };
286 let now = Instant::now();
287 watch.current = false;
288 news |= match outcome {
289 Ok((stamp, moved)) => {
290 watch.stamp = Some(stamp);
291 watch.due = watch.due.min(now + interval);
292 if moved {
293 changed.push(path);
294 }
295 let before = summary(&watch.status);
296 if let Some(queued) = queued {
297 watch.status = SyncStatus {
298 synced: Some(crate::now()),
299 error: None,
300 queued,
301 };
302 }
303 moved || before != summary(&watch.status)
304 }
305 // Another holder has the replica for a moment, as a session closing or an
306 // earlier background finishing its own check does: the section is checked
307 // again soon, and the change it may have taken is not passed over.
308 Err(error)
309 if error.busy()
310 || matches!(&error, Error::Io(error)
311 if error.kind() == io::ErrorKind::WouldBlock) =>
312 {
313 watch.due = watch.due.min(now + HELD);
314 false
315 }
316 Err(error) => {
317 watch.due = watch.due.min(now + RETRY);
318 watch.fail(&error, queued)
319 }
320 };
321 }
322 if let Ok(mut watched) = owner.watched.lock() {
323 watched.watching(false);
324 if owner.discard.load(Ordering::Acquire) {
325 for replica in watched
326 .sections
327 .iter()
328 .filter_map(|watch| watch.replica.as_ref())
329 {
330 discard(replica);
331 }
332 }
333 }
334 })?;
335 Ok(Self(shared, Mutex::new(Some(thread))))
336 }
337
338 /// Keeps the sections of a notebook on a share in sync while they are not open, with an
339 /// offline copy of each, and one watch on the notebook's folder reporting what changed,
340 /// as OneNote 2010 watches it; `connect` runs again after a transport failure. Paths are
341 /// relative to `root`.
342 #[cfg(feature = "smb")]
343 pub fn smb(
344 root: &str,
345 limit: usize,
346 mut connect: impl FnMut() -> io::Result<crate::smb::Client> + Send + 'static,
347 notify: impl Fn() + Send + 'static,
348 ) -> Result<Self> {
349 let root = root.replace('\\', "/");
350 Self::start(
351 true,
352 move |reports| {
353 let client = Arc::new(connect()?);
354 let reported = match client.watch(&root, move |changed| match changed {
355 Ok(paths) => reports.touched(&paths),
356 Err(_) => reports.lost(),
357 }) {
358 Ok(()) => true,
359 Err(error) if error.kind() == io::ErrorKind::Unsupported => false,
360 Err(error) => return Err(error),
361 };
362 let (bound, folder) = (Arc::clone(&client), root.clone());
363 let bind = move |path: &str, _: Option<&Path>| {
364 let file = match folder.as_str() {
365 "" => path.to_owned(),
366 root => format!("{root}/{path}"),
367 };
368 crate::SmbRemote::new(Arc::clone(&bound), file, limit)
369 };
370 let root = root.clone();
371 let list = move |folder: String| {
372 std::future::ready((|| {
373 use crate::discover::Source;
374 crate::discover::Smb::new(&client, &root)?
375 .entries(&folder, crate::session::LIMITS.entries)
376 })())
377 };
378 Ok(((bind, list), reported))
379 },
380 notify,
381 )
382 }
383
384 /// Keeps the sections of a notebook a Live Share host serves in sync while they are not
385 /// open, with an offline copy of each; the host reports what changed. Paths are catalog
386 /// paths.
387 #[cfg(feature = "live")]
388 pub fn hosted(
389 guest: Arc<crate::live::share::Guest>,
390 notify: impl Fn() + Send + 'static,
391 ) -> Result<Self> {
392 let background = Self::start(
393 true,
394 move |reports| {
395 guest.watch(reports)?;
396 let (bound, listing) = (Arc::clone(&guest), Arc::clone(&guest));
397 let bind = move |path: &str, _: Option<&Path>| {
398 crate::live::share::HostedRemote::new(&bound, path)
399 };
400 let list = move |folder: String| {
401 let listing = listing.clone();
402 async move { listing.entries_async(&folder).await }
403 };
404 Ok(((bind, list), true))
405 },
406 notify,
407 )?;
408 background.set_settle(crate::live::share::SETTLE);
409 Ok(background)
410 }
411
412 /// Keeps the sections of a notebook a document provider keeps in sync while they are not
413 /// open, with an offline copy of each. Nothing reports the folder's changes; the host
414 /// passes what it hears of them to `touched`. Paths are catalog paths.
415 pub fn provider(
416 documents: Arc<crate::provider::Documents>,
417 notify: impl Fn() + Send + 'static,
418 ) -> Result<Self> {
419 Self::start(
420 true,
421 move |_| {
422 let (bound, listing) = (Arc::clone(&documents), Arc::clone(&documents));
423 let bind = move |path: &str, replica: Option<&Path>| {
424 crate::provider::ProviderRemote::new(&bound, path, replica)
425 };
426 let list = move |folder: String| std::future::ready(listing.entries(&folder));
427 Ok(((bind, list), false))
428 },
429 notify,
430 )
431 }
432
433 /// Checks what a report names after `settle` rather than a second, where reports come
434 /// one to a commit, as a Live Share host sends them.
435 pub fn set_settle(&self, settle: Duration) {
436 if let Ok(mut watched) = self.0.watched.lock() {
437 watched.settle = Some(settle);
438 }
439 }
440
441 /// Has `listener` hear every report of changed paths from now on, as a Live Share host
442 /// passes them to its guests; `None` stops.
443 pub fn on_touched(&self, listener: Option<Listener>) {
444 if let Ok(mut held) = self.0.listener.lock() {
445 *held = listener;
446 }
447 }
448
449 /// Watches these sections (`Notebook::replicas`); a section not watched before is first
450 /// checked soon after, the next one a little later.
451 pub fn watch(&self, sections: Vec<Known>) {
452 if let Ok(mut watched) = self.0.watched.lock() {
453 watched.watch(sections, Instant::now());
454 }
455 self.0.signal.wake();
456 }
457
458 /// Leaves the section at catalog `path` to `section`'s worker, which from now on the watch
459 /// on the notebook's folder wakes when the file changes, instead of the worker checking
460 /// it every few seconds. Once the section closes, this takes it over again.
461 pub fn hold(&self, path: &str, section: &Section) {
462 let replica = section.replica();
463 let Some(worker) = replica
464 .section
465 .worker
466 .lock()
467 .ok()
468 .and_then(|worker| worker.upgrade())
469 else {
470 return;
471 };
472 if let Ok(mut watched) = self.0.watched.lock() {
473 let reported = watched.reported;
474 if let Some(watch) = watched.sections.iter_mut().find(|watch| watch.path == path) {
475 worker.watched.store(reported, Ordering::Release);
476 watch.held = Some(Held {
477 worker: Arc::downgrade(&worker),
478 replica: Arc::downgrade(replica),
479 observed: Arc::downgrade(&section.observed),
480 });
481 }
482 }
483 let (shared, path) = (Arc::downgrade(&self.0), path.to_owned());
484 if let Ok(mut released) = replica.section.released.0.lock() {
485 *released = Some(Box::new(move || {
486 if let Some(shared) = shared.upgrade() {
487 shared.released(&path);
488 }
489 }));
490 }
491 }
492
493 /// Checks the sections at or below these catalog paths soon, as a watch on the notebook's
494 /// folder reports them changed: a section's own path checks it, a folder's lists it first
495 /// and checks the sections listed otherwise. `""` names the notebook's folder.
496 pub fn touched(&self, paths: &[String]) {
497 self.0.touched(paths);
498 }
499
500 /// Each watched section's status, in watch order: a held section's live state while its
501 /// session syncs, otherwise this thread's last check of it.
502 pub fn status(&self) -> Vec<(String, SyncStatus)> {
503 let sections: Vec<_> = self.0.watched.lock().map_or_else(
504 |_| Vec::new(),
505 |watched| {
506 watched
507 .sections
508 .iter()
509 .map(|watch| {
510 let status = &watch.status;
511 (
512 watch.path.clone(),
513 SyncStatus {
514 synced: status.synced,
515 error: status
516 .error
517 .as_ref()
518 .map(|error| io::Error::new(error.kind(), error.to_string())),
519 queued: status.queued,
520 },
521 watch.held.clone(),
522 )
523 })
524 .collect()
525 },
526 );
527 sections
528 .into_iter()
529 .map(|(path, fallback, held)| {
530 let live = held.and_then(|held| {
531 let worker = (held.worker.upgrade())
532 .filter(|worker| !worker.stopped.load(Ordering::Acquire))?;
533 let replica = held.replica.upgrade()?;
534 let observed = held.observed.upgrade()?;
535 let synced =
536 || Some(worker.synced.load(Ordering::Acquire)).filter(|time| *time != 0);
537 Some(sync_status(&replica, synced, &observed))
538 });
539 let status = match live {
540 Some(Ok(status)) => status,
541 Some(Err(error)) => SyncStatus {
542 error: Some(reached(&error)),
543 ..fallback
544 },
545 None => fallback,
546 };
547 (path, status)
548 })
549 .collect()
550 }
551
552 /// Sections whose file changed since the last call, by catalog path.
553 pub fn changed(&self) -> Vec<String> {
554 self.0
555 .watched
556 .lock()
557 .map(|mut watched| std::mem::take(&mut watched.changed))
558 .unwrap_or_default()
559 }
560
561 /// Reads every section's stamp now, working offline included (Sync Now). A section already
562 /// due keeps its place: waking again while a round runs would otherwise tie every section
563 /// at now, and the first would be checked over and over while the rest waited.
564 pub fn wake(&self) {
565 if let Ok(mut watched) = self.0.watched.lock() {
566 let now = Instant::now();
567 for watch in &mut watched.sections {
568 watch.due = watch.due.min(now);
569 watch.current = false;
570 }
571 }
572 self.0.signal.requested.store(true, Ordering::Release);
573 self.0.signal.wake();
574 }
575
576 /// Stops for good, then deletes each section's replica that holds nothing unpublished, as
577 /// OneNote lets go of a notebook it closes; one with edits waiting, or that a session
578 /// holds, stays.
579 pub fn discard(&self) {
580 self.0.discard.store(true, Ordering::Release);
581 self.0.signal.stopped.store(true, Ordering::Release);
582 self.0.signal.wake();
583 }
584
585 /// Stops future checks; native threads finish the current step before returning.
586 pub fn stop(&self) {
587 self.0.signal.stopped.store(true, Ordering::Release);
588 self.0.signal.wake();
589 let thread = self.1.lock().ok().and_then(|mut thread| thread.take());
590 #[cfg(not(target_arch = "wasm32"))]
591 if let Some(thread) = thread {
592 let _ = thread.join();
593 }
594 #[cfg(target_arch = "wasm32")]
595 drop(thread);
596 }
597
598 /// Stops future checks and awaits the current step before files can move.
599 pub async fn stop_async(&self) {
600 #[cfg(not(target_arch = "wasm32"))]
601 self.stop();
602 #[cfg(target_arch = "wasm32")]
603 {
604 self.0.signal.stopped.store(true, Ordering::Release);
605 self.0.signal.wake();
606 let thread = self.1.lock().ok().and_then(|mut thread| thread.take());
607 if let Some(thread) = thread {
608 let _ = thread.join().await;
609 }
610 }
611 }
612
613 /// Working offline, nothing is checked until `wake`, or until working online again, which
614 /// lists every folder again.
615 pub fn set_offline(&self, offline: bool) {
616 self.0.signal.offline.store(offline, Ordering::Release);
617 self.0.signal.wake();
618 }
619}
620
621impl Drop for Background {
622 fn drop(&mut self) {
623 self.0.signal.stopped.store(true, Ordering::Release);
624 self.0.signal.wake();
625 }
626}
627
628impl Shared {
629 fn touched(&self, paths: &[String]) {
630 if let Ok(mut watched) = self.watched.lock() {
631 watched.touched(paths, Instant::now());
632 }
633 self.signal.wake();
634 if let Ok(listener) = self.listener.lock()
635 && let Some(listener) = &*listener
636 {
637 listener(paths);
638 }
639 }
640
641 /// The session holding the section at `path` let it go: it is checked now.
642 fn released(&self, path: &str) {
643 if let Ok(mut watched) = self.watched.lock()
644 && let Some(watch) = watched.sections.iter_mut().find(|watch| watch.path == path)
645 {
646 watch.held = None;
647 watch.current = false;
648 watch.due = Instant::now();
649 }
650 self.signal.wake();
651 }
652}
653
654#[cfg_attr(not(any(feature = "smb", feature = "live")), allow(dead_code))]
655impl Reports {
656 #[cfg(all(feature = "live", target_arch = "wasm32"))]
657 pub(crate) fn catalog(&self, folder: &str) {
658 if let Some(shared) = self.shared.upgrade()
659 && let Ok(mut watched) = shared.watched.lock()
660 && !watched.changed.iter().any(|path| path == folder)
661 {
662 watched.changed.push(folder.to_owned());
663 }
664 }
665
666 /// The sections at or below these paths changed.
667 pub(crate) fn touched(&self, paths: &[String]) {
668 if let Some(shared) = self.shared.upgrade() {
669 shared.touched(paths);
670 }
671 }
672
673 /// The watch ended, and with it, as far as anyone can tell, the connection.
674 pub(crate) fn lost(&self) {
675 if let Some(shared) = self.shared.upgrade() {
676 if let Ok(mut watched) = shared.watched.lock()
677 && watched.connection == self.connection
678 {
679 watched.lost = true;
680 }
681 shared.signal.wake();
682 }
683 }
684}
685
686/// What the background thread does next.
687enum Next {
688 Wait(Option<Duration>),
689 /// Connects, as the current connection is `.0`, then lists every folder.
690 Connect(u64),
691 /// Lists these folders, checking the sections listed otherwise.
692 List(BTreeSet<String>),
693 Check {
694 path: String,
695 replica: Option<PathBuf>,
696 seen: Option<Box<Stamp>>,
697 current: bool,
698 image: Option<Vec<u8>>,
699 },
700}
701
702impl Watched {
703 fn watch(&mut self, sections: Vec<Known>, now: Instant) {
704 let mut previous = std::mem::take(&mut self.sections);
705 let mut new = 0;
706 self.sections = sections
707 .into_iter()
708 .map(
709 |known| match previous.iter().position(|watch| watch.path == known.path) {
710 Some(index) => Watch {
711 replica: known.replica,
712 image: known.image,
713 ..previous.swap_remove(index)
714 },
715 None => {
716 new += 1;
717 let (listed, stamp) = known.found.unzip();
718 Watch {
719 path: known.path,
720 replica: known.replica,
721 stamp,
722 listed,
723 current: false,
724 reported: false,
725 status: SyncStatus {
726 synced: None,
727 error: None,
728 queued: 0,
729 },
730 image: known.image,
731 due: now + STAGGER * (new - 1),
732 held: None,
733 }
734 }
735 },
736 )
737 .collect();
738 }
739
740 fn interval(&self) -> Duration {
741 if self.reported {
742 Background::BACKSTOP
743 } else {
744 Background::UNWATCHED
745 }
746 }
747
748 /// Whether a watch reports the folder's changes from now on, as the held sessions' workers
749 /// learn.
750 fn watching(&mut self, reported: bool) {
751 self.reported = reported;
752 for signal in self
753 .sections
754 .iter()
755 .filter_map(|watch| watch.held.as_ref()?.worker.upgrade())
756 {
757 signal.watched.store(reported, Ordering::Release);
758 signal.wake();
759 }
760 }
761
762 fn touched(&mut self, paths: &[String], now: Instant) {
763 let settled = now + self.settle.unwrap_or(SETTLE);
764 for path in paths {
765 let path = path.trim_matches('/');
766 let section = self
767 .sections
768 .iter()
769 .position(|watch| watch.path.eq_ignore_ascii_case(path));
770 match section {
771 Some(index) => {
772 let watch = &mut self.sections[index];
773 watch.due = watch.due.min(settled);
774 watch.current = false;
775 watch.reported = true;
776 }
777 None if self.sections.iter().any(|watch| within(&watch.path, path)) => {
778 self.folders.insert(path.to_owned());
779 self.relist = Some(self.relist.map_or(settled, |due| due.min(settled)));
780 }
781 None => {}
782 }
783 }
784 }
785
786 /// Every folder holding a section, to list them all, as a listing begins.
787 fn rescanning(&mut self) -> BTreeSet<String> {
788 for watch in &mut self.sections {
789 watch.reported = false;
790 }
791 self.parents(&[String::new()])
792 }
793
794 /// The folders holding the sections at or below `paths`.
795 fn parents<'a>(&self, paths: impl IntoIterator<Item = &'a String> + Clone) -> BTreeSet<String> {
796 self.sections
797 .iter()
798 .filter(|watch| {
799 paths
800 .clone()
801 .into_iter()
802 .any(|path| within(&watch.path, path))
803 })
804 .map(|watch| split(&watch.path).0.to_owned())
805 .collect()
806 }
807
808 /// Takes the folders' listings. With `rescan`, as on connecting (whether copies are kept),
809 /// every section of a listed folder is checked, from now: first those whose file lists as
810 /// when its stamp was last read, which need no reading unless for a copy, then the others
811 /// one `STAGGER` after another. Otherwise only the sections listed otherwise are, as are
812 /// those a watch reported meanwhile either way.
813 fn listed(
814 &mut self,
815 listings: &BTreeMap<String, Vec<Entry>>,
816 rescan: Option<bool>,
817 now: Instant,
818 ) {
819 let mut staggered = 0;
820 for watch in &mut self.sections {
821 let (folder, name) = split(&watch.path);
822 let Some(entries) = listings.get(folder) else {
823 continue;
824 };
825 let listed = entries
826 .iter()
827 .find(|entry| entry.name.eq_ignore_ascii_case(name))
828 .map(|entry| entry.listed);
829 let unchanged = watch.stamp.is_some() && listed.is_some() && listed == watch.listed;
830 watch.listed = listed;
831 match rescan {
832 // A report while listing may name a change the listing missed.
833 Some(_) if watch.reported => watch.current = false,
834 Some(copies) => {
835 watch.current = unchanged;
836 let read = !unchanged
837 || copies
838 && watch.image.is_none()
839 && watch
840 .replica
841 .as_ref()
842 .is_some_and(|replica| fs::metadata(replica).is_err());
843 watch.due = if read {
844 staggered += 1;
845 now + STAGGER * (staggered - 1)
846 } else {
847 now
848 };
849 }
850 None if !unchanged => {
851 watch.current = false;
852 watch.due = watch.due.min(now);
853 }
854 None => {}
855 }
856 }
857 }
858
859 /// What to do at `now`, waking the held sections that are due; `bound` while connected.
860 fn next(&mut self, now: Instant, bound: bool) -> Next {
861 let interval = self.interval();
862 loop {
863 let due = (0..self.sections.len()).min_by_key(|&index| self.sections[index].due);
864 let at = due.map(|index| self.sections[index].due);
865 if let Some(relist) = self.relist
866 && relist <= now
867 && at.is_none_or(|at| relist <= at)
868 {
869 if !bound {
870 return Next::Connect(self.connection);
871 }
872 let folders = std::mem::take(&mut self.folders);
873 self.relist = None;
874 return Next::List(self.parents(&folders));
875 }
876 let Some(index) = due.filter(|&index| self.sections[index].due <= now) else {
877 let wait = [at, self.relist].into_iter().flatten().min();
878 return Next::Wait(wait.map(|at| at.saturating_duration_since(now)));
879 };
880 let watch = &mut self.sections[index];
881 if !bound {
882 return Next::Connect(self.connection);
883 }
884 if let Some(worker) = watch.held.as_ref().and_then(|held| held.worker.upgrade()) {
885 worker.wake();
886 watch.due = now + interval;
887 continue;
888 }
889 // Anything asking for the section during the check can only bring this forward.
890 watch.due = now + interval.max(RETRY);
891 return Next::Check {
892 path: watch.path.clone(),
893 replica: watch.replica.clone(),
894 seen: watch.stamp.clone().map(Box::new),
895 current: watch.current,
896 image: watch.image.take(),
897 };
898 }
899 }
900}
901
902/// Lists each of `folders` through `list`; a folder that cannot be listed lists nothing, so
903/// that its sections are checked.
904async fn list<F: Future<Output = io::Result<Vec<Entry>>>>(
905 list: &mut impl FnMut(String) -> F,
906 folders: BTreeSet<String>,
907) -> BTreeMap<String, Vec<Entry>> {
908 let mut listings = BTreeMap::new();
909 for folder in folders {
910 let entries = list(folder.clone()).await.unwrap_or_default();
911 listings.insert(folder, entries);
912 }
913 listings
914}
915
916/// Deletes the replica at `replica` if it holds nothing unpublished and no one holds it. One
917/// whose section keeps images of its publications stays as an edit waiting keeps it: an image
918/// may be an upload the file lost, which merges back once the notebook opens again.
919fn discard(replica: &Path) {
920 if !crate::published::keeps(replica)
921 && matches!(
922 crate::closed(replica).and_then(|held| crate::peek(&held)),
923 Ok((_, 0))
924 )
925 {
926 let _ = crate::remove_replica(replica);
927 }
928}
929
930/// Whether the catalog path `section` is `path` or lies below it, as a share compares names.
931fn within(section: &str, path: &str) -> bool {
932 let path = path.trim_matches('/');
933 path.is_empty()
934 || section.len() >= path.len()
935 && section.is_char_boundary(path.len())
936 && section[..path.len()].eq_ignore_ascii_case(path)
937 && matches!(section.as_bytes().get(path.len()), None | Some(b'/'))
938}
939
940/// A catalog path's folder and name.
941fn split(path: &str) -> (&str, &str) {
942 path.rsplit_once('/').unwrap_or(("", path))
943}
944
945/// Whether a failed step lost the connection, rather than failing for its one file.
946fn disconnected(error: &Error) -> bool {
947 use io::ErrorKind::*;
948 let kind = match error {
949 Error::RemoteIo(error) => error.kind(),
950 Error::Remote(error) => error.error.kind(),
951 _ => return false,
952 };
953 matches!(
954 kind,
955 NotConnected | TimedOut | ConnectionReset | ConnectionAborted | BrokenPipe
956 )
957}
958
959impl Watch {
960 /// Records a failed step and what it found waiting, answering whether the status shown
961 /// changes.
962 fn fail(&mut self, error: &Error, queued: Option<u64>) -> bool {
963 let before = summary(&self.status);
964 self.status.error = Some(reached(error));
965 self.status.queued = queued.unwrap_or(self.status.queued);
966 before != summary(&self.status)
967 }
968}
969
970/// What the host shows of a status.
971fn summary(status: &SyncStatus) -> (bool, Option<io::ErrorKind>, u64) {
972 (
973 status.synced.is_some(),
974 status.error.as_ref().map(io::Error::kind),
975 status.queued,
976 )
977}
978
979/// One section's step: how many of its edits wait (`None` while unknown, as while a session
980/// holds its replica), then the file's stamp now and whether it changed since `seen`, which
981/// with `current` is the stamp now, unread. With `copies`, a section without a replica gets
982/// one from the file as it is now. `image`, the file as discovery read it, stands in for
983/// reading it while the stamp is still its own.
984async fn step_async<R: Remote>(
985 remote: &mut R,
986 replica: Option<&Path>,
987 seen: Option<&Stamp>,
988 current: bool,
989 image: Option<Vec<u8>>,
990 copies: bool,
991) -> (Option<u64>, Result<(Stamp, bool)>) {
992 let stamp = match seen.filter(|_| current) {
993 Some(seen) => seen.clone(),
994 None => match crate::sync::awaited(remote, Remote::stamp).await {
995 Ok(stamp) => stamp,
996 Err(error) => return (None, Err(Error::RemoteIo(error))),
997 },
998 };
999 let remote = &mut Discovered {
1000 image: image.and_then(|image| Some((Stamp::of(&image).ok()?, image))),
1001 stamp: stamp.clone(),
1002 remote,
1003 };
1004 let moved = seen.is_some_and(|seen| *seen != stamp);
1005 let Some(replica) = replica else {
1006 return (Some(0), Ok((stamp, moved)));
1007 };
1008 if fs::metadata(replica).is_err() {
1009 if !copies {
1010 return (Some(0), Ok((stamp, moved)));
1011 }
1012 let copied = (async {
1013 let image = crate::sync::awaited(remote, Remote::read)
1014 .await
1015 .map_err(Error::RemoteIo)?;
1016 if let Some(folder) = replica.parent() {
1017 fs::create_dir_all(folder)?;
1018 }
1019 Replica::seed(replica, &image, None)?;
1020 fs::durable().await?;
1021 Ok(Stamp::of(&image)?)
1022 })
1023 .await;
1024 return match copied {
1025 Ok(stamp) => (Some(0), Ok((stamp, moved))),
1026 // A session made it first.
1027 Err(Error::Io(error)) if error.kind() == io::ErrorKind::AlreadyExists => {
1028 (None, Ok((stamp, false)))
1029 }
1030 Err(error) => (None, Err(error)),
1031 };
1032 }
1033 // A version kept beside the file leaves its stamp as it was.
1034 let versions = match crate::sync::awaited(remote, Remote::versions).await {
1035 Ok(versions) => versions,
1036 Err(error) => return (None, Err(Error::RemoteIo(error))),
1037 };
1038 match crate::closed(replica).and_then(|held| crate::peek(&held)) {
1039 Ok((base, 0)) if base == stamp && versions.is_empty() => {
1040 return (Some(0), Ok((stamp, moved)));
1041 }
1042 Err(error) if error.busy() => return (None, Err(error)),
1043 _ => {}
1044 }
1045 let replica = match Replica::open(replica) {
1046 Ok(replica) => replica,
1047 Err(error) => return (None, Err(error)),
1048 };
1049 let synced = (async {
1050 let mut changed = moved;
1051 loop {
1052 let synced = replica.sync_once_async(remote).await?;
1053 changed |= !synced.changed.is_empty();
1054 if !matches!(synced.edit, Some((_, EditStatus::Published { .. }))) {
1055 return Ok((
1056 crate::sync::awaited(remote, Remote::stamp)
1057 .await
1058 .map_err(Error::RemoteIo)?,
1059 changed,
1060 ));
1061 }
1062 }
1063 })
1064 .await;
1065 let queued = replica
1066 .recovery_summary()
1067 .ok()
1068 .map(|summary| summary.queued_edits);
1069 (queued, synced)
1070}
1071
1072/// A remote whose first read, while the file's stamp is still `image`'s, answers `image`.
1073struct Discovered<'a, R> {
1074 remote: &'a mut R,
1075 image: Option<(Stamp, Vec<u8>)>,
1076 /// The stamp last read.
1077 stamp: Stamp,
1078}
1079
1080impl<R: Remote> Remote for Discovered<'_, R> {
1081 fn pending(&mut self) -> Option<std::pin::Pin<Box<dyn Future<Output = ()> + '_>>> {
1082 self.remote.pending()
1083 }
1084
1085 fn read(&mut self) -> io::Result<Vec<u8>> {
1086 match self.image.take() {
1087 Some((stamp, image)) if stamp == self.stamp => Ok(image),
1088 _ => self.remote.read(),
1089 }
1090 }
1091
1092 fn stamp(&mut self) -> io::Result<Stamp> {
1093 self.stamp = self.remote.stamp()?;
1094 Ok(self.stamp.clone())
1095 }
1096
1097 fn publish(
1098 &mut self,
1099 transaction: &onestore::Transaction,
1100 ) -> std::result::Result<(), onestore::CommitError> {
1101 self.remote.publish(transaction)
1102 }
1103
1104 fn confirm(&mut self, base: &Stamp) -> std::result::Result<(), onestore::CommitError> {
1105 self.remote.confirm(base)
1106 }
1107
1108 fn accepts_edits(&self) -> bool {
1109 self.remote.accepts_edits()
1110 }
1111
1112 fn publish_edits(
1113 &mut self,
1114 transaction: &onestore::Transaction,
1115 edits: &[crate::PendingEdit],
1116 revisions: &std::collections::BTreeMap<onestore::ExGuid, onestore::ExGuid>,
1117 ) -> std::result::Result<(), onestore::CommitError> {
1118 self.remote.publish_edits(transaction, edits, revisions)
1119 }
1120
1121 fn versions(&mut self) -> io::Result<Vec<crate::Version>> {
1122 self.remote.versions()
1123 }
1124
1125 fn version(&mut self, id: &str) -> io::Result<Vec<u8>> {
1126 self.remote.version(id)
1127 }
1128
1129 fn retire(&mut self, id: &str, keep: bool) -> io::Result<()> {
1130 self.remote.retire(id, keep)
1131 }
1132}
1133
1134#[cfg(test)]
1135mod tests {
1136 use super::*;
1137 use crate::discover::EntryKind;
1138 const BACKSTOP: Duration = Background::BACKSTOP;
1139 use onestore::{CommitError, Transaction};
1140 use std::{
1141 collections::HashMap,
1142 sync::mpsc::{self, Receiver},
1143 };
1144
1145 fn path(n: usize) -> String {
1146 let folder = if n.is_multiple_of(2) { "" } else { "Group/" };
1147 format!("{folder}Section {n:03}.one")
1148 }
1149
1150 fn listed(n: usize) -> Listed {
1151 Listed {
1152 size: 1000 + n as u64,
1153 modified: 7,
1154 }
1155 }
1156
1157 fn stamp(n: usize) -> Stamp {
1158 Stamp {
1159 header: [n as u8; 1024],
1160 length: n as u64,
1161 }
1162 }
1163
1164 /// `count` sections, each found by discovery as `listed` and `stamp` have it, with `warm`.
1165 fn sections(count: usize, warm: bool) -> Vec<Known> {
1166 (0..count)
1167 .map(|n| Known {
1168 path: path(n),
1169 replica: None,
1170 found: warm.then(|| (listed(n), stamp(n))),
1171 image: None,
1172 })
1173 .collect()
1174 }
1175
1176 #[test]
1177 fn a_notebook_with_every_section_held_still_connects_its_watch() {
1178 let now = Instant::now();
1179 let mut watched = Watched::default();
1180 watched.watch(sections(1, true), now);
1181 let (held, woken) = Signal::new();
1182 watched.sections[0].held = Some(Held {
1183 worker: Arc::downgrade(&held),
1184 replica: Weak::new(),
1185 observed: Weak::new(),
1186 });
1187 assert!(matches!(watched.next(now, false), Next::Connect(0)));
1188 watched.watching(true);
1189 assert!(held.watched.load(Ordering::Acquire));
1190 assert!(matches!(watched.next(now, true), Next::Wait(_)));
1191 assert!(woken.recv_timeout(Duration::from_millis(50)).is_ok());
1192 }
1193
1194 /// The notebook's folders as a listing shows its first `count` sections.
1195 fn listing(count: usize) -> BTreeMap<String, Vec<Entry>> {
1196 let mut folders: BTreeMap<String, Vec<Entry>> = BTreeMap::new();
1197 for n in 0..count {
1198 let path = path(n);
1199 let (folder, name) = split(&path);
1200 folders.entry(folder.to_owned()).or_default().push(Entry {
1201 name: name.to_owned(),
1202 kind: EntryKind::File,
1203 listed: listed(n),
1204 });
1205 }
1206 folders
1207 }
1208
1209 /// Connects at `now`, a watch reporting, and the folders listing as `listings` has them;
1210 /// `meanwhile` runs while they are listed.
1211 fn connect(
1212 watched: &mut Watched,
1213 listings: &BTreeMap<String, Vec<Entry>>,
1214 now: Instant,
1215 meanwhile: impl FnOnce(&mut Watched),
1216 ) {
1217 watched.watching(true);
1218 let folders = watched.rescanning();
1219 meanwhile(watched);
1220 let listings = folders
1221 .into_iter()
1222 .map(|folder| (folder.clone(), listings[&folder].clone()))
1223 .collect();
1224 watched.listed(&listings, Some(false), now);
1225 }
1226
1227 /// Runs the schedule as the thread would from `now` to `end`, every check succeeding and
1228 /// every folder listing as `listings` has it, answering each check: when, which section,
1229 /// and whether it read the file's stamp.
1230 fn run(
1231 watched: &mut Watched,
1232 mut now: Instant,
1233 end: Instant,
1234 listings: &BTreeMap<String, Vec<Entry>>,
1235 ) -> Vec<(Instant, String, bool)> {
1236 let mut checks = Vec::new();
1237 loop {
1238 match watched.next(now, true) {
1239 Next::Wait(Some(wait)) if now + wait <= end => now += wait,
1240 Next::Wait(_) => return checks,
1241 Next::Connect(_) => unreachable!("connected"),
1242 Next::List(folders) => {
1243 let listings = folders
1244 .into_iter()
1245 .map(|folder| (folder.clone(), listings[&folder].clone()))
1246 .collect();
1247 watched.listed(&listings, None, now);
1248 }
1249 Next::Check { path, current, .. } => {
1250 let interval = watched.interval();
1251 let watch = watched
1252 .sections
1253 .iter_mut()
1254 .find(|watch| watch.path == path)
1255 .unwrap();
1256 watch.current = false;
1257 watch.due = watch.due.min(now + interval);
1258 checks.push((now, path, !current));
1259 }
1260 }
1261 }
1262 }
1263
1264 #[test]
1265 fn a_new_notebook_is_read_once_staggered_then_left_alone() {
1266 let start = Instant::now();
1267 let mut watched = Watched::default();
1268 watched.watch(sections(200, false), start);
1269 connect(&mut watched, &listing(200), start, |_| {});
1270 let checks = run(
1271 &mut watched,
1272 start,
1273 start + BACKSTOP - SETTLE,
1274 &listing(200),
1275 );
1276 assert_eq!(checks.len(), 200, "one first check each, then none");
1277 assert!(checks.iter().all(|(.., read)| *read));
1278 for pair in checks.windows(2) {
1279 assert!(pair[1].0 - pair[0].0 >= STAGGER, "never a burst");
1280 }
1281 // Then each section costs one backstop check an interval: over a day, 24 stamp reads
1282 // where a 15-second poll made 5,760.
1283 let day = run(
1284 &mut watched,
1285 start + BACKSTOP - SETTLE,
1286 start + Duration::from_secs(86_400) - SETTLE,
1287 &listing(200),
1288 );
1289 assert_eq!(day.len(), 200 * (86_400 / BACKSTOP.as_secs() as usize - 1));
1290 }
1291
1292 #[test]
1293 fn reopening_reads_only_the_files_listed_otherwise() {
1294 let start = Instant::now();
1295 let mut watched = Watched::default();
1296 watched.watch(sections(200, true), start);
1297 let mut listings = listing(200);
1298 // Another client wrote one section while the notebook was closed.
1299 listings.get_mut("Group").unwrap()[3].listed.modified += 1;
1300 connect(&mut watched, &listings, start, |_| {});
1301 let checks = run(&mut watched, start, start + SETTLE, &listings);
1302 assert_eq!(checks.len(), 200);
1303 let read: Vec<_> = checks.iter().filter(|(.., read)| *read).collect();
1304 assert_eq!(read.len(), 1, "{read:?}");
1305 assert_eq!(read[0].1, "Group/Section 007.one");
1306 assert!(
1307 checks.iter().all(|(at, ..)| *at == start),
1308 "nothing to read, nothing to stagger"
1309 );
1310 }
1311
1312 #[test]
1313 fn a_change_reported_while_listing_is_read_though_the_listing_missed_it() {
1314 let start = Instant::now();
1315 let mut watched = Watched::default();
1316 watched.watch(sections(4, true), start);
1317 connect(&mut watched, &listing(4), start, |watched| {
1318 watched.touched(&[path(2)], start);
1319 });
1320 let checks = run(&mut watched, start, start + SETTLE * 2, &listing(4));
1321 let read: Vec<_> = checks
1322 .into_iter()
1323 .filter(|(.., read)| *read)
1324 .map(|(_, path, _)| path)
1325 .collect();
1326 assert_eq!(read, vec![path(2)]);
1327 }
1328
1329 #[test]
1330 fn a_reported_change_checks_exactly_the_sections_it_names() {
1331 let start = Instant::now();
1332 let mut watched = Watched::default();
1333 watched.watch(sections(200, true), start);
1334 let mut listings = listing(200);
1335 connect(&mut watched, &listings, start, |_| {});
1336 let now = start + Duration::from_secs(60);
1337 run(&mut watched, start, now, &listings);
1338 // A commit's several writes are reported apiece, and settle into one check.
1339 for _ in 0..3 {
1340 watched.touched(&["section 004.ONE".into()], now);
1341 }
1342 watched.touched(
1343 &["Section 004.one".into()],
1344 now + Duration::from_millis(300),
1345 );
1346 let checks = run(&mut watched, now, now + Duration::from_secs(60), &listings);
1347 assert_eq!(
1348 checks,
1349 vec![(now + SETTLE, "Section 004.one".to_owned(), true)]
1350 );
1351 // A folder, as a watch names it when it cannot name the file, is listed, and only the
1352 // section listed otherwise is checked.
1353 let now = now + Duration::from_secs(60);
1354 listings.get_mut("Group").unwrap()[2].listed.size += 1;
1355 watched.touched(&["Group".into()], now);
1356 let group = run(&mut watched, now, now + SETTLE * 2, &listings);
1357 assert_eq!(
1358 group,
1359 vec![(now + SETTLE, "Group/Section 005.one".to_owned(), true)]
1360 );
1361 // `""` lists every folder; nothing listed otherwise, nothing is checked.
1362 watched.touched(&["Grou".into(), String::new()], now + SETTLE * 2);
1363 assert!(run(&mut watched, now + SETTLE * 2, now + SETTLE * 4, &listings).is_empty());
1364 }
1365
1366 /// Each file's image and how many times it was written, by path.
1367 type Images = HashMap<String, (Vec<u8>, u64)>;
1368
1369 /// Section files in memory, each stamp read reported as it happens.
1370 #[derive(Clone)]
1371 struct Files {
1372 images: Arc<Mutex<Images>>,
1373 stamps: mpsc::Sender<String>,
1374 }
1375
1376 impl Files {
1377 fn write(&self, path: &str, image: Vec<u8>) {
1378 let mut images = self.images.lock().unwrap();
1379 let version = images.get(path).map_or(0, |(_, version)| version + 1);
1380 images.insert(path.to_owned(), (image, version));
1381 }
1382
1383 fn list(&self, folder: &str) -> Vec<Entry> {
1384 let images = self.images.lock().unwrap();
1385 images
1386 .iter()
1387 .filter(|(path, _)| split(path).0 == folder)
1388 .map(|(path, (image, version))| Entry {
1389 name: split(path).1.to_owned(),
1390 kind: EntryKind::File,
1391 listed: Listed {
1392 size: image.len() as u64,
1393 modified: *version,
1394 },
1395 })
1396 .collect()
1397 }
1398
1399 fn known(&self, path: &str) -> Known {
1400 let (image, version) = self.images.lock().unwrap()[path].clone();
1401 Known {
1402 path: path.to_owned(),
1403 replica: None,
1404 found: Some((
1405 Listed {
1406 size: image.len() as u64,
1407 modified: version,
1408 },
1409 Stamp::of(&image).unwrap(),
1410 )),
1411 image: None,
1412 }
1413 }
1414 }
1415
1416 struct File(Files, String);
1417
1418 impl Remote for File {
1419 fn read(&mut self) -> io::Result<Vec<u8>> {
1420 let images = self.0.images.lock().unwrap();
1421 Ok(images[&self.1].0.clone())
1422 }
1423
1424 fn stamp(&mut self) -> io::Result<Stamp> {
1425 let _ = self.0.stamps.send(self.1.clone());
1426 Stamp::of(&self.read()?).map_err(io::Error::other)
1427 }
1428
1429 fn publish(&mut self, _: &Transaction) -> std::result::Result<(), CommitError> {
1430 unreachable!("nothing is queued")
1431 }
1432
1433 fn confirm(&mut self, _: &Stamp) -> std::result::Result<(), CommitError> {
1434 unreachable!("nothing is queued")
1435 }
1436 }
1437
1438 fn quiet(stamps: &Receiver<String>, wait: Duration) -> Vec<String> {
1439 let mut read = Vec::new();
1440 while let Ok(path) = stamps.recv_timeout(wait) {
1441 read.push(path);
1442 }
1443 read
1444 }
1445
1446 #[test]
1447 fn a_watch_wakes_the_section_it_reports_and_a_lost_one_lists_again() {
1448 let (sender, stamps) = mpsc::channel();
1449 let files = Files {
1450 images: Arc::default(),
1451 stamps: sender,
1452 };
1453 let mut paths: Vec<String> = (0..6).map(path).collect();
1454 paths.sort();
1455 for path in &paths {
1456 files.write(
1457 path,
1458 onestore::create_section("s.one", path, "Author").unwrap(),
1459 );
1460 }
1461 let (armed, watches) = mpsc::channel();
1462 let remote = files.clone();
1463 let background = Background::start(
1464 false,
1465 move |reports| {
1466 armed.send(reports).unwrap();
1467 let (files, listed) = (remote.clone(), remote.clone());
1468 let bind = move |path: &str, _: Option<&Path>| File(files.clone(), path.to_owned());
1469 let list = move |folder: String| std::future::ready(Ok(listed.list(&folder)));
1470 Ok(((bind, list), true))
1471 },
1472 || {},
1473 )
1474 .unwrap();
1475 // A section the catalog read unchanged is not read again; a new one is.
1476 let mut known: Vec<Known> = paths[1..].iter().map(|path| files.known(path)).collect();
1477 known.push(Known {
1478 path: paths[0].clone(),
1479 replica: None,
1480 found: None,
1481 image: None,
1482 });
1483 background.watch(known);
1484 assert_eq!(quiet(&stamps, STAGGER * 4), vec![paths[0].clone()]);
1485 let watch = watches.recv().unwrap();
1486 assert!(quiet(&stamps, SETTLE).is_empty(), "idle reads nothing");
1487
1488 // A folder reported without its file is listed; only the file listed otherwise is read.
1489 let other = &paths[4];
1490 files.write(
1491 other,
1492 onestore::create_section("s.one", "Other", "Author").unwrap(),
1493 );
1494 watch.touched(&[String::new()]);
1495 assert_eq!(quiet(&stamps, SETTLE * 2), vec![other.clone()]);
1496 assert_eq!(background.changed(), vec![other.clone()]);
1497
1498 let changed = &paths[3];
1499 files.write(
1500 changed,
1501 onestore::create_section("s.one", "Changed", "Author").unwrap(),
1502 );
1503 watch.touched(std::slice::from_ref(changed));
1504 assert_eq!(quiet(&stamps, SETTLE * 2), vec![changed.clone()]);
1505 assert_eq!(background.changed(), vec![changed.clone()]);
1506
1507 // A watch that ended leaves changes unreported, so every folder is listed again, and
1508 // the files listed otherwise since the last listing are read.
1509 let third = &paths[5];
1510 files.write(
1511 third,
1512 onestore::create_section("s.one", "Third", "Author").unwrap(),
1513 );
1514 watch.lost();
1515 let rewatch = watches.recv_timeout(SETTLE).unwrap();
1516 let mut read = quiet(&stamps, STAGGER * 4);
1517 read.sort();
1518 assert_eq!(read, vec![changed.clone(), third.clone()]);
1519 // The ended watch's connection is gone; only the current one's loss counts.
1520 watch.lost();
1521 assert!(quiet(&stamps, SETTLE).is_empty());
1522 drop(rewatch);
1523 }
1524
1525 #[test]
1526 fn a_section_released_during_its_check_is_checked_again_at_once() {
1527 let (sender, stamps) = mpsc::channel();
1528 let files = Files {
1529 images: Arc::default(),
1530 stamps: sender,
1531 };
1532 let section = path(0);
1533 files.write(
1534 &section,
1535 onestore::create_section("s.one", &section, "Author").unwrap(),
1536 );
1537 let (armed, watches) = mpsc::channel();
1538 let remote = files.clone();
1539 let background = Background::start(
1540 false,
1541 move |reports| {
1542 armed.send(reports).unwrap();
1543 let (files, listed) = (remote.clone(), remote.clone());
1544 let bind = move |path: &str, _: Option<&Path>| File(files.clone(), path.to_owned());
1545 let list = move |folder: String| std::future::ready(Ok(listed.list(&folder)));
1546 Ok(((bind, list), true))
1547 },
1548 || {},
1549 )
1550 .unwrap();
1551 background.watch(vec![files.known(&section)]);
1552 let watch = watches.recv().unwrap();
1553 assert!(quiet(&stamps, SETTLE).is_empty());
1554 // Holding the files parks the check reported next inside its stamp read.
1555 let parked = files.images.lock().unwrap();
1556 watch.touched(std::slice::from_ref(&section));
1557 assert_eq!(stamps.recv_timeout(SETTLE * 2).unwrap(), section);
1558 background.0.released(&section);
1559 drop(parked);
1560 assert_eq!(stamps.recv_timeout(SETTLE).unwrap(), section);
1561 drop(background);
1562 }
1563
1564 #[test]
1565 fn held_status_tracks_its_worker_without_retaining_the_replica() {
1566 use crate::session::SyncState;
1567 use onestore::{
1568 PageCreation,
1569 op::{Edit, Op, SectionOp},
1570 };
1571
1572 let directory = tempfile::tempdir().unwrap();
1573 let file = directory.path().join("Held.one");
1574 let source = onestore::create_section("Held.one", "", "Author").unwrap();
1575 fs::write(&file, &source).unwrap();
1576 let (changed, changes) = mpsc::channel();
1577 let section = Section::open(&file, directory.path().join("cache"), false, move || {
1578 let _ = changed.send(());
1579 })
1580 .unwrap();
1581 changes.recv_timeout(Duration::from_secs(3)).unwrap();
1582 section.set_offline(true);
1583
1584 let (stamps, _) = mpsc::channel();
1585 let files = Files {
1586 images: Arc::default(),
1587 stamps,
1588 };
1589 files.write("Held.one", source);
1590 let remote = files.clone();
1591 let background = Background::start(
1592 false,
1593 move |_| {
1594 let (files, listed) = (remote.clone(), remote.clone());
1595 let bind = move |path: &str, _: Option<&Path>| File(files.clone(), path.to_owned());
1596 let list = move |folder: String| std::future::ready(Ok(listed.list(&folder)));
1597 Ok(((bind, list), true))
1598 },
1599 || {},
1600 )
1601 .unwrap();
1602 background.set_offline(true);
1603 background.watch(vec![files.known("Held.one")]);
1604 background.hold("Held.one", &section);
1605 section
1606 .apply(
1607 "Author",
1608 Edit {
1609 at: crate::now(),
1610 ops: vec![Op::Section(SectionOp::Create(
1611 PageCreation::new(None, Some("Queued"), "Author").unwrap(),
1612 ))],
1613 },
1614 )
1615 .unwrap();
1616 section.written().unwrap();
1617 let pending = section.pending().unwrap();
1618 assert_eq!(pending.len(), 1);
1619 let status = background.status().remove(0).1;
1620 assert_eq!(status.queued, 1);
1621 assert!(status.synced.is_some());
1622 assert_eq!(status.state(), SyncState::Syncing);
1623 {
1624 let watched = background.0.watched.lock().unwrap();
1625 assert!(watched.sections[0].status.synced.is_none());
1626 assert_eq!(watched.sections[0].status.queued, 0);
1627 }
1628
1629 let wait = |expected| {
1630 let deadline = Instant::now() + Duration::from_secs(3);
1631 loop {
1632 let status = background.status().remove(0).1;
1633 if status.state() == expected {
1634 return status;
1635 }
1636 changes
1637 .recv_timeout(deadline.saturating_duration_since(Instant::now()))
1638 .unwrap();
1639 }
1640 };
1641 section.set_offline(false);
1642 assert_eq!(wait(SyncState::UpToDate).queued, 0);
1643 assert!(matches!(
1644 section.status(pending[0].id).unwrap(),
1645 Some(EditStatus::Published { .. })
1646 ));
1647
1648 let published = fs::read_file(&file).unwrap();
1649 fs::remove_file(&file).unwrap();
1650 section.wake();
1651 assert_eq!(
1652 wait(SyncState::NotConnected).error.unwrap().kind(),
1653 io::ErrorKind::NotFound
1654 );
1655 fs::write(&file, published).unwrap();
1656 section.wake();
1657 assert!(wait(SyncState::UpToDate).error.is_none());
1658 assert!(
1659 background.0.watched.lock().unwrap().sections[0]
1660 .status
1661 .synced
1662 .is_none()
1663 );
1664
1665 let replica = Arc::downgrade(section.replica());
1666 section.close().unwrap();
1667 assert!(replica.upgrade().is_none());
1668 assert!(
1669 background.0.watched.lock().unwrap().sections[0]
1670 .held
1671 .is_none()
1672 );
1673 }
1674
1675 #[test]
1676 fn a_held_section_is_left_to_its_worker_which_the_watch_wakes() {
1677 let (sender, stamps) = mpsc::channel();
1678 let files = Files {
1679 images: Arc::default(),
1680 stamps: sender,
1681 };
1682 let held = path(0);
1683 files.write(
1684 &held,
1685 onestore::create_section("s.one", &held, "Author").unwrap(),
1686 );
1687 let (armed, watches) = mpsc::channel();
1688 let remote = files.clone();
1689 let background = Background::start(
1690 false,
1691 move |reports| {
1692 armed.send(reports).unwrap();
1693 let (files, listed) = (remote.clone(), remote.clone());
1694 let bind = move |path: &str, _: Option<&Path>| File(files.clone(), path.to_owned());
1695 let list = move |folder: String| std::future::ready(Ok(listed.list(&folder)));
1696 Ok(((bind, list), true))
1697 },
1698 || {},
1699 )
1700 .unwrap();
1701 background.watch(vec![files.known(&held)]);
1702 let watch = watches.recv().unwrap();
1703 assert!(quiet(&stamps, SETTLE).is_empty());
1704 // As `hold` leaves it to a session's worker.
1705 let (signal, woken) = Signal::new();
1706 if let Ok(mut watched) = background.0.watched.lock() {
1707 watched.sections[0].held = Some(Held {
1708 worker: Arc::downgrade(&signal),
1709 replica: Weak::new(),
1710 observed: Weak::new(),
1711 });
1712 signal.watched.store(watched.reported, Ordering::Release);
1713 }
1714 assert!(
1715 signal.watched.load(Ordering::Acquire),
1716 "the watch reports, so the worker need not poll"
1717 );
1718 watch.touched(std::slice::from_ref(&held));
1719 assert!(woken.recv_timeout(SETTLE * 2).is_ok(), "the watch wakes it");
1720 assert!(
1721 quiet(&stamps, SETTLE).is_empty(),
1722 "the worker reads, not this"
1723 );
1724 watch.lost();
1725 assert!(woken.recv_timeout(SETTLE).is_ok());
1726 let rearmed = watches.recv_timeout(SETTLE).unwrap();
1727 while !signal.watched.load(Ordering::Acquire) {
1728 woken.recv_timeout(SETTLE * 2).unwrap();
1729 }
1730 assert!(signal.watched.load(Ordering::Acquire));
1731 rearmed.touched(std::slice::from_ref(&held));
1732 assert!(woken.recv_timeout(SETTLE * 2).is_ok());
1733 assert!(quiet(&stamps, SETTLE).is_empty());
1734 drop(signal);
1735 drop(background);
1736 }
1737}