1// One Win32 call, where std has no safe form: `session`'s hidden attribute.
2#![deny(unsafe_code)]
3#![doc = include_str!("../README.md")]
4
5pub mod discover;
6pub mod fs;
7#[cfg(feature = "live")]
8#[cfg_attr(target_arch = "wasm32", path = "live/web.rs")]
9pub mod live;
10#[cfg(feature = "smb")]
11pub mod smb;
12
13use fs::OpenOptions;
14use onestore::{
15 ExGuid,
16 op::{Edit, OpError},
17 page::Page,
18 protected::Key,
19};
20use rusqlite::{Connection, OpenFlags, TransactionBehavior, params};
21use std::{
22 io,
23 path::{Path, PathBuf},
24 sync::{Arc, Mutex, MutexGuard, mpsc},
25 time::Duration,
26};
27
28mod assets;
29mod background;
30mod base;
31pub mod location;
32mod merge;
33mod migrate;
34pub mod package;
35pub mod provider;
36pub mod published;
37mod queue;
38mod recovery;
39mod resolve;
40pub use resolve::Version;
41mod schema;
42pub mod session;
43pub use recovery::{Recovery, RecoverySummary};
44pub mod sidecar;
45mod sync;
46pub use sync::{EditStatus, Remote, Synced};
47mod task;
48mod worker;
49mod working;
50#[cfg(feature = "smb")]
51pub use smb::SmbRemote;
52pub use worker::SyncWorker;
53
54/// The largest file a notebook session or Live Share reads or writes whole.
55pub const MAX_FILE_BYTES: usize = 256 << 20;
56
57#[derive(Debug, thiserror::Error)]
58pub enum Error {
59 #[error(transparent)]
60 Database(#[from] rusqlite::Error),
61 #[error(transparent)]
62 Io(#[from] io::Error),
63 #[error(transparent)]
64 Document(#[from] onestore::Error),
65 #[error(transparent)]
66 Remote(#[from] onestore::CommitError),
67 #[error(transparent)]
68 RemoteIo(io::Error),
69 #[error(transparent)]
70 Discovery(#[from] discover::Error),
71 /// The section refused an edit; the pages it names are as they were.
72 #[error(transparent)]
73 Rejected(#[from] OpError),
74 #[error("External payload identity now refers to different bytes")]
75 AssetChanged,
76 /// A password-protected section's password did not match, or its format is unknown.
77 #[error(transparent)]
78 Protected(#[from] onestore::protected::Error),
79}
80
81impl Error {
82 /// Whether the replica is open elsewhere, as in another section session of this process.
83 pub fn busy(&self) -> bool {
84 matches!(self, Self::Database(rusqlite::Error::SqliteFailure(error, _))
85 if error.code == rusqlite::ErrorCode::DatabaseBusy)
86 }
87}
88
89type Result<T> = std::result::Result<T, Error>;
90
91const APPLICATION_ID: u32 = 0x4f4e454f;
92
93/// A page as a move copies it (`Replica::moving`), with its conflict pages and versions, which
94/// stay behind, read together.
95#[derive(Debug, PartialEq)]
96pub struct Moving {
97 space: ExGuid,
98 page: Page,
99 conflicts: Vec<onestore::ConflictPage>,
100 versions: Vec<onestore::PageVersion>,
101}
102
103impl Moving {
104 pub fn page(&self) -> &Page {
105 &self.page
106 }
107}
108
109/// A locally durable edit; its ID remains stable across cache reopen.
110#[derive(Debug, Clone, PartialEq)]
111pub struct PendingEdit {
112 pub id: u64,
113 pub author: String,
114 pub edit: Edit,
115}
116
117/// How an uncertain attempt ends after review: `Mine` publishes it again, `Theirs` drops
118/// the whole unpublished branch.
119#[derive(Debug, Clone, Copy, PartialEq, Eq)]
120pub enum Resolution {
121 Mine,
122 Theirs,
123}
124
125/// Owns one local cache. Share this handle between threads; a second open fails busy.
126/// Edits apply on the cache's section thread, which keeps the section parsed; SQLite's
127/// exclusive connection retains ownership between local transactions.
128pub struct Replica {
129 section: Arc<working::Thread>,
130 synchronization: Mutex<()>,
131 /// The section's root object space, which names the document.
132 root: ExGuid,
133}
134
135/// Edits that sections of this process hold in memory because their cache refused them for now,
136/// a dropped replica's included, which its section thread keeps writing.
137static UNWRITTEN: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
138
139/// How many edits wait in memory for a cache to write them; quitting loses them.
140pub fn unwritten() -> usize {
141 UNWRITTEN.load(std::sync::atomic::Ordering::Relaxed)
142}
143
144/// Runs once the replica is released and its cache closed, as `Background::hold` asks.
145#[derive(Default)]
146struct Released(Mutex<Option<Box<dyn FnOnce() + Send>>>);
147
148impl Drop for Released {
149 fn drop(&mut self) {
150 if let Some(released) = self.0.get_mut().ok().and_then(Option::take) {
151 released();
152 }
153 }
154}
155
156/// Deletes the closed replica at `replica`, with the files SQLite keeps beside it and the
157/// images its section's publications keep (`published`).
158pub(crate) fn remove_replica(replica: &Path) -> io::Result<()> {
159 for suffix in ["", "-wal", "-shm"] {
160 let mut file = replica.as_os_str().to_owned();
161 file.push(suffix);
162 match fs::remove_file(file) {
163 Err(error) if error.kind() != io::ErrorKind::NotFound => return Err(error),
164 _ => {}
165 }
166 }
167 match fs::remove_dir_all(published::folder(replica)) {
168 Err(error) if error.kind() != io::ErrorKind::NotFound => Err(error),
169 _ => Ok(()),
170 }
171}
172
173impl Replica {
174 /// Seeds a new cache from a validated section image, refusing any existing path.
175 /// An initialization error preserves the created file for inspection.
176 pub fn create(path: impl AsRef<Path>, source: &[u8]) -> Result<Self> {
177 Self::seed(path.as_ref(), source, None)?;
178 Self::start(cache_connection(path.as_ref())?, None)
179 }
180
181 /// Opens the cache at `path`, a protected section's under `key`, first creating it from
182 /// the image `source` reads where there is none. A cache another thread creates meanwhile,
183 /// as the background makes an offline copy, is opened instead.
184 pub fn open_or_create(
185 path: impl AsRef<Path>,
186 key: Option<&Key>,
187 source: impl FnOnce() -> Result<Vec<u8>>,
188 ) -> Result<Self> {
189 let path = path.as_ref();
190 if fs::metadata(path).is_err() {
191 match Self::seed(path, &source()?, key) {
192 Err(Error::Io(error)) if error.kind() == io::ErrorKind::AlreadyExists => {}
193 seeded => seeded?,
194 }
195 }
196 Self::open_with(path, key.cloned())
197 }
198
199 /// `create` without opening the cache it made, as for an offline copy.
200 pub(crate) fn seed(path: &Path, source: &[u8], key: Option<&Key>) -> Result<()> {
201 validate(source, key)?;
202 // Built under a name of its own and moved into place whole, so that a cache that
203 // exists is complete, and two threads making the same one never share a build.
204 static BUILDS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
205 let build = BUILDS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
206 let mut building = path.as_os_str().to_owned();
207 building.push(format!(".creating-{}-{build}", fs::process_id()));
208 let building = PathBuf::from(building);
209 let built = Self::build(&building, source);
210 let placed = built.and_then(|()| Ok(fs::rename_new(&building, path)?));
211 for suffix in ["", "-wal", "-shm"] {
212 let mut file = building.as_os_str().to_owned();
213 file.push(suffix);
214 let _ = fs::remove_file(file);
215 }
216 placed
217 }
218
219 fn build(path: &Path, source: &[u8]) -> Result<()> {
220 let mut options = OpenOptions::new();
221 options.read(true).write(true).create_new(true);
222 #[cfg(unix)]
223 {
224 use std::os::unix::fs::OpenOptionsExt;
225 options.mode(0o600);
226 }
227 drop(options.open(path)?);
228 let mut connection = cache_connection(path)?;
229 write_ahead(&connection)?;
230 let transaction = connection.transaction_with_behavior(TransactionBehavior::Exclusive)?;
231 let tables: i64 =
232 transaction.query_row("SELECT count(*) FROM sqlite_schema", [], |row| row.get(0))?;
233 let application: u32 =
234 transaction.pragma_query_value(None, "application_id", |row| row.get(0))?;
235 if application != 0 || tables != 0 {
236 return Err(io::Error::new(
237 io::ErrorKind::AlreadyExists,
238 "Cache initialization found an existing database",
239 )
240 .into());
241 }
242 transaction.pragma_update(None, "application_id", APPLICATION_ID)?;
243 transaction.pragma_update(None, "user_version", schema::VERSION)?;
244 schema::create(&transaction)?;
245 base::write(&transaction, base::Image::Base, source)?;
246 transaction.commit()?;
247 Ok(connection.close().map_err(|(_, error)| error)?)
248 }
249
250 /// Reopens an existing cache and its durable pending edits without network access.
251 /// A schema-14 cache is converted once, after exporting it to `<path>.v14-recovery`;
252 /// a conversion that cannot reproduce every queued page leaves it untouched.
253 /// Unrecognized databases and unsupported journal modes are rejected.
254 pub fn open(path: impl AsRef<Path>) -> Result<Self> {
255 Self::open_with(path.as_ref(), None)
256 }
257
258 fn open_with(path: &Path, key: Option<Key>) -> Result<Self> {
259 let mut connection = cache_connection(path)?;
260 let application: u32 =
261 connection.pragma_query_value(None, "application_id", |row| row.get(0))?;
262 if application != APPLICATION_ID {
263 return Err(io::Error::new(io::ErrorKind::InvalidData, "Not a notebook cache").into());
264 }
265 let integrity: String = connection.query_row("PRAGMA quick_check", [], |row| row.get(0))?;
266 if integrity != "ok" {
267 return Err(
268 io::Error::new(io::ErrorKind::InvalidData, "Cache integrity check failed").into(),
269 );
270 }
271 let version: u32 = connection.pragma_query_value(None, "user_version", |row| row.get(0))?;
272 // A schema-14 cache converts in its rollback journal, so a failed conversion leaves
273 // the file as it was.
274 match version {
275 migrate::VERSION => migrate::migrate(&mut connection, path)?,
276 schema::PREVIOUS => schema::upgrade(&mut connection)?,
277 schema::VERSION => {}
278 _ => {
279 return Err(io::Error::new(
280 io::ErrorKind::InvalidData,
281 format!(
282 "Cache schema version {version} is not the supported version {}",
283 schema::VERSION
284 ),
285 )
286 .into());
287 }
288 }
289 write_ahead(&connection)?;
290 Self::start(connection, key)
291 }
292
293 fn start(connection: Connection, key: Option<Key>) -> Result<Self> {
294 let (section, root) = working::spawn(connection, key)?;
295 Ok(Self {
296 section,
297 synchronization: Mutex::new(()),
298 root,
299 })
300 }
301
302 fn lock(&self) -> Result<Open<'_>> {
303 lock(&self.section.cache)
304 }
305
306 /// Where the cache is.
307 pub fn path(&self) -> Option<PathBuf> {
308 self.lock().ok()?.path().map(PathBuf::from)
309 }
310
311 /// Hands `request` to the section thread.
312 fn send(&self, request: working::Request) -> Result<()> {
313 self.section.send(request)
314 }
315
316 /// Asks the section thread and waits for its answer.
317 fn ask<T: Send + 'static>(
318 &self,
319 request: impl FnOnce(working::Reply<T>) -> working::Request,
320 ) -> Result<T> {
321 let (sender, receiver) = mpsc::sync_channel(1);
322 self.send(request(Box::new(move |result| {
323 let _ = sender.send(result);
324 })))?;
325 receiver
326 .recv()
327 .map_err(|_| io::Error::other("The section thread stopped"))?
328 }
329
330 async fn ask_async<T: Send + 'static>(
331 &self,
332 request: impl FnOnce(working::Reply<T>) -> working::Request + Send,
333 ) -> Result<T> {
334 let (sender, receiver) = task::response();
335 self.send(request(Box::new(move |result| {
336 let _ = sender.send(result);
337 })))?;
338 #[cfg(target_arch = "wasm32")]
339 let answer = task::receive(&receiver).await;
340 #[cfg(not(target_arch = "wasm32"))]
341 let answer = receiver.recv();
342 answer.map_err(|_| io::Error::other("The section thread stopped"))?
343 }
344
345 /// Applies an edit and queues it durably for publication, returning its id once
346 /// written. A refused edit returns `Rejected` and leaves every page as it was.
347 /// Browser callers use `apply_async`; this returns `WouldBlock` without submitting.
348 pub fn apply(&self, author: &str, edit: Edit) -> Result<u64> {
349 task::blocking(self.apply_async(author, edit))?
350 }
351
352 /// Applies an edit, awaiting its durable local queue receipt without blocking browser reads.
353 pub async fn apply_async(&self, author: &str, edit: Edit) -> Result<u64> {
354 self.ask_async(|reply| {
355 working::Request::Apply(working::Accepted {
356 author: author.to_owned(),
357 edit,
358 reply,
359 waiting: None,
360 moving: None,
361 })
362 })
363 .await
364 }
365
366 /// Page `space` as a move copies it, read at once with what the copy leaves behind.
367 pub fn moving(&self, space: ExGuid) -> Result<Moving> {
368 self.ask(|reply| working::Request::Moving { space, reply })
369 }
370
371 /// `retire_async`, blocking.
372 pub fn retire(&self, author: &str, edit: Edit, moving: Moving) -> Result<u64> {
373 task::blocking(self.retire_async(author, edit, moving))?
374 }
375
376 /// Applies `edit`, which deletes the page `moving` read once its copy has landed elsewhere,
377 /// only while the page and what it leaves behind are as read: checked in order with every
378 /// other edit, so none made since is deleted with it. One changed is refused as `Rejected`.
379 pub async fn retire_async(&self, author: &str, edit: Edit, moving: Moving) -> Result<u64> {
380 self.ask_async(|reply| {
381 working::Request::Apply(working::Accepted {
382 author: author.to_owned(),
383 edit,
384 reply,
385 waiting: None,
386 moving: Some(Box::new(moving)),
387 })
388 })
389 .await
390 }
391
392 /// `apply` without waiting: `reply` runs once the edit is durable or refused. While the
393 /// cache refuses to write it, the edit waits in memory and each failed write tells `waiting`.
394 pub(crate) fn submit(
395 &self,
396 author: &str,
397 edit: Edit,
398 reply: working::Reply<u64>,
399 waiting: working::Notice,
400 ) -> Result<()> {
401 self.send(working::Request::Apply(working::Accepted {
402 author: author.to_owned(),
403 edit,
404 reply,
405 waiting: Some(waiting),
406 moving: None,
407 }))
408 }
409
410 /// The page in `space` as the queued edits leave it; O(page), for opening and reloading.
411 pub fn page(&self, space: ExGuid) -> Result<Page> {
412 self.ask(|reply| working::Request::Page { space, reply })
413 }
414
415 /// Page spaces, titles and outline levels (1 at the top) in section order.
416 pub fn pages(&self) -> Result<Vec<(ExGuid, String, u32)>> {
417 self.ask(|reply| working::Request::Pages { reply })
418 }
419
420 /// Each page's notebook-management identity, which internal links name.
421 pub fn identities(&self) -> Result<Vec<(ExGuid, Option<[u8; 16]>)>> {
422 self.ask(|reply| working::Request::Identities { reply })
423 }
424
425 /// The conflict pages of each page that has them (`onestore::Section::conflicts`).
426 pub fn conflicts(&self) -> Result<Vec<(ExGuid, Vec<onestore::ConflictPage>)>> {
427 self.ask(|reply| working::Request::Conflicts { reply })
428 }
429
430 /// The versions of each page that has them (`onestore::Section::versions`).
431 pub fn versions(&self) -> Result<Vec<(ExGuid, Vec<onestore::PageVersion>)>> {
432 self.ask(|reply| working::Request::Versions { reply })
433 }
434
435 /// A page as one of its versions holds it; O(section).
436 pub fn version(&self, space: ExGuid, version: ExGuid) -> Result<Page> {
437 self.ask(|reply| working::Request::Version {
438 space,
439 version,
440 reply,
441 })
442 }
443
444 /// The section image the queued edits leave, the unsealed ones sealed as one more
445 /// revision whose identities differ per call: O(section).
446 pub fn snapshot(&self) -> Result<Vec<u8>> {
447 self.ask(|reply| working::Request::Flush {
448 reply,
449 durable: false,
450 })?;
451 working::image(&*self.lock()?, self.section.key.as_ref())
452 }
453
454 /// Waits until the edits applied before it are durable in the local queue.
455 /// Browser callers use `written_async`; this returns `WouldBlock` without submitting.
456 pub fn written(&self) -> Result<()> {
457 task::blocking(self.written_async())?
458 }
459
460 /// Waits for durable local storage of the edits submitted before this request.
461 pub async fn written_async(&self) -> Result<()> {
462 self.ask_async(|reply| working::Request::Flush {
463 reply,
464 durable: true,
465 })
466 .await
467 }
468
469 /// The section file's identity, which internal links name as `section-id`.
470 pub fn identity(&self) -> Result<[u8; 16]> {
471 let stamp = base::base_stamp(&*self.lock()?)?;
472 Ok(onestore::Header::parse(&stamp.header)?.file_id)
473 }
474
475 /// Queued edits, oldest first.
476 pub fn pending(&self) -> Result<Vec<PendingEdit>> {
477 pending(&*self.lock()?, self.section.key.as_ref())
478 }
479
480 /// The edits putting each page the queue changed, as the queue leaves it, into another
481 /// section as a copy under fresh identities, by the author of the first edit changing it;
482 /// content outside the page model stays behind.
483 pub(crate) fn copies(&self) -> Result<Vec<(String, Edit)>> {
484 let arena = onestore::Arena::default();
485 let base = base::base(&*self.lock()?)?;
486 let base = working::open(&arena, base, self.section.key.as_ref())?;
487 let mut seen = std::collections::BTreeSet::from([self.root]);
488 let mut copies = Vec::new();
489 for queued in self.pending()? {
490 for space in queue::spaces(&queued.edit, self.root) {
491 if !seen.insert(space) {
492 continue;
493 }
494 let Ok(mut page) = self.page(space) else {
495 continue;
496 };
497 if base.page(space).is_ok_and(|base| base == page) {
498 continue;
499 }
500 page.objects
501 .retain(|object| !matches!(object, onestore::page::PageObject::Unsupported(_)));
502 let creation =
503 onestore::PageCreation::new(None, Some(&page.title), &queued.author)?;
504 let ops = vec![onestore::op::Op::Section(onestore::op::SectionOp::Import {
505 creation,
506 page: page.copy()?,
507 })];
508 copies.push((queued.author.clone(), Edit { at: now(), ops }));
509 }
510 }
511 Ok(copies)
512 }
513
514 fn wake_sync(&self) {
515 wake(&self.section.worker);
516 }
517}
518
519impl Drop for Replica {
520 fn drop(&mut self) {
521 self.section.stop();
522 }
523}
524
525/// The open cache's connection, for as long as its lock is held.
526struct Open<'a>(MutexGuard<'a, working::Cache>);
527
528impl std::ops::Deref for Open<'_> {
529 type Target = Connection;
530
531 fn deref(&self) -> &Connection {
532 match &*self.0 {
533 working::Cache::Open(connection) => connection,
534 _ => unreachable!("Only an open cache is lent"),
535 }
536 }
537}
538
539impl std::ops::DerefMut for Open<'_> {
540 fn deref_mut(&mut self) -> &mut Connection {
541 match &mut *self.0 {
542 working::Cache::Open(connection) => connection,
543 _ => unreachable!("Only an open cache is lent"),
544 }
545 }
546}
547
548/// The cache's connection; `WouldBlock` while a failed commit keeps the cache closed.
549fn lock(cache: &Mutex<working::Cache>) -> Result<Open<'_>> {
550 let cache = cache
551 .lock()
552 .map_err(|_| io::Error::other("Cache owner panicked"))?;
553 match &*cache {
554 working::Cache::Open(_) => Ok(Open(cache)),
555 working::Cache::Closed { .. } => {
556 Err(io::Error::new(io::ErrorKind::WouldBlock, "The cache reopens once it can").into())
557 }
558 working::Cache::Lost(error) => Err(io::Error::other(error.clone()).into()),
559 }
560}
561
562/// Tells the worker a burst of local edits is durable.
563fn edited(worker: &Mutex<std::sync::Weak<worker::Signal>>) {
564 if let Ok(worker) = worker.lock()
565 && let Some(worker) = worker.upgrade()
566 {
567 worker.edited();
568 }
569}
570
571fn wake(worker: &Mutex<std::sync::Weak<worker::Signal>>) {
572 if let Ok(worker) = worker.lock()
573 && let Some(worker) = worker.upgrade()
574 {
575 worker.wake();
576 }
577}
578
579/// Fully validates a section image, a protected one under `key`, returning its root object
580/// space.
581fn validate(source: &[u8], key: Option<&Key>) -> Result<ExGuid> {
582 let arena = onestore::Arena::default();
583 Ok(match key {
584 Some(key) => onestore::Section::unlock(&arena, source.to_vec(), key)?.root(),
585 None => onestore::Section::open(&arena, source.to_vec())?.root(),
586 })
587}
588
589/// A closed cache, without opening the replica.
590fn closed(path: &Path) -> Result<Connection> {
591 let connection = cache_connection(path)?;
592 let application: u32 =
593 connection.pragma_query_value(None, "application_id", |row| row.get(0))?;
594 let version: u32 = connection.pragma_query_value(None, "user_version", |row| row.get(0))?;
595 if application != APPLICATION_ID || version != schema::VERSION {
596 return Err(io::Error::from(io::ErrorKind::InvalidData).into());
597 }
598 Ok(connection)
599}
600
601/// A closed cache's base stamp and how many edits wait.
602fn peek(connection: &Connection) -> Result<(onestore::Stamp, u64)> {
603 let base = base::base_stamp(connection)?;
604 let queued: i64 = connection.query_row("SELECT count(*) FROM edits", [], |row| row.get(0))?;
605 Ok((base, unsigned(queued)?))
606}
607
608fn pending(connection: &Connection, key: Option<&Key>) -> Result<Vec<PendingEdit>> {
609 queue::load(connection, key, None)
610}
611
612fn unsigned(value: i64) -> Result<u64> {
613 Ok(u64::try_from(value).map_err(|_| io::Error::from(io::ErrorKind::InvalidData))?)
614}
615
616fn signed(value: u64) -> Result<i64> {
617 Ok(i64::try_from(value).map_err(|_| io::Error::from(io::ErrorKind::InvalidInput))?)
618}
619
620/// `connect`, busy while anyone owns the cache: SQLite's lock, or the `Owned` a section holds
621/// while a failed commit keeps the cache closed, checked once SQLite's is held, as that
622/// section takes its own before letting SQLite's go.
623fn cache_connection(path: &Path) -> Result<Connection> {
624 let connection = connect(path)?;
625 connection.query_row("SELECT count(*) FROM sqlite_schema", [], |_| Ok(()))?;
626 let owned = identity(path)
627 .is_ok_and(|identity| OWNED.lock().is_ok_and(|owned| owned.contains(&identity)))
628 || std::fs::File::open(owner_lock(path)).is_ok_and(|lock| {
629 matches!(
630 lock.try_lock_shared(),
631 Err(std::fs::TryLockError::WouldBlock)
632 )
633 });
634 if owned {
635 return Err(rusqlite::Error::SqliteFailure(
636 rusqlite::ffi::Error::new(rusqlite::ffi::SQLITE_BUSY),
637 Some("A section holds the cache while it reopens".into()),
638 )
639 .into());
640 }
641 Ok(connection)
642}
643
644/// The file beside a cache whose lock keeps it owned while a failed commit keeps it closed.
645fn owner_lock(cache: &Path) -> PathBuf {
646 let mut lock = cache.as_os_str().to_owned();
647 lock.push("-lock");
648 lock.into()
649}
650
651/// Caches an `Owned` holds in this process, where a lock on a network filesystem (`flock` over
652/// NFS on Linux) need not exclude.
653static OWNED: Mutex<std::collections::BTreeSet<Identity>> =
654 Mutex::new(std::collections::BTreeSet::new());
655
656/// A cache file however its path is spelled: its device and inode, or elsewhere its
657/// canonical path.
658#[cfg(unix)]
659type Identity = (u64, u64);
660#[cfg(not(unix))]
661type Identity = PathBuf;
662
663fn identity(cache: &Path) -> io::Result<Identity> {
664 #[cfg(unix)]
665 {
666 use std::os::unix::fs::MetadataExt;
667 let metadata = std::fs::metadata(cache)?;
668 Ok((metadata.dev(), metadata.ino()))
669 }
670 #[cfg(not(unix))]
671 std::fs::canonicalize(cache)
672}
673
674/// Ownership of a closed cache, which every open honours until it drops: `<cache>-lock`
675/// locked, and the cache listed in `OWNED`.
676struct Owned {
677 cache: PathBuf,
678 identity: Identity,
679 _lock: std::fs::File,
680}
681
682impl Owned {
683 fn take(cache: &Path) -> Result<Self> {
684 let lock = std::fs::File::options()
685 .create(true)
686 .truncate(false)
687 .write(true)
688 .open(owner_lock(cache))?;
689 lock.try_lock().map_err(io::Error::from)?;
690 let identity = identity(cache)?;
691 #[cfg_attr(unix, allow(clippy::clone_on_copy))]
692 (OWNED.lock())
693 .map_err(|_| io::Error::other("Cache owners panicked"))?
694 .insert(identity.clone());
695 Ok(Self {
696 cache: cache.to_owned(),
697 identity,
698 _lock: lock,
699 })
700 }
701}
702
703impl Drop for Owned {
704 fn drop(&mut self) {
705 if let Ok(mut owned) = OWNED.lock() {
706 owned.remove(&self.identity);
707 }
708 let _ = std::fs::remove_file(owner_lock(&self.cache));
709 }
710}
711
712/// Opens a cache without writing to it: exclusive locking, a full sync of every commit
713/// (`F_FULLFSYNC` on macOS, the WAL's syncs included) and foreign keys, each queried back.
714fn connect(path: &Path) -> Result<Connection> {
715 #[cfg(target_arch = "wasm32")]
716 fs::install_sqlite();
717 let connection = Connection::open_with_flags(path, OpenFlags::SQLITE_OPEN_READ_WRITE)?;
718 connection.busy_timeout(Duration::ZERO)?;
719 connection.execute_batch(
720 "PRAGMA locking_mode=EXCLUSIVE; PRAGMA synchronous=FULL; PRAGMA fullfsync=ON; PRAGMA foreign_keys=ON;",
721 )?;
722 let locking: String = connection.pragma_query_value(None, "locking_mode", |row| row.get(0))?;
723 let journal: String = connection.pragma_query_value(None, "journal_mode", |row| row.get(0))?;
724 if locking != "exclusive" || !["wal", "delete"].contains(&journal.as_str()) {
725 return Err(io::Error::new(
726 io::ErrorKind::InvalidData,
727 "Unsupported cache locking or journal mode",
728 )
729 .into());
730 }
731 for (name, expected) in [("synchronous", 2), ("fullfsync", 1), ("foreign_keys", 1)] {
732 let actual: i64 = connection.pragma_query_value(None, name, |row| row.get(0))?;
733 if actual != expected {
734 return Err(io::Error::new(
735 io::ErrorKind::Unsupported,
736 "Required cache synchronization is unavailable",
737 )
738 .into());
739 }
740 }
741 Ok(connection)
742}
743
744/// Switches a cache to write-ahead logging: a commit appends its pages to `<cache>-wal`
745/// instead of copying the originals to a rollback journal. Under exclusive locking the WAL
746/// index lives in memory, so the WAL is the only file beside the cache; it is checkpointed
747/// and removed on close, and replayed on the next open after a crash.
748fn write_ahead(connection: &Connection) -> Result<()> {
749 let mode: String =
750 connection.pragma_update_and_check(None, "journal_mode", "WAL", |row| row.get(0))?;
751 if mode != "wal" {
752 return Err(io::Error::new(
753 io::ErrorKind::Unsupported,
754 "The cache cannot use write-ahead logging",
755 )
756 .into());
757 }
758 Ok(())
759}
760
761/// FILETIME now, as an edit's `at`: later than any this process took before, as Windows 7's
762/// clock ticks only every 15.6 ms and a later edit must still order after an earlier one.
763pub(crate) fn now() -> u64 {
764 use std::sync::atomic::{AtomicU64, Ordering};
765 static LAST: AtomicU64 = AtomicU64::new(0);
766 let unix = web_time::SystemTime::now()
767 .duration_since(web_time::UNIX_EPOCH)
768 .unwrap_or_default();
769 let clock =
770 (unix.as_secs() + 11_644_473_600) * 10_000_000 + u64::from(unix.subsec_nanos() / 100);
771 let previous = LAST
772 .try_update(Ordering::Relaxed, Ordering::Relaxed, |last| {
773 Some(clock.max(last + 1))
774 })
775 .unwrap_or_default();
776 clock.max(previous + 1)
777}