Skip to main content

coven_database/
database.rs

1//! Opening is the composition root; a shared handle owns all connections and
2//! the writer lock. Blocking calls retain these resources after its last owner
3//! drops, while another open waits for their release.
4
5use crate::store_call::StoreCall;
6use coven_foundation::locks::{lock_unpoisoned, read_unpoisoned, write_unpoisoned};
7use coven_foundation::task::{blocking_completing, CarriesBug};
8use std::collections::BTreeSet;
9use std::sync::{Arc, Mutex, RwLock};
10
11#[path = "file_database.rs"]
12pub(crate) mod file_database;
13
14#[path = "database_local_bytes.rs"]
15pub(crate) mod local_bytes;
16
17#[path = "library_bytes.rs"]
18pub(crate) mod library_bytes;
19
20#[path = "archive_bytes.rs"]
21pub(crate) mod archive_bytes;
22
23#[path = "database_mode.rs"]
24mod mode;
25pub use mode::{Mode, ReadOnly, Writer};
26
27#[path = "file_staging.rs"]
28mod file_staging;
29pub use file_staging::StagedFiles;
30
31#[path = "input_database.rs"]
32pub(crate) mod input_database;
33
34#[path = "database_operations.rs"]
35mod operations;
36#[path = "database_provider_access.rs"]
37mod provider_access;
38
39#[path = "database_changes.rs"]
40mod changes;
41#[path = "circle_rebuild.rs"]
42mod circle_rebuild;
43#[path = "database_file_retention.rs"]
44pub(crate) mod file_retention;
45#[path = "database_live_queries.rs"]
46mod live_queries;
47#[path = "database_snapshots.rs"]
48mod snapshots;
49pub use circle_rebuild::{ExportStopped, RebuildDatabase, RebuildError};
50
51#[cfg(any(test, feature = "test-utils"))]
52#[path = "database_operations_tests.rs"]
53pub(crate) mod operation_tests;
54
55use coven_foundation::clock::{ClockRef, SystemClock};
56use coven_foundation::files::{StoreDir, StoreLock};
57use coven_foundation::id_source::FileId;
58use coven_foundation::id_source::{DeviceId, IdSourceRef, UuidIds};
59
60use crate::app_policy::CovenPolicy;
61use crate::read::RunningRead;
62use crate::sqlite::StoreSql;
63use crate::store_failure::StoreFailure;
64use crate::store_failure::StoreHandle;
65use crate::write_failure::Hosted;
66use crate::{DbError, Migration, MigrationOutcome, SyncedTable};
67use crate::{LiveQuery, LostValue, Read, SqlReadContext};
68use sqlive::Setup;
69
70#[path = "database_builder.rs"]
71mod builder;
72#[cfg(test)]
73pub(crate) use builder::coven_only;
74#[path = "database_store.rs"]
75mod store;
76
77#[path = "database_call.rs"]
78mod call;
79#[path = "database_connection_calls.rs"]
80mod connection_calls;
81#[path = "database_retry.rs"]
82mod retry;
83#[path = "database_sync.rs"]
84mod sync;
85pub use builder::{
86    closed_sync_facts, discarded_operations, discarded_store_name, read_device_id_in_use,
87    read_store_name, DatabaseBuilder,
88};
89pub(crate) use call::{finish_blocking, process, start_call};
90
91/// Shared ownership of the database, as its writer or a read-only handle
92/// (`StoreDatabase<ReadOnly>`), which reads the store through the same calls and
93/// cannot write synced rows or migrate. A read-only handle's connections can
94/// change only local cache metadata, and its shared store lock prevents
95/// deletion until all of them close. Closing any clone closes them all.
96///
97/// ```compile_fail
98/// async fn cannot_write(handle: &coven_database::Database<coven_database::ReadOnly>) {
99///     handle.write(|_| Ok(())).await;
100/// }
101/// ```
102/// ```compile_fail
103/// fn cannot_subscribe(handle: &coven_database::Database<coven_database::ReadOnly>) {
104///     handle.subscribe(|_| Ok::<_, coven_database::DbError>(()));
105/// }
106/// ```
107/// ```compile_fail
108/// fn cannot_reconfigure(handle: &coven_database::Database<coven_database::ReadOnly>) {
109///     handle.subscribe_reconfigurable((), |_, _| Ok::<_, coven_database::DbError>(()));
110/// }
111/// ```
112/// ```compile_fail
113/// fn cannot_subscribe_losses(handle: &coven_database::Database<coven_database::ReadOnly>) {
114///     handle.subscribe_lost_values();
115/// }
116/// ```
117/// ```compile_fail
118/// fn sends_nothing(handle: &coven_database::Database<coven_database::ReadOnly>) {
119///     handle.uploads_in_flight();
120/// }
121/// ```
122pub struct StoreDatabase<M: Mode = Writer> {
123    /// Where every connection reports its commits (§4); it outlives them, and
124    /// once they close makes only closed subscriptions.
125    observer: StoreHandle,
126    /// Where a bug in the store's work that nobody waits for goes (E15).
127    bugs: coven_foundation::task::BugSinkRef,
128    /// The open store, `None` once closed. Closing takes it before anything
129    /// that can panic, so a panic while it is written leaves it `None`, a
130    /// whole state: the lock is taken as it is (E15).
131    inner: Arc<RwLock<Option<M::Open>>>,
132    /// Marks the store's lock closing, for a wait in this process on its
133    /// release, once closing begins or the last clone drops.
134    closing: Arc<coven_foundation::files::StoreClosingGuard>,
135    /// What only the writer holds beside it.
136    writer: M::WriterParts,
137}
138
139// Written out: `derive(Clone)` would ask the open store to be `Clone`.
140impl<M: Mode> Clone for StoreDatabase<M> {
141    fn clone(&self) -> Self {
142        Self {
143            observer: self.observer.clone(),
144            bugs: self.bugs.clone(),
145            inner: self.inner.clone(),
146            closing: self.closing.clone(),
147            writer: self.writer.clone(),
148        }
149    }
150}
151
152/// What the store's writer holds beside its open store.
153#[derive(Clone)]
154pub struct WriterParts {
155    /// The files this process is sending and downloading now, and the
156    /// device's network as this process last heard of it, which coven's
157    /// views read (§4).
158    facts: crate::memory_facts::ProcessFacts,
159    file_tasks: Arc<tokio::sync::RwLock<()>>,
160    /// Told when a close finds a call holding the open store and waits for
161    /// it to end.
162    #[cfg(test)]
163    close_waits: Arc<Mutex<Option<tokio::sync::oneshot::Sender<()>>>>,
164    /// The removals of snapshot stagings their callers abandoned, for a test
165    /// to wait on.
166    #[cfg(test)]
167    abandoned_stagings: Arc<Mutex<Vec<tests::hooks::StagingRemoval>>>,
168}
169
170/// The writer's open store.
171pub struct DatabaseInner {
172    inputs: input_database::InputDatabase,
173    access: DatabaseAccess<StoreLock>,
174    migrations: Vec<MigrationOutcome>,
175    /// The journal through which passes publish raise captures, when the
176    /// composition root supplied one (`DatabaseBuilder::migration_operation`):
177    /// a circle captured after the migration's journal finished opens it
178    /// again (§18.3).
179    raise_operation: Option<Box<crate::migration::MigrationOperation>>,
180    /// The app's write for a member's device as its registration applies:
181    /// the transaction that first applies this device's registration runs it
182    /// (§13.2).
183    joining_write: Option<Box<crate::joining_write::JoiningHook>>,
184    /// The app's before-commit function, which each transaction that changes
185    /// the app's rows runs last (§9.4).
186    before_commit: Option<Box<crate::before_commit::BeforeCommit>>,
187    /// What a rebuild opens its database with (§18.3).
188    open_inputs: builder::OpenInputs,
189    clock: ClockRef,
190    ids: IdSourceRef,
191    /// The names of copies being written, or written and waiting for the
192    /// write that names them, which no write's removal takes (Appendix C.3):
193    /// staged app bytes and cache files. Shared with what holds them, so
194    /// letting one go never takes the store's own lock. Each change under
195    /// its lock, and `copying`'s, is whole before it can panic, so both are
196    /// taken as they are (E15).
197    staging: Arc<crate::reserved_names::ReservedNames>,
198    /// The paths of the copies the calls making files device-only are
199    /// writing now, which no other write's removal takes (§17.3).
200    copying: Arc<Mutex<BTreeSet<String>>>,
201    /// Runs where released files' bytes are about to go, after the writer is
202    /// free, so a test can stall that disk work.
203    #[cfg(test)]
204    removal_gate: Mutex<Option<Arc<dyn Fn() + Send + Sync>>>,
205    /// Runs where a write's staged files have been flushed, before its
206    /// commit, so a test can see the order or fail the flush.
207    #[cfg(test)]
208    flush_hook: Mutex<Option<coven_foundation::files::FlushHook>>,
209    /// Fail this many coming `end_retry_waits` transactions with a disk
210    /// error, so a test can show that a failed end leaves every wait.
211    #[cfg(any(test, feature = "test-utils"))]
212    retry_end_failures: std::sync::atomic::AtomicUsize,
213    /// Fail this many coming `applied_slot` reads with a disk error, so a
214    /// test can show what a failed read leaves in memory.
215    #[cfg(any(test, feature = "test-utils"))]
216    applied_slot_failures: std::sync::atomic::AtomicUsize,
217}
218
219/// The connections every handle reads through, and the lock on the store's
220/// directory, which outlives every connection, including when the last
221/// handle is dropped.
222pub struct DatabaseAccess<L> {
223    /// The store's database: its writer, readers and upkeep threads.
224    database: sqlive::Database<CovenPolicy>,
225    // Every connection reports its commits and handle failures here (§4).
226    observer: StoreHandle,
227    write_schema: crate::write_schema::WriteSchema,
228    directory: StoreDir,
229    device: DeviceId,
230    lock: L,
231    /// What coven's tests read back of the calls on these connections.
232    tests: crate::store_call::TestRecords,
233    /// Runs once, where the next read of a file on this device only has
234    /// found where its bytes are and is about to open them, so a test can
235    /// commit between the two.
236    #[cfg(test)]
237    local_open_gate: Mutex<Option<Box<dyn FnOnce() + Send>>>,
238}
239
240impl<L> DatabaseAccess<L> {
241    /// Refuse calls once a connection failed the handle. A call whose own
242    /// work failed the handle with a bug returns that bug as `DbError::Bug`:
243    /// its own error, such as a statement the broken authorizer refused,
244    /// says less, and the app's closure may have dropped it. A bug its error
245    /// carries beside that one goes to the sink, so neither is lost. Any
246    /// other failing call keeps its own error, and one that succeeds while
247    /// the handle fails reports the failure (E15).
248    fn call<R, E: From<DbError> + CarriesBug>(
249        &self,
250        run: impl FnOnce() -> Result<R, E>,
251    ) -> Result<R, E> {
252        if let Some(error) = self.observer.error() {
253            return Err(DbError::from(error).into());
254        }
255        let (result, own) = self.observer.calling(run);
256        if let Some(bug) = own {
257            let carried = result.as_ref().err().and_then(CarriesBug::bug);
258            if let Some(other) = carried.filter(|other| **other != bug) {
259                self.observer.report(other);
260            }
261            return Err(DbError::Bug(bug).into());
262        }
263        match (result, self.observer.error()) {
264            (Ok(_), Some(error)) => Err(DbError::from(error).into()),
265            (result, _) => result,
266        }
267    }
268
269    /// Remove released files' bytes now that the writer is free, then forget
270    /// their records under it (§21.2, Appendix C.3). `chosen` is what the writer
271    /// that recorded them chose.
272    fn remove_released(&self, chosen: crate::file_removals::Chosen) -> Vec<DbError> {
273        let released = match chosen {
274            Ok(released) => released,
275            Err(error) => return vec![error],
276        };
277        let (removed, mut failures) = crate::file_removals::remove_bytes(&self.directory, released);
278        if !removed.is_empty() {
279            let forgotten = self.with_writer(|writer, call| {
280                writer.transaction(|db| crate::file_removals::forget(db, call, &removed))?;
281                #[cfg(any(test, feature = "test-utils"))]
282                call.write_checkpoint(crate::test_utils::WriteCheckpoint::Finished);
283                Ok::<_, DbError>(())
284            });
285            if let Err(error) = forgotten {
286                failures.push(error);
287            }
288        }
289        failures
290    }
291
292    /// The bytes here of a file its record says is on this device only,
293    /// opened, or the record that says otherwise. They are found in one
294    /// committed state and opened after it, and a write committing between
295    /// the two, such as its upload's completion, can release them, which
296    /// coven deletes as that write returns (Appendix C.3). Bytes are released
297    /// only once no record names them, so bytes missing or changed are
298    /// judged by the record as it stands after the open: one that no longer
299    /// names bytes here means the file left this device only meanwhile, and
300    /// the read goes on as that record says; one that still names them
301    /// leaves the failure standing.
302    fn open_local_file(
303        &self,
304        reference: &crate::FileRef,
305        place: coven_foundation::files::LeasePlace,
306    ) -> Result<crate::Located<crate::LocalFileStream>, crate::LocalFileError> {
307        let file = reference.id();
308        let source = || {
309            self.with_committed(|db, _| crate::file_ref::device_only_source(db, self.device, file))
310        };
311        let found = match source()?.here() {
312            Ok(found) => found,
313            Err(elsewhere) => return Ok(elsewhere),
314        };
315        #[cfg(test)]
316        if let Some(gate) = lock_unpoisoned(&self.local_open_gate).take() {
317            gate();
318        }
319        match crate::file_ref::open_source(
320            &self.directory,
321            &file.to_string(),
322            reference.size(),
323            found,
324            place,
325        ) {
326            Ok(stream) => Ok(crate::Located::Here(stream)),
327            Err(error) if error.judges_bytes() => match source()?.here() {
328                Ok(_) => Err(error),
329                Err(elsewhere) => Ok(elsewhere),
330            },
331            Err(error) => Err(error),
332        }
333    }
334
335    fn file_ref(&self, file: FileId) -> Result<crate::FileRef, DbError> {
336        self.with_committed(|db, _| crate::file_ref::read(db, file))
337    }
338
339    fn user_file(&self, file: FileId) -> Result<Option<crate::UserFile>, DbError> {
340        self.with_committed(|db, _| crate::user_file::read(db, file))
341    }
342
343    /// Run `read` in one snapshot on an idle reader, reading each constant
344    /// once.
345    fn read<R, E: From<DbError>>(
346        &self,
347        read: impl FnOnce(SqlReadContext<'_>) -> Result<R, E>,
348    ) -> Result<R, E> {
349        self.with_reader(|reader, call| {
350            let _constants = crate::transaction_constants::keep_constants(reader, call);
351            reader
352                .read_snapshot(|reader| read(SqlReadContext::new(reader)).map_err(Hosted))
353                .map_err(Hosted::into_inner)
354        })
355    }
356
357    fn schema_version(&self) -> Result<u32, DbError> {
358        self.with_reader(crate::transaction_constants::schema_version)
359    }
360
361    /// Every connection has the same settings, so one reader reports them.
362    fn sqlite_settings(&self) -> Result<crate::SqliteSettingsInEffect, DbError> {
363        Ok(self.database.reader().host(StoreSql::sqlite_settings)?)
364    }
365
366    fn close(self) -> Result<(), DbError> {
367        self.observer.close();
368        let failures: Vec<DbError> = self.database.close().into_iter().map(DbError::from).collect();
369        drop(self.lock);
370        if failures.is_empty() {
371            Ok(())
372        } else {
373            Err(DbError::Closing { failures })
374        }
375    }
376}
377
378impl DatabaseInner {
379    fn call<R, E: From<DbError> + CarriesBug>(
380        &self,
381        run: impl FnOnce(&Self) -> Result<R, E>,
382    ) -> Result<R, E> {
383        self.access.call(|| run(self))
384    }
385
386    // Their durable removal records remain for the next write or open.
387    fn release_file_reservations(&self, names: &[crate::file_removals::OwnedFile]) {
388        self.staging.release(names);
389    }
390
391    /// Run `operation`, a write, under the writer, then remove the files it
392    /// released once the writer is free (Appendix C.3), and run what its
393    /// steps asked to follow its commit. A panic in it fails it with
394    /// `DbError::Bug` once its transaction has rolled back, and its released
395    /// files go as after any failed write.
396    fn with_files<R, E: crate::WriteFailure>(
397        &self,
398        operation: &'static str,
399        run: impl FnOnce(
400            &mut StoreSql,
401            &StoreCall<'_>,
402            &crate::file_write::WriteFiles<'_>,
403        ) -> Result<R, E>,
404    ) -> Result<R, E> {
405        let (result, chosen, committed) = self.access.with_writer(|writer, call| {
406            let files = crate::file_write::WriteFiles::new(
407                &self.access.write_schema,
408                self.access.device,
409                self.ids.as_ref(),
410                &self.staging,
411                &self.copying,
412                self.before_commit.as_deref(),
413            );
414            let result =
415                coven_foundation::task::caught_sync(operation, || run(writer, call, &files))
416                    .unwrap_or_else(|bug| Err(E::from(DbError::Bug(bug))));
417            // After a failed rollback the writer may still hold this write;
418            // removal records wait for the next open (Appendix C.3).
419            let usable = !matches!(
420                self.access.observer.error::<DbError>(),
421                Some(sqlive::Error::Host(StoreFailure::Rollback))
422            );
423            let chosen = usable.then(|| released(writer, call, self));
424            Ok::<_, E>((result, chosen, files.take_committed()))
425        })?;
426        let result = match chosen {
427            Some(chosen) => self.finish_removals(result, chosen),
428            None => result,
429        };
430        // A write that returns success has committed.
431        if result.is_ok() {
432            committed.into_iter().for_each(|effect| effect());
433        }
434        result
435    }
436
437    /// Remove what `chosen` names, after the writer that chose it is
438    /// released (§21.2, Appendix C.3).
439    fn remove_chosen(&self, chosen: crate::file_removals::Chosen) -> Vec<DbError> {
440        #[cfg(test)]
441        {
442            let gate = lock_unpoisoned(&self.removal_gate).clone();
443            if let Some(gate) = gate {
444                gate();
445            }
446        }
447        self.access.remove_released(chosen)
448    }
449
450    /// `result`, after removing the files it released, as `chosen` names
451    /// them; a failed removal keeps its record for the next write or open.
452    fn finish_removals<R, E: crate::WriteFailure>(
453        &self,
454        result: Result<R, E>,
455        chosen: crate::file_removals::Chosen,
456    ) -> Result<R, E> {
457        crate::write_failure::after_cleanup(result, self.remove_chosen(chosen))
458    }
459}
460
461/// Let `paths` go from the copies a store keeps out of removals, once the
462/// write that brought them has decided (§17.3).
463pub(crate) fn release_copies(copying: &Mutex<BTreeSet<String>>, paths: &[String]) {
464    let mut held = lock_unpoisoned(copying);
465    for path in paths {
466        held.remove(path);
467    }
468}
469
470/// The removals the write that just ran under `writer` released, chosen
471/// with the staging and copying sets held (Appendix C.3).
472fn released(
473    writer: &StoreSql,
474    call: &StoreCall<'_>,
475    inner: &DatabaseInner,
476) -> crate::file_removals::Chosen {
477    inner.staging.with_names(|active| {
478        let copying = lock_unpoisoned(&inner.copying);
479        crate::file_removals::choose(writer, call, active, &copying)
480    })
481}
482
483impl<M: Mode> StoreDatabase<M> {
484    /// Where a bug in the store's work that nobody waits for goes (E15).
485    pub fn bugs(&self) -> &coven_foundation::task::BugSinkRef {
486        &self.bugs
487    }
488
489    /// Run `run` on the open store on the blocking pool, refused once a
490    /// connection failed the handle.
491    async fn call<R, E>(
492        &self,
493        run: impl FnOnce(&M::Open) -> Result<R, E> + Send + 'static,
494    ) -> Result<R, E>
495    where
496        R: Send + 'static,
497        E: From<DbError> + CarriesBug + Send + 'static,
498    {
499        finish_blocking(
500            start_call("database call", &self.bugs, self.inner.clone(), move |open| {
501                M::access(open).call(|| run(open))
502            })
503            .await,
504        )
505    }
506
507    /// Open the local source of a file still on this device only, in `place`
508    /// of the app's budget, which the stream holds until its last read ends.
509    /// No storage operation occurs. For a file whose record no longer keeps
510    /// it on this device only, or that has no record, it returns what the
511    /// open found instead, and the place goes back.
512    pub async fn open_local_file(
513        &self,
514        reference: &crate::FileRef,
515        place: coven_foundation::files::LeasePlace,
516    ) -> Result<crate::Located<crate::LocalFileStream>, crate::LocalFileError> {
517        let reference = reference.clone();
518        self.call(move |open| M::access(open).open_local_file(&reference, place)).await
519    }
520
521    /// The file this device has a record of under this id, from one
522    /// committed state.
523    pub async fn file_ref(&self, file: FileId) -> Result<crate::FileRef, DbError> {
524        self.call(move |open| M::access(open).file_ref(file)).await
525    }
526
527    /// The recorded original's path, size and modification time; never reread its bytes.
528    pub async fn user_file(&self, file: FileId) -> Result<Option<crate::UserFile>, DbError> {
529        self.call(move |open| M::access(open).user_file(file)).await
530    }
531
532    /// Run ordinary SQL against one consistent snapshot when awaited. The
533    /// read fails with the closure's own error type, and with a failure of
534    /// the database's own as that type's `From<DbError>`.
535    pub fn read<F, R, E>(&self, read: F) -> Read<'_, F, M>
536    where
537        F: FnOnce(SqlReadContext<'_>) -> Result<R, E> + Send + 'static,
538        R: Send + 'static,
539        E: From<DbError> + CarriesBug + Send + 'static,
540    {
541        Read::new(self, read)
542    }
543
544    /// Decode every lost cell and removed row in one snapshot.
545    pub async fn lost_values(&self) -> Result<Vec<LostValue>, DbError> {
546        self.read_committed(crate::loss_record::lost_values).await
547    }
548
549    /// Run `read`, coven's own SQL on its tables, in one committed state on
550    /// an idle reader, on the blocking pool.
551    pub(crate) async fn read_committed<R, E>(
552        &self,
553        read: impl FnOnce(&StoreSql) -> Result<R, E> + Send + 'static,
554    ) -> Result<R, E>
555    where
556        R: Send + 'static,
557        E: From<DbError> + CarriesBug + Send + 'static,
558    {
559        self.call(move |open| M::access(open).with_committed(|db, _| read(db))).await
560    }
561
562    pub(crate) fn start_read<F, R, E>(&self, read: F) -> RunningRead<R, E>
563    where
564        F: FnOnce(SqlReadContext<'_>) -> Result<R, E> + Send + 'static,
565        R: Send + 'static,
566        E: From<DbError> + CarriesBug + Send + 'static,
567    {
568        RunningRead::new(start_call("read", &self.bugs, self.inner.clone(), move |open| {
569            let access = M::access(open);
570            access.call(|| access.read(read))
571        }))
572    }
573
574    /// The committed app schema version, read on a read-only connection.
575    pub async fn schema_version(&self) -> Result<u32, DbError> {
576        self.call(|open| M::access(open).schema_version()).await
577    }
578
579    /// The SQLite settings the store's connections have in effect (§4).
580    pub async fn sqlite_settings(&self) -> Result<crate::SqliteSettingsInEffect, DbError> {
581        self.call(|open| M::access(open).sqlite_settings()).await
582    }
583}
584
585impl StoreDatabase {
586    /// Mark this instance as closing for a reopen to wait on, though workers
587    /// still hold clones of it: the facade's owning scope ended (F.4).
588    pub fn begin_close(&self) {
589        self.closing.begin_close();
590    }
591    /// The handle's clock could not wait for an invite's expiry: every
592    /// later call and live query fails with `DbError::WallTimer` until the
593    /// store is reopened (§13.2).
594    pub fn fail_expiry_wait(&self, error: coven_foundation::clock::WallTimerError) {
595        self.observer.fail(StoreFailure::WallTimer(error));
596    }
597
598    /// The files this process is sending now: the upload worker marks each
599    /// attempt, and coven's views read them (§4, §17.9).
600    pub fn uploads_in_flight(&self) -> crate::InFlight {
601        self.writer.facts.uploads()
602    }
603
604    /// The files this process is downloading to keep whole now: each pin's
605    /// download marks its attempt, and `coven_downloading` reads them (§4,
606    /// §17.8).
607    pub fn downloads_in_flight(&self) -> crate::InFlight {
608        self.writer.facts.downloads()
609    }
610
611    /// The store's watch says the device's network is now `network`:
612    /// coven's views show it, and a live query that read them runs again
613    /// (§4, §6.7).
614    pub fn record_network(&self, network: coven_foundation::network_watch::NetworkState) {
615        self.writer.facts.record_network(network);
616    }
617
618    /// Run app SQL and coven's steps, and commit its unsigned write record
619    /// and merge metadata in one IMMEDIATE transaction (§4). The closure's
620    /// result is returned after commit.
621    pub async fn write<F, R>(&self, sql: F) -> Result<R, DbError>
622    where
623        F: FnOnce(crate::SqlContext<'_, '_>) -> Result<R, DbError> + Send + 'static,
624        R: Send + 'static,
625    {
626        self.write_as(sql).await
627    }
628
629    /// `write`, for a closure whose failures are `E`: callback errors retain
630    /// their type alongside rollback or byte-cleanup failures.
631    pub async fn write_as<F, R, E>(&self, sql: F) -> Result<R, E>
632    where
633        F: FnOnce(crate::SqlContext<'_, '_>) -> Result<R, E> + Send + 'static,
634        R: Send + 'static,
635        E: crate::WriteFailure + Send + 'static,
636    {
637        self.call(move |inner| {
638            inner.with_files("write", |writer, call, files| {
639                let result = coven_foundation::task::caught_sync("write", || {
640                    crate::local_write::local_write(
641                        writer,
642                        call,
643                        &inner.access.write_schema,
644                        inner.access.device,
645                        inner.clock.now(),
646                        files,
647                        |files| sql(crate::SqlContext::new(files)),
648                    )
649                });
650                // Staged files the write brought in go free once it has
651                // decided: a write that rolled back leaves their bytes to the
652                // removals its cleanup chooses.
653                inner.release_file_reservations(&files.take_brought());
654                release_copies(&inner.copying, &files.take_held_copies());
655                #[cfg(any(test, feature = "test-utils"))]
656                call.write_checkpoint(crate::test_utils::WriteCheckpoint::StagingReleased);
657                result.unwrap_or_else(|bug| Err(E::from(DbError::Bug(bug))))
658            })
659        })
660        .await
661    }
662
663    /// Stage app bytes for a later write (§17.2): `stage` names each file's
664    /// namespace and place and returns what that write's SQL needs, such as
665    /// the ids staging gave them. Their bytes are streamed to coven's own
666    /// copies, each synced, and flushed, before this returns; close waits for
667    /// that, and for its cleanup if it fails or is cancelled. The result
668    /// holds nothing close waits for. A write takes it with `put_staged`.
669    pub async fn stage_files<F, T, E>(&self, stage: F) -> Result<StagedFiles<T>, E>
670    where
671        F: FnOnce(&mut crate::WriteBatch<'_>) -> Result<T, E> + Send + 'static,
672        T: Send + 'static,
673        E: crate::WriteFailure + Send + 'static,
674    {
675        let lease = self.writer.file_tasks.clone().read_owned().await;
676        let database = self.inner.clone();
677        let (staging, value) = finish_blocking(
678            blocking_completing(
679                "stage files",
680                self.bugs.clone(),
681                crate::commit_task::bind(move || {
682                    file_staging::FileStaging::new(database, lease, stage)
683                }),
684            )
685            .await,
686        )?;
687        let (staging, flushed) =
688            staging.write().await.map_err(|failed| E::from(DbError::from(failed)))?;
689        match flushed {
690            Ok(_flushed) => Ok(staging.into_staged(value)),
691            // A failed copy or flush removes what the staging wrote.
692            // The discard's result is the call's failure, so a bug it
693            // carries reaches the sink too once no caller waits.
694            Err(error) => finish_blocking(
695                blocking_completing(
696                    "discard staged files",
697                    self.bugs.clone(),
698                    crate::commit_task::bind(move || {
699                        Err::<std::convert::Infallible, E>(staging.discard::<E>(error))
700                    }),
701                )
702                .await,
703            )
704            .map(|never| match never {}),
705        }
706    }
707
708    /// Stage app bytes, then run a write that puts them in its rows, as an
709    /// app does with `stage_files` and `put_staged`, for tests.
710    #[cfg(any(test, feature = "test-utils"))]
711    pub async fn staged_write<F, S, T, R, E>(&self, stage: F, write: S) -> Result<R, E>
712    where
713        F: FnOnce(&mut crate::WriteBatch<'_>) -> Result<T, E> + Send + 'static,
714        S: FnOnce(crate::SqlContext<'_, '_>, T) -> Result<R, E> + Send + 'static,
715        T: Send + 'static,
716        R: Send + 'static,
717        E: crate::WriteFailure + Send + 'static,
718    {
719        let staged = self.stage_files(stage).await?;
720        self.write_as(move |sql| {
721            let value = sql.put_staged(staged)?;
722            write(sql, value)
723        })
724        .await
725    }
726
727    /// Run app SQL that writes device-local tables alone in one IMMEDIATE
728    /// transaction, as plain SQLite: no pre-update hook records its row
729    /// changes, so SQLite empties a table in one step and fills one at its
730    /// own speed (§4). A statement that would write a synced table, itself or
731    /// through a trigger or foreign-key action, fails the write with
732    /// `SyncedTableInBulkWrite`, and everything rolls back. The app's
733    /// before-commit function runs after the closure, in the same
734    /// transaction (§9.4). After commit, every live query that read a table
735    /// the write's statements or the function's may change runs again,
736    /// whatever rows it read. The closure's result is returned after commit.
737    pub async fn write_bulk<F, R, E>(&self, sql: F) -> Result<R, E>
738    where
739        F: FnOnce(crate::BulkSqlContext<'_>) -> Result<R, E> + Send + 'static,
740        R: Send + 'static,
741        E: crate::WriteFailure + Send + 'static,
742    {
743        self.call(move |inner| {
744            inner.access.with_writer(|writer, _| {
745                writer
746                    .bulk_write(|bulk| {
747                        let result = sql(crate::BulkSqlContext::new(bulk)).map_err(Hosted)?;
748                        crate::before_commit::run(bulk, inner.before_commit.as_deref())
749                            .map_err(|error| Hosted(E::from(error)))?;
750                        Ok(result)
751                    })
752                    .map_err(Hosted::into_inner)
753            })
754        })
755        .await
756    }
757
758    /// Checkpoint the store's WAL on the writer, between writes (§4).
759    pub async fn checkpoint(
760        &self,
761        mode: crate::CheckpointMode,
762    ) -> Result<crate::WalCheckpoint, DbError> {
763        self.call(move |inner| {
764            inner.access.with_writer(|writer, _| Ok(writer.wal_checkpoint(mode)?))
765        })
766        .await
767    }
768
769    /// Give back free pages of a store created with incremental auto-vacuum,
770    /// on the writer, between writes (§4). On any other store it does nothing.
771    pub async fn incremental_vacuum(&self, pages: crate::IncrementalVacuum) -> Result<(), DbError> {
772        self.call(move |inner| {
773            inner.access.with_writer(|writer, _| Ok(writer.incremental_vacuum(pages)?))
774        })
775        .await
776    }
777
778    /// Give back every connection's cached pages that no statement is using
779    /// (§4). SQLite as coven builds it (`SQLITE_ENABLE_MEMORY_MANAGEMENT`)
780    /// keeps the unused pages of every connection in the process in one
781    /// pool, and one connection's release empties the whole pool: so one
782    /// release on an idle reader frees the writer's, the input database's
783    /// and the checkpointers' too, and never waits for a write.
784    pub async fn release_memory(&self) -> Result<(), DbError> {
785        self.call(|inner| {
786            inner.access.database.reader().host(|reader| Ok(reader.release_memory()?))
787        })
788        .await
789    }
790
791    /// The migrations this open committed, classified individually.
792    pub fn applied_migrations(&self) -> Result<Vec<MigrationOutcome>, DbError> {
793        let inner = read_unpoisoned(&self.inner);
794        let inner = inner.as_ref().ok_or(DbError::StoreClosed)?;
795        if let Some(error) = inner.access.observer.error() {
796            return Err(error.into());
797        }
798        Ok(inner.migrations.clone())
799    }
800
801    /// Wait for database calls, close all connections, then release the writer lock.
802    /// Every subsequent database call, including close, reports `StoreClosed`.
803    pub async fn close(&self) -> Result<(), DbError> {
804        self.closing.begin_close();
805        let database = self.clone();
806        // Closing runs as its own task so that a caller dropping this future
807        // doesn't stop it partway; the runtime dropping that task can.
808        let bugs = self.bugs.clone();
809        coven_foundation::task::spawn_completing("close the store", self.bugs.clone(), async move {
810            let file_tasks = database.writer.file_tasks.clone().write_owned().await;
811            finish_blocking(
812                blocking_completing(
813                    "close the store",
814                    bugs,
815                    crate::commit_task::bind(move || {
816                        let _file_tasks = file_tasks;
817                        #[cfg(test)]
818                        database.tell_close_wait();
819                        let mut slot = write_unpoisoned(&database.inner);
820                        let Some(inner) = slot.take() else {
821                            return Err(DbError::StoreClosed);
822                        };
823                        let mut failures = inner.inputs.close();
824                        match inner.access.close() {
825                            Err(DbError::Closing { failures: application }) => {
826                                failures.extend(application)
827                            }
828                            Err(error) => failures.push(error),
829                            Ok(()) => (),
830                        }
831                        if failures.is_empty() {
832                            Ok(())
833                        } else {
834                            Err(DbError::Closing { failures })
835                        }
836                    }),
837                )
838                .await,
839            )
840        })
841        .await
842        .map_err(DbError::from)?
843    }
844}
845
846impl StoreDatabase<ReadOnly> {
847    /// Begin closing every clone of this handle, at once and before its
848    /// connections close: every later call fails with `StoreClosed`, a call
849    /// already running answers `StoreClosed` too, and a deletion in this
850    /// process waits for the readers' lock to be released (E1).
851    pub fn begin_close(&self) {
852        self.observer.close();
853        self.closing.begin_close();
854    }
855
856    /// Wait for active calls and close every clone of this handle.
857    pub async fn close(&self) -> Result<(), DbError> {
858        let handle = self.clone();
859        finish_blocking(
860            blocking_completing("close the store", self.bugs.clone(), move || {
861                let mut slot = write_unpoisoned(&handle.inner);
862                slot.take().ok_or(DbError::StoreClosed)?.close()
863            })
864            .await,
865        )
866    }
867}
868
869#[cfg(test)]
870#[path = "database_tests.rs"]
871mod tests;