Skip to main content

Crate coven

Crate coven 

Source
Expand description

The application API for coven stores (api.md).

Declare tables and migrations on Coven::builder, then create or open the store. SQL, files, keys and their capabilities remain with the crates that own them. Opening resumes committed file work without starting a sync loop; unfinished operations resume once storage connects.

Modules§

task
Background work whose panic comes back as a TaskFailed (api.md E15). Work run apart from its caller — on the blocking pool, as its own task, or as one message of a long-lived loop — whose panic comes back to that caller as a value instead of an unwind (api.md E15).
types
Traits dealing with SQLite data types.

Macros§

named_params
A macro making it more convenient to pass lists of named parameters as a &[(&str, &dyn ToSql)].
params
A macro making it more convenient to pass longer lists of parameters as a &[&dyn ToSql].

Structs§

BulkSqlContext
App SQL inside one bulk write (§4): it changes device-local tables alone, and may read any table app SQL reads. Returning an error rolls back every statement. This borrowed context cannot change the transaction, access coven’s tables or write a synced one.
ByteRange
A nonempty half-open byte range; end must not exceed the object’s length.
ChangeSource
An original row change or direct execution target used as data (§9.5, §9.6).
Circle
A circle the local member belongs to (E12).
CircleId
A circle’s identity, independent of its name or current key (§15.5).
CircleKey
One circle’s identified 32-byte key, introduced by creation or rotation (§12.1). Cloning supplies an independent unlocked snapshot to in-memory custody.
CircleMemberInfo
An active store member in a circle (E12).
Circles
A borrowed namespace whose work remains owned by the open store. Making a circle and each change is its CovenWrite step in a write of its own, returning the operation’s id; a change returns None when the applied state already has what it asks for (§11.1). Lists read the committed state, as their subscriptions do.
ClosedSyncStatus
A closed store’s sync status, as Coven::closed_sync_status reads it (E1): the state opening shows before sync starts, and what deleting the store would lose. A queued write or file waits to sync with NotSyncing, as sync isn’t running; unsent counts them.
CodeMetadata
Store, member and provider facts shared by both code kinds.
ColumnChange
One column of a change, retaining its original parent generations privately.
ConfirmationNumber
Six digits naming a join request’s keys, which the requester’s device and the admin’s both compute (§13.2). It names only the keys and the invite: the invite secret adds nothing a stranger who saw the code lacks, and the device name is the requester’s free choice. Displays as 041 778.
ConnectedStorage
The configured location and the result of opening this device’s keys.
Coven
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.
CovenBuilder
The choices for creating or opening a store (E1).
CovenHandle
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.
CovenReadHandle
A handle that reads synced rows and maintains its local file cache (§4, E1). Its shared store lock prevents deletion until all its connections close. Its SQL may not read coven_sync_status: it can’t tell whether the writer that last wrote the row still runs (E5).
CovenWrite
One write’s SQL and coven’s steps, in one transaction (§4, E3). A step runs where it is called: the write’s later SQL sees what it changed, and it commits or rolls back with the app’s statements. A failed step fails the write, even if the closure goes on and returns success. Returning an error rolls back every statement and step.
DamagedObject
An object whose checks failed (§19.1).
DesktopOAuthPresenter
Desktop sign-in using the system browser and a loopback callback listener. Register http://localhost:19284/callback with each provider’s client.
DeviceId
One install of the app, by its 64-bit device id (§10).
DeviceInfo
One of a member’s device ids in the committed prefix (E9).
DeviceReset
A replacement of this installation, not a membership removal (E5).
EmptiedS3Bucket
What emptying an S3 bucket removed (api.md E14).
Faults
Faults applied to the next calls, including accepted parts with lost replies.
FileColumn
A column holding a file’s id, or NULL (§17.2, E2). It references the file as a foreign key references its parent.
FileId
A file record’s random identity, independent of its content and of where its bytes are stored (§17.2).
FileLocation
A stored file’s fixed location: the uploader, the stored object’s id and the file’s key. Equality compares the whole text, so another object or key is another location. Diagnostics never show the key.
FileLock
An OS lock on an open file, released when dropped. Separate opens of one file exclude each other, within a process and across processes.
FileName
A portable single filename: ASCII letters, digits, -, _ and interior dots, up to 255 bytes. Windows device names are refused on every platform.
FileRangeStream
A borrowed stream of bounded authenticated plaintext buffers.
FileRef
One file as its record stood when it was read.
FileStream
An open file. A file never changes its bytes, so nothing later changes what it reads. Its shared store lock prevents deletion until the stream and its I/O finish, including reads still running after the store closes or the caller cancels.
FixedClock
A clock that returns the instant supplied by a test until it is set again.
FolderLabel
A Dropbox shared folder’s or a OneDrive folder’s name and web address, as the member’s account named them at this device’s latest connection (§20.2). Display only: coven never reaches storage through them.
FunctionArguments
The arguments SQLite passes one call of an app function. Only the arguments: the connection running the statement stays coven’s.
GuidedAccessKey
What guided console steps need to make a member key by hand (§20.10).
Invite
One of this device’s open invites (§13.2).
InviteId
An invitation’s identity, independent of its one-time secret (§13.2).
InviteInfo
What an invite code tells before connecting: as typed or scanned, and as a join under way saved it (§13.2).
JoinControl
The app’s hold on a running join: cancel it, or ask it to check for approval often while the app shows the wait.
JoinRequest
A checked request, presented with the account from its local invitation.
KeyId
A store or circle key’s identity, named by the entry introducing it (§12.1).
KeychainError
A native keychain error whose diagnostic output never includes secret bytes. Its original typed cause remains available through std::error::Error.
LiveQuery
A subscription’s results and lifetime; dropping it ends future runs. Its results fail with E, the query closure’s own error type.
LiveQueryClosed
The query was dropped before its request could be replaced.
LiveQueryRequests
Shared access to replacing a live query’s request.
LiveQueryRevision
A request revision assigned by one live query.
LiveQueryRuns
How often a live query had run when asked, for tests and benchmarks that measure how many of its runs writes caused, and how many found nothing new.
LocalBytes
What a store keeps on this device, in bytes on disk (§17.8, §19.3).
LocalBytesWatch
The measurements of what the store keeps on this device, as they change.
LostCell
One retained value and the write that set it.
LostValue
One durable lost cell or removed row.
MemberId
A member’s random stable identity, independent of their keys (§10). Device ownership, circle membership and slot authors name it; a key replacement keeps it.
MemberIdentity
This device’s member: the stable id and every private pair it holds (E1, E11). Identity custody keeps it; the id never derives from the keys. The active pair is the one the last installed binding made current. A self-replacement keeps its candidate here before publishing it, and every pair a kept replacement retired stays held, because copies name the exact credential they open with (§12.1). Which pair may sign is replay’s decision, never this record’s (§12.3).
MemberInfo
A live member and every device they registered (E9).
MemberKeys
A member’s Ed25519 signing pair and independent X25519 sealing pair (Appendix D). Both secrets erase on drop. Clone is needed by in-memory custody to keep its keys while returning an independently owned unlocked pair.
MemberPublicKeys
A member’s public signing and sealing keys, independent of their stable MemberId (§10, D2). Creation, addition and replacement bind a pair to an id.
MemoryProvider
In-memory native calls used beneath the shared storage connection.
MemoryStorageBuilder
Shared storage fixture choices; production providers do not use these defaults.
Migration
One numbered change to the app’s database, with its declared kind. Clones retain the same callbacks across bootstrap and database opening.
MigrationContext
App SQL inside the transaction owned by the migration run. The context borrows its owner and cannot change the transaction or connection.
MoveId
One move’s identity on this device, never reused (§17.3, E3).
Namespace
A kind of file with its cache budget, declared when the store opens (§17.1, §17.8, E1).
NamespaceBytes
One namespace’s cache, in bytes on disk.
OAuthClients
The app’s OAuth client ids (E10).
OAuthRedirectError
The original checked error callback. Diagnostics show only its error code (RFC 6749 §4.1.2.1), such as server_error: the callback’s other fields may contain secrets echoed by the provider.
ObjectId
A stored object’s random id, the last part of its path <store>/files/<uploader>/<object> (§17.5).
ObjectPath
One validated encrypted-object path in the layout of §§5, 10, 12, 13, 16 and 17.
ObjectPrefix
A prefix of the validated object layout, used for provider listing.
OperationId
The local, never reused identity of an operation.
Passphrase
A memorized secret that protects custody with Argon2id (E1).
PathBytesError
Bytes that path_bytes never gives on this operating system, so no path here: on Windows, bytes that aren’t WTF-8. Unix takes any bytes.
PathError
A path is outside the canonical object layout.
PendingRecord
One local first unmet condition, identified by its subject (§19.1, E5).
PinProgress
Verified cache coverage of requested files (§17.8, E8).
PollingClock
A fixed clock whose waits end only as its time reaches them. A backoff or cooldown the code waits out passes as the code arms it: this clock moves the fixed clock to the wait’s end, as the wait’s passing would, so retries run without real time and their timestamps are the waits the code chose. A deadline, which work races, and the idle interval end only when the test moves the clock, as does every wait once hold_waits is set. It records each wait_out it is given.
PreparedDeviceOnly
Cloud files downloaded to copies in the person’s folder, ready for one write to make them device-only here (§17.3, E8). It holds nothing close waits for. Committed by no write, its copies stay reserved while it is held, and the next write or open removes them once it drops; abandon removes them at once.
PreparedPin
Files ready to pin in one write (§17.8). It holds nothing close waits for. Dropped uncommitted, or after the store closes, its copies’ names go free, and the next write or open removes their bytes.
PreparedUserFile
An original read whole once before entering a write: its path, size and modification time, and the content hash and chunk hashes of the bytes that read found, which coven records and checks the original against.
Progress
How far an operation has come: the step it is on, and how many of that step’s units are done out of its total. Each step names its unit. Steps arrive in the order the operation runs them, and within a step done only grows and never passes total, which never shrinks.
ProviderResponse
The original error response. Its body is never printed; providers may echo secrets.
QueuedUpload
One queued upload: whether it is being sent, and its committed progress.
Read
A read that starts when polled and retains its store borrow until it ends, on the store’s writer or a read-only handle.
ReadProgress
Where a read that fetches from storage tells how much of its range is here: the count of the range’s bytes in hand, cached or received, each time it grows while the read fetches. A read this device serves alone, from its own copy or the cache, tells it nothing (§17.7).
ReconfigurableLiveQuery
A subscription whose request may be replaced while it runs. Its results fail with E, the query closure’s own error type.
ReconfigurableLiveQueryEvent
One result with the exact request and revision that produced it.
RelativePath
A path below a folder, as the names the app gives, outermost first: an album’s name, then a track’s. Each name is one name on every platform, whatever it holds, / and \ included. Coven writes each through one rule that makes it valid on any volume (§17.3), so joined to the folder the path stays inside it.
RetainedAccess
A grant that revocation left for the owner to inspect.
RetryAnswer
Resolves when the first sync pass after a retry request ends (E5). Dropping it leaves the retry in place.
Row
A single result row of a query.
RowChange
One row change of a waiting write (E13).
RowKey
The primary-key values of a row, in the table’s declared key order (api.md).
S3Credentials
This member’s S3 credentials, made by an admin in the provider console (§20.10).
S3Detection
What detection observed at one location (§20.7).
S3ProbeResult
One probe’s outcome.
S3Settings
Every S3 behavior the adapter varies, one value each (§20.7).
SavedRestoreCode
A store whose restore code is saved in iCloud Keychain or Block Store, without secrets.
SealingKey
The public half of a member’s X25519 pair, used for anonymous sealed keys. A copy names the exact sealing key it is sealed to (D9).
SecretBytes
Secret bytes for custody or a restore code, erased on drop and never printed. Callers retaining a copy are responsible for erasing that copy too.
SecretText
UTF-8 secret text, erased on drop and redacted in diagnostic output. Callers retaining a copy are responsible for erasing that copy too.
SequentialIds
A deterministic sequence of UUIDs and device ids, starting at one.
SigningKey
A member’s validated Ed25519 public signing key (Appendix D). It is bound to a stable MemberId by admin entries and is never that identity.
Slot
A positive position in the store’s shared sequence (§5). Slot 0 names nothing: a prefix applied through 0 has applied no slot, and that count stays a plain u64.
SnapshotId
A snapshot’s identity without a storage path (§16.2).
SqlReadContext
SQL access to one read-only snapshot. The connection and internal tables remain private; even SQL with RETURNING cannot write through this context.
SqliteSettings
SQLite settings for every connection coven opens to the store’s database: the writer and the readers of a writable handle, and every connection of a read-only one. A setting left None keeps SQLite’s own default, except checkpoint_fullfsync on macOS and iOS, which coven turns on, and auto_vacuum, which is Incremental. Coven applies them as each connection opens, before any of its own statements.
SqliteSettingsInEffect
The SQLite settings one connection to the store’s database has in effect, as SQLite reports them. Every connection has the same, except that a writable handle’s writer never checkpoints as it commits.
StagedFiles
App bytes stage_files wrote to coven’s copies of them, under names reserved in this store, with what its batch returned, until a write puts them in rows (§17.2). It holds nothing close waits for. Dropped uncommitted, or after the store closes, its names go free, and the next write or open removes the bytes.
StorageFolder
A provider folder’s display name and the exact location accepted by setup.
StorageSetup
Storage setup’s committed connection and this member’s restore code.
StorageTime
A provider storage time: Unix seconds and a nanosecond fraction (§20.5). It keeps every returned digit on every platform, unlike SystemTime, which counts 100 ns on Windows; ordering is time order.
StoreDir
One store’s directory, owning the paths to its database, app-provided files, cache, settings and sibling locks. It never exposes the directory as a raw path.
StoreId
A store’s identity, independent of its name and location on disk.
StoreInfo
A store on this device (E1).
StoreKey
A store’s identified 32-byte key (§12), erased on drop. Cloning supplies an independent unlocked snapshot to in-memory custody.
StoreKeyring
Every store and circle key this device has opened, including older keys (§12.2). Cloning lets in-memory custody keep its copy while returning an unlocked one.
StoredObject
Metadata of an object returned by a provider read, exact status or listing.
SyncOftenGuard
An app’s request for idle passes at most its interval apart. The request lasts until the guard drops; the shortest interval held wins.
SyncStatus
What a status screen shows (E5, §19.1): the sync state and when sync last finished, as sync_status() reads it and the handle’s live query follows it.
SyncedTable
A synced table’s key, audience, file references, shared triggers and whether only each row’s original creator writes it directly (E2).
SystemClock
The system wall clock.
TestNetwork
A network a test drives in place of the platform’s (api.md E1 network): clones drive the same network.
TransferLimits
Limits shared by the open store’s transfer consumers (E5).
TransferProgress
How far one transfer has got: the bytes of its encrypted object handed to the connection or received, in whatever order, out of the object’s whole size. Known from the transfer’s start; never stored.
TransferWatch
Hears how far each file in flight one way has got. Changes that arrive faster than the reader reads are heard together: the next read names each file that differs from what the reader last heard, and how each one it heard in flight ended.
UnsentWork
What this device committed and has not uploaded: writes and files (E1).
UploadProgress
Bytes the provider confirmed in a recorded upload session. Sending bytes alone does not advance it.
UploadQueue
Observable upload queue state (E7): one committed snapshot of the queue, with the uploads this process is sending as it is read.
UploadSettings
The writer’s copies of the upload settings, and the connections its upload runs’ attempts use.
UserFile
The facts recorded for the user’s original, which coven never changes.
UuidIds
Random UUIDv4 ids, independent of the clock (E1).
UuidText
Bind or read a UUID as canonical lowercase hyphenated SQL text. Rusqlite’s uuid feature binds a bare UUID as a BLOB instead.
WorkCounter
Injected counter; clones observe the same database, never other test databases.
WorkCounts
Local database work observed at its execution boundaries.
WriteBatch
App bytes to stage, before the write that puts them in rows; a failure discards all of them. Each staged file gets a new id from the store’s id source, which the batch borrows while the app stages; the write’s SQL puts the id in the rows that reference the file.
WriteId
One device’s numbered write (§4).

Enums§

AnalysisLimit
How many rows of each index ANALYZE reads.
Audience
Every synced row reaches the store or one circle (§15).
AutoVacuum
What happens to the pages deleted content frees.
Binding
When a write setting a file reference goes out (§17.4, E2).
BodyFailure
Failures after response metadata has arrived.
BootstrapDirectoryError
Filesystem failures while reserving, publishing or cancelling a new device.
BootstrapError
Opening a new installation failed. A join’s unpublished work, and a recorded restore’s, remain for an explicit retry unless the call was cancelled or the invite was settled; a restore before its record removes its own.
BootstrapStatus
Bootstrap progress (E10), before an open handle exists.
CacheSize
A page cache’s size, which SQLite counts in pages or in kibibytes.
CacheSpill
Whether a transaction may spill changed pages before it commits.
ChangeOp
The operation a waiting write performs on a row.
CheckpointMode
SQLite’s checkpoint modes (PRAGMA wal_checkpoint).
ChecksumValue
The algorithm and native encoding of a provider checksum.
CloudProvider
A provider supported by coven (§20.2).
CodeError
A malformed code or one intended for the other operation.
CodeInfo
Code metadata safe for presentation before opening the store.
CodeKind
The two codes that can open a store on a new device.
CopyPathError
Why a copy can’t go where the app named.
CovenError
Failures of opening, reading and writing a store (§4, E1, E3).
CovenMigrationError
Coven’s local tables cannot be used at this version (Appendix C.1, E1).
CryptoError
A cryptographic operation could not produce or authenticate its result.
CustodyChoice
Where this device keeps T (E1).
CutOffRefusal
Why confirm_device_cut_off refused (§14.2, §20.9). Each is a reason the call can’t change anything; the app tells the person which one.
DbError
A failed database call or a write the database refuses (§4, §9, §15, §17).
Determinism
Whether a scalar function’s result depends on its arguments alone.
DeviceIdEvidence
Authenticated evidence that another installation uses this device id.
DeviceOnlyError
Why no file of a call was made device-only (E8). Whatever the call made is removed before it returns, or, if removing it failed too, at the next open.
DeviceOnlyStep
A step of preparing files to be made device-only (§17.3, E8), which a host draws a bar for: one step for each file downloaded, in order. Done and total count the file’s bytes; done plus before, out of all, is how far the whole call has come.
DeviceState
What counted administrative slots did to a device id (E9). Later slots from a removed or replaced device are refused (§14.1, D6).
DeviceStop
Why a device stopped for good (§14.1, §19.3).
DirectoryCreationError
A store creation failure, with publication and rollback failures explicit.
DrainOutcome
Result of an app retry (retry_uploads_now), or of one upload run. Individual failures stay in pending().
DropboxAccess
Dropbox fixes this access level on the app registration (§20.2).
DropboxClients
The app’s Dropbox registrations, with an explicit access choice when both exist.
DropboxLocation
Dropbox’s permanent creation choice, retained in settings and restore codes.
EmptyS3BucketError
Why an S3 bucket was not emptied (api.md E14).
EntryTarget
The target a proposed change can no longer affect.
FileError
A file operation’s cause, including whether replacement already happened.
FileMissingReason
Why a file can’t be read (§17.6).
FileNameError
A name that could escape its directory or alias a Windows device.
FilePlace
Where a file is (§17.2): in storage, or only on one device.
FileReadError
Reading a file failed with a cause the app can distinguish (E8).
FileSource
An owned buffer or a reader whose stream coven consumes exactly once.
FileSourceFailure
The staging device cannot supply the file’s original bytes.
FileStatus
A file’s current availability (E8).
IdentityError
Initializing this device’s member identity failed (E11).
IfUnsent
What delete_store does with writes and files not yet uploaded.
IncrementalVacuum
How many free pages an incremental vacuum gives back.
InviteAccess
How the invited person reaches the store’s provider.
InviteKind
What an invite is for, fixed when the admin makes it (§13.2, §13.3). It decides which person a join request may name (objects::Joiner).
InviteLifetime
How long an invite stays open after it is made, by the inviting device’s clock (§13.2).
InviteStage
Where one of this device’s open invites is (§13.2).
InviteTarget
The admin’s choice, fixed before the invite is shown (§13.2, §13.3).
Joiner
Who a join request is for (§13.2). The invite’s kind fixes which a request may carry.
JournalSizeLimit
How large the WAL file may stay after a checkpoint resets it.
KeyError
A failure unlocking, keeping or forgetting keys or host secrets (E11).
LastPass
How the last pass that reached storage, or failed trying, ended (E5), as coven_sync_status.last_pass holds it. It outlives each connection: opening keeps it, and the running loop writes it as each pass ends. An error is kept as its text, which names every cause below it with secrets and URLs already cut, so a pass read after the process that ran it ended still says why.
ListedStore
A store on this device as the listing found it (E1).
LiveQueryCause
Why this run was requested; the first run answers the initial request.
LoadStep
A step of loading a store from storage (§13.4), in the order they run. A step runs only when it has work to do.
LocalFailure
A local invariant or resource failure; immediate calls retain the native cause.
LockMode
Whether other holders may share the lock.
Lost
Values retained when a cell loses or a row is removed.
MaterialError
A key or serialized secret violates its representation.
MemberAccess
An account to share with, or the id of a member’s S3 key.
MemberRole
A member’s role in the store (§10).
MemoryRequest
Each attempted native call in the in-memory provider, before fault injection. This provider has one page per listing and no implicit metadata lookups.
MergeError
Invalid input to the pure merge; no partially changed state is returned.
MigrationError
The application migration run could not complete.
MoveFile
A file of this device, on it only, to move to the cloud (§17.3, E3).
NetworkWatchError
The platform refused to let coven watch the device’s network (api.md E1, E5), such as an Android app without coven’s Android library.
OAuthAccess
The access requested by one sign-in and retained with its credentials.
OAuthError
Sign-in failures distinguish cancellation, invalid redirects and provider refusal.
ObjectChecksum
Full-content checksums and multipart composites have different comparison rules.
OldWrites
What a breaking migration does with received late old-version writes.
OpenStep
A step of opening a store for writing (§4), in the order they run. A step runs only when it has work to do, so most opens report none.
OperationKind
The purpose of an unfinished operation, including maintenance.
OperationOutcome
How an operation an app’s write journaled ended (§11.4): coven_operations.outcome holds it from the transaction that ends the operation’s journal row until a write acknowledges it, so an outcome nobody awaited is still there to read.
OperationRejection
Why the current applied state refuses an administrative operation.
PageSize
A database page size: a power of two from 512 bytes to 64 KiB.
PassFailure
Why a pass, or the connection attempt that begins one, failed: how it ended (LastPass, E5).
PendingReason
A typed current condition, never an error’s display string.
PendingSubject
Stable identities of work, independent of attempts and wall-clock time.
Place
Where a staged file is to be: on this device only, or uploaded to the cloud (§17.3).
Prerequisite
A fact required before processing can continue.
Provenance
A namespace’s kind: whose bytes its files are (§17.1).
ProviderAccessAction
The provider’s intended sharing change.
ProviderSignOut
How a removed device’s member cuts off its provider access (§14.2, E9).
ReadOnly
A read-only handle: it reads synced rows and keeps its own file cache, and nothing else (E1).
ReadOnlyOpenError
Opening a read-only store or its saved file-storage connection failed.
Refusal
One vocabulary for refused objects. Native causes survive immediate calls; persisted records retain only the variant. Equality ignores causes.
RelativePathError
Why names can’t be a RelativePath.
RemovalRule
A rule responsible for a removed row.
ReplacedBy
The call that began a replacement, and so the only call that finishes it (§19.3). The other call would load under different keys, or keep or remove a different copy, so it is refused before anything changes.
Replacement
The write, rules, breaking schema version, dropped data or refused permission responsible for a loss.
RequiredUpdate
The software version required to decode or apply an input from storage: the app schema its writes use, or the object format it is encoded in. Sync, setup and unlock all report it, so it lives with the formats.
RetainedAccessReason
The provider’s reason that a grant was retained.
Retry
What can permit another attempt; no attempt count determines it.
RetryEffect
What the person’s retry would do if made now (E5), as coven_retry_effect holds it: run a pass, or be answered at once without one. An app offers a retry only while it is Pass; the status says why it is not.
RetryOutcome
What the first sync pass after the person’s retry came to (E5).
RowAuthorizationFailure
Why a member’s row change was refused (§9.6).
RowIdentity
How independently inserted rows choose their identity (§9.2).
S3BucketVersioning
The bucket’s versioning state, read through the service’s XML API (§20.7).
S3Checksums
How returned checksums are read.
S3CopyCondition
The destination condition on a publishing copy.
S3CopyPublication
Which publications proceed by a conditional copy of a reserved temporary (§20.6).
S3Listing
The listing protocol.
S3MultipartTimestamp
What a native multipart object’s Last-Modified dates.
S3Probe
A behavior detection probes.
S3Profile
An S3 location’s behaviors: a catalogued service’s, or its own.
S3ProfileName
An S3 service whose catalogued profile a location names (§20.7). Self-hosted services have arbitrary endpoints, so no hostname identifies them.
S3ResponseHeaders
Which response headers carry metadata, generation and hashes.
S3Revision
Where a replaceable object’s revision comes from.
S3Signing
Request authentication.
S3SinglePut
The create-once condition on a single PUT.
SavedRestoreEntry
One store’s saved entry, as listing found it (§13.1).
SchemaError
A schema rule checked on open and after migrating (§9, §15.1).
SecureDelete
Whether deleted content is overwritten.
SettingsError
Missing, damaged or unreadable store settings remain distinct errors.
SetupCancellation
What cancelling storage setup did (E5).
SharingRefusal
Why the provider refused to share the store, in a way only a person can fix: the invited address’s side or the inviting account’s. Retrying is refused the same way until an address or an account changes.
SnapshotError
Snapshots or their gap writes could not be loaded into this database.
SqliteError
Enum listing possible errors from rusqlite.
StatusFailure
What stopped a pass as a whole, as LastPass keeps it: a SyncFailure without the error objects, whose text it holds beside it (E5).
StorageCheck
The provider operation checked before setup commits anything (E5).
StorageCheckError
A provider or S3 settings check refused the location (§20.7, §20.8).
StorageConfig
The store’s location; credentials are kept separately in key custody.
StorageError
A storage error preserves its cause without converting it into text.
StorageFailure
Failures the app can distinguish and act on (Appendix F.5).
StorageSetupError
A failed setup commits no local storage settings or credentials.
StorageSetupStep
A step of setting up storage, in the order they run. Which steps run depends on the provider and on whether setup creates the store. A step other than Loading is one unit, done when it ends. Setup can be cancelled until CreatingStore or RecordingAccess begins, its point of no return (§11.6).
StoreCreationError
Creating a store failed, with publication and rollback made explicit (E1).
StoreDeletionError
Deleting the local store stopped at a step the caller may retry (E1).
StoreKeyState
Whether this device’s custody holds opened store keys.
StoreKeyUnlockError
Opening this member’s sealed store keys failed.
StoreListError
A failure listing the stores. A store that can’t be read is not one: it is listed as ListedStore::Unreadable.
StoreLockError
A store in use is distinct from a filesystem failure.
SyncCause
What names a state: the last pass, or the first pending record, in the order they arose, that names it, with the cause coven_pending keeps.
SyncError
A synchronization request failed; its durable queue, if any, remains retryable.
SyncFailure
A sync step stopped as a whole (E5).
SyncState
The sync state (§19.1). With several candidates, the first of Removed, NeedsReset, UpdateNeeded, SignedOut, NoAccess, FolderMissing, ClockWrong, StorageFull, OfflineWithUnsentChanges, Offline, Failed, Syncing, WaitingToSync, Synced shows; NotSynced comes before them all.
SyncWait
What waiting to sync waits for, as WaitingToSync names it: what holds every transfer, the pass’s and each file’s alike, first; then, for a file waiting in the upload queue, what holds that file (§19.1).
TempStore
Where temporary tables and indices are kept.
TemporaryDirectoryError
Why the folder for temporary tables could not be named (E1).
TransferChange
A change to one file’s progress, or every file’s.
TransferEnd
How a file’s transfer ended, decided in the step that takes it out of the files in flight. When two attempts move one file at once, the last to end says it.
UndoCause
Why an operation was undone (§11.6).
Unfinished
Work on a store that must finish before it opens (E1).
UnreadableSavedCode
Why a saved entry can’t be restored from. Listing shows it, with its store id, so the person can forget it (§13.1).
UploadPhase
Whether a queued file is being sent. Nothing about it is persisted: a reopened store starts with every file waiting.
WalAutocheckpoint
When coven checkpoints the WAL by itself.
WalCheckpoint
What a checkpoint did, as SQLite reports it.
WallTimerError
A clock couldn’t wait for a wall-clock time (§13.2): the system refused its timer, or the clock has none.
WriteCutoff
Why a lower slot permanently excludes an original write.
WriteWait
A prerequisite for applying a downloaded write.
Writer
The store’s one writer: it writes, migrates, transfers files and keeps their records (§4).

Constants§

BOUND_FILE_LIMIT
The size limit of a bound reference that declares none: 1.5 MiB (§17.4).
CHUNK_SIZE
Plaintext bytes in a full file, write-part or snapshot chunk.

Traits§

Clock
The wall clock that timestamps use (§7.2).
Custody
The app’s own store for key material this device holds (E1).
FilesMode
What a handle’s mode adds to its file owner: the writer’s upload settings, which the upload runs and the app’s setting changes use, and nothing for a read-only handle, which runs no upload. Sealed with Mode.
IdSource
The source of new ids, supplied when creating or opening a store.
KeyMaterial
What custody keeps: the store keys or the member’s identity. Sealed: coven alone says how each is named and encoded.
Mode
The mode a store’s handle opened in: Writer or ReadOnly.
OAuthPresenter
Presents sign-in without handling tokens. The platform sheet must be dismissed when its future is dropped. Native cancellation returns OAuthError::Cancelled.
Params
Trait used for sets of parameter passed into SQL statements/queries.
SqlRead
Ordinary SQL reads through a read context or a write’s, so code that reads the same way inside a write and outside one is written once. Inside a write it sees the write’s own changes.
Storage
The operations coven needs from a provider (§20.1).
StorageConnector
Constructs provider connections without committing settings or credentials. Tests replace the connection boundary with in-memory storage.
ToSql
A trait for types that can be converted into SQLite values. Returns crate::Error::ToSqlConversionFailure if the conversion fails.
WriteFailure
A caller’s write error can retain both its original cause and failures that happen while rolling back or removing bytes, and says which bug it carries, for a write whose caller stopped waiting (E15). A write fails with its closure’s own error type, which implements this: DbError for ordinary database clients, sync’s error for sync’s writes, and an app’s own type for the app’s writes through the facade (E3).

Functions§

assert_no_open_files_under
Panic naming every file under dir this process has open.
decode_code_info
Decode and validate the complete code before returning public metadata.
empty_s3_bucket
Delete every object and abort every unfinished upload in an S3 location’s bucket, whatever wrote them, and return how many of each went (E14). A bucket whose root holds anything but stores’ folders and the location marker is refused with EmptyS3BucketError::OtherFiles before anything is removed. The first failure stops it; calling again finishes. Retained versions in a versioned bucket stay. It uses the app’s clock and ids, the ones given to CovenBuilder::clock and CovenBuilder::id_source, and makes none of its own.
followed_tables_sql
The SQL that makes each table the app’s local triggers may follow, as every store makes it, coven_sync_status and coven_retry_effect with their one row. An app’s test that runs its own schema on a connection it opened itself, outside any store, runs these first, so its triggers on them apply and fire as in a store. Nothing of coven’s writes the tables there: the test writes the rows coven would.
join_with_invite
Accept provider access, retain one signed request across restarts, and wait for approval. Returns the open store, or None when declined or expired. joiner is the new person with the name they typed, or a recovery, as the invite’s InviteInfo::kind says; the other kind fails with CodeError::WrongJoiner before anything changes. Dropping the future before the join finds its admission preserves the unfinished join for a subsequent call with the same invite, device name and person, or resume_join. On Dropbox and OneDrive the builder’s sign-in is kept on the device beside the saved code until the join ends, and a later call without one uses it (§13.2). control cancels the join or asks for a check for approval at once. Cancelling before the request may have been sent removes the unpublished installation; after, the call ends with BootstrapError::JoinRequestSent and keeps it, as dropping does. Once the join finds its admission it publishes the store, a cancel notwithstanding, then loads it, reporting Loading; a failure while it loads returns BootstrapError::Published with the open handle (§13.2). A store whose unfinished installation holds a restore’s record is refused with StoreLockError::BootstrapPending before anything changes (§13.4).
open_files_under
Every file under dir this process has open, once per open descriptor or handle. Directories are not files: a handle on one, the kind resolving a path takes for a moment on Windows, holds no file open. Panics if the directory cannot be resolved or enumeration fails. Descriptors closed while being inspected may disappear from the result.
path_bytes
The path’s bytes as coven records them. On Unix they are the path’s own bytes. On Windows they are its UTF-16 units in WTF-8: UTF-8, with each unpaired surrogate written as the three bytes UTF-8 would give its code point. Rust’s OsStr::as_encoded_bytes holds the same bytes today, but its encoding is unspecified and not to be stored, so coven writes them itself. A path that is valid Unicode is its UTF-8 on every platform.
path_from_bytes
The path path_bytes recorded. Bytes it never gives fail with PathBytesError: on Windows, bytes that aren’t WTF-8, such as Latin-1 from a Linux device. On Unix any bytes are a path.
path_text
The text that shows path: path_bytes_text of its bytes.
path_text_sql
What coven_path_text returns for its argument, for an app’s test that registers the function on a connection it opened itself, outside any store: the body every store registers.
prepare_user_file
Read a user’s original once, recording its whole-file hash and each upload chunk’s hash from the same bytes, and reporting total bytes read. Changes during the read are refused; later ones fail its upload, whether it is staged for the cloud or moved there later.
restore_from_code
Restore this person’s store on a new device, returning its open handle. S3 requires a key: the one the code carries, or one entered separately, never both. Other providers require None and use the builder’s own sign-in. Invalid key inputs fail before bootstrap begins. A store whose unfinished installation holds a join’s saved code is refused with StoreLockError::BootstrapPending before anything changes (§13.4). Until the restore records itself, a cancel or a failure removes the installation it loaded into (§13.1).
restore_from_saved_code
Restore a readable entry selected from saved_restore_codes. Reads the current code by store id, including a replacement saved since listing. Returns None if that store’s code is no longer saved. S3 uses the explicit key when supplied, otherwise its key saved beside the code. Missing keys, wrong-provider keys and keychain failures precede bootstrap.
sqlite_error_is_disk
Whether SQLite failed because of the disk under it: full, failing, gone read-only, or damaged.
unix_seconds_and_nanos
A time as coven_user_files lists a modification time, in modified_seconds and modified_nanos: whole seconds since the Unix epoch, rounded down, and the nanoseconds past that second, from 0 through 999,999,999 (§17.3). Half a second before the epoch is (-1, 500,000,000). An app compares a file’s time on disk with the view’s through it.
write_atomic
Write and sync a temporary sibling, atomically replace path, then sync its directory. The parent must exist. Concurrent readers see whole versions. A pre-replacement failure leaves the target unchanged; FileError::AfterReplace reports that new bytes are visible but directory syncing failed. Windows requires the POSIX replacement support described by AtomicFile::replace.

Type Aliases§

ClockRef
A shared wall clock, supplied when the store opens.
CovenResult
A store call’s result, retaining its typed cause.
IdSourceRef
A shared source of new ids.
MemoryStorage
Clones share a provider’s durable objects and sessions across simulated crashes. Publication is timestamped by the injected clock and retains the upload’s identity after pending parts are discarded. Faults can lose part/completion replies or expire pending sessions without losing published objects.
OperationError
An operation failure retains the same typed causes as an ordinary sync call.
SqliteResult
A typedef of the result returned by many methods.