Struct CovenHandle 

pub struct CovenHandle { /* private fields */ }

A shared handle to the open store and its running work (Appendix F.4). Administrative changes catch up with storage before starting and report a refusal by the applied state as SyncError::Rejected, including its typed target.

Implementations

impl CovenHandle

pub async fn file_status( &self, file: &FileRef, ) -> Result<FileStatus, FileReadError>

The file’s status as its record now stands (§17.6): one this device uploads from local facts, one only on another device from its record, and a stored one by a single-object status call. Network failures and denied access are errors, not Missing.

pub async fn prepare_pin( &self, files: &[FileRef], ) -> Result<PreparedPin, FileReadError>

Prepares keeping stored files whole on this device regardless of the cache budget, which pinned bytes don’t count toward (§17.8): downloads what each lacks into a whole copy, checked against its content hash, and pins nothing; a write commits the result with CovenWrite::pin. A file only on one device, this one included while it uploads, is refused with FileReadError::DeviceOnly, and one whose record goes, or leaves its stored bytes, while they download keeps nothing and fails with DbError::NoLongerStored. A prepare that stops, dropped or ended by a crash, keeps the bytes it downloaded of each file, apart from the cache, and the next prepare of the file continues from them; the app’s unpin of the file ends them, and a prepare it ends fails with DbError::PinChanged. Which files are downloading is in coven_downloading, how far each has got on the download watch.

pub async fn pin(&self, files: &[FileRef]) -> Result<(), FileReadError>

Prepares a pin and commits it in a write of its own.

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

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

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

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

pub async fn unpin(&self, files: &[FileId]) -> CovenResult<()>

Remove the files’ copies from this device, in a write of its own (CovenWrite::unpin).

pub async fn files_pinned( &self, files: &[FileId], ) -> CovenResult<Vec<Option<bool>>>

Whether each file is pinned, one answer per file in order, or None for a file this device has no record of. The answer is whether coven_pins lists it.

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

The same internal query, live. To watch different files, drop this query and subscribe with the new files.

pub async fn evict_file(&self, file: FileId) -> CovenResult<()>

Remove cache copies only, in a write of its own (CovenWrite::evict_file).

pub async fn clear_cache(&self, namespace: &str) -> CovenResult<()>

Clear a namespace’s cache, in a write of its own (CovenWrite::clear_cache).

pub async fn set_cache_budget( &self, namespace: &str, max_bytes: u64, ) -> CovenResult<()>

Set and enforce a namespace’s independent byte budget, in a write of its own (CovenWrite::set_cache_budget).

pub async fn get_cache_budget(&self, namespace: &str) -> Result<u64, DbError>

The namespace’s budget, declared or since set.

impl CovenHandle

pub async fn restore_code(&self) -> Result<String, SyncError>

This member’s current restore code, for their other devices (§13.1). It carries no S3 key.

pub async fn restore_code_for_transfer(&self) -> Result<String, SyncError>

This member’s current restore code for the app to show in a QR code to the person’s own new device, behind the same tap (§13.1, E10). On S3 it carries the key this device uses now, so the new device asks for none; after a replacement it is the new key. Without a key, on other providers or when this device holds none, it is restore_code’s.

pub async fn replace_access_key( &self, access_key_id: String, secret_access_key: SecretText, ) -> Result<(), SyncError>

Commit a replacement S3 key and publish its id; the restore code is unchanged (E9). A publication failure retains the credentials; retry with the same key. Coven never deletes the key it replaces; the person deletes it in the provider’s console (§14.3). Once this member’s removal applies, returns Removed and saves nothing.

pub async fn update_credentials( &self, access_key_id: String, secret_access_key: SecretText, ) -> Result<(), SyncError>

Install this member’s separately supplied S3 key (E9). Identity, location and restore code stay unchanged; disconnected handles keep it for connecting. Once this member’s removal applies, returns Removed and saves nothing: the key would return to the person entries the removal emptied (§14.1).

impl CovenHandle

pub async fn start_sync(&self) -> Result<(), SyncError>

Start syncing; the first pass builds an absent client from custody credentials and backs off like any failed pass. Already running or unconfigured stores do nothing.

pub async fn stop_sync(&self) -> Result<(), SyncError>

Stop syncing: coven_retry_effect says sync isn’t running and the waiting retries are answered NotSyncing first; then the active pass and transfers finish, the provider client is released and the location recorded as custody holds it, and this returns. Once it has, no pass or upload runs until sync starts again, whatever connects the handle meanwhile. Keys remain unlocked for the handle session. A start_sync asked meanwhile starts after it, and dropping this future leaves stopping to finish. Stopping changes nothing the sync state reads; a release failure is recorded as the last pass’s failure and returned. A failure writing either row has failed the handle; stopping goes on and the failure is returned.

pub fn sync_now(&self)

Request a pass while started. Requests during a pass, and local writes committed during it, retain one more pass; the pass’s own bookkeeping retains none. A failed connection’s backoff and a provider cooldown hold requests until they end.

pub async fn retry_now(&self) -> Result<RetryAnswer, SyncError>

The person asked to retry everything now, such as by pulling to refresh. Every ordinary backoff ends, answered or not: the connection’s, operations’ and uploads’; a pass runs now. Provider cooldowns hold, and failures that never retry stay. An ended wait keeps its failure count, so a retry that fails again waits the next longer delay. Requests coalesce as sync_now requests do.

The retry takes effect once this returns, with the answer as a future, which resolves at once as coven_retry_effect says when no pass runs for it: CoolingDown with when the provider cooldown ends, Failed with a failure only the person can clear, or NotSyncing while sync is stopped. Otherwise it resolves when the first pass after the retry ends: Synced, or Failed with why. A closed handle answers NotSyncing. Dropping the future leaves the retry in place. Deciding the answer writes the retry effect’s row; a failed write has failed the handle, and is returned.

pub fn test_retry_effect(&self) -> Followed<RetryEffect, DbError>

Follow coven_retry_effect with a live query, as an app does (E5).

pub fn sync_often(&self, interval: Duration) -> SyncOftenGuard

Run idle passes at most interval apart, instead of every 30 seconds, until the returned guard drops, such as while a screen waits for another device. With several guards held, the shortest interval wins; once the last drops, idle passes return to every 30 seconds. The next idle pass comes interval after the last pass ended, so one that is already due runs at once. Connection backoff and provider cooldowns still hold every pass. The request outlives stopping and starting sync, and does nothing while sync is stopped.

impl CovenHandle

pub async fn sync_status(&self) -> CovenResult<SyncStatus>

The sync state and when sync last finished, computed from coven_sync_status, coven_retry_effect, the send queue, the upload queue, the files moving and the pending records in one committed snapshot (§19.1).

pub fn subscribe_sync_status(&self) -> LiveQuery<SyncStatus, CovenError>

The same pre-built query, live (E4): its first value is the current state.

pub fn test_sync_status(&self) -> Followed<SyncStatus, CovenError>

Follow the sync state with subscribe_sync_status, as an app does (E5).

pub fn test_last_pass(&self) -> Followed<Option<LastPass>, DbError>

Follow coven_sync_status.last_pass with a live query, as an app’s SQL does (E4): None until a pass ends on this device.

impl CovenHandle

pub async fn replace_member_keys(&self) -> Result<SecretText, SyncError>

Replace this member’s signing and sealing pair (§10, §12.3). App writes return DbError::MemberKeysChanging until it finishes; this installation’s queued writes and entries are confirmed first. A fresh pair is kept in identity custody before its key copies and the entry signed by the current pair are published. Returns once its slot binds the pair and custody hold the new pair, returning its restore code. A failure keeps both pairs and the attempt for retry; a rejection is returned and never overridden. Other installations holding the old pair report MemberKeysReplaced and need the current keys.

pub async fn replace_member_keys_for( &self, member: &MemberId, keys: MemberPublicKeys, ) -> Result<Option<OperationId>, SyncError>

Publishes a prepared public pair for another active member, in a write of its own (CovenWrite::replace_member_keys_for).

impl CovenHandle

pub async fn unsent_work(&self) -> CovenResult<UnsentWork>

The writes and files this device committed and has not uploaded, from one committed snapshot: what deleting the store would lose. With storage set up, delete_store(IfUnsent::Refuse) refuses with these counts. Available while disconnected.

pub fn subscribe_unsent_work(&self) -> LiveQuery<UnsentWork, CovenError>

The same pre-built query, live (E4).

pub async fn delete_store( &self, unsent: IfUnsent, ) -> Result<(), StoreDeletionError>

Deletes this store from this device. With storage set up, a location recorded without credentials is refused with SignInRequired; then unsent writes and files are refused unless unsent discards them; both change nothing. The deletion then records itself in the store’s directory and publishes this device’s removal (§14.1), waiting until it applies. A failure before the removal is journaled removes the record and is Sync, the store as it was. From the journal on the deletion only goes forward: a failure closes the handle and is Unfinished, and the store lists as being deleted, refuses opens and is finished by CovenBuilder::resume_deletion (§11.6). Once the removal applied, or with no storage set up, it closes this handle, a failure there being Closing, and deletes as Coven::discard_store. The call runs to its end even if the app drops its future. Only this device leaves: the person’s restore code and S3 key in iCloud Keychain stay for their other devices (§13.1).

impl CovenHandle

pub async fn onedrive_root(&self) -> Result<StorageFolder, StorageSetupError>

The signed-in person’s default OneDrive root and setup location. Call authenticate first; tokens stay in coven and settings are unchanged.

pub async fn onedrive_folders( &self, parent: &StorageConfig, ) -> Result<Vec<StorageFolder>, StorageSetupError>

Every immediate child folder of this OneDrive location, across every page.

pub async fn create_onedrive_folder( &self, parent: &StorageConfig, name: &str, ) -> Result<StorageFolder, StorageSetupError>

Create this exact name in the chosen OneDrive parent; occupied names fail. Returns a setup location without committing it. Close waits for creation, including when the awaiting app drops its future.

pub async fn dropbox_shared_folders( &self, ) -> Result<Vec<StorageFolder>, StorageSetupError>

Every shared Dropbox namespace the signed-in account can access. Requires Full Dropbox sign-in; each returned location goes directly to setup.

pub async fn create_dropbox_shared_folder( &self, name: &str, ) -> Result<StorageFolder, StorageSetupError>

Make a folder named name at the top of the signed-in person’s Dropbox and share it, for “New folder…” in the picker; a name already taken fails with AlreadyExists and nothing is made or shared. Requires Full Dropbox sign-in. Returns a setup location without committing it. Close waits for the folder, including when the awaiting app drops its future.

impl CovenHandle

pub async fn clean_up_gone_devices_files(&self) -> Result<(), SyncError>

Delete the stored files of devices gone for good (§14.1) that nothing refers to (§17.10): for every such device this device is responsible for, end the uploads it left and delete the snapshot bodies of its that no announcement names (§16.6), list its file folder again, then delete each file found that no retained row, write or snapshot names, once every other device not gone for good has published a write that read past the listing; later passes delete the rest as those writes arrive. A gone device can keep uploading while its provider access still works, but nothing it writes after the entry that stopped it counts, so this is safe to run at any time. Returns once the listing and deletions finish, or with the failure that stopped them; SyncError::SnapshotPending while a snapshot of this device’s is still being published.

impl CovenHandle

pub async fn delete_discarded_devices(&self) -> CovenResult<()>

Delete the installations reset_device kept in this store’s directory, each moved aside when its reset swapped it out (§19.3). Nothing reads them once the reset’s notice is in the database, and the store’s own files stay. Returns once they are gone and the directory is synced. A failure midway returns its error and leaves the rest, part of one perhaps, for the next call, which removes what remains; with none left it succeeds.

impl CovenHandle

pub async fn local_bytes(&self) -> CovenResult<LocalBytes>

One measurement of what the store keeps on this device. The cache’s counters, the partial downloads’ sizes and the budgets come from one read of the database; the store’s directory is then walked for its own files and the archives resets kept. The cache’s bytes are counted by its entries, so the walk leaves its folder out.

pub fn subscribe_local_bytes(&self) -> LocalBytesWatch

The first measurement at once, then a new one after each write that changes the cache’s committed entries or a budget, and after each delete_discarded_devices. Partial downloads are measured with each but start none.

impl CovenHandle

pub async fn prepare_device_only( &self, folder: &Path, files: Vec<(FileId, RelativePath)>, cancel: &Receiver<bool>, on_progress: impl Fn(Progress<DeviceOnlyStep>), ) -> Result<PreparedDeviceOnly, DeviceOnlyError>

Downloads cloud files to the paths named under folder, for a write to switch them all to device-only on this device with CovenWrite::make_device_only, each copy becoming the original this device records (§17.3). Each name is written as the one rule for every platform makes it. The member must be in each file’s audience and may change every row referencing it. A path through a symbolic link below the folder, where something is already, or naming what another path names once written, case and Unicode form aside, is refused. on_progress is called on this task with each file’s download and how many of its bytes, and of all the call’s, are down, at most a few times a second. Until it returns, cancel stops the call; a failure, a panic in a download among them, or a cancel removes every copy and folder it made.

pub async fn make_device_only( &self, folder: &Path, files: Vec<(FileId, RelativePath)>, cancel: &Receiver<bool>, on_progress: impl Fn(Progress<DeviceOnlyStep>), ) -> Result<(), DeviceOnlyError>

prepare_device_only, then CovenWrite::make_device_only in a write of its own. A write that fails removes the copies.

impl CovenHandle

pub fn subscribe_upload_transfers(&self) -> TransferWatch

How far each file this process is sending has got, by file: every one being sent first, then each change as its bytes go, until the store closes (E7). The files are the ones coven_sending lists.

pub fn subscribe_download_transfers(&self) -> TransferWatch

How far each file this process is downloading to keep whole has got, by file, for a pin: every one being downloaded first, then each change as its bytes arrive, until the store closes (E8). The files are the ones coven_downloading lists.

impl CovenHandle

pub async fn uploads(&self) -> CovenResult<UploadQueue>

Queue, pause setting and provider-confirmed session progress in one committed database snapshot, available while disconnected, with the files this device is sending now (E7).

pub async fn retry_uploads_now(&self) -> Result<DrainOutcome, SyncError>

Optionally retry recoverable uploads early; provider cooldowns still hold them and individual failures stay in pending() (§17.9). While uploads are paused, or the network is metered and the app moves files only on unmetered networks, it tries only bound ones, and while sync is stopped none, saying so (§17.4, §17.9). Once the upload worker has ended other than with the store, it fails with why (E15).

pub async fn set_uploads_paused(&self, paused: bool) -> CovenResult<()>

Pause trailing uploads, or resume them, in a write of its own (CovenWrite::set_uploads_paused).

pub async fn set_unmetered_only(&self, unmetered_only: bool) -> CovenResult<()>

Move files only on unmetered networks, or on any, in a write of its own (CovenWrite::set_unmetered_only).

impl CovenHandle

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

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

Runs one write: the app’s SQL and coven’s steps, in one transaction. It fails with the closure’s own error type, which keeps a failed rollback or byte removal beside the write’s failure (WriteFailure).

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,

Runs one bulk write: SQL that changes device-local tables alone, run as plain SQLite with no record of each row change, so emptying a table takes one step and filling one runs at SQLite’s 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. Triggers still run. After commit, every live query that read a table the write’s statements may change runs again, whatever rows it read; a small change that should rerun only the live queries reading its rows belongs in write.

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,

Stages app bytes for a write that puts them in rows (§17.2): stage stages each file and returns what that write needs, such as the ids staging gave them, and the write takes it with CovenWrite::put_staged. The bytes are streamed to coven’s own copies, synced and flushed before this returns; close waits for staging and its cleanup, including cancellation. The staged files hold nothing close waits for: dropped uncommitted, or after the store closes, they are removed by the next write or open. An undeclared namespace fails with UndeclaredNamespace, a user one with NamespaceKind.

impl CovenHandle

pub fn store_id(&self) -> StoreId

The store’s stable id, including before storage is configured.

pub async fn store_name(&self) -> CovenResult<String>

The store’s current name, from this device’s committed state (E9).

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

The same name query, live (E4).

pub async fn joined_invitee(&self) -> CovenResult<Option<String>>

The new person’s name the join’s request carried, which a store a join published keeps on this device until a write acknowledges it (CovenWrite::acknowledge_joined_invitee). None for a store no join published, for a recovery invite’s, which carries no name, and once acknowledged (§13.2).

pub async fn rename_store( &self, name: &str, ) -> Result<Option<OperationId>, SyncError>

Renames the store, in a write of its own (CovenWrite::rename_store).

pub fn device_id(&self) -> DeviceId

This installation’s device id, available before setup and retained after close.

pub async fn storage_config(&self) -> Result<Option<StorageConfig>, SyncError>

The committed storage location, without credentials or provider requests. None before setup; once set up, it stays. A closed handle refuses the call.

pub fn transfer_limits(&self) -> TransferLimits

How many file uploads and file downloads run at once. Each upload checks the upload limit as it starts; a pin captures the download limit.

pub fn set_transfer_limits(&self, limits: TransferLimits)

Set limits for future transfers; transfers already running continue.

pub async fn setup_s3_storage( &self, storage: StorageConfig, device_name: &str, access_key_id: String, secret_access_key: SecretText, on_progress: impl Fn(Progress<StorageSetupStep>), ) -> Result<StorageSetup, StorageSetupError>

Check S3 safety and provider operations, then set up S3 using this member’s own access key. The returned location is the recorded one, carrying detected settings when the endpoint needed them. on_progress is called on this task with each step as it runs (E1).

pub async fn detect_s3_settings( &self, storage: StorageConfig, access_key_id: String, secret_access_key: SecretText, ) -> Result<S3Detection, StorageSetupError>

Probe the S3 service at this location with this member’s key (§20.7), writing only fresh objects under the store’s .coven-check prefix and deleting them, also on failure, then removing what earlier recorded detection runs at that bucket and prefix left. Commits only its run’s record, kept until its probes and uploads are confirmed gone.

pub async fn authenticate( &self, access: OAuthAccess, ) -> Result<(), StorageSetupError>

Present provider sign-in and keep tokens in coven’s session custody. Call setup to attach the chosen account to storage and persist credentials. Dropping the future cancels sign-in without replacing the previous tokens.

pub async fn setup_oauth_storage( &self, storage: StorageConfig, device_name: &str, on_progress: impl Fn(Progress<StorageSetupStep>), ) -> Result<StorageSetup, StorageSetupError>

Check provider operations and set up OAuth storage using coven’s held sign-in. on_progress is called on this task with each step as it runs (E1).

pub async fn setup_cloudkit_storage( &self, container: &str, device_name: &str, on_progress: impl Fn(Progress<StorageSetupStep>), ) -> Result<StorageSetup, StorageSetupError>

Set up native iCloud storage in the entitled container. Coven obtains the owner and creates a custom zone; reconnects retain the recorded location. Unsupported platforms return StorageFailure::ProviderUnavailable. on_progress is called on this task with each step as it runs (E1).

pub fn cancel_storage_setup(&self) -> SetupCancellation

Cancel the storage setup running on this store (§11.6). Before its point of no return setup undoes what it wrote, fails with StorageSetupError::Cancelled, and coven_operations lists it cancelled. Past that point, from its CreatingStore or RecordingAccess step on or once a crash cut it there, it finishes, and the answer says so. Holds no lock: setup holds its call’s.

pub async fn unlock_store_key( &self, ) -> Result<ConnectedStorage, StoreKeyUnlockError>

Open this member’s sealed keys and connect without starting the loop.

pub fn store_key_state(&self) -> Result<StoreKeyState, KeyError>

Whether custody holds opened store keys.

pub async fn device_reset(&self) -> CovenResult<Option<DeviceReset>>

The latest completed replacement stored in this installation, or None. It survives reopening; unsent edits of the old copy were discarded (§19.3).

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

The same pre-built query, including a replacement completed before opening.

pub async fn pending(&self) -> CovenResult<Vec<PendingRecord>>

Current local conditions, including while disconnected, each with the cause coven_pending.cause keeps beside it.

pub async fn members(&self) -> CovenResult<Vec<MemberInfo>>

The members and their devices, as this device’s applied slots have them (E9).

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

The same internal query, live (E4).

pub async fn set_member_role( &self, member: &MemberId, role: MemberRole, ) -> Result<Option<OperationId>, SyncError>

Changes a member’s role, in a write of its own (CovenWrite::set_member_role).

pub async fn remove_member( &self, member: &MemberId, ) -> Result<Option<OperationId>, SyncError>

Removes a member, in a write of its own (CovenWrite::remove_member).

pub async fn remove_device( &self, device: DeviceId, ) -> Result<(Option<OperationId>, Option<ProviderSignOut>), SyncError>

Removes a device, in a write of its own (CovenWrite::remove_device).

pub async fn confirm_device_cut_off( &self, device: DeviceId, ) -> Result<(), SyncError>

The person did the provider step for a lost device of the account that holds the store (§14.2): signed it out, so nothing it sent can land any more. This device takes back every account that device’s invite shares named which no member or open invite uses, with requests like any other revocation, which run after this call returns. Needs the connection (NoStorage without it), and is refused with CutOffRefused naming why: NoAccountShared on S3, NotStoreOwner on a device that isn’t of the member whose account holds the store (see holds_store), and DeviceNotGone for a device not gone for good, which a later pass may change. While a request to one of those accounts runs it fails with DbError::ProviderRequestRunning and changes nothing: call again once it ends (§20.9).

pub async fn holds_store(&self) -> Result<bool, SyncError>

Whether this device’s member reaches storage through the account that holds the store (§20.9): only their devices share it and take sharing back, so only they can confirm a device cut off. False on S3, where no account holds the store. Reads the sequence forward first; needs the connection (NoStorage without it).

pub async fn operation_outcome( &self, operation: OperationId, ) -> Result<OperationOutcome, SyncError>

Waits for an operation the app’s writes journaled to end and returns its outcome, as coven_operations lists it (§11.4, E6); the outcome stays listed until a write acknowledges it. It waits for storage too: a pass runs the operation once storage is connected. An operation not listed fails with OperationUnknown.

pub async fn guided_access_key(&self) -> Result<GuidedAccessKey, SyncError>

The bucket, store prefix and filled member policy for making a key in the provider’s console (§20.10).

pub async fn reload_from_snapshot(&self) -> Result<(), OperationError>

Reload this device from snapshots, retaining and replaying its waiting writes (§19.2).

pub async fn reset_store(&self) -> Result<(), SyncError>

Reset the store audience from this device as an admin, then reload locally (§19.4).

pub async fn retry_pending_operation( &self, operation: OperationId, ) -> Result<(), OperationError>

Make an operation’s retry or undo due now, from its recorded progress, in a write of its own (CovenWrite::retry_pending_operation).

pub async fn create_invite( &self, target: InviteTarget, access: InviteAccess, lifetime: InviteLifetime, inviter: String, ) -> Result<(InviteId, MemberId, OperationId), SyncError>

Makes an invite, in a write of its own (CovenWrite::create_invite).

pub fn test_invites(&self) -> Followed<Vec<Invite>, DbError>

Follow coven_invites with a live query, as an app does (E10).

pub async fn approve_join_request( &self, request: &JoinRequest, ) -> Result<OperationId, SyncError>

Approves a request, in a write of its own (CovenWrite::approve_join_request).

pub async fn decline_join_request( &self, request: &JoinRequest, ) -> Result<(), SyncError>

Declines a request, in a write of its own (CovenWrite::decline_join_request).

pub async fn cancel_invite(&self, invite: &InviteId) -> Result<(), SyncError>

Cancels an invite, in a write of its own (CovenWrite::cancel_invite).

pub fn circles(&self) -> Circles<'_>

Circle calls borrowing this store’s operation owner.

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

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

A read of one consistent snapshot, run when awaited. Attach process to work on the result after the connection is released. It fails with the closure’s own error type, a database failure as its From<DbError>.

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,

A live query. Coven records the tables, columns and keys the query reads, and reruns it only for writes that touch them.

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,

A live query whose request, such as a page or a search term, can be replaced without starting a new subscription.

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

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

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

Checkpoints the store’s WAL between writes, returning what SQLite reports (§4). Restart and Truncate wait up to the busy timeout for reads still using the WAL, and report busy if they outlast it. NotStarted when another connection was checkpointing or committing.

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

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

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

Gives back the memory every connection’s page cache holds, as SQLite’s sqlite3_db_release_memory does, for when the OS warns of low memory or the app goes to the background (§4). SQLite keeps every connection’s unused pages in one pool for the process, so one release on an idle reader frees them all. Safe at any time, and never waits for a write. Later reads load the pages they need again.

pub async fn lost_values(&self) -> CovenResult<Vec<LostValue>>

Every lost value and removed row, as _coven_lost holds them (§8.2, §8.4).

pub async fn dismiss_lost_values(&self, values: &[LostValue]) -> CovenResult<()>

Dismisses lost values in a write of its own (CovenWrite::dismiss_lost_values).

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

The same, as a live query.

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

The file a row references, by the id the row holds: its size, namespace, audience and place, read in one committed state. An id this device has no record of returns DbError::FileAbsent; a malformed record returns DbError::DamagedDatabase.

pub async fn read_file(&self, file: &FileRef) -> Result<Vec<u8>, FileReadError>

Reads a whole file. A stored file is checked against its content hash.

pub async fn open_file_stream( &self, file: &FileRef, ) -> Result<FileStream, FileReadError>

Opens a file for reading ranges (§17.7), as its record stands when it opens; keep the stream for as long as the file is read. A file only on another device fails with FileReadError::DeviceOnly. Its shared store lock prevents deletion until it and its I/O finish.

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

The path, size and modification time coven recorded for a file’s user original on this device, or None when it has none.

pub async fn forget_store_keys(&self) -> Result<(), KeyError>

Removes the store keys from key custody. A failed removal leaves the custody failure visible to the caller; member identity is retained.

pub fn set_host_secret(&self, name: &str, value: &str) -> Result<(), KeyError>

Keeps an app secret, such as an API token, in the same keychain and under the same access policy as coven’s keys. Names are arbitrary strings. Coven records the name in a keychain list before writing the value to its own entry, retaining the platform’s per-secret size limit. Deleting the store removes every listed secret even if its database is damaged. Failure may leave an extra name; retrying is safe.

pub fn host_secret(&self, name: &str) -> Result<Option<String>, KeyError>

The secret, or None if it was never set.

pub fn delete_host_secret(&self, name: &str) -> Result<(), KeyError>

Deletes the secret before its recorded name; succeeds if absent. Failure may leave an extra name; retrying is safe.

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

Stops operation and file work, closes connections and releases the writer lock. Open file streams retain their shared deletion guards. Later database calls on any clone fail with DbError::StoreClosed; custody calls fail with KeyError::StoreClosed. Closing reports every failure: one alone as itself, several chained as SyncError::Cleanup.

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

Count the work the store’s connections run into counter, in application tests: its reads’ SQLite steps, the app’s and coven’s narrowing apart. Install it between calls, before the measured one.

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

The plaintext bytes each section of a store snapshot would hold now, for a test measuring what a snapshot keeps (D7). Every section’s place is in coven_format::snapshot::section.

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

Read committed plaintext records still awaiting upload in application tests.

Trait Implementations

impl Clone for CovenHandle

fn clone(&self) -> CovenHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CovenHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.