Skip to main content

coven_database/
database_snapshots.rs

1//! Snapshot streams and atomic reload through the database owner.
2
3use super::StoreDatabase;
4use crate::DbError;
5use coven_foundation::progress::ProgressReport;
6
7impl StoreDatabase {
8    /// The sealed bytes a new device replays for `audience` after a
9    /// snapshot's coverage (§16.2): each applied writes slot carrying one of
10    /// its parts, and for the store every admin, key-copy and announcement
11    /// slot too. Local originals without a slot do not request a snapshot of
12    /// unpublished data, and slots this installation loaded inside a
13    /// snapshot instead of reading count nothing.
14    pub async fn snapshot_slot_bytes(
15        &self,
16        audience: coven_merge::Audience,
17        after: u64,
18    ) -> Result<u64, DbError> {
19        self.call(move |inner| {
20            inner.access.with_committed(|db, _| {
21                let mut bytes = 0u64;
22                db.for_each("SELECT s.size FROM _coven_write_slot_audiences a JOIN _coven_write_slots s ON s.slot=a.slot WHERE a.audience=?1 AND a.slot>?2",
23                    sqlive::rusqlite::params![audience, after.to_be_bytes()], |row| {
24                        let size = u64::try_from(row.get::<_, i64>(0)?).map_err(|_negative| DbError::DamagedDatabase)?;
25                        bytes = crate::sqlite::add_total("snapshot slot bytes", bytes, size)?;
26                        Ok::<_, DbError>(())
27                    })?;
28                if audience == coven_merge::Audience::Store {
29                    let records: i64 = db.query_row("SELECT coalesce(sum(length(record)),0) FROM _coven_slot_records WHERE slot>?1",
30                        [after.to_be_bytes()], |row| row.get(0))?;
31                    let records = u64::try_from(records).map_err(|_negative| DbError::DamagedDatabase)?;
32                    bytes = crate::sqlite::add_total("snapshot slot bytes", bytes, records)?;
33                }
34                Ok(bytes)
35            })
36        }).await
37    }
38
39    /// Whether an applied writes slot carries a part for `audience` that no
40    /// ordinary snapshot of it covers yet (§16.2, §16.4).
41    pub async fn audience_holds_parts(
42        &self,
43        audience: coven_merge::Audience,
44    ) -> Result<bool, DbError> {
45        self.call(move |inner| {
46            inner.access.with_committed(|db, _| {
47                let held: i64 = db.query_row(
48                    "SELECT EXISTS(SELECT 1 FROM _coven_write_slot_audiences WHERE audience=?1)",
49                    sqlive::rusqlite::params![audience],
50                    |row| row.get(0),
51                )?;
52                Ok(held != 0)
53            })
54        })
55        .await
56    }
57
58    /// Headers of waiting plaintext writes, including fixed upload attempts.
59    /// Snapshot growth counts these parts before their eventual publication.
60    pub async fn waiting_snapshot_headers(
61        &self,
62    ) -> Result<Vec<coven_format::write_stream::WriteHeaderFrame>, DbError> {
63        self.call(move |inner| {
64            inner.access.with_committed(|db, _| {
65                let mut headers = Vec::new();
66                crate::upload::each_plaintext(db, |header, _| {
67                    headers.push(header);
68                    Ok(())
69                })?;
70                Ok(headers)
71            })
72        })
73        .await
74    }
75
76    /// Run the snapshot loader's schema and merge checks over a staged
77    /// snapshot in a transaction that always rolls back, returning the uploaded
78    /// files it names. File retention uses this for a snapshot no reload has
79    /// read; a damaged snapshot cannot leave rows, metadata or observations
80    /// behind. Supply the staging of a body that authenticated: the check is
81    /// its last phase, and removes its records whether it passes or fails
82    /// (§16.2).
83    pub async fn validate_snapshot(
84        &self,
85        id: coven_format::admin::SnapshotId,
86        staging: crate::SnapshotStaging,
87        author: coven_foundation::id_source::MemberId,
88        authorship: std::sync::Arc<dyn crate::Authorship>,
89    ) -> Result<
90        std::collections::BTreeSet<(
91            coven_foundation::id_source::DeviceId,
92            coven_foundation::id_source::ObjectId,
93        )>,
94        DbError,
95    > {
96        if !staging.staged_by(self) {
97            return Err(
98                super::input_database::staging::refuse(vec![staging], STAGED_ELSEWHERE).await
99            );
100        }
101        let mut stagings = [staging];
102        self.call(move |inner| {
103            inner.inputs.read_staged(&mut stagings, |inputs, [staging]| {
104                // A failure reading the body names the snapshot.
105                let body = |error: DbError| crate::SnapshotError::Body {
106                    snapshot: id.clone(),
107                    error: Box::new(error),
108                    staged: None,
109                };
110                let prepared = staging.prepare(inputs, authorship.as_ref()).map_err(&body)?;
111                inner.access.with_writer(|writer, call| {
112                    let db = &*writer;
113                    db.discarded_transaction(|_| {
114                        let writer = &db;
115                        let schema = &inner.access.write_schema;
116                        crate::snapshot_state::create_tables(writer)?;
117                        crate::snapshot_install::create_tables(writer, schema)?;
118                        // Validating runs installing's passes where no
119                        // host draws them.
120                        let mut progress = ProgressReport::unwatched(inner.clock.clone());
121                        crate::snapshot_load::begin_installing(schema, 1, &mut progress);
122                        crate::snapshot_load::read(
123                            writer,
124                            call,
125                            schema,
126                            prepared,
127                            Some(author),
128                            &mut progress,
129                        )
130                        .map_err(&body)?;
131                        super::file_retention::snapshot_references(writer, schema, &id.audience)
132                    })
133                })
134            })
135        })
136        .await
137    }
138
139    /// Stream an audience's plaintext snapshot frames from one committed reader
140    /// transaction. `begin` receives metadata before any frame, so the consumer
141    /// can write the sealed prefix and seal each subsequent frame as it arrives;
142    /// commits on the writer connection continue throughout this call. While
143    /// this device's raise of the audience waits, it refuses with
144    /// [`DbError::RaiseWaiting`]: the snapshot would be written at a schema
145    /// version the history doesn't hold yet (§16.2). Returns the snapshot's
146    /// breaking version, for its announcement (§16.3).
147    pub async fn write_snapshot<B, F, E>(
148        &self,
149        id: coven_format::admin::SnapshotId,
150        begin: B,
151        emit: F,
152    ) -> Result<u32, crate::SnapshotWriteError<E>>
153    where
154        B: FnOnce(&coven_format::snapshot::SnapshotHeader) -> Result<(), E> + Send + 'static,
155        F: FnMut(Vec<u8>) -> Result<(), E> + Send + 'static,
156        E: coven_foundation::task::CarriesBug + Send + 'static,
157    {
158        self.call(move |inner| {
159            inner.access.with_committed(|reader, call| {
160                // In the transaction that reads the schema version the
161                // snapshot is written at.
162                if crate::raise_capture::provisional(reader)?
163                    .iter()
164                    .any(|(audience, _, _)| *audience == id.audience)
165                {
166                    return Err(DbError::RaiseWaiting.into());
167                }
168                crate::write_schema::prepare_evaluators(reader, &inner.access.write_schema)?;
169                crate::snapshot_write::write(
170                    reader,
171                    call,
172                    &inner.access.write_schema,
173                    id,
174                    begin,
175                    emit,
176                )
177            })
178        })
179        .await
180    }
181
182    /// Stream an audience's plaintext frames as [`Self::write_snapshot`] does,
183    /// without refusing while a raise of the audience waits: a rebuild's store
184    /// holds such raises and writes the circle's state it counted (§18.3).
185    pub(crate) async fn write_counted_snapshot<B, F, E>(
186        &self,
187        id: coven_format::admin::SnapshotId,
188        begin: B,
189        emit: F,
190    ) -> Result<u32, crate::SnapshotWriteError<E>>
191    where
192        B: FnOnce(&coven_format::snapshot::SnapshotHeader) -> Result<(), E> + Send + 'static,
193        F: FnMut(Vec<u8>) -> Result<(), E> + Send + 'static,
194        E: coven_foundation::task::CarriesBug + Send + 'static,
195    {
196        self.call(move |inner| {
197            inner.access.with_committed(|reader, call| {
198                crate::write_schema::prepare_evaluators(reader, &inner.access.write_schema)?;
199                crate::snapshot_write::write(
200                    reader,
201                    call,
202                    &inner.access.write_schema,
203                    id,
204                    begin,
205                    emit,
206                )
207            })
208        })
209        .await
210    }
211
212    /// The version of the newest breaking migration this installation ran,
213    /// zero if none: its snapshots' breaking version (§16.3).
214    pub async fn breaking_version(&self) -> Result<u32, DbError> {
215        self.call(move |inner| {
216            inner.access.with_reader(|db, _| crate::raise_capture::breaking_version(db))
217        })
218        .await
219    }
220
221    /// The raise snapshots a breaking migration captured through its marker,
222    /// one per audience this device read then (§18.3, §11.5).
223    pub async fn raise_captures(&self) -> Result<Vec<crate::RaiseCapture>, DbError> {
224        self.call(move |inner| {
225            inner.access.with_reader(|reader, _| {
226                crate::raise_capture::captures(reader, inner.access.device)
227            })
228        })
229        .await
230    }
231
232    /// The capture to seal for an audience's raise, right after a completed
233    /// catch-up: kept if that catch-up applied nothing past it, otherwise
234    /// captured again from the current state through this device's newest
235    /// write, which then joins the prefix to confirm (§16.3, §18.5). None when
236    /// a later migration replaced the capture.
237    pub async fn prepare_raise_capture(
238        &self,
239        audience: coven_merge::Audience,
240        version: u32,
241    ) -> Result<Option<crate::RaiseCapture>, DbError> {
242        self.call(move |inner| {
243            let device = inner.access.device;
244            inner.access.with_writer(|writer, _| {
245                writer.transaction(|writer| {
246                    crate::raise_capture::prepare(
247                        writer,
248                        &inner.access.write_schema,
249                        device,
250                        &audience,
251                        version,
252                    )
253                })
254            })
255        })
256        .await
257    }
258
259    /// The first own write of a snapshot's captured prefix, through its
260    /// own position, not yet confirmed stored. Any snapshot, ordinary, raise
261    /// or reset, is sent only once this is `None` (§16.1); a raise starts
262    /// only then (§18.5).
263    pub async fn unconfirmed_own_prefix(
264        &self,
265        through: coven_merge::WriteId,
266    ) -> Result<Option<coven_merge::WriteId>, DbError> {
267        self.call(move |inner| {
268            inner.access.with_reader(|reader, _| crate::upload::unconfirmed(reader, through))
269        })
270        .await
271    }
272
273    /// Stream an audience's captured raise snapshot under its published
274    /// identity, like `write_snapshot` but from the migration's capture.
275    pub async fn write_raise_snapshot<B, F, E>(
276        &self,
277        id: coven_format::admin::SnapshotId,
278        version: u32,
279        begin: B,
280        emit: F,
281    ) -> Result<u32, crate::SnapshotWriteError<E>>
282    where
283        B: FnOnce(&coven_format::snapshot::SnapshotHeader) -> Result<(), E> + Send + 'static,
284        F: FnMut(Vec<u8>) -> Result<(), E> + Send + 'static,
285        E: coven_foundation::task::CarriesBug + Send + 'static,
286    {
287        self.call(move |inner| {
288            inner.access.with_committed(|reader, call| {
289                crate::write_schema::prepare_evaluators(reader, &inner.access.write_schema)?;
290                crate::raise_capture::write(
291                    reader,
292                    call,
293                    &inner.access.write_schema,
294                    id,
295                    version,
296                    begin,
297                    emit,
298                )
299            })
300        })
301        .await
302    }
303
304    /// Forget a capture whose raise is published or superseded.
305    pub async fn discard_raise_capture(
306        &self,
307        audience: coven_merge::Audience,
308        version: u32,
309    ) -> Result<(), DbError> {
310        self.call(move |inner| {
311            inner.access.with_writer(|writer, _| {
312                writer
313                    .transaction(|writer| crate::raise_capture::discard(writer, &audience, version))
314            })
315        })
316        .await
317    }
318
319    /// Load authenticated snapshots and gap writes supplied by sync. Each stored
320    /// snapshot supplies its identity and its staging, of a body whose stream
321    /// checked out to its end; their write evidence is authenticated, and write
322    /// parts are staged on the input connection, before taking the application
323    /// writer. Inputs name a fixed target and consecutive retained slots.
324    ///
325    /// Replaces the selected audiences and replays uncovered parts and waiting
326    /// uploads in one transaction. The load is each staging's last phase: it
327    /// reads each staged snapshot once and removes its records, whether it
328    /// commits or fails. Every audience finishes at the common target slot;
329    /// missing history, read errors and failed checks roll the whole load back,
330    /// a body's failure as `SnapshotError::Body` naming that snapshot. Returns
331    /// the uploaded files each stored snapshot names.
332    /// Supply each readable audience's parts, including those needed by waiting
333    /// writes and the device's own earlier writes. Other audiences retain their
334    /// merge history. Upload records, numbers and sealing key ids stay unchanged.
335    /// `progress`, when given, hears the `Installing` and `InstallingSlots`
336    /// steps as they run (§13.4).
337    pub async fn load_snapshots<P: crate::PendingValue, W>(
338        &self,
339        reload: crate::SnapshotReload<crate::SnapshotStaging, crate::DownloadedWriteStream<W>>,
340        progress: Option<ProgressReport<crate::LoadStep>>,
341    ) -> Result<Vec<crate::LoadedSnapshot>, DbError>
342    where
343        W: std::io::Read + Send + 'static,
344    {
345        self.load_through::<P, W>(reload, progress, None, None).await
346    }
347
348    /// Install `circle`, which this device rebuilt under its migration write
349    /// `marker`: its start is the rebuilt snapshot, its raise is captured
350    /// through the marker, and its wait for the rebuild ends, all in the one
351    /// commit that loads it (§18.3). `reload` is a [`Self::load_snapshots`]
352    /// input whose `circle` start is the stored snapshot the rebuild exported.
353    pub async fn install_rebuilt<P: crate::PendingValue, W>(
354        &self,
355        reload: crate::SnapshotReload<crate::SnapshotStaging, crate::DownloadedWriteStream<W>>,
356        circle: coven_merge::Audience,
357        marker: coven_merge::WriteId,
358    ) -> Result<Vec<crate::LoadedSnapshot>, DbError>
359    where
360        W: std::io::Read + Send + 'static,
361    {
362        self.load_through::<P, W>(reload, None, None, Some((circle, marker))).await
363    }
364
365    /// [`Self::load_snapshots`], for a rebuild's store when `rebuilding` is
366    /// given: the store's parts in slots after `rebuilding.store_through`
367    /// aren't read, and a write above this database's version is kept as a
368    /// lost value, not waited for (§18.3).
369    pub(crate) async fn load_through<P: crate::PendingValue, W>(
370        &self,
371        reload: crate::SnapshotReload<crate::SnapshotStaging, crate::DownloadedWriteStream<W>>,
372        progress: Option<ProgressReport<crate::LoadStep>>,
373        rebuilding: Option<crate::snapshot_coverage::Rebuilding>,
374        rebuilt: Option<(coven_merge::Audience, coven_merge::WriteId)>,
375    ) -> Result<Vec<crate::LoadedSnapshot>, DbError>
376    where
377        W: std::io::Read + Send + 'static,
378    {
379        // Each stored source names its staging by its place among them.
380        let mut stagings = Vec::new();
381        let sources: Vec<crate::SnapshotSource<usize>> = reload
382            .snapshots
383            .into_iter()
384            .map(|source| match source {
385                crate::SnapshotSource::Stored { id, input, author } => {
386                    stagings.push(input);
387                    crate::SnapshotSource::Stored { id, input: stagings.len() - 1, author }
388                }
389                crate::SnapshotSource::Empty(audience, covers) => {
390                    crate::SnapshotSource::Empty(audience, covers)
391                }
392                crate::SnapshotSource::Current(audience) => {
393                    crate::SnapshotSource::Current(audience)
394                }
395            })
396            .collect();
397        if !stagings.iter().all(|staging| staging.staged_by(self)) {
398            return Err(super::input_database::staging::refuse(stagings, STAGED_ELSEWHERE).await);
399        }
400        let authorship = reload.authorship;
401        self.call(move |inner| {
402            let started = inner.clock.elapsed();
403            let mut progress =
404                progress.unwrap_or_else(|| ProgressReport::unwatched(inner.clock.clone()));
405            inner.inputs.read_staged(&mut stagings, |inputs, stagings| {
406                let snapshots = sources
407                    .into_iter()
408                    .map(|source| {
409                        Ok(match source {
410                            crate::SnapshotSource::Stored { id, input, author } => {
411                                let input = stagings[input]
412                                    .prepare(inputs, authorship.as_ref())
413                                    .map_err(|error| crate::SnapshotError::Body {
414                                        snapshot: id.clone(),
415                                        error: Box::new(error),
416                                        staged: None,
417                                    })?;
418                                crate::SnapshotSource::Stored { id, input, author }
419                            }
420                            crate::SnapshotSource::Empty(audience, covers) => {
421                                crate::SnapshotSource::Empty(audience, covers)
422                            }
423                            crate::SnapshotSource::Current(audience) => {
424                                crate::SnapshotSource::Current(audience)
425                            }
426                        })
427                    })
428                    .collect::<Result<_, DbError>>()?;
429                let reload = crate::SnapshotReload {
430                    slots: reload
431                        .slots
432                        .into_iter()
433                        .map(|slot| slot.prepare(inputs))
434                        .collect::<Result<_, _>>()?,
435                    snapshots,
436                    target: reload.target,
437                    state: reload.state,
438                    provider_access: reload.provider_access,
439                    cutoffs: reload.cutoffs,
440                    boundaries: reload.boundaries,
441                    operation: reload.operation,
442                    rebuilds: reload.rebuilds,
443                    authorship,
444                };
445                let prepared = inner.clock.elapsed();
446                // Reserve a reader before locking the writer: snapshot consumers
447                // may be waiting for a commit before releasing their readers.
448                let reader = inner.access.database.reader();
449                let loaded = inner.with_files("load a snapshot", |writer, call, files| {
450                    inner.access.with_leased(&reader, |reader, reader_call| {
451                        crate::transaction_constants::read_with_constants(
452                            reader,
453                            reader_call,
454                            || {
455                                crate::write_schema::prepare_evaluators(
456                                    reader,
457                                    &inner.access.write_schema,
458                                )?;
459                                crate::snapshot_load::load::<P>(
460                                    writer,
461                                    call,
462                                    reader,
463                                    reader_call,
464                                    &inner.access.write_schema,
465                                    reload,
466                                    files,
467                                    &mut progress,
468                                    rebuilding,
469                                    inner.joining_write.as_deref(),
470                                    inner.clock.now(),
471                                    rebuilt.map(|(circle, marker)| crate::snapshot_load::Rebuilt {
472                                        circle,
473                                        marker,
474                                        operation: inner.raise_operation.as_deref(),
475                                    }),
476                                )
477                            },
478                        )
479                    })
480                });
481                tracing::info!(
482                    preparing = ?(prepared - started),
483                    installing = ?(inner.clock.elapsed() - prepared),
484                    "installed snapshots"
485                );
486                loaded
487            })
488        })
489        .await
490    }
491}
492
493/// A staging another store made: its records are on that store's input
494/// connection, not this one's.
495const STAGED_ELSEWHERE: DbError =
496    DbError::Invariant { what: "a snapshot is loaded by the store that staged it" };