Skip to main content

coven_database/
circle_rebuild.rs

1//! The database a rebuild of a circle runs in: a coven store of its own, in
2//! the folder `rebuild` of the store's folder, at the version the circle is
3//! at, holding this device's copy of the store and the circle as they were
4//! (§18.3). The real store is changed only by installing what the rebuild
5//! makes, never by running it.
6
7use super::builder::OpenInputs;
8use super::{DatabaseBuilder, StoreDatabase};
9use crate::migration::MigrationKind;
10use crate::{DbError, OpenError, SnapshotWriteError};
11use coven_foundation::clock::ClockRef;
12use coven_foundation::files::{FileError, SettingsError, StoreDir, StoreDirAccess};
13use coven_foundation::id_source::IdSourceRef;
14use coven_merge::Audience;
15
16/// Why a rebuild could not run.
17#[derive(Debug, thiserror::Error)]
18pub enum RebuildError {
19    /// The app has no breaking migration past the circle's version: nothing
20    /// to rebuild it for.
21    #[error("{circle} at version {version} is not below a breaking migration")]
22    NotBelow {
23        /// The circle.
24        circle: Audience,
25        /// Its version.
26        version: u32,
27    },
28    /// The rebuild's store could not open at the circle's version or migrate.
29    #[error(transparent)]
30    Open(#[from] OpenError),
31    /// The circle's state could not be read out of the rebuild's store.
32    #[error(transparent)]
33    Export(#[from] SnapshotWriteError<ExportStopped>),
34    /// The rebuild's store failed.
35    #[error(transparent)]
36    Database(#[from] DbError),
37    /// The rebuild's folder could not be made.
38    #[error("the rebuild's store: {0}")]
39    Directory(#[from] SettingsError),
40    /// The rebuild's folder could not be removed.
41    #[error("the rebuild's folder: {0}")]
42    Folder(#[from] FileError),
43    /// A rebuild failed, and so did removing what it left.
44    #[error("{operation}; removing what it left also failed: {cleanup}")]
45    Cleanup {
46        /// The failure that ended the rebuild.
47        operation: Box<RebuildError>,
48        /// The failure of the removal that followed.
49        cleanup: Box<RebuildError>,
50    },
51}
52
53/// A rebuild's store, open at the version its circle is at. Its owner is the
54/// only one that writes to it or closes it; `discard` closes it and removes
55/// its folder.
56pub struct RebuildDatabase {
57    /// None once `discard` took it to close.
58    database: Option<StoreDatabase>,
59    /// The rebuild's own store, which `migrate` opens again.
60    scratch: StoreDir,
61    /// What the real store opened with.
62    inputs: OpenInputs,
63    clock: ClockRef,
64    ids: IdSourceRef,
65    /// The real store's handle, whose `coven_library_bytes` counts the
66    /// rebuild's store while its folder is there: the folder is on this
67    /// device's disk, so the storage figures count it (§17.8).
68    parent: StoreDatabase,
69}
70
71impl StoreDatabase {
72    /// Open a database of its own for rebuilding `circle`, which is at
73    /// breaking version `version`: the app's migrations through the version
74    /// before the first breaking one past `version`, declared as that
75    /// migration's `starts_from` (§18.3). A circle with no breaking
76    /// migration past its version is `NotBelow`. A leftover rebuild from a
77    /// crash is replaced; on a failure nothing is left behind.
78    pub async fn open_rebuild(
79        &self,
80        circle: Audience,
81        version: u32,
82    ) -> Result<RebuildDatabase, RebuildError> {
83        let (real, inputs, clock, ids) = self
84            .call(|inner| {
85                Ok::<_, DbError>((
86                    inner.access.directory.clone(),
87                    inner.open_inputs.clone(),
88                    inner.clock.clone(),
89                    inner.ids.clone(),
90                ))
91            })
92            .await?;
93        let first = first_past(&inputs, &circle, version)?;
94        // Delete a leftover rebuild's folder and its row, then add the new
95        // rebuild's row at no bytes before making its folder (§17.8).
96        self.remove_rebuild().await?;
97        self.begin_counting_rebuild().await?;
98        let scratch = match real.rebuild_directory().await {
99            Ok(scratch) => scratch,
100            Err(operation) => return Err(removed_after(self, operation.into()).await),
101        };
102        let opened =
103            at_version(&inputs, first, &scratch, &clock, &ids).loading_store().open().await;
104        let database = match opened {
105            Ok(database) => database,
106            Err(operation) => return Err(removed_after(self, operation.into()).await),
107        };
108        let counted = self.count_rebuild(&database).await;
109        let mut rebuild = RebuildDatabase {
110            database: Some(database),
111            scratch,
112            inputs,
113            clock,
114            ids,
115            parent: self.clone(),
116        };
117        match counted {
118            Ok(()) => Ok(rebuild),
119            Err(operation) => Err(match rebuild.discard_inner().await {
120                Ok(()) => operation.into(),
121                Err(cleanup) => RebuildError::Cleanup {
122                    operation: Box::new(operation.into()),
123                    cleanup: Box::new(cleanup),
124                },
125            }),
126        }
127    }
128}
129
130impl RebuildDatabase {
131    /// Begin staging a snapshot into the rebuild's store (§16.2).
132    pub async fn stage_snapshot(
133        &self,
134        id: coven_format::admin::SnapshotId,
135        prefix: coven_format::sealed_snapshot::SnapshotObjectPrefix,
136    ) -> Result<crate::SnapshotStaging, DbError> {
137        let Some(database) = &self.database else {
138            return Err(DbError::StoreClosed);
139        };
140        database.stage_snapshot(id, prefix).await
141    }
142
143    /// Load snapshots staged here and the slots after them into the
144    /// rebuild's store, as a device loads them (§16.2).
145    ///
146    /// The store's parts in slots after `store_through` aren't read: past the
147    /// slot before the store's raise beyond the circle's version, the store
148    /// holds no rows at the circle's version. A write above the rebuild's
149    /// version is kept as a frozen lost value naming the breaking version it
150    /// needs, not waited for (§18.3).
151    pub async fn load<P: crate::PendingValue, W>(
152        &self,
153        reload: crate::SnapshotReload<crate::SnapshotStaging, crate::DownloadedWriteStream<W>>,
154        store_through: u64,
155    ) -> Result<Vec<crate::LoadedSnapshot>, DbError>
156    where
157        W: std::io::Read + Send + 'static,
158    {
159        let Some(database) = &self.database else {
160            return Err(DbError::StoreClosed);
161        };
162        let rebuilding = crate::snapshot_coverage::Rebuilding {
163            store_through,
164            breaking: self
165                .inputs
166                .migrations
167                .iter()
168                .filter(|m| matches!(m.kind, MigrationKind::Breaking(_)))
169                .map(|m| m.version)
170                .collect(),
171        };
172        let loaded = database.load_through::<P, W>(reload, None, Some(rebuilding), None).await;
173        loaded
174    }
175
176    /// Close the rebuild's store and remove its folder with its row in the
177    /// real store's `coven_library_bytes`, reporting the first failure
178    /// (both, as `Cleanup`, when both fail).
179    pub async fn discard(mut self) -> Result<(), RebuildError> {
180        self.discard_inner().await
181    }
182
183    async fn discard_inner(&mut self) -> Result<(), RebuildError> {
184        let closed = match self.database.take() {
185            Some(database) => database.close().await.map_err(RebuildError::from),
186            None => Ok(()),
187        };
188        let removed = self.parent.remove_rebuild().await;
189        match (closed, removed) {
190            (Ok(()), Ok(())) => Ok(()),
191            (Ok(()), Err(cleanup)) => Err(cleanup.into()),
192            (Err(operation), Ok(())) => Err(operation),
193            (Err(operation), Err(cleanup)) => Err(RebuildError::Cleanup {
194                operation: Box::new(operation),
195                cleanup: Box::new(cleanup.into()),
196            }),
197        }
198    }
199
200    /// Count the rebuild's store, just opened again, in the real store's
201    /// `rebuild` row, and keep it.
202    async fn reopened(&mut self, database: StoreDatabase) -> Result<(), RebuildError> {
203        let counted = self.parent.count_rebuild(&database).await;
204        self.database = Some(database);
205        Ok(counted?)
206    }
207}
208
209/// The position of the first breaking migration past `version`, which is
210/// where a store at `version` stops.
211fn first_past(inputs: &OpenInputs, circle: &Audience, version: u32) -> Result<usize, RebuildError> {
212    inputs
213        .migrations
214        .iter()
215        .position(|m| m.version > version && matches!(m.kind, MigrationKind::Breaking(_)))
216        .ok_or_else(|| RebuildError::NotBelow { circle: circle.clone(), version })
217}
218
219/// The builder of a store of the rebuild's folder that runs the app's
220/// migrations before its migration number `first`, declaring the tables that
221/// one starts from.
222fn at_version(
223    inputs: &OpenInputs,
224    first: usize,
225    scratch: &StoreDir,
226    clock: &ClockRef,
227    ids: &IdSourceRef,
228) -> DatabaseBuilder {
229    DatabaseBuilder::new(scratch.clone())
230        .synced_tables(inputs.migrations[first].starts_from.clone())
231        .migrations(inputs.migrations[..first].to_vec())
232        .namespaces(inputs.namespaces.clone())
233        .sqlite_settings(inputs.sqlite.clone())
234        .sql_functions(inputs.functions.clone())
235        .sync_functions_as_opened(inputs.sync_functions.clone())
236        .clock(clock.clone())
237        .id_source(ids.clone())
238}
239
240/// `operation` after removing the rebuild's folder and its row in the real
241/// store `parent`.
242async fn removed_after(parent: &StoreDatabase, operation: RebuildError) -> RebuildError {
243    match parent.remove_rebuild().await {
244        Ok(()) => operation,
245        Err(cleanup) => RebuildError::Cleanup {
246            operation: Box::new(operation),
247            cleanup: Box::new(cleanup.into()),
248        },
249    }
250}
251
252#[path = "circle_rebuild_migration.rs"]
253mod migration;
254pub use migration::ExportStopped;
255
256#[cfg(test)]
257#[path = "circle_rebuild_tests.rs"]
258pub(crate) mod tests;