mnemo_engine/store/shared.rs
1//! 12.4 shared mode's handle (v0.14.0 step 2b): [`SharedMnemo`], from
2//! [`Mnemo::open_shared`]. The design is `docs/design/12.4-shared-access.md`,
3//! "The protocol" steps 4 to 8, "Catching up" (the full reload) and "Writes
4//! that only this handle makes".
5//!
6//! A shared handle holds no lock and no descriptor on the brain between
7//! calls. Each call is a **window** on the file:
8//! 1. take the lock through the lock layer (`crate::shared`): shared for
9//! [`SharedMnemo::read`], exclusive for [`SharedMnemo::write`];
10//! 2. catch up: compare the header's seal (and, on Unix, the file's
11//! identity) with the stamp of the state the handle holds, and reload
12//! if they differ. A pending WAL or a torn page 0 takes the exclusive
13//! lock first, then replays or heals, then reloads;
14//! 3. run the caller's closure on the handle: read-only for a read, with
15//! access statistics kept as a delta; for a write, the stamp is cleared
16//! first, the generation lease is reset (the first page the window seals
17//! takes a fresh one), the delta is applied, and the window commits
18//! before it lets go;
19//! 4. unlock and close.
20
21use std::collections::HashMap;
22use std::sync::Arc;
23
24use zeroize::Zeroizing;
25
26use super::*;
27use crate::shared::{BrainLocks, Call, CancelToken, LockKind, SharedOptions};
28
29/// Access statistics a shared handle saw while it held only the shared lock
30/// (recall hits, cache hits): applied with the handle's next commit, and
31/// dropped at close (12.4 design note, "Writes that only this handle
32/// makes").
33#[derive(Clone, Debug, Default)]
34pub(crate) struct AccessDelta {
35 /// Memory id → (hits, latest hit).
36 memories: HashMap<u128, (u32, i64)>,
37 /// (namespace, key hash) → (hits, latest hit).
38 cache: HashMap<(String, [u8; 32]), (u32, i64)>,
39}
40
41impl AccessDelta {
42 pub(crate) fn memory_hit(&mut self, id: u128, at: i64) {
43 let e = self.memories.entry(id).or_insert((0, at));
44 e.0 = e.0.saturating_add(1);
45 e.1 = e.1.max(at);
46 }
47
48 pub(crate) fn cache_hit(&mut self, namespace: &str, key_hash: [u8; 32], at: i64) {
49 let e = self
50 .cache
51 .entry((namespace.to_string(), key_hash))
52 .or_insert((0, at));
53 e.0 = e.0.saturating_add(1);
54 e.1 = e.1.max(at);
55 }
56}
57
58impl Mnemo {
59 /// Open the brain at `path` in **shared mode** (12.4): several
60 /// processes, sessions and tools can use one file at once. The handle
61 /// takes the file's lock for each call and holds nothing between calls.
62 ///
63 /// The file must exist and be v9; shared mode never creates one. It's
64 /// refused on a network or synced filesystem unless
65 /// [`SharedOptions::allow_network_fs`], and on Windows builds made with
66 /// Rust before 1.85 ([`MnemoError::Unsupported`]).
67 ///
68 /// The handle **keeps its secret** for its whole life, because every
69 /// compaction gives the file a new data key: without the secret, a
70 /// handle couldn't follow a `mnemo compact`. The passphrase is zeroized
71 /// when the handle drops.
72 ///
73 /// Use [`SharedMnemo::read`] and [`SharedMnemo::write`] to call the
74 /// handle's methods. Rust API only for now; the Python, CLI and MCP
75 /// surfaces come later.
76 pub fn open_shared(
77 path: impl AsRef<Path>,
78 passphrase: &str,
79 opts: SharedOptions,
80 ) -> Result<SharedMnemo> {
81 let mut s = SharedMnemo::open(path.as_ref(), passphrase.as_bytes(), opts)?;
82 // 12.3 (the keys note, section 1, rule 7).
83 let kdf = s.read(|db| Ok(db.kdf_params()))?;
84 if let Some(n) = super::open::passphrase_floor_notice(&s.path, kdf) {
85 s.locks.notice(n);
86 }
87 Ok(s)
88 }
89
90 /// [`Mnemo::open_shared`] for a raw-key file.
91 pub fn open_shared_with_key(
92 path: impl AsRef<Path>,
93 key: &[u8; crypto::KEY_LEN],
94 opts: SharedOptions,
95 ) -> Result<SharedMnemo> {
96 SharedMnemo::open(path.as_ref(), key, opts)
97 }
98
99 /// Apply a shared handle's statistics delta to the catalog and the cache
100 /// directory, marking them dirty for this window's commit.
101 fn apply_access_delta(&mut self, d: &AccessDelta) {
102 for (id, (n, at)) in &d.memories {
103 if let Some(idx) = self.index.get(*id, &self.catalog) {
104 self.touch(idx);
105 let e = &mut self.catalog[idx];
106 e.access_count = e.access_count.saturating_add(*n);
107 e.accessed_at = e.accessed_at.max(*at);
108 self.dirty_catalog = true;
109 }
110 }
111 for ((ns, key), (n, at)) in &d.cache {
112 for e in self.cache_dir.iter_mut() {
113 if !e.deleted && e.namespace == *ns && e.key_hash == *key {
114 e.access_count = e.access_count.saturating_add(*n);
115 e.accessed_at = e.accessed_at.max(*at);
116 self.dirty_cache = true;
117 }
118 }
119 }
120 }
121}
122
123/// The settings that decide what a commit does to the whole file. In v0.14
124/// a shared handle keeps the defaults and refuses a change.
125#[derive(PartialEq, Debug)]
126struct FileSettings {
127 max_snapshots: usize,
128 snapshot_cap_explicit: bool,
129 turn_compress_after: i64,
130 /// The per-namespace budgets themselves, sorted: a changed value is a
131 /// change, not only an added or removed namespace.
132 cache_budgets: Vec<(String, usize, u64)>,
133 cache_flush_policy: String,
134}
135
136impl FileSettings {
137 fn of(db: &Mnemo) -> Self {
138 FileSettings {
139 max_snapshots: db.max_snapshots,
140 snapshot_cap_explicit: db.snapshot_cap_explicit,
141 turn_compress_after: db.turn_compress_after,
142 cache_budgets: {
143 let mut b: Vec<_> = db
144 .cache_budgets
145 .iter()
146 .map(|(ns, b)| (ns.clone(), b.max_entries, b.max_bytes))
147 .collect();
148 b.sort();
149 b
150 },
151 cache_flush_policy: format!("{:?}", db.cache_flush_policy),
152 }
153 }
154}
155
156const SETTINGS_KEPT: &str = "a shared-mode handle keeps the file's default settings in v0.14 \
157 (snapshot retention, cache budgets, the cache flush policy, turn compression): every \
158 process's commits would apply one handle's setting to the whole file";
159
160fn settings_refused() -> MnemoError {
161 MnemoError::Unsupported(format!("{SETTINGS_KEPT}. Nothing was changed"))
162}
163
164/// RB-007.5: the window's closure committed part of its work itself (a
165/// `flush`, or a method that commits, such as `commit_deltas`) before `e`.
166fn part_stored(e: impl std::fmt::Display) -> MnemoError {
167 MnemoError::MaybeStored(format!(
168 "{e}; an earlier commit in this window is in the file, so part of the window \
169 was stored"
170 ))
171}
172
173/// A read had to heal the file (a pending WAL, a torn page 0) and this
174/// process can't open it for writing (RB-007.8 item 5).
175const HEAL_NEEDS_WRITE: &str = "the file has a pending WAL or a torn header to recover, \
176 and this process can't write to it";
177
178/// What tells a shared handle that the file changed (12.4 protocol step 5):
179/// the header's seal, which gets a fresh random nonce on every header
180/// write, with the file's identity as the quick first test on Unix.
181#[derive(Clone, Copy, PartialEq, Eq, Debug)]
182struct Stamp {
183 identity: Option<(u64, u64)>,
184 seal: Option<([u8; crypto::NONCE_LEN], [u8; crypto::TAG_LEN])>,
185}
186
187impl Stamp {
188 fn of(file: &File, header: &Header) -> Self {
189 Stamp {
190 identity: identity(file),
191 seal: header.seal_nonce.zip(header.seal_tag),
192 }
193 }
194}
195
196#[cfg(unix)]
197fn identity(file: &File) -> Option<(u64, u64)> {
198 use std::os::unix::fs::MetadataExt;
199 file.metadata().ok().map(|m| (m.dev(), m.ino()))
200}
201
202/// Off Unix the seal alone tells (std has no stable file index there).
203#[cfg(not(unix))]
204fn identity(_file: &File) -> Option<(u64, u64)> {
205 None
206}
207
208fn read_page0(file: &mut File) -> std::io::Result<[u8; PAGE_SIZE]> {
209 let mut page = [0u8; PAGE_SIZE];
210 file.seek(SeekFrom::Start(0))?;
211 file.read_exact(&mut page)?;
212 Ok(page)
213}
214
215/// After catching up: go on, or take the exclusive lock first.
216enum Next {
217 Ready,
218 NeedExclusive,
219}
220
221/// A brain opened in shared mode (12.4): see [`Mnemo::open_shared`].
222///
223/// Every call goes through [`SharedMnemo::read`] or [`SharedMnemo::write`],
224/// which give the closure the handle for one window on the file:
225///
226/// ```no_run
227/// # use mnemo_engine::{Memory, MemoryType, Mnemo, SharedOptions, RecallRequest};
228/// # fn main() -> mnemo_engine::Result<()> {
229/// let mut brain = Mnemo::open_shared("team.mnemo", "passphrase", SharedOptions::default())?;
230/// let id = brain.write(|db| db.remember(Memory::new("we ship on Fridays", MemoryType::Semantic, vec![0.1, 0.2])))?;
231/// let hits = brain.read(|db| db.recall(&RecallRequest::new(vec![0.1, 0.2]).top_k(5)))?;
232/// # let _ = (id, hits); Ok(()) }
233/// ```
234///
235/// - **A read** runs under the shared lock, on a read-only handle. A
236/// recall's or a cache hit's access statistics are kept and applied with
237/// this handle's next write; they're dropped at [`SharedMnemo::close`].
238/// - **A write** runs under the exclusive lock and commits before the
239/// window ends. If it fails before the commit point, nothing was stored,
240/// for a closure that doesn't commit by itself. A closure that does (it
241/// calls `flush`, or a method that commits, such as `commit_deltas` or
242/// `restore_to`) and then fails gets [`MnemoError::MaybeStored`], saying
243/// part of the window is in the file. If the window's own commit fails
244/// after its commit point, the handle finishes the commit itself and
245/// returns `Ok`, or returns [`MnemoError::MaybeStored`]. If the file was
246/// renamed away during the commit, [`MnemoError::ReplacedDuringWrite`].
247/// Keep to one engine call per window where you can.
248/// - **Access statistics** a failed write window applied are dropped when
249/// its commit fails; they're statistics, and the next hits count again.
250/// - **Settings** that act on the whole file (snapshot retention, cache
251/// budgets, the cache flush policy, turn compression) are refused in
252/// v0.14 with [`MnemoError::Unsupported`], and so is `rekey` inside a
253/// closure (use [`SharedMnemo::rekey`], which also updates the secret the
254/// handle keeps). The page cache's size, the vector cache budget and the
255/// embedder (however it was set) are kept across reloads.
256/// - **A cancel** ([`SharedMnemo::set_cancel`]) reaches only a call that is
257/// waiting for a lock; once a call holds the lock it runs to its end.
258pub struct SharedMnemo {
259 locks: BrainLocks,
260 opts: SharedOptions,
261 path: PathBuf,
262 secret: Zeroizing<Vec<u8>>,
263 db: Option<Mnemo>,
264 /// `None` means "reload at the next call" (12.4 protocol step 7).
265 stamp: Option<Stamp>,
266 delta: AccessDelta,
267 embedder: Option<Arc<dyn Embedder>>,
268 reloads: u64,
269 /// What the last [`SharedMnemo::rekey`] couldn't scrub.
270 rekey_cleanup: Option<String>,
271}
272
273impl std::fmt::Debug for SharedMnemo {
274 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
275 f.debug_struct("SharedMnemo")
276 .field("path", &self.path)
277 .field("loaded", &self.db.is_some())
278 .field("reloads", &self.reloads)
279 .finish()
280 }
281}
282
283impl SharedMnemo {
284 fn open(path: &Path, secret: &[u8], opts: SharedOptions) -> Result<SharedMnemo> {
285 let locks = BrainLocks::new(path, &opts)?;
286 let mut s = SharedMnemo {
287 locks,
288 opts,
289 path: absolute(path.to_path_buf()),
290 secret: Zeroizing::new(secret.to_vec()),
291 db: None,
292 stamp: None,
293 delta: AccessDelta::default(),
294 embedder: None,
295 reloads: 0,
296 rekey_cleanup: None,
297 };
298 // Load now, so a wrong secret or an old format fails at open.
299 s.read(|_| Ok(()))?;
300 Ok(s)
301 }
302
303 /// Run `f` on the handle under the file's shared lock, after catching up
304 /// with any other process's commits. The handle is read-only inside;
305 /// recall's default access tracking works and is applied with this
306 /// handle's next write.
307 pub fn read<R>(&mut self, f: impl FnOnce(&mut Mnemo) -> Result<R>) -> Result<R> {
308 self.window(LockKind::Shared, |s| s.run_read(f))
309 }
310
311 /// Run `f` on the handle under the file's exclusive lock, after catching
312 /// up, and commit before the lock is released. See [`SharedMnemo`] for
313 /// what each failure means.
314 ///
315 /// A closure that commits part of its work itself and then fails, or
316 /// then changes a setting, gets [`MnemoError::MaybeStored`]: the earlier
317 /// commit is in the file.
318 pub fn write<R>(&mut self, f: impl FnOnce(&mut Mnemo) -> Result<R>) -> Result<R> {
319 self.window(LockKind::Exclusive, |s| s.run_write(f))
320 }
321
322 /// Attach an embedder (as [`Mnemo::set_embedder`]). It's kept across
323 /// reloads. When the file already records this embedder's identity,
324 /// this is a read window and writes nothing; otherwise the identity is
325 /// recorded in a write window.
326 pub fn set_embedder<E: Embedder + 'static>(&mut self, embedder: E) -> Result<()> {
327 let identity = embedder.identity();
328 let needs_write = self.read(move |db| {
329 if db.embedder_would_record(&identity)? {
330 return Ok(Some(embedder));
331 }
332 db.set_embedder(embedder)?;
333 Ok(None)
334 })?;
335 if let Some(embedder) = needs_write {
336 self.write(|db| db.set_embedder(embedder))?;
337 }
338 Ok(())
339 }
340
341 /// Change the passphrase (as [`Mnemo::rekey`], in a write window), and
342 /// replace the secret the handle keeps once the new one is in force, so
343 /// the handle can still follow a compaction or recover the file
344 /// afterwards. An error leaves the old secret in force and kept, unless
345 /// it says the file may open with either.
346 pub fn rekey(&mut self, new_passphrase: &str, kdf: KdfParams) -> Result<()> {
347 self.rekey_secret(new_passphrase.as_bytes(), SecretKind::Passphrase, kdf)
348 }
349
350 /// [`SharedMnemo::rekey`] to a raw 256-bit key (as
351 /// [`Mnemo::rekey_with_key`]).
352 pub fn rekey_with_key(&mut self, new_key: &[u8; crypto::KEY_LEN]) -> Result<()> {
353 self.rekey_secret(new_key, SecretKind::Key, KdfParams::raw_key())
354 }
355
356 /// After a successful [`SharedMnemo::rekey`], what couldn't be scrubbed
357 /// of the old key wrap (see [`Mnemo::rekey_cleanup_error`]).
358 pub fn rekey_cleanup_error(&self) -> Option<&str> {
359 self.rekey_cleanup.as_deref()
360 }
361
362 fn rekey_secret(&mut self, secret: &[u8], kind: SecretKind, kdf: KdfParams) -> Result<()> {
363 // The rekey window applies no statistics, so its only commit is the
364 // rekey's and its errors are the rekey's own; the next write applies
365 // them.
366 let held_back = std::mem::take(&mut self.delta);
367 let mut in_force = None;
368 let r = self.write(|db| {
369 db.rekey_unchecked(secret, kind, kdf, None)?;
370 in_force = Some(db.rekey_cleanup.clone());
371 Ok(())
372 });
373 self.delta = held_back;
374 if let Some(cleanup) = in_force {
375 self.secret = Zeroizing::new(secret.to_vec());
376 self.rekey_cleanup = cleanup;
377 }
378 r
379 }
380
381 /// Give the handle a new cancel token for its later calls, or none
382 /// (RB-007.1). A cancelled token stays cancelled, so after a cancel the
383 /// handle needs a new one (or `None`) to wait for a lock again. A cancel
384 /// reaches only a call that is waiting for a lock.
385 pub fn set_cancel(&mut self, token: Option<CancelToken>) {
386 self.opts.cancel = token;
387 }
388
389 /// The embedder attached to the handle, if any (shared, so a binding can
390 /// embed outside a window and then call [`SharedMnemo::write`]).
391 pub fn embedder_arc(&self) -> Option<Arc<dyn Embedder>> {
392 self.embedder.clone()
393 }
394
395 /// The warnings to show once: a sidecar directory that can't be used, a
396 /// synced folder, an allowed network filesystem.
397 pub fn notices(&self) -> &[String] {
398 self.locks.notices()
399 }
400
401 /// The handle's options: those it was opened with, and the cancel token
402 /// [`SharedMnemo::set_cancel`] gave it last.
403 pub fn options(&self) -> &SharedOptions {
404 &self.opts
405 }
406
407 /// Close the handle. It holds no lock between calls, so this only drops
408 /// what it kept: the secret (zeroized) and the access statistics no
409 /// write has applied yet.
410 pub fn close(self) -> Result<()> {
411 Ok(())
412 }
413
414 /// **Not a stable API** (failpoints builds only). How many times the
415 /// handle has rebuilt its state from the file.
416 #[cfg(any(test, feature = "failpoints"))]
417 #[doc(hidden)]
418 pub fn __reloads(&self) -> u64 {
419 self.reloads
420 }
421
422 /// **Not a stable API** (failpoints builds only). The page cache's
423 /// occupancy and capacity.
424 #[cfg(any(test, feature = "failpoints"))]
425 #[doc(hidden)]
426 pub fn __page_cache(&self) -> (usize, usize) {
427 self.db.as_ref().map_or((0, 0), |d| d.pager.cache_stats())
428 }
429
430 /// **Not a stable API** (failpoints builds only). The handle's state as
431 /// it stands, without a window (no lock, no catch-up): for tests that
432 /// look at what a failed call left in memory. No file is attached, so
433 /// only calls that stay in memory may be made; one that reads or
434 /// writes the file panics.
435 #[cfg(any(test, feature = "failpoints"))]
436 #[doc(hidden)]
437 pub fn __state(&mut self) -> Option<&mut Mnemo> {
438 self.db.as_mut()
439 }
440
441 /// One window: lock, catch up, run, unlock. One [`Call`], so one
442 /// deadline and one cancel token, covers every lock it takes.
443 fn window<R>(&mut self, kind: LockKind, run: impl FnOnce(&mut Self) -> Result<R>) -> Result<R> {
444 let mut call = Call::new(self.opts.deadline, self.opts.cancel.as_ref());
445 let mut lock = kind;
446 let held = loop {
447 let mut held = match self.locks.acquire(lock, &mut call) {
448 Ok(h) => h,
449 // A read that has to heal the file, which this process can
450 // only read.
451 Err(MnemoError::Io(e))
452 if lock != kind && e.kind() == std::io::ErrorKind::PermissionDenied =>
453 {
454 return Err(MnemoError::NeedsWriteOpen {
455 reason: HEAL_NEEDS_WRITE,
456 })
457 }
458 Err(e) => return Err(e),
459 };
460 let file = held.take_file();
461 match self.catch_up(lock, file)? {
462 Next::Ready => break held,
463 // A pending WAL or a torn page 0 under the shared lock:
464 // heal it under the exclusive one, then carry on.
465 Next::NeedExclusive => lock = LockKind::Exclusive,
466 }
467 };
468 // The pager now holds the call's locked file. Release it however
469 // `run` ends: a closure that panics, caught by the caller (UniFFI
470 // catches panics at its boundary, and so do thread pools and
471 // `catch_unwind`), must not leave the handle holding the lock. So
472 // the unwind is caught here, the lock released, and the panic
473 // resumed. A write window has cleared its stamp before running the
474 // closure, so the handle's next call reloads.
475 let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| run(self)));
476 // The lock-info note (if any) goes before the unlock.
477 drop(held);
478 if let Some(db) = self.db.as_mut() {
479 drop(db.pager.detach_file());
480 // An embedder set inside a closure is kept across reloads too
481 // (RB-007.8 item 4).
482 self.embedder = db.embedder.clone();
483 }
484 match r {
485 Ok(r) => r,
486 Err(panic) => {
487 // Whatever the closure left half done in memory, read or
488 // write, is reloaded by the next call (RB-007.8 item 6).
489 self.stamp = None;
490 std::panic::resume_unwind(panic)
491 }
492 }
493 }
494
495 /// 12.4 protocol steps 5 and 6 (the identity check of step 4 ran in the
496 /// lock layer): leave `self.db` current, holding `file`.
497 fn catch_up(&mut self, lock: LockKind, mut file: LockedFile) -> Result<Next> {
498 let header = match read_page0(&mut file)
499 .map_err(MnemoError::Io)
500 .and_then(|p| Header::from_page(&p))
501 {
502 Ok(h) => h,
503 // A torn page 0: the scan that heals it reads the whole file and
504 // runs the KDF per candidate, so never under the shared lock.
505 Err(_) if lock == LockKind::Shared => return Ok(Next::NeedExclusive),
506 Err(_) => return self.load(file),
507 };
508 let pending = wal::recover(
509 &mut file,
510 header.wal_start,
511 header.wal_pages,
512 header.wal_seq,
513 )?
514 .is_some();
515 if pending {
516 if lock == LockKind::Shared {
517 return Ok(Next::NeedExclusive);
518 }
519 // Replay, then always reload: the replay moved page 0 past the
520 // handle's state.
521 return self.load(file);
522 }
523 let stamp = Stamp::of(&file, &header);
524 if let (Some(db), Some(held)) = (self.db.as_mut(), self.stamp) {
525 if held == stamp {
526 db.pager.attach_file(file);
527 return Ok(Next::Ready);
528 }
529 }
530 // Another commit (the seal verifies under the key the handle
531 // holds): rebuild from the file without the KDF.
532 if let Some(old) = &self.db {
533 if header.validate_seal(old.pager.dek()).is_ok() {
534 let dek = Zeroizing::new(*old.pager.dek());
535 let kdf = KdfParams {
536 m_cost: header.m_cost,
537 t_cost: header.t_cost,
538 p_cost: header.p_cost,
539 };
540 let new = Mnemo::from_locked(self.path.clone(), file, header, dek, kdf, false)?;
541 self.install(new);
542 return Ok(Next::Ready);
543 }
544 }
545 // The seal doesn't verify under the held key (a compaction's new
546 // data key, a file copied over this one) or nothing is loaded yet:
547 // open it with the kept secret, which returns the specific error
548 // (`WrongPassphrase`, `HeaderTampered`) if that fails too.
549 self.load(file)
550 }
551
552 /// The full open on the call's locked file (heal, replay), then install
553 /// it.
554 fn load(&mut self, file: LockedFile) -> Result<Next> {
555 let new = self.reopen(file)?;
556 self.install(new);
557 Ok(Next::Ready)
558 }
559
560 /// Open the call's locked file as `open` does (heal a torn page 0,
561 /// replay a pending WAL), with the data key the handle holds when the
562 /// header it would recover to verifies under it (no KDF), and the kept
563 /// secret otherwise (RB-007.2): a rekey by another process changes the
564 /// secret but not the data key.
565 fn reopen(&self, file: LockedFile) -> Result<Mnemo> {
566 let held = self.db.as_ref().map(|d| Zeroizing::new(*d.pager.dek()));
567 Mnemo::load_locked_with(
568 self.path.clone(),
569 file,
570 &self.secret,
571 held.as_deref(),
572 false,
573 )
574 }
575
576 /// Take `new` as the handle's state: carry over what is per-process (the
577 /// page cache's size, the vector cache budget, the embedder), and stamp
578 /// it.
579 fn install(&mut self, mut new: Mnemo) {
580 if let Some(old) = &self.db {
581 new.pager.set_cache_capacity(old.pager.cache_stats().1);
582 new.set_vector_cache_budget(old.vector_cache_budget);
583 }
584 if let Some(e) = &self.embedder {
585 new.embedder = Some(e.clone());
586 }
587 new.shared = true;
588 self.stamp = Some(Stamp::of(new.pager.file(), &new.header));
589 self.db = Some(new);
590 self.reloads += 1;
591 }
592
593 fn run_read<R>(&mut self, f: impl FnOnce(&mut Mnemo) -> Result<R>) -> Result<R> {
594 let db = self.db.as_mut().expect("loaded by the window");
595 db.read_only = true;
596 db.access_delta = Some(std::mem::take(&mut self.delta));
597 let before = FileSettings::of(db);
598 let r = f(db);
599 db.read_only = false;
600 self.delta = db.access_delta.take().unwrap_or_default();
601 if FileSettings::of(db) != before {
602 self.stamp = None;
603 return Err(settings_refused());
604 }
605 r
606 }
607
608 fn run_write<R>(&mut self, f: impl FnOnce(&mut Mnemo) -> Result<R>) -> Result<R> {
609 // Cleared before anything touches the handle's memory, set again
610 // only from a successful commit: an error, or a panic, leaves the
611 // next call to reload (protocol step 7).
612 self.stamp = None;
613 let db = self.db.as_mut().expect("loaded by the window");
614 db.read_only = false;
615 db.access_delta = None;
616 db.commit_point = None;
617 db.window_committed = false;
618 // No lease carries over from an earlier window. Every place that
619 // seals a page takes the lease first when it's missing
620 // (`ensure_gen_lease`), so every page this window seals carries a
621 // generation no other writer has used, even when windows interleave
622 // and one fails before its commit; and a window that seals nothing
623 // commits nothing (RB-007.6).
624 db.gen_leased = false;
625 let delta = std::mem::take(&mut self.delta);
626 db.apply_access_delta(&delta);
627 let before = FileSettings::of(db);
628 let r = f(db).map_err(in_shared_window);
629 let db = self.db.as_mut().expect("loaded by the window");
630 let r = match r {
631 Ok(r) => r,
632 // A commit inside the closure finished (RB-007.5), or got past
633 // its commit point, before the error: it may be in the file.
634 Err(e) if db.window_committed => return Err(part_stored(e)),
635 Err(e) if db.commit_point.is_some() => {
636 return Err(MnemoError::MaybeStored(e.to_string()))
637 }
638 Err(e) => {
639 self.delta = delta;
640 return Err(e);
641 }
642 };
643 if FileSettings::of(db) != before {
644 if db.window_committed || db.commit_point.is_some() {
645 return Err(part_stored(format!(
646 "{SETTINGS_KEPT}, so the setting wasn't applied"
647 )));
648 }
649 self.delta = delta;
650 return Err(settings_refused());
651 }
652 let committed_before = db.window_committed;
653 #[cfg(any(test, feature = "failpoints"))]
654 crate::__failpoints::run_before_shared_commit();
655 if let Err(e) = db.flush().map_err(in_shared_window) {
656 match self.finish_failed_commit(e) {
657 Ok(()) => {}
658 Err(e @ MnemoError::MaybeStored(_)) => return Err(e),
659 Err(e) if committed_before => return Err(part_stored(e)),
660 Err(e) => return Err(e),
661 }
662 }
663 #[cfg(any(test, feature = "failpoints"))]
664 crate::__failpoints::run_after_shared_commit();
665 // Protocol step 8: the path must still name the file just written.
666 let db = self.db.as_ref().expect("loaded");
667 if !is_file_at(db.pager.file(), &db.path)? {
668 return Err(MnemoError::ReplacedDuringWrite {
669 path: db.path.clone(),
670 });
671 }
672 self.stamp = Some(Stamp::of(db.pager.file(), &db.header));
673 Ok(r)
674 }
675
676 /// A commit failed (protocol step 7). Before the WAL's commit point,
677 /// nothing was stored: return the error. After it, finish the commit
678 /// from the WAL (the same replay an open does) and return `Ok` if the
679 /// transaction is in the file, or [`MnemoError::MaybeStored`] if that
680 /// can't be found out.
681 fn finish_failed_commit(&mut self, e: MnemoError) -> Result<()> {
682 let db = self.db.as_mut().expect("loaded");
683 let Some(txn) = db.commit_point.take() else {
684 return Err(e);
685 };
686 let Some(mut file) = db.pager.detach_file() else {
687 return Err(MnemoError::MaybeStored(e.to_string()));
688 };
689 // Replay a pending transaction here, through the write failpoint,
690 // so a test can fail this step too; `load_locked` then finds the
691 // file current (or heals a torn page 0 itself).
692 let replay = (|| -> Result<()> {
693 let Ok(header) = read_page0(&mut file)
694 .map_err(MnemoError::Io)
695 .and_then(|p| Header::from_page(&p))
696 else {
697 return Ok(());
698 };
699 if let Some(frames) = wal::recover(
700 &mut file,
701 header.wal_start,
702 header.wal_pages,
703 header.wal_seq,
704 )? {
705 for (page_no, bytes) in &frames {
706 crate::pager::__failpoint_check()?;
707 file.seek(SeekFrom::Start(page_no * PAGE_SIZE as u64))?;
708 file.write_all(bytes)?;
709 }
710 file.sync_all()?;
711 crate::bump_fsync();
712 }
713 Ok(())
714 })();
715 if let Err(e2) = replay {
716 return Err(MnemoError::MaybeStored(format!(
717 "{e}; finishing the commit failed too: {e2}"
718 )));
719 }
720 match self.reopen(file) {
721 Ok(new) => {
722 let stored = new.header.wal_seq >= txn;
723 self.install(new);
724 if stored {
725 Ok(())
726 } else {
727 // The commit never became durable: nothing was stored,
728 // and the handle now holds the file as it is.
729 self.stamp = None;
730 Err(e)
731 }
732 }
733 Err(e2) => Err(MnemoError::MaybeStored(format!(
734 "{e}; reading the file back failed: {e2}"
735 ))),
736 }
737 }
738}
739
740/// A commit's pre-write identity check (`Mnemo::ensure_not_replaced`) inside
741/// a write window: the rename came after the window's own identity check
742/// (protocol step 4), from something renaming without the lock (an older
743/// build's compaction). Nothing was written, and the stamp is already
744/// cleared, so the next call follows the new file: say that instead of the
745/// plain handle's "reopen it".
746fn in_shared_window(e: MnemoError) -> MnemoError {
747 match e {
748 MnemoError::Replaced { path, missing, .. } => MnemoError::Replaced {
749 path,
750 shared: true,
751 missing,
752 },
753 e => e,
754 }
755}