Struct Database 

pub struct Database<M: Mode = Writer> { /* private fields */ }

Shared ownership of the database, as its writer or a read-only handle (Database<ReadOnly>), which reads the store through the same calls and cannot write synced rows or migrate. A read-only handle’s connections can change only local cache metadata, and its shared store lock prevents deletion until all of them close. Closing any clone closes them all.

async fn cannot_write(handle: &coven_database::Database<coven_database::ReadOnly>) {
    handle.write(|_| Ok(())).await;
}

fn cannot_subscribe(handle: &coven_database::Database<coven_database::ReadOnly>) {
    handle.subscribe(|_| Ok::<_, coven_database::DbError>(()));
}

fn cannot_reconfigure(handle: &coven_database::Database<coven_database::ReadOnly>) {
    handle.subscribe_reconfigurable((), |_, _| Ok::<_, coven_database::DbError>(()));
}

fn cannot_subscribe_losses(handle: &coven_database::Database<coven_database::ReadOnly>) {
    handle.subscribe_lost_values();
}

fn sends_nothing(handle: &coven_database::Database<coven_database::ReadOnly>) {
    handle.uploads_in_flight();
}

Implementations

impl Database

pub async fn settle_files(&self) -> Result<(), DbError>

Settle what other devices’ writes left for this device’s files, in one write of its own (§17.2): delete each record they left with no reference. An audience reloading, or a pause of this device’s writes, leaves its files for a later call.

impl<M: Mode> Database<M>

pub async fn cache_bytes(&self) -> Result<CacheBytes, DbError>

The cache’s counters and the partial downloads’ sizes, from one snapshot, for the namespaces declared at open, in declaration order.

impl Database

pub fn subscribe_cache_budgets<E>(&self) -> LiveQuery<Vec<NamespaceBytes>, E>

where E: From<DbError> + CarriesBug + Send + 'static,

The namespaces’ budgets and counters, now and after each change to either. Reads nothing else, so a cached read’s recency or a pin download’s partial growing starts no run.

impl Database

pub async fn local_bytes(&self) -> Result<LocalBytes, DbError>

One measurement of what the store keeps on this device: the cache’s counters, budgets and partials from one snapshot, then the store’s directory walked for its own files and the archives resets kept. The cache’s folder is left out of the walk, since its entries count it.

pub fn subscribe_local_bytes(&self) -> LocalBytesWatch

The first measurement at once, then a new one after each write that changes a namespace’s counters or budget, and after each local_bytes_changed. Partial downloads are measured with each but start none.

pub fn local_bytes_changed(&self)

Say that the store’s directory changed in a way its database doesn’t report, such as the archives resets kept going.

impl Database

pub async fn fail_next_staging_removal(&self) -> Result<(), DbError>

Fail the next removal of the stagings a failed load or file check ends, as a disk error would; the stagings keep their records until they are dropped (§16.2).

impl Database

pub async fn stage_snapshot( &self, id: SnapshotId, prefix: SnapshotObjectPrefix, ) -> Result<SnapshotStaging, DbError>

Begin staging the snapshot id, whose signed prefix is prefix (§16.2). Nothing outside the loader reads what it stages.

pub async fn input_temp_store(&self) -> Result<u8, DbError>

Where the input connection keeps temporary tables (PRAGMA temp_store): 1 is in files.

pub async fn damage_next_staged_read(&self) -> Result<(), DbError>

Change a staged record before the next load or file check reads it, as damage to this device’s disk would (§19.1).

pub async fn damage_staged_finishes( &self, damage: StagedDamage, count: u32, ) -> Result<(), DbError>

Make damage to each of the next count stagings as it finishes, before finishing checks it, as damage to this device’s disk would (§19.1). Damage to two stagings of one snapshot alike stands for a snapshot whose own records fail.

pub async fn staged_snapshot_records(&self) -> Result<u64, DbError>

The records staged on the input connection now, for every snapshot: the rows of every staging’s tables, and their applied writes.

impl Database

pub async fn forget_slot_inputs_below(&self, first: Slot) -> Result<(), DbError>

Forget the input records of the slots below a checked floor’s first: nothing reads them again (§16.4). A record a live read holds stays.

pub async fn claim_input(&self) -> Result<RetainedBytes, DbError>

A seekable local input for applying the current claim without a provider reread after successful creation. One cache identity is reused across claims; the journal remains the authoritative copy until settlement.

pub async fn retained_observation( &self, path: String, ) -> Result<Option<Vec<u8>>, DbError>

The retained provider observation of an exact path, if any. A drained writer’s discovered objects are found here instead of by probing (§6.1).

pub async fn observe_input( &self, path: String, identity: Vec<u8>, observation_bytes: Vec<u8>, replaceable: bool, ) -> Result<Option<RetainedInput>, DbError>

Retain a provider observation before reading it. Immutable identity changes return None and preserve the preceding evidence. A replacement discards only that path’s preceding version. Equal observations acquire no writer.

pub async fn set_input_budget( &self, maximum: u64, ) -> Result<InputBudget, DbError>

Configure retained encrypted input independently of application file caches. Lowering the budget evicts oldest completed inputs atomically with accounting. Checked facts and file protection are never evicted with their bytes.

pub async fn input_budget(&self) -> Result<InputBudget, DbError>

Report byte retention and explicit eviction without scanning cached chunks.

pub async fn input_peak(&self) -> Result<u64, DbError>

The most retained bytes any input write has required since this was first called, before its evictions, sampled on every change.

impl Database

pub async fn operations(&self) -> Result<Vec<OperationRecord>, DbError>

Read every unfinished operation, including permanently failed ones.

pub async fn operation( &self, id: OperationId, ) -> Result<Option<OperationRecord>, DbError>

Read one committed journal row without loading unrelated operation data. Absence means the operation has finished or never existed.

pub async fn first_operation( &self, kind: &str, ) -> Result<Option<OperationRecord>, DbError>

Read the earliest unfinished row of a sync-owned kind, including failures.

pub async fn start_operation( &self, operation: NewOperation, ) -> Result<OperationId, DbError>

Commit the operation before its first step.

pub async fn start_listed_operation( &self, operation: NewOperation, kind: String, ) -> Result<OperationId, DbError>

Commit an operation a call of the app’s starts, before its first step, listed in coven_operations as kind names it from this commit until a write acknowledges its outcome (§11.4, §11.6).

pub async fn start_operation_advancing<E: WriteFailure + Send + 'static>( &self, operation: NewOperation, update: impl FnOnce(OperationId) -> Result<OperationUpdate, E> + Send + 'static, ) -> Result<OperationId, E>

Commit a new operation and a step of another that names it, in one transaction: update builds the step from the new operation’s id. A parent that journals a child this way never loses track of it, nor starts a second one, whenever it stops.

pub async fn reserve_snapshot_number(&self) -> Result<NonZeroU64, DbError>

Reserve the path number of a snapshot attempt about to be prepared: the next of this device’s snapshot sequence, never reused, which §19.3 compares with its stored snapshots.

pub async fn advance_operation( &self, update: OperationUpdate, ) -> Result<(), DbError>

Commit a local step’s state after an idempotent storage effect.

pub async fn advance_operations<T: Send + 'static>( &self, kind: &str, step: impl FnOnce(&[OperationRecord]) -> Result<(Vec<OperationUpdate>, T), DbError> + Send + 'static, ) -> Result<T, DbError>

Read the journal’s rows of kind and commit the transitions step makes from them, in one transaction on the writer: no other write comes between the read and the transitions. step also returns what it concluded from the rows. A failure fails this handle with its cause, as losing a pending record does: the rows would go on showing the app a state their owner has left.

pub async fn hold_member_keys( &self, keys: Vec<MemberPublicKeys>, ) -> Result<(), DbError>

Record member pairs this installation holds, or is about to keep in custody, before custody keeps them: applying a binding of its member to a pair not recorded stops it for good (§12.3).

pub async fn operation_pending<P: PendingValue>( &self, id: OperationId, ) -> Result<Option<P>, DbError>

Read the pending condition associated with a journal row.

pub async fn finish_operation_with_outcome( &self, id: OperationId, outcome: OperationOutcome, ) -> Result<(), DbError>

Retire a finished operation with its outcome, as sync encodes it, which coven_operations lists for an operation the app’s write journaled, in the same transaction: an outcome nobody awaits is never lost (§11.4).

pub async fn finish_operation_with_removal( &self, id: OperationId, children: Vec<OperationId>, removal: ObjectRemoval, outcome: Option<(String, OperationOutcome)>, ) -> Result<(), DbError>

Retire an ended invite in one commit with the operations it started that are still journaled, its children, and with the deletion it leaves owed: its marker’s, once that has passed (§13.2). An outcome the invite ends with, with its kind as coven_operations lists it, is listed there until the app acknowledges it. An invite, or a child, that has ended already fails with OperationChanged.

pub async fn finish_operation_advancing( &self, child: OperationId, outcome: OperationOutcome, parent: OperationUpdate, ) -> Result<(), DbError>

End an operation another started, with its outcome, in the transaction that advances its parent past it: the parent’s step and the child’s end commit together, so no restart finds one without the other. An outcome coven_operations lists is written as finish_operation_with_outcome writes it. A parent that has moved on since, or a child already ended, fails with OperationChanged.

pub async fn end_for_good(&self, stop: DeviceStop) -> Result<(), DbError>

End every operation the app’s writes journaled that still runs, and every invite this device made, as the transaction applying a stop for good does, for a stop no slot applies: history shows another copy of this installation using its device id (§19.3). A failure fails this handle with its cause: they would otherwise run, listed, forever.

pub async fn device_stop(&self) -> Result<Option<DeviceStop>, DbError>

How the applied state stops this installation for good, if it does: its device removed or replaced, its member removed, or its member bound to a pair it doesn’t hold (§14.1). None while the applied state doesn’t name its device. A restore ending without its store reads it for the facts (§13.1).

pub async fn due_object_removals( &self, now: u64, ) -> Result<Vec<String>, DbError>

The paths of objects whose time to go has passed by now, in seconds since the Unix epoch.

pub async fn object_removed(&self, path: String) -> Result<(), DbError>

The object at path is gone from storage.

pub async fn requests_ended(&self) -> Result<BTreeSet<DeviceId>, DbError>

The devices gone for good whose join requests this device ended (§13.2).

pub async fn record_requests_ended( &self, device: DeviceId, ) -> Result<(), DbError>

This device ended device’s join requests: its gone marker is in storage, and nothing else was under its requests when listed (§13.2).

pub async fn gone_storage_cleared(&self) -> Result<BTreeSet<DeviceId>, DbError>

The devices gone for good whose storage this device cleared once (§16.6, §17.10).

pub async fn record_gone_storage_cleared( &self, device: DeviceId, ) -> Result<(), DbError>

This device ended the uploads device left, listed its snapshot folders and deleted every body there that no announcement names (§16.6, §17.10). Recording it again, after clearing repeated because its operation hadn’t finished, changes nothing.

pub async fn finish_operation(&self, id: OperationId) -> Result<(), DbError>

Retire a finished operation. The caller must publish every reserved entry before discarding; removing this row cannot retire the publication queue.

impl Database

pub async fn provider_access( &self, account: String, ) -> Result<Option<ProviderAccess>, DbError>

Read confirmed sharing and its unfinished request from one committed row.

pub async fn start_operation_with_access<P: PendingValue>( &self, operation: NewOperation, changes: Vec<ProviderAccessChange>, ) -> Result<OperationId, DbError>

Record a new invitation and its account intention atomically.

pub async fn advance_operation_with_access<P: PendingValue>( &self, update: OperationUpdate, changes: Vec<ProviderAccessChange>, child: Option<(OperationId, OperationOutcome)>, ) -> Result<(), DbError>

Advance an invitation and its account intention atomically, ending the operation it started for the step it leaves, child, with its outcome, in the same transaction (§13.2).

pub async fn retake_provider_access<P: PendingValue>( &self, changes: Vec<ProviderAccessChange>, ) -> Result<(), DbError>

Forget each account’s confirmed grant and queue a request for its intention, atomically (provider_access::retake).

pub async fn start_provider_request<P: PendingValue>( &self, account: String, id: OperationId, ) -> Result<bool, DbError>

Fix the request’s target before calling storage. A failed or interrupted request has unknown provider state, so retry must confirm the target again.

pub async fn fail_provider_request<P: PendingValue>( &self, account: String, id: OperationId, data: Vec<u8>, pending: P, ) -> Result<bool, DbError>

Record a revocation’s reply that listed grants left in place: the operation id moves from its fixed request to a reported failure, recording data, with pending as its record. An entry that made the account intended again while the request ran makes the reply obsolete: the opposite request is queued on the same pending subject instead, as a confirmation’s is, and this returns false (§20.9).

pub async fn advance_operation_refusing_grant( &self, update: OperationUpdate, account: String, grant: OperationId, ) -> Result<(), DbError>

Advance an invite whose grant the provider refused for good, and end the account’s grant request grant as not granted, in one commit: the refusal leaves nothing shared, and retrying the grant would be refused the same way. The account’s intention is the invite’s end’s to change (§13.2). A request that is not grant, fixed on granting, fails with OperationChanged.

pub async fn complete_provider_request<P: PendingValue>( &self, account: String, id: OperationId, target: bool, invitation: Option<SecretBytes>, ) -> Result<bool, DbError>

Confirm a fixed request and either finish it or queue the opposite target on the same pending subject, in one commit.

impl Database

pub async fn snapshot_absent(&self, id: SnapshotId) -> Result<bool, DbError>

A snapshot whose absence was confirmed by an exact read or deletion.

pub async fn record_absent_snapshot( &self, id: SnapshotId, files: BTreeSet<(DeviceId, ObjectId)>, ) -> Result<(), DbError>

Confirm that a snapshot no longer protects its checked file references. The references become candidates in the same transaction as that fact.

pub async fn forget_announcements( &self, slots: BTreeSet<Slot>, snapshots: BTreeSet<SnapshotId>, listings: Vec<NewOperation>, ) -> Result<(), DbError>

Forget announcements no rule reads any more (§16.8): their original slots at slots, and the absences recorded for snapshots, the bodies only they named. listings journals the listings that find those bodies in storage, in the same transaction, so a forgotten announcement’s body is never left without one.

pub async fn write_file_references<R: Read + Send + 'static>( &self, write: DownloadedWriteStream<R>, skipped: BTreeSet<(Audience, KeyId)>, ) -> Result<FileEvidence, DbError>

Stream the stored paths a write’s records name from checked plaintext. The caller must authenticate the complete object before using this result. It names the audience and key of each part it skipped: a skipped part, or a schema version this version cannot interpret, proves no file absent.

pub async fn write_schema_versions( &self, ) -> Result<RangeInclusive<u32>, DbError>

The schema versions whose writes and snapshots this version interprets.

pub async fn file_candidates( &self, uploaders: BTreeSet<DeviceId>, ) -> Result<Vec<FileCandidate>, DbError>

The candidates of these uploaders, each with whether local data still protects it (§17.10). Other uploaders’ candidates are not read: their files are deleted by another device until ownership changes.

pub async fn published_reads( &self, devices: BTreeSet<DeviceId>, ) -> Result<BTreeMap<DeviceId, u64>, DbError>

The slot count each of these devices had read through when it made its last published write, for those that published one. Every write it made before is published too (§6.3, §17.10).

pub async fn settle_file_candidates( &self, protected: Vec<(DeviceId, ObjectId)>, deleted: Vec<(DeviceId, ObjectId)>, ) -> Result<(), DbError>

Settle candidates in one transaction. A protected one goes only while local data still protects it, so releasing that protection adds it again; a deleted one goes after storage confirmed its deletion.

pub async fn file_scan(&self, device: DeviceId) -> Result<Option<Slot>, DbError>

The counted entry stopping device for good at which this device last listed its file folder, if it did (§17.10).

pub async fn complete_file_scan( &self, device: DeviceId, stop: Slot, objects: BTreeSet<ObjectId>, ) -> Result<bool, DbError>

Record a complete listing of the file folder of an uploader gone for good, taken once the entry at stop stopped it, with every path it found as a candidate. Returns false, recording nothing, when this device hasn’t applied a counted cut-off at stop naming the device or its member: the history the caller judged by is not the one applied here. Whether a replacement of the member’s keys stopped the device, which depends on the slot that added it and the entry’s author, the caller’s history decides (§14.1). Nothing the device writes after the stop counts, so any listing taken after it is sound, however often it is taken (§17.10).

impl Database

pub async fn snapshot_slot_bytes( &self, audience: Audience, after: u64, ) -> Result<u64, DbError>

The sealed bytes a new device replays for audience after a snapshot’s coverage (§16.2): each applied writes slot carrying one of its parts, and for the store every admin, key-copy and announcement slot too. Local originals without a slot do not request a snapshot of unpublished data, and slots this installation loaded inside a snapshot instead of reading count nothing.

pub async fn waiting_snapshot_headers( &self, ) -> Result<Vec<WriteHeaderFrame>, DbError>

Headers of waiting plaintext writes, including fixed upload attempts. Snapshot growth counts these parts before their eventual publication.

pub async fn validate_snapshot( &self, id: SnapshotId, staging: SnapshotStaging, author: MemberId, authorship: Arc<dyn Authorship>, ) -> Result<BTreeSet<(DeviceId, ObjectId)>, DbError>

Run the snapshot loader’s schema and merge checks over a staged snapshot in a transaction that always rolls back, returning the uploaded files it names. File retention uses this for a snapshot no reload has read; a damaged snapshot cannot leave rows, metadata or observations behind. Supply the staging of a body that authenticated: the check is its last phase, and removes its records whether it passes or fails (§16.2).

pub async fn write_snapshot<B, F, E>( &self, id: SnapshotId, begin: B, emit: F, ) -> Result<u32, SnapshotWriteError<E>>

where B: FnOnce(&SnapshotHeader) -> Result<(), E> + Send + 'static, F: FnMut(Vec<u8>) -> Result<(), E> + Send + 'static, E: CarriesBug + Send + 'static,

Stream an audience’s plaintext snapshot frames from one committed reader transaction. begin receives metadata before any frame, so the consumer can write the sealed prefix and seal each subsequent frame as it arrives; commits on the writer connection continue throughout this call. While this device’s raise of the audience waits, it refuses with DbError::RaiseWaiting: the snapshot would be written at a schema version the history doesn’t hold yet (§16.2). Returns the snapshot’s breaking version, for its announcement (§16.3).

pub async fn breaking_version(&self) -> Result<u32, DbError>

The version of the newest breaking migration this installation ran, zero if none: its snapshots’ breaking version (§16.3).

pub async fn raise_captures(&self) -> Result<Vec<RaiseCapture>, DbError>

The raise snapshots a breaking migration captured through its marker, one per audience this device read then (§18.3, §11.5).

pub async fn prepare_raise_capture( &self, audience: Audience, version: u32, ) -> Result<Option<RaiseCapture>, DbError>

The capture to seal for an audience’s raise, right after a completed catch-up: kept if that catch-up applied nothing past it, otherwise captured again from the current state through this device’s newest write, which then joins the prefix to confirm (§16.3, §18.5). None when a later migration replaced the capture.

pub async fn unconfirmed_own_prefix( &self, through: WriteId, ) -> Result<Option<WriteId>, DbError>

The first own write of a snapshot’s captured prefix, through its own position, not yet confirmed stored. Any snapshot, ordinary, raise or reset, is sent only once this is None (§16.1); a raise starts only then (§18.5).

pub async fn write_raise_snapshot<B, F, E>( &self, id: SnapshotId, version: u32, begin: B, emit: F, ) -> Result<u32, SnapshotWriteError<E>>

where B: FnOnce(&SnapshotHeader) -> Result<(), E> + Send + 'static, F: FnMut(Vec<u8>) -> Result<(), E> + Send + 'static, E: CarriesBug + Send + 'static,

Stream an audience’s captured raise snapshot under its published identity, like write_snapshot but from the migration’s capture.

pub async fn discard_raise_capture( &self, audience: Audience, version: u32, ) -> Result<(), DbError>

Forget a capture whose raise is published or superseded.

pub async fn load_snapshots<P: PendingValue, W>( &self, reload: SnapshotReload<SnapshotStaging, DownloadedWriteStream<W>>, progress: Option<ProgressReport<LoadStep>>, ) -> Result<Vec<LoadedSnapshot>, DbError>

where W: Read + Send + 'static,

Load authenticated snapshots and gap writes supplied by sync. Each stored snapshot supplies its identity and its staging, of a body whose stream checked out to its end; their write evidence is authenticated, and write parts are staged on the input connection, before taking the application writer. Inputs name a fixed target and consecutive retained slots.

Replaces the selected audiences and replays uncovered parts and waiting uploads in one transaction. The load is each staging’s last phase: it reads each staged snapshot once and removes its records, whether it commits or fails. Every audience finishes at the common target slot; missing history, read errors and failed checks roll the whole load back, a body’s failure as SnapshotError::Body naming that snapshot. Returns the uploaded files each stored snapshot names. Supply each readable audience’s parts, including those needed by waiting writes and the device’s own earlier writes. Other audiences retain their merge history. Upload records, numbers and sealing key ids stay unchanged. progress, when given, hears the Installing and InstallingSlots steps as they run (§13.4).

impl Database

pub async fn test_track_work(&self, counter: WorkCounter) -> Result<(), DbError>

Count executed work on every connection without including counter reads. Install while the database is quiescent, before starting the measured pass.

pub async fn test_snapshot_section_bytes( &self, id: SnapshotId, ) -> Result<[u64; 11], SnapshotWriteError<Infallible>>

The plaintext bytes each section of a snapshot id would hold now: what the sealed object’s size can’t tell apart.

pub async fn test_on_write_checkpoint( &self, callback: impl Fn(WriteCheckpoint) + Send + 'static, ) -> Result<(), DbError>

Observe transaction completion and file cleanup on the writer thread. Install after setup; the callback may terminate a subprocess to simulate a crash without Rust destructors or SQLite connection shutdown.

pub async fn test_panic_in_next_write( &self, message: &'static str, ) -> Result<(), DbError>

Panic in the next write the writer judges, before it commits, as a bug in it would: the write rolls back, and its call fails with DbError::Bug carrying message (E15).

pub async fn test_fail_sync_status(&self) -> Result<(), DbError>

Make every later write of how the passes go fail, as a full disk would: their move, their end and the last synced time. Counting a start still writes, so the loop starts and its first pass fails.

pub async fn test_fail_device_reset(&self) -> Result<(), DbError>

Make every later write of the reset notice fail, as a full disk would.

pub async fn test_fail_retry_effect(&self) -> Result<(), DbError>

Make every later write of the retry effect fail, as a full disk would.

pub async fn test_queued_writes(&self) -> Result<Vec<WriteRecord>, DbError>

Test transport: read actual queued records without reauthoring their writes.

impl Database

pub async fn initialize_store_name(&self, name: String) -> Result<(), DbError>

Save the name chosen for a local store before publishing its directory, which slot 1 will set (§10.3). This row is not sequence membership until the applied history creates the store and sets its name.

pub async fn initialize_joined_store( &self, name: String, named_at: Slot, invitee: Option<String>, ) -> Result<(), DbError>

Save what the store a join publishes keeps from its invite before it loads, in one transaction: the store’s name, set by named_at, the slot the inviting device had applied, and the new person’s name, invitee, which it keeps until the app acknowledges it. A recovery’s request carries none (§13.2).

pub async fn joined_invitee(&self) -> Result<Option<String>, DbError>

The new person’s name the store a join published keeps until the app acknowledges it; None for any other store, and once acknowledged (§13.2).

pub fn subscribe_store_name<E>(&self) -> LiveQuery<String, E>

where E: From<DbError> + CarriesBug + Send + 'static,

The same name query, live (E4).

pub async fn named_store(&self) -> Result<(String, Slot), DbError>

The committed name and the slot that set it, including a local creation’s name, which slot 1 will set. A saved restore code keeps whichever name has the later slot (§13.1).

impl<M: Mode> Database<M>

pub async fn store_name(&self) -> Result<String, DbError>

The name in this device’s committed state, including a local creation on the writer (E9).

impl Database

pub async fn record_sync_retry<P: PendingValue>( &self, connection: P::Subject, record: Option<P>, wait: Option<RetryWait>, ) -> Result<(), DbError>

where P::Subject: Send + 'static,

Persist a failed pass’s connection condition and retry deadline together. A failure already owned by a slot or operation supplies no connection record.

pub async fn clear_sync_retry<S: Serialize + Send + 'static>( &self, connection: S, ) -> Result<(), DbError>

A successful pass settles its connection condition and wait atomically.

pub async fn record_operation_retry<P: PendingValue>( &self, record: P, wait: Option<RetryWait>, ) -> Result<(), DbError>

Persist an operation’s failure and its automatic retry deadline together.

pub async fn record_operation_retry_at<P: PendingValue>( &self, record: P, wait: Option<RetryWait>, step: u32, ) -> Result<bool, DbError>

Persist an operation’s failure and its automatic retry deadline together, while the operation is still at step, the step the failed attempt read, and return whether it did. A writer outside the attempt, such as the app’s write deciding an invite or the invite’s expiry, may have moved the operation on since, or ended it: the failure then belongs to a step the operation has left, and recording it would hold the operation’s next step back behind a wait it never met.

pub async fn retry_waits( &self, ) -> Result<Vec<(RetrySubject, RetryWait)>, DbError>

Every persisted wait, for arming on reopen (§6.7).

pub async fn retry_wait( &self, subject: RetrySubject, ) -> Result<Option<RetryWait>, DbError>

The subject’s persisted wait, if one is armed.

pub fn subscribe_retry_wait( &self, subject: RetrySubject, ) -> LiveQuery<Option<RetryWait>, DbError>

The same wait, live (E4), for a test waiting for a failure to arm it.

pub async fn record_retry( &self, subject: RetrySubject, wait: RetryWait, ) -> Result<(), DbError>

Persist T and W before the subject waits. A failure here fails the initiating work; it is never permission to retry immediately.

pub async fn end_retry_waits<P: PendingValue>( &self, now: SystemTime, select: impl FnOnce(&[(RetrySubject, RetryWait)], &[P], &[FileUpload], &[PinRequest]) -> Vec<RetrySubject> + Send + 'static, ) -> Result<Vec<(RetrySubject, RetryWait)>, DbError>

End, in one transaction, the persisted waits select picks after reading every wait, every pending record, the upload queue and the pin requests as one committed state. Each ended wait keeps its failure count; its deadline becomes now and its full wait zero, so reopening arms none (§6.7). Returns the ended waits.

pub async fn fail_retry_ends(&self, count: usize)

Fail the next count end_retry_waits transactions with a disk error.

pub async fn clear_retry(&self, subject: RetrySubject) -> Result<(), DbError>

Forget a wait once its work succeeds or no longer retries automatically.

impl Database

pub async fn record_device_reset<P: PendingValue>( &self, reset: DeviceReset, operations: Vec<NewOperation>, provider_access: Vec<ProviderAccessChange>, ) -> Result<(), DbError>

Commit carried provider cleanup with the replacement notice before publication. A resumed bootstrap cannot import the same work twice.

pub async fn members(&self) -> Result<Vec<MemberInfo>, DbError>

Store members and every device they registered, from the committed sequence prefix (E9). subscribe_members runs the same query.

pub fn subscribe_members<E>(&self) -> LiveQuery<Vec<MemberInfo>, E>

where E: From<DbError> + CarriesBug + Send + 'static,

The same members query, live (E4).

pub async fn circles(&self) -> Result<Vec<Circle>, DbError>

The circles this installation’s member belongs to (E12).

pub fn subscribe_circles<E>(&self) -> LiveQuery<Vec<Circle>, E>

where E: From<DbError> + CarriesBug + Send + 'static,

The same circle-list query, live (E4).

pub async fn circle_members( &self, circle: CircleId, ) -> Result<Vec<CircleMemberInfo>, DbError>

A circle’s members who remain in the store; none for an absent or deleted circle (E12).

pub fn subscribe_circle_members<E>( &self, circle: CircleId, ) -> LiveQuery<Vec<CircleMemberInfo>, E>

where E: From<DbError> + CarriesBug + Send + 'static,

The same circle-members query, live (E4).

pub async fn device_reset(&self) -> Result<Option<DeviceReset>, DbError>

The latest completed replacement of this installation, or None (E5).

pub fn subscribe_device_reset<E>(&self) -> LiveQuery<Option<DeviceReset>, E>

where E: From<DbError> + CarriesBug + Send + 'static,

The same pre-built query, observing committed changes (E4).

impl Database

pub async fn claim_upload(&self) -> Result<ClaimUpload, DbError>

Transfer metadata of the current durable claim attempt.

pub async fn claim_range( &self, offset: u64, length: usize, ) -> Result<Vec<u8>, DbError>

A bounded range of the current attempt, used by a recorded upload.

pub async fn save_claim_upload(&self, session: Vec<u8>) -> Result<(), DbError>

Save provider-confirmed progress before the next part is sent.

pub async fn prepare_uploads<E, F>( &self, through: u64, select: F, ) -> Result<PreparedUploads, E>

where E: From<DbError> + From<Error> + CarriesBug + Send + 'static, F: FnMut(&WriteHeaderFrame) -> Result<WriteObjectPrefix, E> + Send + 'static,

Fix first-attempt keys for this captured queue prefix. Previously attempted originals retain their exact format and keys.

pub async fn read_uploads<E, F>( &self, prepared: PreparedUploads, consume: F, ) -> Result<(), E>

where E: From<DbError> + CarriesBug + Send + 'static, F: FnMut(WaitingUpload<'_>) -> Result<(), E> + Send + 'static,

Stream the prepared originals through one committed reader. Concurrent app commits append after the prepared prefix and remain for the next pass.

pub async fn apply_slot<P, R, F>( &self, incoming: IncomingSlot<DownloadedWriteStream<R>>, writers: Writers, authenticate: F, ) -> Result<ApplyOutcome, DbError>

where P: PendingValue, R: Read + Send + 'static, F: FnOnce() -> Result<(), DbError> + Send + 'static,

Commit one complete slot, its claim number and every readable effect. Authentication failure rolls back the slot and leaves its predecessor applied. writers are the other devices that can still write once the slot is applied, which kept records wait for (§16.7).

pub async fn sendable_through<P: PendingValue>( &self, ) -> Result<Option<u64>, DbError>

The newest waiting write this device may send now, read in one committed state with the queue (§6.3): none past an unpublished breaking raise’s capture or from a write ahead of an audience’s version, whose wait it records (§18.5), and none from a write a bound upload holds on (§17.4). None with no write waiting.

pub async fn reloading_audiences(&self) -> Result<BTreeSet<Audience>, DbError>

Audiences whose counted administrative effects require replacement data. Loading their replacement rows removes the requirement atomically.

pub async fn pending<P: PendingValue>(&self) -> Result<Vec<P>, DbError>

Current pending records, decoded as the sync owner’s typed values.

pub async fn unsent(&self) -> Result<UnsentWork, DbError>

Writes and files this device committed and has not uploaded, from one committed state.

pub fn subscribe_unsent<E>(&self) -> LiveQuery<UnsentWork, E>

where E: From<DbError> + CarriesBug + Send + 'static,

The same pre-built unsent-work query, observing committed changes.

pub async fn sync_facts<P, T, E>( &self, compute: impl FnOnce(SyncFacts<P>) -> Result<T, E> + Send + 'static, ) -> Result<T, E>

where P: PendingValue + Clone, T: Send + 'static, E: From<DbError> + CarriesBug + Send + 'static,

What the sync state is computed from, in one committed snapshot (§19.1): coven_sync_status’s row, coven_retry_effect’s, the send and upload queues, the files moving and the pending records, decoded as the sync owner’s typed values, given to compute in the read.

pub fn subscribe_sync_facts<P, T, E>( &self, compute: impl Fn(SyncFacts<P>) -> Result<T, E> + Send + Sync + 'static, ) -> LiveQuery<T, E>

where P: PendingValue + Clone, T: Send + 'static, E: From<DbError> + CarriesBug + Send + 'static,

The same pre-built query, live: it runs again on each committed change of what it reads, and as a file starts or ends a transfer.

pub async fn upload_queue(&self) -> Result<UploadQueueState, DbError>

The upload queue, its pause setting and each file’s recorded provider session in one committed snapshot, available while disconnected (E7).

pub async fn record_opened( &self, location: RecordedLocation<String>, finished: Option<SystemTime>, ) -> Result<(), DbError>

Record, as the store opens, whether a storage location is recorded here and its credentials held, and that no pass moves, keeping how the last pass ended and when sync last finished; finished, for a store joining or restoring read to its end, is when (api.md E5). The provider is as sync names it. A failure fails this handle with its cause, as losing a pending record does.

pub async fn record_location( &self, location: RecordedLocation<String>, finished: Option<SystemTime>, ) -> Result<(), DbError>

Record whether a storage location is recorded here and its credentials held, as setup, a change of credentials or releasing a connection finds it; finished, for setup, is when it read the store to its end. A failure fails this handle, as record_opened’s does.

pub async fn record_moving(&self) -> Result<(), DbError>

Record that the running pass read a slot it hadn’t, or claimed one. A failure fails this handle, as record_opened’s does.

pub async fn record_last_pass(&self, last_pass: Vec<u8>) -> Result<(), DbError>

Record how the last pass ended, as sync encodes it, when sync failed outside a pass’s end: starting, stopping, or a local failure or panic of the loop’s, in a pass or outside one; and that nothing moves. A failure fails this handle, as record_opened’s does.

pub async fn record_halt(&self, last_pass: Vec<u8>) -> Result<(), DbError>

Record that a store-wide worker’s panic halted sync until the store reopens, with its failure, as sync encodes it, as how the last pass ended, and that nothing moves: from here no pass writes the row. A failure fails this handle, as record_opened’s does.

pub async fn record_pass_end( &self, last_pass: Vec<u8>, finished: Option<SystemTime>, ) -> Result<(), DbError>

Record how the running pass ended, as sync encodes it, and that it moves no more; finished, for a pass that reached the end of the sequence, is when, which becomes the last synced time unless that is later. A failure fails this handle, as record_opened’s does.

pub async fn change_retry_state<T: Send + 'static>( &self, change: impl FnOnce(RetryState) -> RetryState + Send + 'static, then: impl FnOnce(RetryState) -> T + Send + 'static, ) -> Result<T, DbError>

Change what decides the person’s retry, coven_retry_effect’s row, then run then with the state as committed, in one step on the writer: no other change to the state, and no other then, comes between them, so a decision then makes from the state is the one the row shows. change gets the state as the row holds it; then runs only once the change commits. A failed write fails this handle with its cause, as losing a pending record does.

pub async fn start_retry_state<T: Send + 'static>( &self, change: impl FnOnce(RetryState) -> RetryState + Send + 'static, then: impl FnOnce(RetryState) -> T + Send + 'static, ) -> Result<T, DbError>

Change the retry state as sync starts, as change_retry_state does, and count the start in coven_sync_status.starts in the same transaction: every start writes the row, even one that holds for the reason the last one did.

pub async fn record_cooldown( &self, wait: RetryWait, change: impl FnOnce(RetryState) -> RetryState + Send + 'static, ) -> Result<(), DbError>

Record the provider cooldown’s wait, and change the retry state as change_retry_state does, in one transaction: the cooldown that holds every pass and the effect it gives a retry commit together.

pub async fn record_pending<P: PendingValue>( &self, record: P, ) -> Result<(), DbError>

Record one local first unmet condition, replacing its previous reason.

pub async fn clear_pending<S: Serialize + Send + 'static>( &self, subject: S, ) -> Result<(), DbError>

Clear this device’s observation when its subject advances. The usual case, with nothing recorded, reads without taking the writer.

pub async fn pending_can_retry<P: PendingValue>( &self, subject: P::Subject, ) -> Result<bool, DbError>

where P::Subject: Send + 'static,

Apply the persisted condition’s retry policy to this installed version.

pub async fn set_pending_build(&self, build: u128) -> Result<(), DbError>

Make every pending record one build recorded, as a store opened by another build of coven finds the records an earlier one wrote (§19.1).

pub async fn read_oldest_upload<F, R, E>( &self, consume: F, ) -> Result<Option<R>, UploadReadError<E>>

where F: FnOnce(UploadPlaintext<'_>) -> Result<R, E> + Send + 'static, R: Send + 'static, E: CarriesBug + Send + 'static,

Read the oldest waiting plaintext. The callback runs in a committed reader transaction; its result is None when the queue is empty.

pub fn subscribe_store_state(&self) -> LiveQuery<StoreState, DbError>

The same state, live (E4), for a test waiting for passes to change it, such as to apply a raise.

pub async fn applied_slot(&self) -> Result<u64, DbError>

The store prefix whose complete effects have committed.

pub async fn fail_applied_slots(&self, count: usize)

Fail the next count applied_slot reads with a disk error.

pub async fn last_claims(&self) -> Result<Vec<LastClaim>, DbError>

Claim numbers and complete-slot digests recorded by every consumed slot, including refusals.

pub async fn original_slots(&self) -> Result<Vec<OriginalSlot>, DbError>

Original administrative, copy and announcement evidence retained by snapshots.

pub async fn claim_counter(&self) -> Result<u64, DbError>

Greatest locally reserved claim number, including finished journals.

pub async fn attempted_slot( &self, number: u64, path: ObjectPath, digest: [u8; 32], ) -> Result<bool, DbError>

Whether this copy journaled these complete bytes at this exact slot.

pub async fn current_claim(&self) -> Result<Option<Claim>, DbError>

The active claim and every durable attempted path. claim_range reads the current attempt’s exact bytes.

pub async fn begin_claim<F, R, E>( &self, work: ClaimWork, seal: F, ) -> Result<Claim, E>

where F: FnOnce(u64) -> Result<ClaimAttempt<R>, E> + Send + 'static, R: Read + Send + 'static, E: From<DbError> + CarriesBug + Send + 'static,

Seal and stage outside the application writer, then atomically reserve the claim number and retain its complete attempted bytes. Returning the attempt proves the journal transaction has committed.

pub async fn read_current_attempt<T, E, F>(&self, consume: F) -> Result<T, E>

where T: Send + 'static, E: From<DbError> + CarriesBug + Send + 'static, F: FnOnce(ClaimBytes<'_>) -> Result<T, E> + Send + 'static,

Stream the current attempt’s exact ciphertext from one committed reader.

pub async fn retry_claim<R: Read + Send + 'static>( &self, attempt: ClaimAttempt<R>, ) -> Result<(), DbError>

Retain a new envelope only after the prior attempt was proved not landed.

pub async fn settle_claim( &self, read: ClaimRead, ) -> Result<ClaimSettlement, DbError>

Settle from checked kept bytes or the floor’s authenticated snapshot.

pub async fn finish_claim( &self, operation: Option<OperationUpdate>, ) -> Result<(), DbError>

Finish a settled claim and its optional operation transition atomically.

pub async fn attempted_claim(&self, path: ObjectPath) -> Result<bool, DbError>

Whether the open claim attempted this path. Finished journals are deleted.

impl<M: Mode> Database<M>

pub async fn store_state(&self) -> Result<StoreState, DbError>

Membership and audience state of the committed sequence prefix.

impl<M: Mode> Database<M>

pub fn bugs(&self) -> &BugSinkRef

Where a bug in the store’s work that nobody waits for goes (E15).

pub async fn open_local_file( &self, reference: &FileRef, ) -> Result<Option<LocalFileStream>, LocalFileError>

Open the local source of a file still on this device only. No storage operation occurs; None means the bytes come from the cache or storage.

pub async fn file_ref(&self, file: FileId) -> Result<FileRef, DbError>

The file this device has a record of under this id, from one committed state.

pub async fn user_file(&self, file: FileId) -> Result<Option<UserFile>, DbError>

The recorded original’s path, size and modification time; never reread its bytes.

pub fn read<F, R, E>(&self, read: F) -> Read<'_, F, M>

where F: FnOnce(SqlReadContext<'_>) -> Result<R, E> + Send + 'static, R: Send + 'static, E: From<DbError> + CarriesBug + Send + 'static,

Run ordinary SQL against one consistent snapshot when awaited. The read fails with the closure’s own error type, and with a failure of the database’s own as that type’s From<DbError>.

pub async fn lost_values(&self) -> Result<Vec<LostValue>, DbError>

Decode every lost cell and removed row in one snapshot.

pub async fn schema_version(&self) -> Result<u32, DbError>

The committed app schema version, read on a read-only connection.

pub async fn sqlite_settings(&self) -> Result<SqliteSettingsInEffect, DbError>

The SQLite settings the store’s connections have in effect (§4).

impl Database

pub fn begin_close(&self)

Mark this instance as closing for a reopen to wait on, though workers still hold clones of it: the facade’s owning scope ended (F.4).

pub fn sync_changes(&self) -> DatabaseChanges

Observe new local writes: rows inserted into the outgoing write queue. Upload confirmation removing a row is this device’s own bookkeeping and wakes nothing (§6.7). Register before the first sync to include writes committed while a pass is running.

pub fn started_operations(&self) -> DatabaseChanges

Observe operations as they start: rows inserted into the journal, such as an invite, whose expiry the handle wakes to write (§13.2).

pub fn fail_expiry_wait(&self, error: WallTimerError)

The handle’s clock could not wait for an invite’s expiry: every later call and live query fails with DbError::WallTimer until the store is reopened (§13.2).

pub fn attempt_commits(&self, attempt: CommitScope) -> AttemptCommits

Observe, from now, every commit made outside attempt: an operation attempt’s own commits are no evidence against the wait it ends in, and which rows matter is known only when it ends (§6.7).

pub fn watch_attempt( &self, attempt: AttemptCommits, rows: &[PrerequisiteRows], ) -> DatabaseChanges

Observe rows from here on, after attempt. The result first reports whether a commit since the attempt began changed one of them: such a commit is evidence against the wait the attempt ends in (IO racing_commit_wakes).

pub fn uploads_in_flight(&self) -> InFlight

The files this process is sending now: the upload worker marks each attempt, and coven’s views read them (§4, §17.9).

pub fn downloads_in_flight(&self) -> InFlight

The files this process is downloading to keep whole now: each pin’s download marks its attempt, and coven_downloading reads them (§4, §17.8).

pub fn record_network(&self, network: NetworkState)

The store’s watch says the device’s network is now network: coven’s views show it, and a live query that read them runs again (§4, §6.7).

pub fn subscribe<F, R, E>(&self, query: F) -> LiveQuery<R, E>

where F: Fn(SqlReadContext<'_>) -> Result<R, E> + Send + Sync + 'static, R: Send + 'static, E: From<DbError> + CarriesBug + Send + 'static,

Observe the tables and columns a query reads, and the rows its conditions allow. Its results fail with the closure’s own error type.

pub fn subscribe_reconfigurable<Q, F, R, E>( &self, initial_request: Q, query: F, ) -> ReconfigurableLiveQuery<Q, R, E>

where Q: Clone + PartialEq + Send + Sync + 'static, F: Fn(&Q, SqlReadContext<'_>) -> Result<R, E> + Send + Sync + 'static, R: Send + 'static, E: From<DbError> + CarriesBug + Send + 'static,

Observe a query whose request can be replaced through a shared handle.

pub fn subscribe_lost_values<E>(&self) -> LiveQuery<Vec<LostValue>, E>

where E: From<DbError> + CarriesBug + Send + 'static,

Observe the decoded lost cells and removed rows.

pub async fn write<F, R>(&self, sql: F) -> Result<R, DbError>

where F: FnOnce(SqlContext<'_, '_>) -> Result<R, DbError> + Send + 'static, R: Send + 'static,

Run app SQL and coven’s steps, and commit its unsigned write record and merge metadata in one IMMEDIATE transaction (§4). The closure’s result is returned after commit.

pub async fn write_as<F, R, E>(&self, sql: F) -> Result<R, E>

where F: FnOnce(SqlContext<'_, '_>) -> Result<R, E> + Send + 'static, R: Send + 'static, E: WriteFailure + Send + 'static,

write, for a closure whose failures are E: callback errors retain their type alongside rollback or byte-cleanup failures.

pub async fn stage_files<F, T, E>(&self, stage: F) -> Result<StagedFiles<T>, E>

where F: FnOnce(&mut WriteBatch<'_>) -> Result<T, E> + Send + 'static, T: Send + 'static, E: WriteFailure + Send + 'static,

Stage app bytes for a later write (§17.2): stage names each file’s namespace and place and returns what that write’s SQL needs, such as the ids staging gave them. Their bytes are streamed to coven’s own copies, each synced, and flushed, before this returns; close waits for that, and for its cleanup if it fails or is cancelled. The result holds nothing close waits for. A write takes it with put_staged.

pub async fn staged_write<F, S, T, R, E>( &self, stage: F, write: S, ) -> Result<R, E>

where F: FnOnce(&mut WriteBatch<'_>) -> Result<T, E> + Send + 'static, S: FnOnce(SqlContext<'_, '_>, T) -> Result<R, E> + Send + 'static, T: Send + 'static, R: Send + 'static, E: WriteFailure + Send + 'static,

Stage app bytes, then run a write that puts them in its rows, as an app does with stage_files and put_staged, for tests.

pub async fn write_bulk<F, R, E>(&self, sql: F) -> Result<R, E>

where F: FnOnce(BulkSqlContext<'_>) -> Result<R, E> + Send + 'static, R: Send + 'static, E: WriteFailure + Send + 'static,

Run app SQL that writes device-local tables alone in one IMMEDIATE transaction, as plain SQLite: no pre-update hook records its row changes, so SQLite empties a table in one step and fills one at its own speed (§4). A statement that would write a synced table, itself or through a trigger or foreign-key action, fails the write with SyncedTableInBulkWrite, and everything rolls back. After commit, every live query that read a table the write’s statements may change runs again, whatever rows it read. The closure’s result is returned after commit.

pub async fn checkpoint( &self, mode: CheckpointMode, ) -> Result<WalCheckpoint, DbError>

Checkpoint the store’s WAL on the writer, between writes (§4).

pub async fn incremental_vacuum( &self, pages: IncrementalVacuum, ) -> Result<(), DbError>

Give back free pages of a store created with incremental auto-vacuum, on the writer, between writes (§4). On any other store it does nothing.

pub async fn release_memory(&self) -> Result<(), DbError>

Give back every connection’s cached pages that no statement is using (§4). SQLite as coven builds it (SQLITE_ENABLE_MEMORY_MANAGEMENT) keeps the unused pages of every connection in the process in one pool, and one connection’s release empties the whole pool: so one release on an idle reader frees the writer’s, the input database’s and the checkpointers’ too, and never waits for a write.

pub fn applied_migrations(&self) -> Result<Vec<MigrationOutcome>, DbError>

The migrations this open committed, classified individually.

pub async fn close(&self) -> Result<(), DbError>

Wait for database calls, close all connections, then release the writer lock. Every subsequent database call, including close, reports StoreClosed.

impl Database<ReadOnly>

pub fn begin_close(&self)

Begin closing every clone of this handle, at once and before its connections close: every later call fails with StoreClosed, a call already running answers StoreClosed too, and a deletion in this process waits for the readers’ lock to be released (E1).

pub async fn close(&self) -> Result<(), DbError>

Wait for active calls and close every clone of this handle.

impl Database

pub async fn pin_progress( &self, files: Vec<FileRef>, ) -> Result<PinProgress, DbError>

Verified cache coverage for these fixed references, in one snapshot.

pub fn subscribe_pin_progress<E>( &self, files: Vec<FileRef>, ) -> LiveQuery<PinProgress, E>

where E: From<DbError> + CarriesBug + Send + 'static,

The same pre-built cache query with the same fixed references.

pub async fn files_pinned( &self, files: Vec<FileId>, ) -> Result<Vec<Option<bool>>, DbError>

Whether each file is pinned, one answer per file in order.

pub fn subscribe_files_pinned<E>( &self, files: Vec<FileId>, ) -> LiveQuery<Vec<Option<bool>>, E>

where E: From<DbError> + CarriesBug + Send + 'static,

The same internal query, live.

Trait Implementations

impl<M: Mode> Clone for Database<M>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.