Struct Coven 

pub struct Coven { /* private fields */ }

This app’s stores on this device (E1): the app directory each has its own directory under, the OS keychain service their keys and secrets are kept under, and the device’s network, which each open store watches. The app builds one at startup and holds it.

Implementations

impl Coven

pub fn in_memory(app_dir: PathBuf) -> Self

An installation for a test: its stores under app_dir, a keychain with no device-only entries and none of the person’s entries, isolated from the OS and other tests, and a usable network that isn’t metered, which the test drives. A new one simulates another device; keep one to test reopening.

pub fn in_memory_reporting_to(app_dir: PathBuf, bugs: BugSinkRef) -> Self

in_memory, whose bugs in work nobody waits for go to bugs, for a test that hears them (E15).

pub fn in_memory_with_saved_keychain( app_dir: PathBuf, path: &Path, ) -> Result<Self, KeyError>

An installation, as in_memory makes, whose keychain’s device-only entries are the ones save_device_keychain saved at path: the same device again, which opens the stores it had, as a test reopens a kept copy of a store in another process. Its person entries start empty.

pub fn with_block_store(app_dir: PathBuf) -> Self

An installation on an Android phone: its person entries behave as Block Store keeps them, this phone’s own, with Block Store’s limits (§13.1).

pub fn another_device(&self, app_dir: PathBuf) -> Self

Another device of the same person, its stores under app_dir: an installation with its own empty device-only keychain. With iCloud Keychain it shares this one’s person entries, as iCloud Keychain carries a restore code and S3 key between the person’s devices; with Block Store it has its own, empty.

pub fn set_up_new_device(&self, app_dir: PathBuf) -> Self

A new phone set up from this one by direct transfer, its stores under app_dir: nothing of this phone’s own, and a copy of its Block Store entries (§13.1). Requires with_block_store.

pub fn restore_new_device_from_cloud(&self, app_dir: PathBuf) -> Self

A new phone set up from this phone’s last cloud backup, its stores under app_dir: the Block Store entries that backup holds (§13.1). Requires with_block_store.

pub fn back_up_to_cloud(&self)

Google’s periodic cloud backup of this phone’s Block Store: the entries stored while end-to-end encryption was available. Requires with_block_store.

pub fn set_end_to_end_encryption(&self, available: bool)

Whether this phone’s cloud backup would be end-to-end encrypted: it has a screen lock. Requires with_block_store.

pub async fn create_closed_store( &self, name: &str, ids: IdSourceRef, ) -> Result<StoreDir, StoreCreationError>

Create through the production builder, then close for a reopening fixture.

pub fn create_store_dir( &self, id: StoreId, ids: &dyn IdSource, ) -> Result<StoreDir, DirectoryCreationError>

Publish a directory fixture without a database or member custody.

pub fn join_network(&self, metered: bool)

The device moves to another usable network: a network report, as the platform’s would make (api.md E5).

pub fn lose_network(&self)

The device loses its network: no report.

pub fn network_cannot_tell(&self)

The platform fails to say what the device’s network is: coven can’t tell, and calls it metered, until the test says again.

pub fn set_network_metered(&self, metered: bool)

The device’s network turns metered or unmetered: no report.

pub fn keep_store_keys( &self, directory: &StoreDir, keys: &StoreKeyring, ) -> Result<(), KeyError>

Seed the simulated OS custody as if this installation had opened keys.

pub fn save_device_keychain(&self, path: &Path) -> Result<(), KeyError>

Save this installation’s device-only keychain entries at path, replacing what is there: each store’s device id, store keys and member keys, which in_memory_with_saved_keychain loads. The person’s entries stay out.

pub fn lose_storage_credentials(&self, store: StoreId) -> Result<(), KeyError>

Delete this installation’s storage credentials for store, as the person deleting the keychain entry by hand does. The recorded location stays: a handle opened afterwards reports no storage set up on this device, and setup connects that location again.

pub fn fail_next_keychain_operation(&self)

Refuse the next keychain operation before changing any stored value.

impl Coven

pub fn new( app_dir: PathBuf, keyring_service: &str, bugs: BugSinkRef, ) -> Result<Self, KeyError>

The stores under app_dir, their keys and secrets in the OS keychain under the service keyring_service, watching the platform’s network. The app creates app_dir; coven creates directories only inside it and never opens a directory above it, which Android refuses. No key is read here. A bug in work nobody waits for, in any store, goes to bugs, the app’s crash reporter (E15). An empty service name, or one containing NUL, fails with KeyError::InvalidServiceName; an OS keychain coven can’t reach fails with its KeyError.

pub async fn storage_config( store_dir: &StoreDir, ) -> Result<Option<StorageConfig>, SyncError>

Read the saved storage location without opening the store or its custody. None means storage has never been set up; once set up, the location stays.

pub async fn closed_sync_status( &self, store_dir: &StoreDir, ) -> Result<ClosedSyncStatus, CovenError>

A closed store’s sync state, last synced time and unsent work, read without opening it (E1, E5): the state opening shows before sync starts. It holds the store’s writer lock while it reads, since only that lock shows that no handle runs the store’s sync: an open handle, here or in another process, refuses it with StoreLockError::AlreadyOpen at once, and the app reads that handle. An instance closing in this process is waited for first, and an open of the store in this process meanwhile waits for this read. Whether this device holds the location’s credentials is read from the keychain, as opening reads it. A store whose replacement or deletion is unfinished is refused as opening refuses it, and one whose device entry the keychain doesn’t hold fails with DeviceKeyMissing.

pub fn set_temporary_directory( directory: &Path, ) -> Result<(), TemporaryDirectoryError>

Keep SQLite’s temporary tables in directory, such as the app’s cache folder, for every store this process opens. An Android app calls this before opening its first store: SQLite finds no folder there by itself, and temporary tables that outgrow a connection’s cache fail without one. Elsewhere SQLite uses the system’s.

pub async fn stores(&self) -> Result<Vec<ListedStore>, StoreListError>

Stores on this device, ordered by id, with their committed names. A store whose replacement record or name can’t be read is listed as Unreadable with why; a listing never substitutes an older name. A store whose replacement or deletion is unfinished lists with the work that must finish, so the app can offer to finish it; an unfinished first installation is not listed. First it finishes every deletion from the device that a cut call left under the directory’s deletion name, which no call holds (§19.3, E1); a failure there fails the listing with StoreListError::Deletion.

pub fn store_dir(&self, id: &StoreId) -> StoreDir

Address a store without reading settings or acquiring the writer lock.

pub fn builder(&self) -> CovenBuilder

Configure creating, opening, restoring or joining a store.

pub async fn discard_store( &self, store_dir: &StoreDir, ) -> Result<(), StoreDeletionError>

Deletes a closed store from this device without opening it: this device’s own keychain entries for it, including every saved host secret, then its directory. The person’s saved restore code and S3 key stay for their next devices; they go only when the person leaves the store (§13.1). Unsent writes and files are lost, and this device stays registered with the store until it is removed; prefer CovenHandle::delete_store. Use this for a store that cannot open, or to finish a handle’s deletion that failed after closing. A store whose reset_device or restore_device stopped past its record is deleted whole: both installations, the replacement’s directory and record, and this device’s entries, which by then may name either device. Refused while a writer, read-only handle, file stream or a running replacement remains; storage is untouched. A handle of it in this process that is closing, or whose last clone was dropped, is waited for. Its first step renames the store’s directory, which hides the store and records the deletion: one that stops part way, a crash included, is finished by retrying, by the next stores(), or by a restore or join of the store (§19.3).

pub async fn saved_restore_codes( &self, ) -> Result<Vec<SavedRestoreEntry>, BootstrapError>

The saved entries of this app’s keychain service, in iCloud Keychain on Apple and in this phone’s Block Store on Android, one per store, ordered by store id; empty when none are saved. An entry coven can’t restore from is listed as Unreadable, never omitted, so the person can forget it. A keychain read failure (the search, an entry’s bytes or an S3 key’s presence) fails the whole call, as does a restore-code account with no store id, KeyError::RestoreCodeStoreId. A keychain with neither iCloud Keychain nor Block Store fails with BootstrapError::SecureStorage(KeyError::Unsupported). Pass a readable entry to restore_from_saved_code, which reads its current code and key.

pub async fn forget_saved_restore_code( &self, store: StoreId, ) -> Result<(), BootstrapError>

Delete the store’s saved S3 key, then its restore code: from iCloud Keychain, and so from every one of the person’s Apple devices, or from this phone’s Block Store, leaving other phones’ own (§13.1). Readable and unreadable entries alike; every keychain group’s copy goes. The store, its storage and every device’s copy stay; no store need be open and no provider connected. Absent entries succeed; after a failure part way the store is still listed, and calling again finishes. A later join, restore, reset or member-key replacement saves the entry again. A keychain with neither iCloud Keychain nor Block Store fails with BootstrapError::SecureStorage(KeyError::Unsupported).

Trait Implementations

impl Clone for Coven

fn clone(&self) -> Coven

Returns a duplicate of the value.

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

Performs copy-assignment from source.