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§

AccessKeyUsed
What using a new S3 key did (E9, §14.3).
AddDevice
A pairing add_device made: what the screen that adds a device shows.
AddDeviceId
A pairing’s UUID, which names its request’s path in an invite’s place (§13.2, format.md D10).
AddDeviceRequest
A checked pairing request, as AddDeviceStatus shows it (§13.2).
BothAccesses
MemberAccess::from_columns returns this error when a row holds both an account and an S3 key id: a member’s access holds only one of them.
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 every code kind.
ColumnChange
One column of a change, retaining its original parent generations privately.
CommitSql
App SQL inside the app’s before-commit function: it reads any table app SQL reads, the transaction’s changes included, and writes device-local tables only. A statement that would write a synced table, itself or through a trigger or foreign-key action, fails with SyncedTableBeforeCommit. Returning an error rolls back the transaction the function runs in.
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.
FileBudget
The installation’s places for open files, shared by every store its app opens. Cloning shares them. The app makes one when it starts, and each piece of work takes a lease of places from it (E1).
FileBudgetWatch
What a test reads of a budget: the places its leases hold, the places holding an open file or stream, and the waits for the budget. Cloning shares the reading.
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 identity, independent of its content and of where its bytes are stored (§17.2). coven takes it from the id source when the app stages the file, or when a write moves a row that names a file to another audience and gives it a new file there.
FileLease
Places taken from a budget in one wait, for one piece of work. The work’s openers share it by cloning it. The places go back to the budget once the lease, every place taken from it and every file opened in one are gone.
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.
Joining
The facts of a member’s latest admission, or of slot 1 for the store’s creator, which the joining write reads (§10.3, §13.2).
JoiningWrite
App SQL inside a joining write: the statements of a local write and nothing of coven’s steps, so no operation, file or journal can be reached from it. Returning an error rolls back the write and the registration it runs with.
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.
LeasePlace
One place of a lease, taken for one open: a file of a user, or a stream whose bytes come from no such file. It goes back to its lease when it drops.
LeaseTooLarge
A lease asked for more places than the budget has, so no wait could grant it.
LeasedFile
An open file holding its place. The file closes before the place goes back.
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).
LostCell
One retained value and the write that set it.
LostValue
One durable lost cell or removed row.
MemberId
A member’s identity, independent of their keys, which never changes (§10). coven takes it from the id source when the first device creates the store or an admin makes the invite that admits the member. 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.
MemberWrite
The app’s SQL as a member begins, in one write with the membership. The creator’s first write runs on it, inside create_store, after slot 1 has registered the creator and their device and made the circles the app asked for, and before the store is visible (§10.3). It offers the app’s SQL only: no operation, file or administrative step exists on it, so what it commits is the member’s own rows and nothing in the store’s membership.
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 id, the last part of its path <store>/files/<uploader>/<object> (§17.5). coven takes it from the id source when a write queues the upload of bytes this device holds.
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.
PairingInfo
What a pairing code tells before connecting (§13.2).
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: what it is doing, 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.
RecordedInvite
An invite a test records outside a store, as make_invite journals one and later steps advance it (api.md E4): its id, the member it fixes, and its stage.
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 sqlive opens to a 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 sqlive turns on, and auto_vacuum, which is Incremental. sqlive applies them as each connection opens, before any of its own statements.
SqliteSettingsInEffect
The SQLite settings one connection to a database has in effect, as SQLite reports them. Every connection has the same, except that a writable handle’s writer and statistics connection never checkpoint as they commit.
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.
StatementLog
The statements that reads ran on the connections this log was given to, in order, from when each connection got it. Clones share one log.
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 coven_sync_state shows them and sync_status() reads them.
SyncedTable
A synced table’s key, audience, file references, shared triggers and who may change its rows 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.
UnknownName
Text that names none of a type’s values.
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§

AddDeviceEnd
How a pairing ended (§13.2).
AddDeviceStatus
Where a pairing is (§13.2). The app offers approving and declining only for a request that is Waiting, and ends the pairing when its screen closes, whatever its status.
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.
ChangeOutcome
How an admin change an app’s write journaled ended, for the kinds RenameStore, SetRole, RemoveMember, RemoveDevice, RenameCircle, DeleteCircle, AddCircleMember, RemoveCircleMember and ApproveJoin (§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.
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 three 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).
CovenSchemaError
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).
FreshChangeOutcome
How an admin change an app’s write journaled ended, for the kinds CreateCircle and ReplaceMemberKeys, as coven_operations.outcome holds it (§11.4). Each names something no applied state holds yet, a new circle or a member’s new pair, so it is never satisfied: a state that already holds it refuses it (§12.3, §15.5).
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.
InviteAdmits
Who an invite code admits, fixed when the admin makes it (§13.2, §13.3): the byte the code carries. It decides which person a join request may name (objects::Joiner); the joining device reads it from the decoded code.
InviteLifetime
How long an invite stays open after it is made, by the inviting device’s clock (§13.2).
InviteOutcome
How an invite ended, the kind Invite, as coven_operations.outcome holds it (§11.4, §13.2): coven_operations lists an invite only once a sharing refusal ends it. Its approval’s binding is an operation of its own, of the kind ApproveJoin.
InviteStage
Where one of this device’s open invites is (§13.2).
Joiner
Who asks to join through an invite (§13.2): one of two, as the invite admits. A member’s own new device asks through an add-device pairing instead, which the format’s request can say and an invite never takes.
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.
ListedOutcome
An outcome as a write keeps it in coven_operations.outcome, in the outcome type of the kind the operation is listed under. The column holds the inner outcome, so each type reads its own kinds’ rows.
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.
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.
RecordedInviteStage
Where an invite a test records is, as coven_invites.stage names it.
RecordedJoiner
Who asks in the request of an invite a test records.
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.
Removal
Why a device is not in the store, and won’t be again (§13.2, §14.1).
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.
ResetReason
Why this installation can’t send under its keys or id, as NeedsReset names it (§19.3, §12.3).
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.
StorageSetupOutcome
How a storage setup ended, the kind StorageSetup, as coven_operations.outcome holds it (§11.4, §11.6).
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).
StoreChange
Every admin operation listed in §10, including store creation.
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.
SyncActivity
What Syncing is doing, as Syncing names it (§19.1): the first of what the running pass moved last, a bound file moving or next in line, a write next in line, and the next pass’s turn.
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. coven_sync_state.detail holds it as JSON, which this type reads.
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 bound file waiting in the upload queue, what holds that file, then a write’s own key (§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
What a queued upload is doing, bound and trailing alike: the sync state names bound files only, so what a trailing file waits for, and its failure, are shown here (§17.9, §19.1). Whether it is sending is persisted nowhere: a reopened store starts with every file waiting.
UploadWait
What a queued upload waits for, the first that holds (§17.9).
UseAccessKeyError
Why use_access_key failed (E9, §14.3). Before the call takes the key, each failure leaves everything as it was.
WalAutocheckpoint
When sqlive 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.
WritePermission
Who may change a synced table’s rows directly (§9.6, E2). Shared-trigger targets count as direct changes; an exact foreign-key action of an authorized change may still reach any row.
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.
copy_tree
Copy the tree at from into to, making to and every folder below it, as restoring a backup of an installation does.
decode_code_info
Decode and validate the complete code before returning public metadata.
decode_invite_info
What an invite code tells, read before any sign-in: the app signs in with its metadata.oauth_access, then calls join_with_invite. Refuses the code as that call would: WrongKind for a restore or pairing code, Invalid for one that doesn’t decode.
decode_pairing_info
What a pairing code tells, read before any sign-in: the app signs in with its metadata.oauth_access, then calls join_with_pairing. Refuses the code as that call would: WrongKind for a restore or invite code, Invalid for one that doesn’t decode.
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.
files_under
Every file in the tree at dir, at any depth, sorted by path. Folders are not listed. Panics on failure.
finish_operation
End the operation id, which the app’s write journaled, on connection as a store ends it with outcome: coven_operations lists the outcome until the app acknowledges it (§11.4). An outcome not in the outcome type of the operation’s kind fails with Invariant, as coven never writes one.
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. name is the name the new person typed when the invite admits a new person, and None when it admits a member’s new keys, as the invite’s InviteInfo::admits says; the other fails with CodeError::WrongJoiner before anything changes. circle_name names the circle the request makes for the person, which the admission creates with them as its only member (§13.2). Dropping the future before the join finds its admission preserves the unfinished join for a subsequent call with the same invite, device name, name and circle name, 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).
join_with_pairing
Ask one of the person’s devices, which shows code, to pair this device, and restore from what it hands over, returning the open store (None when the pairing ended before its handover opened). A restore’s rules hold from its record on; before it, cancelling through control, dropping or failing the call removes the installation, whether or not the request was sent, since approval binds nothing in history (§13.2).
make_readable_objects
Make on connection, a connection an app’s test opened itself outside any store, every object of coven’s that app SQL may read, and register coven’s SQL functions there, with device as this device’s id, as coven_database::test_utils::make_readable_objects says. The sync state function is sync’s own, as every store registers it.
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.
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. The read holds one place of lease until it ends (§17.3).
record_change
Journal change on connection, where make_readable_objects made coven’s objects, as the app’s write journals it, so that coven_operations lists it as running. Returns its operation.
record_connected_storage
Record on connection, where make_readable_objects made coven’s objects, that location is the store’s storage and this device holds its credentials, as opening a connected store records it. Until a test does, coven_sync_state shows not synced, as for a store with no storage (§19.1).
record_invite
Journal invite on connection, where make_readable_objects made coven’s objects, as a store journals an invite at its stage, so that coven_invites shows it. Returns the invite’s operation.
record_last_pass
Save pass on connection, where make_readable_objects made coven’s objects, as how the last pass ended, as a store’s loop writes it when a pass ends, so that coven_sync_status.last_pass holds it and coven_sync_state computes its state from it beside the pending records the test saves with record_pending (§19.1).
record_pending
Save record on connection, where make_readable_objects made coven’s objects, as a store saves a pending record, so that coven_pending shows it (§19.1).
record_user_file
Record on connection, where make_readable_objects made coven’s objects, the original at path, last modified at modified_at and holding bytes, as file’s original on this device, as staging it for the cloud records it: its size, modification time, content hash and chunk hashes (§17.3). coven_user_files then lists it.
refuse_invite
End the invite invite on connection as a store ends one that the provider refused to share with account for refusal, a reason only a person can fix: coven_operations lists it as refused, and it leaves coven_invites (§13.2).
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.
restore_sign_in
The sign-in a restore of store in place from code needs, None on S3 and CloudKit, read before any sign-in: the app signs in with it, then calls CovenBuilder::restore_device. Refuses the code as that call would: WrongKind for an invite or pairing code, WrongStore for another store’s restore code, Invalid for one that doesn’t decode.
sqlite_error_is_disk
Whether SQLite failed because of the disk under it: full, failing, gone read-only, or damaged.
stored_time
The time a stored count of milliseconds since the Unix epoch names, as coven_retry_effect.cooling_until and coven_sync_status.last_synced hold it. One the clock can’t name is DamagedDatabase (§19.3).
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.