Struct CovenBuilder 

pub struct CovenBuilder { /* private fields */ }

Implementations

impl CovenBuilder

pub fn write_policy(self, policy: WritePolicy) -> Self

pub fn synced_tables(self, tables: Vec<SyncedTable>) -> Self

pub fn blob_tombstone_grace(self, grace: Duration) -> Self

How long a deleted blob is kept after its tombstone is written before the tombstone GC erases it: the cross-device convergence window. Defaults to [crate::blob::delete::BLOB_TOMBSTONE_GRACE]. Must be positive — a zero-or-negative grace is refused at open, since it would let the GC erase a blob a lagging peer still references.

pub fn max_concurrent_uploads(self, n: NonZeroUsize) -> Self

How many blob uploads the sync cycle’s upload drain runs at once. Defaults to one (fully serial). A NonZeroUsize so a zero — which would leave the drain admitting nothing and never completing — cannot be set.

pub fn max_concurrent_downloads(self, n: NonZeroUsize) -> Self

How many blob downloads a pin call fetches at once. Defaults to one (fully serial). A NonZeroUsize so a zero — which would leave the pin loop admitting nothing and never completing — cannot be set.

pub fn migrations(self, migrations: Vec<Migration>) -> Self

The host’s synced-schema migration ladder, applied over PRAGMA user_version at open. The top version is the wire schema_version every changeset is stamped with.

pub fn clock(self, clock: ClockRef) -> Self

pub fn key_service(self, key_service: StoreKeys) -> Self

pub fn key_custody(self, custody: KeyCustody) -> Self

How the store’s master key is protected: the OS keyring (the default), a passphrase-wrapped file, an in-memory session value, or a host’s own MasterKeyCustody implementation. coven builds every cipher internally from what this custody supplies — the host never touches a crypto type.

pub fn identity_custody(self, custody: IdentityCustody) -> Self

How this store’s device-signing identity is protected: the OS keyring (the default), a passphrase-wrapped file, an in-memory session value, or a host’s own DeviceIdentityCustody implementation. Selected next to key_custody — the identity is scoped to this store, established as part of creating, joining, or restoring it (see CovenHandle::initialize_identity).

pub fn cloudkit_ops(self, ops: Arc<dyn CloudKitOps>) -> Self

pub fn apply_cloudkit_ops(self, ops: Option<Arc<dyn CloudKitOps>>) -> Self

pub fn observer(self, observer: Arc<dyn BlobTransitionObserver>) -> Self

pub fn open(self) -> CovenResult<CovenHandle>

Open the store, returning the CovenHandle.

Opening performs no keyring interaction: it opens the database, runs migrations, and resolves the master-key custody selection to a value (constructing the trait object, never calling its unlock) — a locked agent (no OS keyring session, no established master key or device identity) can open() a store and use it fully for rows and Local blobs. The first read of any key happens lazily, at the specific call that needs it (CovenHandle::connect_sync, CovenHandle::master_key_fingerprint, and similar).

pub fn open_read_only(self) -> CovenResult<CovenReadHandle>

Open the store read-only for a same-store secondary reader: a separate process (or a second handle) that must read rows and blobs while another handle holds the full open. Returns a [CovenReadHandle], whose surface is reads only — SQL queries and blob reads — with no write, sync, migration, or stamp API by construction.

Unlike open this takes no store lock (see [StoreOpenGuard]): it succeeds while a writer holds the exclusive lock, and any number of read-only opens coexist. It opens a SQLITE_OPEN_READONLY connection against the schema on disk, running no migration ladder — but it refuses a db a newer binary migrated past what this binary supports (CovenError::Migration with [MigrationError::SchemaTooNew]), the same policy the writer enforces. It runs no orphan-temp cleanup either (that is a write the lock-holding writer owns).

Cross-process reads are safe because the writer opens the db in WAL mode; a blob read that misses locally fetches from the cloud into the per-device cache (files written atomically), which is device scratch and touches no synced state.