Skip to main content

coven_database/
circle_rebuild_migration.rs

1//! A rebuild's migration, reading forward and export (§18.3): the steps that
2//! turn the circle loaded at its version into the circle at the app's.
3
4use super::{removed_after, RebuildDatabase, RebuildError};
5use crate::database::{DatabaseBuilder, StoreDatabase};
6use crate::{DbError, SnapshotStaging};
7use coven_foundation::id_source::KeyId;
8
9/// The staging a rebuild's circle is exported into stopped taking frames.
10#[derive(Debug, thiserror::Error)]
11#[error("the snapshot's staging stopped taking frames")]
12pub struct ExportStopped;
13
14impl coven_foundation::task::CarriesBug for ExportStopped {
15    fn bug(&self) -> Option<&coven_foundation::task::Bug> {
16        None
17    }
18}
19
20impl RebuildDatabase {
21    /// Migrate the rebuild's store, which holds only the store, up to
22    /// `version`, the version of the circle about to load, with no migration
23    /// write: the store's changes come only from the store, so the rows are
24    /// the ones every device that raised the store to `version` made, and
25    /// the device's own marker belongs to the migration past it (§18.3). The
26    /// store is closed and opened again with the app's migrations before the
27    /// first breaking one past `version`.
28    ///
29    /// A failure removes the rebuild's folder, as `open_rebuild` does.
30    pub async fn migrate_store_to(
31        &mut self,
32        circle: coven_merge::Audience,
33        version: u32,
34    ) -> Result<(), RebuildError> {
35        let Some(database) = self.database.take() else {
36            return Err(DbError::StoreClosed.into());
37        };
38        let result = match database.close().await {
39            Err(error) => Err(RebuildError::from(error)),
40            Ok(()) => match super::first_past(&self.inputs, &circle, version) {
41                Err(error) => Err(error),
42                Ok(first) => {
43                    super::at_version(&self.inputs, first, &self.scratch, &self.clock, &self.ids)
44                        .loading_store()
45                        .open()
46                        .await
47                        .map_err(RebuildError::from)
48                }
49            },
50        };
51        match result {
52            Ok(database) => self.reopened(database).await,
53            Err(operation) => Err(removed_after(&self.parent, operation).await),
54        }
55    }
56
57    /// Run the app's migrations the rebuild's store hasn't, in one run, the
58    /// breaking ones making the migration write `header` and not a new one:
59    /// the device's migration write for this rebuild, which read the circle
60    /// through the slot the store has applied (§18.3). The store is closed
61    /// and opened again at the app's newest version; the per-audience check
62    /// of the run's reads (§18.3) runs here as on any breaking open.
63    ///
64    /// A failure removes the rebuild's folder, as `open_rebuild` does; the
65    /// caller's `discard` after it finds nothing left.
66    pub async fn migrate(
67        &mut self,
68        header: coven_format::write::WriteHeader,
69    ) -> Result<(), RebuildError> {
70        let Some(database) = self.database.take() else {
71            return Err(DbError::StoreClosed.into());
72        };
73        let closed = database.close().await;
74        let result = match closed {
75            Err(error) => Err(RebuildError::from(error)),
76            Ok(()) => DatabaseBuilder::new(self.scratch.clone())
77                .synced_tables(self.inputs.tables.clone())
78                .migrations(self.inputs.migrations.clone())
79                .namespaces(self.inputs.namespaces.clone())
80                .sqlite_settings(self.inputs.sqlite.clone())
81                .sql_functions(self.inputs.functions.clone())
82                .sync_functions_as_opened(self.inputs.sync_functions.clone())
83                .clock(self.clock.clone())
84                .id_source(self.ids.clone())
85                .rebuilding(header)
86                .open()
87                .await
88                .map_err(RebuildError::from),
89        };
90        match result {
91            Ok(database) => self.reopened(database).await,
92            Err(operation) => Err(removed_after(&self.parent, operation).await),
93        }
94    }
95
96    /// Stage the circle's counted state at the slot the rebuild's store has
97    /// applied into `into` as the snapshot `id`, sealed under `key`, then
98    /// remove the rebuild (§18.3). The rows are the circle's, migrated, as
99    /// a device that held the circle and migrated would write them; the
100    /// raise captures the rebuild's store made are not consulted, since it
101    /// sends nothing. Returns the staging, finished, for the caller to load;
102    /// on a failure the rebuild is removed, nothing stays staged in `into`
103    /// and the failure is returned.
104    pub async fn export(
105        mut self,
106        id: coven_format::admin::SnapshotId,
107        key: KeyId,
108        into: &StoreDatabase,
109    ) -> Result<SnapshotStaging, RebuildError> {
110        let exported = self.stage_export(id, key, into).await;
111        let removed = self.discard_inner().await;
112        match (exported, removed) {
113            (Ok(staging), Ok(())) => Ok(staging),
114            (Ok(staging), Err(error)) => Err(refused(staging, error).await),
115            (Err(error), Ok(())) => Err(error),
116            (Err(error), Err(cleanup)) => Err(RebuildError::Cleanup {
117                operation: Box::new(error),
118                cleanup: Box::new(cleanup),
119            }),
120        }
121    }
122
123    async fn stage_export(
124        &self,
125        id: coven_format::admin::SnapshotId,
126        key: KeyId,
127        into: &StoreDatabase,
128    ) -> Result<SnapshotStaging, RebuildError> {
129        let Some(database) = &self.database else {
130            return Err(DbError::StoreClosed.into());
131        };
132        let audience = id.audience.clone();
133        let (prefixes, prefix) = tokio::sync::oneshot::channel();
134        let (frames, mut received) = tokio::sync::mpsc::channel::<Vec<u8>>(8);
135        let writing = database.write_counted_snapshot(
136            id.clone(),
137            move |header| {
138                let prefix = coven_format::sealed_snapshot::SnapshotObjectPrefix {
139                    audience,
140                    key,
141                    covers: header.covers,
142                    purpose: coven_format::sequence::Purpose::Ordinary,
143                };
144                prefixes.send(prefix).ok().ok_or(ExportStopped)
145            },
146            move |frame| frames.blocking_send(frame).ok().ok_or(ExportStopped),
147        );
148        let staging = async {
149            let Ok(prefix) = prefix.await else {
150                return Ok(None);
151            };
152            let mut staging = into.stage_snapshot(id, prefix).await?;
153            let mut batch = Vec::new();
154            let fed = async {
155                while let Some(frame) = received.recv().await {
156                    batch.extend(frame);
157                    if batch.len() >= coven_format::chunks::CHUNK_SIZE {
158                        staging.stage(std::mem::take(&mut batch)).await?;
159                    }
160                }
161                if !batch.is_empty() {
162                    staging.stage(batch).await?;
163                }
164                staging.finish().await
165            }
166            .await;
167            match fed {
168                Ok(()) => Ok(Some(staging)),
169                Err(error) => {
170                    Err(crate::database::input_database::staging::refuse(vec![staging], error)
171                        .await)
172                }
173            }
174        };
175        let (written, staged) = tokio::join!(writing, staging);
176        match (written, staged) {
177            (Ok(_), Ok(Some(staging))) => Ok(staging),
178            (Ok(_), Ok(None)) => Err(DbError::Invariant {
179                what: "a snapshot's writer names its prefix before its first frame",
180            }
181            .into()),
182            (Ok(_), Err(error)) => Err(error.into()),
183            (Err(error), Ok(staging)) => {
184                let error = RebuildError::from(error);
185                match staging {
186                    Some(staging) => Err(refused(staging, error).await),
187                    None => Err(error),
188                }
189            }
190            (Err(error), Err(_)) => Err(error.into()),
191        }
192    }
193}
194
195/// `error` after discarding `staging`.
196async fn refused(staging: SnapshotStaging, error: RebuildError) -> RebuildError {
197    match staging.discard().await {
198        Ok(()) => error,
199        Err(cleanup) => RebuildError::Cleanup {
200            operation: Box::new(error),
201            cleanup: Box::new(RebuildError::Database(cleanup)),
202        },
203    }
204}
205
206#[cfg(test)]
207#[path = "circle_rebuild_migration_tests.rs"]
208mod tests;