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