Skip to main content

coven_database/
database_sync.rs

1//! Database operations used by synchronization, on the retained connections.
2
3use super::{Mode, StoreDatabase};
4use crate::internal_schema::retry_effect::{self, RetryState};
5use crate::sqlite::StoreSql;
6use crate::store_call::StoreCall;
7use crate::DbError;
8use coven_foundation::task::CarriesBug;
9
10impl StoreDatabase {
11    /// Transfer metadata of the current durable claim attempt.
12    pub async fn claim_upload(&self) -> Result<crate::ClaimUpload, DbError> {
13        self.call(|inner| inner.access.with_committed(|db, _| crate::claim::upload(db))).await
14    }
15    /// A bounded range of the current attempt, used by a recorded upload.
16    pub async fn claim_range(&self, offset: u64, length: usize) -> Result<Vec<u8>, DbError> {
17        self.call(move |inner| {
18            inner.access.with_committed(|db, _| crate::claim::range(db, offset, length))
19        })
20        .await
21    }
22    /// Save provider-confirmed progress before the next part is sent.
23    pub async fn save_claim_upload(&self, session: Vec<u8>) -> Result<(), DbError> {
24        self.call(move |inner| {
25            inner.access.with_writer(|writer, _| {
26                writer.stream_transaction(|db| crate::claim::save_upload(db, session))
27            })
28        })
29        .await
30    }
31    /// Fix first-attempt keys for this captured queue prefix. Previously
32    /// attempted originals retain their exact format and keys.
33    pub async fn prepare_uploads<E, F>(
34        &self,
35        through: u64,
36        select: F,
37    ) -> Result<crate::PreparedUploads, E>
38    where
39        E: From<DbError> + From<coven_format::Error> + CarriesBug + Send + 'static,
40        F: FnMut(
41                &coven_format::write_stream::WriteHeaderFrame,
42            ) -> Result<coven_format::sealed_write::WriteObjectPrefix, E>
43            + Send
44            + 'static,
45    {
46        self.call(move |inner| {
47            inner.access.with_writer(|writer, _| {
48                crate::upload::prepare_batch(writer, inner.access.device, through, select)
49            })
50        })
51        .await
52    }
53
54    /// Stream the prepared originals through one committed reader. Concurrent
55    /// app commits append after the prepared prefix and remain for the next pass.
56    pub async fn read_uploads<E, F>(
57        &self,
58        prepared: crate::PreparedUploads,
59        consume: F,
60    ) -> Result<(), E>
61    where
62        E: From<DbError> + CarriesBug + Send + 'static,
63        F: FnMut(crate::WaitingUpload<'_>) -> Result<(), E> + Send + 'static,
64    {
65        self.call(move |inner| {
66            inner
67                .access
68                .with_committed(|reader, _| crate::upload::read_batch(reader, prepared, consume))
69        })
70        .await
71    }
72
73    /// Authenticate and retain original source records covered by an applied slot
74    /// or snapshot, without applying their data again or changing source verdicts.
75    #[cfg(test)]
76    pub async fn retain_write_sources<R, F>(
77        &self,
78        write: crate::DownloadedWriteStream<R>,
79        authenticate: F,
80    ) -> Result<(), DbError>
81    where
82        R: std::io::Read + Send + 'static,
83        F: FnOnce() -> Result<(), DbError> + Send + 'static,
84    {
85        self.call(move |inner| {
86            inner.inputs.prepare(|inputs| {
87                let write = write.prepare(inputs)?;
88                authenticate()?;
89                inner.access.with_writer(|writer, call| {
90                    writer.stream_transaction(|db| {
91                        crate::download_stream::retain_sources(
92                            db,
93                            call,
94                            &inner.access.write_schema,
95                            write,
96                        )
97                    })
98                })
99            })
100        })
101        .await
102    }
103
104    /// Commit one complete slot, its claim number and every readable effect.
105    /// Authentication failure rolls back the slot and leaves its predecessor
106    /// applied. `writers` are the other devices that can still write once
107    /// the slot is applied, which kept records wait for (§16.7).
108    pub async fn apply_slot<P, R, F>(
109        &self,
110        incoming: crate::IncomingSlot<crate::DownloadedWriteStream<R>>,
111        writers: crate::Writers,
112        authenticate: F,
113    ) -> Result<crate::ApplyOutcome, DbError>
114    where
115        P: crate::PendingValue,
116        R: std::io::Read + Send + 'static,
117        F: FnOnce() -> Result<(), DbError> + Send + 'static,
118    {
119        self.call(move |inner| {
120            if let crate::SlotContent::Admin { effect: Some(effect), .. } = &incoming.content {
121                if let Some(store) = &effect.state.store {
122                    crate::store_state::check_creation(store.id, inner.access.directory.id())?;
123                }
124            }
125            let started = inner.clock.elapsed();
126            inner.inputs.prepare(|inputs| {
127                let slot = incoming.slot;
128                let incoming = incoming.prepare(inputs)?;
129                let prepared = inner.clock.elapsed();
130                let reader = inner.access.database.reader();
131                let applied = inner.with_files("apply a slot", |writer, call, files| {
132                    inner.access.with_leased(&reader, |reader, reader_call| {
133                        crate::transaction_constants::read_with_constants(
134                            reader,
135                            reader_call,
136                            || {
137                                crate::write_schema::prepare_evaluators(
138                                    reader,
139                                    &inner.access.write_schema,
140                                )?;
141                                crate::transaction_constants::schema_version(reader, reader_call)?;
142                                crate::sequence_apply::apply::<P>(
143                                    writer,
144                                    call,
145                                    reader,
146                                    reader_call,
147                                    &inner.access.write_schema,
148                                    incoming,
149                                    &writers,
150                                    files,
151                                    inner.raise_operation.as_deref(),
152                                    inner.joining_write.as_deref(),
153                                    inner.clock.now(),
154                                    authenticate,
155                                )
156                            },
157                        )
158                    })
159                });
160                tracing::debug!(
161                    slot = slot.get(),
162                    preparing = ?(prepared - started),
163                    applying = ?(inner.clock.elapsed() - prepared),
164                    "applied slot"
165                );
166                applied
167            })
168        })
169        .await
170    }
171    /// Fix the keys of the oldest original before constructing its batch.
172    #[cfg(test)]
173    pub async fn prepare_upload<F>(
174        &self,
175        select: F,
176    ) -> Result<Option<coven_merge::WriteId>, DbError>
177    where
178        F: FnOnce(
179                &crate::StoreState,
180                u32,
181                &coven_format::write_stream::WriteHeaderFrame,
182            ) -> Result<coven_format::sealed_write::WriteObjectPrefix, DbError>
183            + Send
184            + 'static,
185    {
186        self.call(move |inner| {
187            inner.access.with_writer(|db, call| {
188                let state = crate::store_state_tables::read(db)?;
189                crate::upload::prepare(db, call, &state, select)
190            })
191        })
192        .await
193    }
194    /// The newest waiting write this device may send now, read in one
195    /// committed state with the queue (§6.3): none past an unpublished
196    /// breaking raise's capture, and none from a write a bound upload holds
197    /// on (§17.4). `None` with no write waiting.
198    pub async fn sendable_through(&self) -> Result<Option<u64>, DbError> {
199        self.call(|inner| {
200            let device = inner.access.device;
201            inner.access.with_committed(|db, _| crate::upload::sendable_through(db, device))
202        })
203        .await
204    }
205
206    /// Original plaintext of an authenticated received or confirmed published header.
207    /// This establishes header facts, not the validity of a subsequently read body.
208    #[cfg(test)]
209    pub async fn checked_write_header(
210        &self,
211        id: coven_merge::WriteId,
212    ) -> Result<Option<coven_format::write_stream::WriteHeaderFrame>, DbError> {
213        self.call(move |inner| inner.access.with_reader(|db, _| crate::write_headers::read(db, id)))
214            .await
215    }
216
217    /// Audiences whose counted administrative effects require replacement data.
218    /// Loading their replacement rows removes the requirement atomically.
219    pub async fn reloading_audiences(
220        &self,
221    ) -> Result<std::collections::BTreeSet<coven_merge::Audience>, DbError> {
222        self.call(move |inner| {
223            inner.access.with_reader(|db, _| crate::reload_gate::reloading_audiences(db))
224        })
225        .await
226    }
227
228    /// The circles waiting for their rebuild (§18.3), each with the migration
229    /// write the rebuild runs under, which this device queued when it started
230    /// reading the circle. Their parts pass unread and writes into them fail
231    /// with `AudienceReloading` until the rebuild commits.
232    pub async fn rebuilds_waiting(
233        &self,
234    ) -> Result<std::collections::BTreeMap<coven_merge::Audience, coven_merge::WriteId>, DbError>
235    {
236        self.call(move |inner| inner.access.with_reader(|db, _| crate::reload_gate::rebuilding(db)))
237            .await
238    }
239
240    /// The header of one of this device's writes the store holds, with the
241    /// slot it landed in if it has landed: a rebuild runs under the header of
242    /// its migration marker, once the marker has a slot (§18.3).
243    pub async fn write_header(
244        &self,
245        write: coven_merge::WriteId,
246    ) -> Result<Option<(coven_format::write::WriteHeader, Option<coven_merge::Slot>)>, DbError>
247    {
248        self.call(move |inner| {
249            inner.access.with_reader(|db, _| {
250                let Some(frame) = crate::write_headers::read(db, write)? else {
251                    return Ok(None);
252                };
253                let slot =
254                    crate::write_metadata::stored_write(db, write)?.and_then(|stored| stored.slot);
255                Ok(Some((frame.header, slot)))
256            })
257        })
258        .await
259    }
260
261    /// Queue a new migration marker, read through the slot applied now, and
262    /// point every waiting rebuild at it: their history at the old marker's
263    /// slot is gone (§18.3).
264    pub async fn restart_rebuilds(&self) -> Result<(), DbError> {
265        self.call(move |inner| {
266            inner.access.with_writer(|writer, call| {
267                writer.transaction(|writer| {
268                    crate::rebuild_wait::restart(
269                        writer,
270                        call,
271                        &inner.access.write_schema,
272                        inner.clock.now(),
273                    )
274                })
275            })
276        })
277        .await
278    }
279
280    /// Current pending records, decoded as the sync owner's typed values.
281    pub async fn pending<P: crate::PendingValue>(&self) -> Result<Vec<P>, DbError> {
282        self.read_committed(crate::pending::read).await
283    }
284
285    /// Writes and files this device committed and has not uploaded, from one
286    /// committed state.
287    pub async fn unsent(&self) -> Result<crate::UnsentWork, DbError> {
288        self.read_committed(crate::file_queue::unsent).await
289    }
290
291    /// The same pre-built unsent-work query, observing committed changes.
292    pub fn subscribe_unsent<E>(&self) -> crate::LiveQuery<crate::UnsentWork, E>
293    where
294        E: From<DbError> + coven_foundation::task::CarriesBug + Send + 'static,
295    {
296        self.follow(|db| crate::file_queue::unsent(db).map_err(E::from))
297    }
298
299    /// The upload queue with what its uploads' phases are computed from
300    /// (§17.9): the facts the sync state reads, what holds trailing uploads,
301    /// every queued file with its recorded provider session, and what is
302    /// recorded about each upload, in one committed snapshot, available while
303    /// disconnected (E7).
304    pub async fn upload_queue_facts<P, T, E>(
305        &self,
306        compute: impl FnOnce(crate::QueueFacts<P>) -> Result<T, E> + Send + 'static,
307    ) -> Result<T, E>
308    where
309        P: crate::PendingValue + Clone,
310        T: Send + 'static,
311        E: From<DbError> + coven_foundation::task::CarriesBug + Send + 'static,
312    {
313        self.read_committed(move |db| compute(crate::sync_facts::read_queue(db)?)).await
314    }
315
316    /// The upload queue, its pause setting and each file's recorded provider
317    /// session in one committed snapshot, available while disconnected (E7).
318    pub async fn upload_queue(&self) -> Result<crate::UploadQueueState, DbError> {
319        self.read_committed(crate::file_queue::state).await
320    }
321
322    /// Record, as the store opens, whether a storage location is recorded
323    /// here and its credentials held, and that no pass moves, keeping how the
324    /// last pass ended and when sync last finished; `finished`, for a store
325    /// joining or restoring read to its end, is when (api.md E5). The
326    /// provider is as sync names it, and the location as its settings text.
327    /// A failure fails this handle with its cause, as losing a pending record
328    /// does.
329    pub async fn record_opened(
330        &self,
331        location: crate::RecordedLocation<crate::StoredLocation>,
332        finished: Option<std::time::SystemTime>,
333    ) -> Result<(), DbError> {
334        self.save_sync_status(move |db, _| {
335            crate::internal_schema::sync_status::save_location(db, &location, finished, true)
336        })
337        .await
338    }
339
340    /// Record whether a storage location is recorded here and its
341    /// credentials held, with the location and its labels, as setup, a
342    /// change of credentials, a connection's new label or releasing a
343    /// connection finds it; `finished`, for setup, is when it read the store
344    /// to its end. A failure fails this handle, as `record_opened`'s does.
345    pub async fn record_location(
346        &self,
347        location: crate::RecordedLocation<crate::StoredLocation>,
348        finished: Option<std::time::SystemTime>,
349    ) -> Result<(), DbError> {
350        self.save_sync_status(move |db, _| {
351            crate::internal_schema::sync_status::save_location(db, &location, finished, false)
352        })
353        .await
354    }
355
356    /// Record what the running pass moved last: a slot it read that it
357    /// hadn't, or one it claimed. A failure fails this handle, as
358    /// `record_opened`'s does.
359    pub async fn record_moved(&self, moved: crate::PassMove) -> Result<(), DbError> {
360        self.save_sync_status(move |db, _| {
361            crate::internal_schema::sync_status::save_moved(db, moved)
362        })
363        .await
364    }
365
366    /// Record how the last pass ended, as sync encodes it, when sync failed
367    /// outside a pass's end: starting, stopping, or a local failure or panic
368    /// of the loop's, in a pass or outside one; and that nothing moves. A
369    /// failure fails this handle, as `record_opened`'s does.
370    pub async fn record_last_pass(&self, last_pass: Vec<u8>) -> Result<(), DbError> {
371        self.save_sync_status(move |db, _| {
372            crate::internal_schema::sync_status::save_last_pass(db, &last_pass)
373        })
374        .await
375    }
376
377    /// Record that a store-wide worker's panic halted sync until the store
378    /// reopens, with its failure, as sync encodes it, as how the last pass
379    /// ended, and that nothing moves: from here no pass writes the row. A
380    /// failure fails this handle, as `record_opened`'s does.
381    pub async fn record_halt(&self, last_pass: Vec<u8>) -> Result<(), DbError> {
382        self.save_sync_status(move |db, _| {
383            crate::internal_schema::sync_status::save_halt(db, &last_pass)
384        })
385        .await
386    }
387
388    /// Record how the running pass ended, as sync encodes it, and that it
389    /// moves no more; `finished`, for a pass that reached the end of the
390    /// sequence, is when, which becomes the last synced time unless that is
391    /// later. A failure fails this handle, as `record_opened`'s does.
392    pub async fn record_pass_end(
393        &self,
394        last_pass: Vec<u8>,
395        finished: Option<std::time::SystemTime>,
396    ) -> Result<(), DbError> {
397        self.save_sync_status(move |db, _| {
398            crate::internal_schema::sync_status::save_pass_end(db, &last_pass, finished)
399        })
400        .await
401    }
402
403    /// Write `coven_sync_status` in the step that changes it, on the writer.
404    async fn save_sync_status(
405        &self,
406        save: impl FnOnce(&StoreSql, &StoreCall<'_>) -> Result<(), DbError> + Send + 'static,
407    ) -> Result<(), DbError> {
408        self.call(move |inner| {
409            inner.access.with_writer(|writer, call| {
410                crate::pending::state_transaction(writer, |db| save(db, call))
411            })
412        })
413        .await
414    }
415
416    /// Change what decides the person's retry, `coven_retry_effect`'s row,
417    /// then run `then` with the state as committed, in one step on the
418    /// writer: no other change to the state, and no other `then`, comes
419    /// between them, so a decision `then` makes from the state is the one
420    /// the row shows. `change` gets the state as the row holds it; `then`
421    /// runs only once the change commits. A failed write fails this handle
422    /// with its cause, as losing a pending record does.
423    pub async fn change_retry_state<T: Send + 'static>(
424        &self,
425        change: impl FnOnce(RetryState) -> RetryState + Send + 'static,
426        then: impl FnOnce(RetryState) -> T + Send + 'static,
427    ) -> Result<T, DbError> {
428        self.retry_step(change, then, |_| Ok(())).await
429    }
430
431    /// Change the retry state as sync starts, as `change_retry_state` does,
432    /// and count the start in `coven_sync_status.starts` in the same
433    /// transaction: every start writes the row, even one that holds for the
434    /// reason the last one did.
435    pub async fn start_retry_state<T: Send + 'static>(
436        &self,
437        change: impl FnOnce(RetryState) -> RetryState + Send + 'static,
438        then: impl FnOnce(RetryState) -> T + Send + 'static,
439    ) -> Result<T, DbError> {
440        self.retry_step(change, then, crate::internal_schema::sync_status::save_start).await
441    }
442
443    async fn retry_step<T: Send + 'static>(
444        &self,
445        change: impl FnOnce(RetryState) -> RetryState + Send + 'static,
446        then: impl FnOnce(RetryState) -> T + Send + 'static,
447        also: fn(&StoreSql) -> Result<(), DbError>,
448    ) -> Result<T, DbError> {
449        self.call(move |inner| {
450            inner.access.with_writer(|writer, _| {
451                let state = crate::pending::state_transaction(writer, |db| {
452                    let state = retry_effect::stored(change(retry_effect::read(db)?))?;
453                    retry_effect::save(db, state)?;
454                    also(db)?;
455                    Ok(state)
456                })?;
457                Ok(then(state))
458            })
459        })
460        .await
461    }
462
463    /// Record the provider cooldown's wait, and change the retry state as
464    /// `change_retry_state` does, in one transaction: the cooldown that
465    /// holds every pass and the effect it gives a retry commit together.
466    pub async fn record_cooldown(
467        &self,
468        wait: crate::RetryWait,
469        change: impl FnOnce(RetryState) -> RetryState + Send + 'static,
470    ) -> Result<(), DbError> {
471        self.call(move |inner| {
472            inner.access.with_writer(|writer, _| {
473                crate::pending::state_transaction(writer, |db| {
474                    crate::retry::save(db, crate::RetrySubject::Provider, &wait)?;
475                    let state = retry_effect::stored(change(retry_effect::read(db)?))?;
476                    retry_effect::save(db, state)
477                })
478            })
479        })
480        .await
481    }
482
483    /// Record one local first unmet condition, replacing its previous reason.
484    pub async fn record_pending<P: crate::PendingValue>(&self, record: P) -> Result<(), DbError> {
485        self.call(move |inner| {
486            inner.access.with_writer(|writer, _| {
487                if let Some(id) = record.operation() {
488                    if crate::operation::find(writer, id)?.is_none() {
489                        return Err(DbError::OperationChanged(id));
490                    }
491                }
492                crate::pending::state_transaction(writer, |db| crate::pending::save(db, &record))
493            })
494        })
495        .await
496    }
497
498    /// Clear this device's observation when its subject advances. The usual
499    /// case, with nothing recorded, reads without taking the writer.
500    pub async fn clear_pending<S: serde::Serialize + Send + 'static>(
501        &self,
502        subject: S,
503    ) -> Result<(), DbError> {
504        self.clear_pending_checked(
505            subject,
506            |db, _, a0| crate::pending::recorded(db, a0),
507            |_, _| Ok(()),
508        )
509        .await
510        .map(drop)
511    }
512
513    /// Settle only the condition the consumer actually checked, using the
514    /// subject's indexed lookup and the same pending transaction as deletion.
515    pub(crate) async fn clear_checked<P: crate::PendingValue>(
516        &self,
517        subject: P::Subject,
518        checked: impl Fn(&P) -> bool + Send + 'static,
519    ) -> Result<(), DbError>
520    where
521        P::Subject: Send + 'static,
522    {
523        self.clear_pending_checked(
524            subject,
525            move |db, _, subject| {
526                Ok(crate::pending::find::<P>(db, subject)?.is_some_and(|record| checked(&record)))
527            },
528            |_, _| Ok(()),
529        )
530        .await
531        .map(drop)
532    }
533
534    /// Settle only the condition the consumer actually checked, as
535    /// `clear_checked` does, ending the wait of `object`'s queued upload
536    /// with it.
537    pub(crate) async fn clear_pending_if<P: crate::PendingValue>(
538        &self,
539        object: (coven_foundation::id_source::DeviceId, coven_foundation::id_source::ObjectId),
540        subject: P::Subject,
541        checked: impl Fn(&P) -> bool + Send + 'static,
542    ) -> Result<Option<crate::RetrySubject>, DbError>
543    where
544        P::Subject: Send + 'static,
545    {
546        self.clear_pending_checked(
547            subject,
548            move |db, _, subject| {
549                Ok(crate::pending::find::<P>(db, subject)?.is_some_and(|record| checked(&record)))
550            },
551            move |db, _| {
552                let retry = crate::file_queue::upload_id(db, object.0, object.1)?
553                    .map(crate::RetrySubject::Upload);
554                if let Some(retry) = retry {
555                    crate::retry::clear(db, retry)?;
556                }
557                Ok(retry)
558            },
559        )
560        .await
561        .map(Option::flatten)
562    }
563
564    async fn clear_pending_checked<S, F, T>(
565        &self,
566        subject: S,
567        checked: F,
568        settled: impl FnOnce(&StoreSql, &StoreCall<'_>) -> Result<T, DbError> + Send + 'static,
569    ) -> Result<Option<T>, DbError>
570    where
571        S: serde::Serialize + Send + 'static,
572        T: Send + 'static,
573        F: Fn(&StoreSql, &StoreCall<'_>, &S) -> Result<bool, DbError> + Send + 'static,
574    {
575        self.call(move |inner| {
576            let should_clear = inner.access.with_reader(|db, call| checked(db, call, &subject))?;
577            if !should_clear {
578                return Ok(None);
579            }
580            inner.access.with_writer(|writer, call| {
581                crate::pending::state_transaction(writer, |db| {
582                    // Another writer may have replaced this condition since
583                    // the committed read; deletion checks that current record.
584                    if checked(db, call, &subject)? {
585                        crate::pending::clear(db, &subject)?;
586                        return settled(db, call).map(Some);
587                    }
588                    Ok(None)
589                })
590            })
591        })
592        .await
593    }
594
595    /// Replace this device's observations of one completed scan atomically:
596    /// its records matching `scanned` become exactly `records`, so a subject
597    /// that now checks, or is no longer listed, loses its record in the same
598    /// transaction. An unchanged set writes nothing.
599    #[cfg(test)]
600    pub async fn replace_local_pending<P: crate::PendingValue>(
601        &self,
602        scanned: impl Fn(&P) -> bool + Send + 'static,
603        records: Vec<P>,
604    ) -> Result<(), DbError> {
605        use std::collections::BTreeSet;
606        self.call(move |inner| {
607            let mut identities = BTreeSet::new();
608            for record in &records {
609                if record.operation().is_some()
610                    || !scanned(record)
611                    || !identities.insert(record.subject())
612                {
613                    return Err(DbError::Invariant {
614                        what: "a scan replaces distinct records it covers",
615                    });
616                }
617            }
618            let encode = |r: &P| serde_json::to_vec(r).map_err(DbError::StateEncoding);
619            let next = records.iter().map(encode).collect::<Result<BTreeSet<_>, _>>()?;
620            // The usual unchanged scan reads its class without taking the writer.
621            let unchanged = inner.access.with_reader(|reader, _| {
622                let current = crate::pending::read::<P>(reader)?
623                    .into_iter()
624                    .filter(|r| scanned(r))
625                    .map(|r| encode(&r))
626                    .collect::<Result<BTreeSet<_>, _>>()?;
627                Ok::<_, DbError>(current == next)
628            })?;
629            if unchanged {
630                return Ok(());
631            }
632            inner.access.with_writer(|writer, _| {
633                let previous: Vec<_> =
634                    crate::pending::read::<P>(writer)?.into_iter().filter(|r| scanned(r)).collect();
635                if previous.iter().map(encode).collect::<Result<BTreeSet<_>, _>>()? == next {
636                    return Ok(());
637                }
638                crate::pending::state_transaction(writer, |db| {
639                    for record in &previous {
640                        if !identities.contains(record.subject()) {
641                            crate::pending::clear(db, record.subject())?;
642                        }
643                    }
644                    for record in &records {
645                        crate::pending::save(db, record)?;
646                    }
647                    Ok(())
648                })
649            })
650        })
651        .await
652    }
653
654    /// Apply the persisted condition's retry policy to this installed version.
655    pub async fn pending_can_retry<P: crate::PendingValue>(
656        &self,
657        subject: P::Subject,
658    ) -> Result<bool, DbError>
659    where
660        P::Subject: Send + 'static,
661    {
662        self.call(move |inner| {
663            inner
664                .access
665                .with_writer(|writer, call| crate::pending::retry::<P>(writer, call, &subject))
666        })
667        .await
668    }
669
670    /// Make every pending record one `build` recorded, as a store opened by
671    /// another build of coven finds the records an earlier one wrote (§19.1).
672    #[cfg(any(test, feature = "test-utils"))]
673    pub async fn set_pending_build(&self, build: u128) -> Result<(), DbError> {
674        self.call(move |inner| {
675            inner.access.with_writer(|writer, _| {
676                crate::pending::state_transaction(writer, |db| crate::pending::set_build(db, build))
677            })
678        })
679        .await
680    }
681
682    /// Read the oldest waiting plaintext.
683    /// The callback runs in a committed reader transaction; its result is `None`
684    /// when the queue is empty.
685    #[cfg(any(test, feature = "test-utils"))]
686    pub async fn read_oldest_upload<F, R, E>(
687        &self,
688        consume: F,
689    ) -> Result<Option<R>, crate::UploadReadError<E>>
690    where
691        F: FnOnce(crate::UploadPlaintext<'_>) -> Result<R, E> + Send + 'static,
692        R: Send + 'static,
693        E: CarriesBug + Send + 'static,
694    {
695        self.call(move |inner| {
696            inner.access.with_reader(|reader, call| {
697                crate::transaction_constants::read_with_constants(reader, call, || {
698                    crate::upload::read(reader, consume)
699                })
700            })
701        })
702        .await
703    }
704
705    /// The oldest waiting write and the keys its first attempt fixed, if
706    /// any; `None` when the queue is empty.
707    #[cfg(test)]
708    pub(crate) async fn oldest_upload_keys(
709        &self,
710    ) -> Result<
711        Option<(coven_merge::WriteId, Option<coven_format::sealed_write::WriteObjectPrefix>)>,
712        DbError,
713    > {
714        self.call(move |inner| {
715            inner.access.with_reader(|reader, call| {
716                crate::transaction_constants::read_with_constants(reader, call, || {
717                    crate::upload::oldest_keys(reader)
718                })
719            })
720        })
721        .await
722    }
723
724    /// The same state, live (E4), for a test waiting for passes to change
725    /// it, such as to apply a raise.
726    #[cfg(any(test, feature = "test-utils"))]
727    pub fn subscribe_store_state(&self) -> crate::LiveQuery<crate::StoreState, DbError> {
728        self.follow(crate::store_state_tables::read)
729    }
730
731    /// The store prefix whose complete effects have committed.
732    pub async fn applied_slot(&self) -> Result<u64, DbError> {
733        self.call(|inner| {
734            #[cfg(any(test, feature = "test-utils"))]
735            if inner
736                .applied_slot_failures
737                .try_update(
738                    std::sync::atomic::Ordering::SeqCst,
739                    std::sync::atomic::Ordering::SeqCst,
740                    |left| left.checked_sub(1),
741                )
742                .is_ok()
743            {
744                return Err(DbError::Sqlite(sqlive::rusqlite::Error::SqliteFailure(
745                    sqlive::rusqlite::ffi::Error::new(sqlive::rusqlite::ffi::SQLITE_IOERR),
746                    Some("injected applied slot read failure".into()),
747                )));
748            }
749            inner.access.with_committed(|db, _| crate::sequence::applied(db))
750        })
751        .await
752    }
753
754    /// Take every change that took a record off this device's bytes as
755    /// past every reset that could undo it (§17.11), then run an empty
756    /// write, after which the bytes no record needs go.
757    #[cfg(any(test, feature = "test-utils"))]
758    pub async fn test_past_every_reset(&self) {
759        self.call(move |inner| {
760            inner
761                .access
762                .with_writer(|writer, _| writer.transaction(crate::reset_bytes::past_every_reset))
763        })
764        .await
765        .expect("an open store settles its kept bytes");
766        self.write(|_| Ok::<_, DbError>(())).await.expect("an empty write commits");
767    }
768
769    /// Fail the next `count` `applied_slot` reads with a disk error.
770    #[cfg(any(test, feature = "test-utils"))]
771    pub async fn fail_applied_slots(&self, count: usize) {
772        self.call(move |inner| {
773            inner.applied_slot_failures.store(count, std::sync::atomic::Ordering::SeqCst);
774            Ok::<_, DbError>(())
775        })
776        .await
777        .expect("an open store arms its applied slot failures");
778    }
779
780    /// Claim numbers and complete-slot digests recorded by every consumed slot, including refusals.
781    #[cfg(any(test, feature = "test-utils"))]
782    pub async fn last_claims(&self) -> Result<Vec<coven_format::snapshot::LastClaim>, DbError> {
783        self.call(|inner| inner.access.with_committed(|db, _| crate::sequence::claims(db))).await
784    }
785
786    /// Original administrative, copy and announcement evidence retained by snapshots.
787    pub async fn original_slots(&self) -> Result<Vec<coven_format::floor::OriginalSlot>, DbError> {
788        self.call(|inner| {
789            inner.access.with_committed(|db, _| {
790                Ok(db.query(
791                    "SELECT slot,record FROM _coven_slot_records ORDER BY slot",
792                    [],
793                    |row| {
794                        Ok(coven_format::floor::OriginalSlot {
795                            slot: crate::write_encoding::slot_counter(row.get(0)?)?,
796                            object: row.get(1)?,
797                        })
798                    },
799                )?)
800            })
801        })
802        .await
803    }
804
805    /// Greatest locally reserved claim number, including finished journals.
806    #[cfg(any(test, feature = "test-utils"))]
807    pub async fn claim_counter(&self) -> Result<u64, DbError> {
808        self.call(|inner| {
809            inner.access.with_committed(|db, _| crate::claim::reserved(db, inner.access.device))
810        })
811        .await
812    }
813
814    /// Whether this copy journaled these complete bytes at this exact slot.
815    pub async fn attempted_slot(
816        &self,
817        number: u64,
818        path: coven_format::path::ObjectPath,
819        digest: [u8; 32],
820    ) -> Result<bool, DbError> {
821        self.call(move |inner| {
822            inner
823                .access
824                .with_committed(|db, _| crate::claim::attempted_digest(db, number, &path, &digest))
825        })
826        .await
827    }
828
829    /// The active claim and every durable attempted path. `claim_range`
830    /// reads the current attempt's exact bytes.
831    pub async fn current_claim(&self) -> Result<Option<crate::Claim>, DbError> {
832        self.call(|inner| inner.access.with_committed(|db, _| crate::claim::current(db))).await
833    }
834
835    /// Seal and stage outside the application writer, then atomically reserve
836    /// the claim number and retain its complete attempted bytes.
837    /// Returning the attempt proves the journal transaction has committed.
838    pub async fn begin_claim<F, R, E>(
839        &self,
840        work: crate::ClaimWork,
841        seal: F,
842    ) -> Result<crate::Claim, E>
843    where
844        F: FnOnce(u64) -> Result<crate::ClaimAttempt<R>, E> + Send + 'static,
845        R: std::io::Read + Send + 'static,
846        E: From<DbError> + CarriesBug + Send + 'static,
847    {
848        self.call(move |inner| {
849            let number = inner
850                .access
851                .with_committed(|db, _| crate::claim::reserved(db, inner.access.device))?
852                .checked_add(1)
853                .ok_or(DbError::ClaimNumberExhausted)?;
854            let attempt = seal(number)?;
855            Ok(inner.inputs.prepare_claim(attempt, |prepared| {
856                inner.access.with_writer(|writer, _| {
857                    writer.stream_transaction(|db| {
858                        crate::claim::begin(db, inner.access.device, work, number, prepared)
859                    })
860                })
861            })?)
862        })
863        .await
864    }
865
866    /// Stream the current attempt's exact ciphertext from one committed reader.
867    #[cfg(any(test, feature = "test-utils"))]
868    pub async fn read_current_attempt<T, E, F>(&self, consume: F) -> Result<T, E>
869    where
870        T: Send + 'static,
871        E: From<DbError> + CarriesBug + Send + 'static,
872        F: FnOnce(crate::ClaimBytes<'_>) -> Result<T, E> + Send + 'static,
873    {
874        self.call(move |inner| {
875            inner.access.with_reader(|db, call| {
876                crate::transaction_constants::read_with_constants(db, call, || {
877                    crate::claim::read_attempt(db, consume)
878                })
879            })
880        })
881        .await
882    }
883
884    /// Retain a new envelope only after the prior attempt was proved not landed.
885    pub async fn retry_claim<R: std::io::Read + Send + 'static>(
886        &self,
887        attempt: crate::ClaimAttempt<R>,
888    ) -> Result<(), DbError> {
889        self.call(move |inner| {
890            inner.inputs.prepare_claim(attempt, |prepared| {
891                inner.access.with_writer(|writer, _| {
892                    writer.stream_transaction(|db| crate::claim::retry(db, prepared))
893                })
894            })
895        })
896        .await
897    }
898
899    /// Settle from checked kept bytes or the floor's authenticated snapshot.
900    pub async fn settle_claim(
901        &self,
902        read: crate::ClaimRead,
903    ) -> Result<crate::ClaimSettlement, DbError> {
904        self.call(move |inner| {
905            inner.access.with_writer(|writer, _| {
906                writer.stream_transaction(|db| crate::claim::settle(db, read))
907            })
908        })
909        .await
910    }
911
912    /// Finish a settled claim and its optional operation transition atomically.
913    pub async fn finish_claim(
914        &self,
915        operation: Option<crate::OperationUpdate>,
916    ) -> Result<(), DbError> {
917        self.call(move |inner| {
918            inner.access.with_writer(|writer, _| {
919                writer.stream_transaction(|db| {
920                    crate::claim::finish(db)?;
921                    if let Some(update) = operation {
922                        crate::operation::advance(db, &update)?;
923                    }
924                    Ok(())
925                })
926            })
927        })
928        .await
929    }
930
931    /// Whether the open claim attempted this path. Finished journals are deleted.
932    #[cfg(any(test, feature = "test-utils"))]
933    pub async fn attempted_claim(
934        &self,
935        path: coven_format::path::ObjectPath,
936    ) -> Result<bool, DbError> {
937        self.call(move |inner| {
938            inner.access.with_committed(|db, _| crate::claim::attempted(db, &path))
939        })
940        .await
941    }
942}
943
944#[path = "database_device.rs"]
945mod device;
946
947impl<M: Mode> StoreDatabase<M> {
948    /// Membership and audience state of the committed sequence prefix.
949    pub async fn store_state(&self) -> Result<crate::StoreState, DbError> {
950        self.call(|open| {
951            M::access(open).with_committed(|db, _| crate::store_state_tables::read(db))
952        })
953        .await
954    }
955}