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§
- Access
KeyUsed - What using a new S3 key did (E9, §14.3).
- AddDevice
- A pairing
add_devicemade: what the screen that adds a device shows. - AddDevice
Id - A pairing’s UUID, which names its request’s path in an invite’s place (§13.2, format.md D10).
- AddDevice
Request - A checked pairing request, as
AddDeviceStatusshows it (§13.2). - Both
Accesses MemberAccess::from_columnsreturns this error when a row holds both an account and an S3 key id: a member’s access holds only one of them.- Bulk
SqlContext - 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.
- Byte
Range - A nonempty half-open byte range; end must not exceed the object’s length.
- Change
Source - An original row change or direct execution target used as data (§9.5, §9.6).
- Circle
- A circle the local member belongs to (E12).
- Circle
Id - A circle’s identity, independent of its name or current key (§15.5).
- Circle
Key - One circle’s identified 32-byte key, introduced by creation or rotation (§12.1). Cloning supplies an independent unlocked snapshot to in-memory custody.
- Circle
Member Info - 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
CovenWritestep in a write of its own, returning the operation’s id; a change returnsNonewhen the applied state already has what it asks for (§11.1). Lists read the committed state, as their subscriptions do. - Closed
Sync Status - A closed store’s sync status, as
Coven::closed_sync_statusreads it (E1): the state opening shows before sync starts, and what deleting the store would lose. A queued write or file waits to sync withNotSyncing, as sync isn’t running;unsentcounts them. - Code
Metadata - Store, member and provider facts shared by every code kind.
- Column
Change - One column of a change, retaining its original parent generations privately.
- Commit
Sql - 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. - Confirmation
Number - 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. - Connected
Storage - 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.
- Coven
Builder - The choices for creating or opening a store (E1).
- Coven
Handle - 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. - Coven
Read Handle - 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). - Coven
Write - 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.
- Damaged
Object - An object whose checks failed (§19.1).
- DesktopO
Auth Presenter - Desktop sign-in using the system browser and a loopback callback listener.
Register
http://localhost:19284/callbackwith each provider’s client. - Device
Id - One install of the app, by its 64-bit device id (§10).
- Device
Info - One of a member’s device ids in the committed prefix (E9).
- Device
Reset - A replacement of this installation, not a membership removal (E5).
- Emptied
S3Bucket - What emptying an S3 bucket removed (api.md E14).
- Faults
- Faults applied to the next calls, including accepted parts with lost replies.
- File
Budget - 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).
- File
Budget Watch - 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.
- File
Column - 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.
- File
Lease - 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.
- File
Location - 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.
- File
Lock - An OS lock on an open file, released when dropped. Separate opens of one file exclude each other, within a process and across processes.
- File
Name - A portable single filename: ASCII letters, digits,
-,_and interior dots, up to 255 bytes. Windows device names are refused on every platform. - File
Range Stream - A borrowed stream of bounded authenticated plaintext buffers.
- FileRef
- One file as its record stood when it was read.
- File
Stream - 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.
- Fixed
Clock - A clock that returns the instant supplied by a test until it is set again.
- Folder
Label - 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.
- Function
Arguments - The arguments SQLite passes one call of an app function. Only the arguments: the connection running the statement stays coven’s.
- Guided
Access Key - What guided console steps need to make a member key by hand (§20.10).
- Invite
- One of this device’s open invites (§13.2).
- Invite
Id - An invitation’s identity, independent of its one-time secret (§13.2).
- Invite
Info - What an invite code tells before connecting: as typed or scanned, and as a join under way saved it (§13.2).
- Join
Control - The app’s hold on a running join: cancel it, or ask it to check for approval often while the app shows the wait.
- Join
Request - 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).
- Joining
Write - 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).
- Keychain
Error - A native keychain error whose diagnostic output never includes secret bytes.
Its original typed cause remains available through
std::error::Error. - Lease
Place - 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.
- Lease
TooLarge - A lease asked for more places than the budget has, so no wait could grant it.
- Leased
File - An open file holding its place. The file closes before the place goes back.
- Live
Query - A subscription’s results and lifetime; dropping it ends future runs. Its
results fail with
E, the query closure’s own error type. - Live
Query Closed - The query was dropped before its request could be replaced.
- Live
Query Requests - Shared access to replacing a live query’s request.
- Live
Query Revision - A request revision assigned by one live query.
- Live
Query Runs - 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.
- Local
Bytes - What a store keeps on this device, in bytes on disk (§17.8, §19.3).
- Lost
Cell - One retained value and the write that set it.
- Lost
Value - One durable lost cell or removed row.
- Member
Id - 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.
- Member
Identity - 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).
- Member
Info - A live member and every device they registered (E9).
- Member
Keys - 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.
- Member
Public Keys - 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. - Member
Write - 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. - Memory
Provider - In-memory native calls used beneath the shared storage connection.
- Memory
Storage Builder - 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.
- Migration
Context - 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).
- Namespace
Bytes - One namespace’s cache, in bytes on disk.
- OAuth
Clients - The app’s OAuth client ids (E10).
- OAuth
Redirect Error - The original checked error callback. Diagnostics show only its
errorcode (RFC 6749 §4.1.2.1), such asserver_error: the callback’s other fields may contain secrets echoed by the provider. - Object
Id - 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. - Object
Path - One validated encrypted-object path in the layout of §§5, 10, 12, 13, 16 and 17.
- Object
Prefix - A prefix of the validated object layout, used for provider listing.
- Operation
Id - The local, never reused identity of an operation.
- Pairing
Info - What a pairing code tells before connecting (§13.2).
- Passphrase
- A memorized secret that protects custody with Argon2id (E1).
- Path
Bytes Error - Bytes that
path_bytesnever gives on this operating system, so no path here: on Windows, bytes that aren’t WTF-8. Unix takes any bytes. - Path
Error - A path is outside the canonical object layout.
- Pending
Record - One local first unmet condition, identified by its subject (§19.1, E5).
- PinProgress
- Verified cache coverage of requested files (§17.8, E8).
- Polling
Clock - 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_waitsis set. It records eachwait_outit is given. - Prepared
Device Only - 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;
abandonremoves them at once. - Prepared
Pin - 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.
- Prepared
User File - 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
doneonly grows and never passestotal, which never shrinks. - Provider
Response - The original error response. Its body is never printed; providers may echo secrets.
- Queued
Upload - 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.
- Read
Progress - 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).
- Reconfigurable
Live Query - A subscription whose request may be replaced while it runs. Its results
fail with
E, the query closure’s own error type. - Reconfigurable
Live Query Event - One result with the exact request and revision that produced it.
- Recorded
Invite - An invite a test records outside a store, as
make_invitejournals one and later steps advance it (api.md E4): its id, the member it fixes, and its stage. - Relative
Path - 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. - Retained
Access - A grant that revocation left for the owner to inspect.
- Retry
Answer - 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).
- S3Probe
Result - One probe’s outcome.
- S3Settings
- Every S3 behavior the adapter varies, one value each (§20.7).
- Saved
Restore Code - A store whose restore code is saved in iCloud Keychain or Block Store, without secrets.
- Sealing
Key - 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).
- Secret
Bytes - 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.
- Secret
Text - UTF-8 secret text, erased on drop and redacted in diagnostic output. Callers retaining a copy are responsible for erasing that copy too.
- Sequential
Ids - A deterministic sequence of UUIDs and device ids, starting at one.
- Signing
Key - A member’s validated Ed25519 public signing key (Appendix D). It is bound to a
stable
MemberIdby 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. - Snapshot
Id - A snapshot’s identity without a storage path (§16.2).
- SqlRead
Context - SQL access to one read-only snapshot. The connection and internal tables remain private; even SQL with RETURNING cannot write through this context.
- Sqlite
Settings - 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
Nonekeeps SQLite’s own default, exceptcheckpoint_fullfsyncon macOS and iOS, which sqlive turns on, andauto_vacuum, which isIncremental. sqlive applies them as each connection opens, before any of its own statements. - Sqlite
Settings InEffect - 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.
- Staged
Files - App bytes
stage_fileswrote 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. - Statement
Log - 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.
- Storage
Folder - A provider folder’s display name and the exact location accepted by setup.
- Storage
Setup - Storage setup’s committed connection and this member’s restore code.
- Storage
Time - 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. - Store
Dir - 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.
- Store
Info - A store on this device (E1).
- Store
Key - A store’s identified 32-byte key (§12), erased on drop. Cloning supplies an independent unlocked snapshot to in-memory custody.
- Store
Keyring - 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.
- Stored
Object - Metadata of an object returned by a provider read, exact status or listing.
- Sync
Often Guard - An app’s request for idle passes at most its interval apart. The request lasts until the guard drops; the shortest interval held wins.
- Sync
Status - What a status screen shows (E5, §19.1): the sync state and when sync
last finished, as
coven_sync_stateshows them andsync_status()reads them. - Synced
Table - A synced table’s key, audience, file references, shared triggers and who may change its rows directly (E2).
- System
Clock - The system wall clock.
- Test
Network - A network a test drives in place of the platform’s (api.md E1
network): clones drive the same network. - Transfer
Limits - Limits shared by the open store’s transfer consumers (E5).
- Transfer
Progress - 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.
- Transfer
Watch - 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.
- Unknown
Name - Text that names none of a type’s values.
- Unsent
Work - What this device committed and has not uploaded: writes and files (E1).
- Upload
Progress - Bytes the provider confirmed in a recorded upload session. Sending bytes alone does not advance it.
- Upload
Queue - Observable upload queue state (E7): one committed snapshot of the queue, with the uploads this process is sending as it is read.
- Upload
Settings - The writer’s copies of the upload settings, and the connections its upload runs’ attempts use.
- User
File - The facts recorded for the user’s original, which coven never changes.
- UuidIds
- Random UUIDv4 ids, independent of the clock (E1).
- Uuid
Text - Bind or read a UUID as canonical lowercase hyphenated SQL text.
Rusqlite’s
uuidfeature binds a bare UUID as a BLOB instead. - Work
Counter - Injected counter; clones observe the same database, never other test databases.
- Work
Counts - Local database work observed at its execution boundaries.
- Write
Batch - 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§
- AddDevice
End - How a pairing ended (§13.2).
- AddDevice
Status - 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. - Analysis
Limit - How many rows of each index
ANALYZEreads. - Audience
- Every synced row reaches the store or one circle (§15).
- Auto
Vacuum - What happens to the pages deleted content frees.
- Binding
- When a write setting a file reference goes out (§17.4, E2).
- Body
Failure - Failures after response metadata has arrived.
- Bootstrap
Directory Error - Filesystem failures while reserving, publishing or cancelling a new device.
- Bootstrap
Error - 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.
- Bootstrap
Status - Bootstrap progress (E10), before an open handle exists.
- Cache
Size - A page cache’s size, which SQLite counts in pages or in kibibytes.
- Cache
Spill - Whether a transaction may spill changed pages before it commits.
- Change
Op - The operation a waiting write performs on a row.
- Change
Outcome - How an admin change an app’s write journaled ended, for the kinds
RenameStore,SetRole,RemoveMember,RemoveDevice,RenameCircle,DeleteCircle,AddCircleMember,RemoveCircleMemberandApproveJoin(§11.4):coven_operations.outcomeholds 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. - Checkpoint
Mode - SQLite’s checkpoint modes (
PRAGMA wal_checkpoint). - Checksum
Value - The algorithm and native encoding of a provider checksum.
- Cloud
Provider - A provider supported by coven (§20.2).
- Code
Error - A malformed code or one intended for the other operation.
- Code
Info - Code metadata safe for presentation before opening the store.
- Code
Kind - The three codes that can open a store on a new device.
- Copy
Path Error - Why a copy can’t go where the app named.
- Coven
Error - Failures of opening, reading and writing a store (§4, E1, E3).
- Coven
Schema Error - Coven’s local tables cannot be used at this version (Appendix C.1, E1).
- Crypto
Error - A cryptographic operation could not produce or authenticate its result.
- Custody
Choice - Where this device keeps
T(E1). - CutOff
Refusal - Why
confirm_device_cut_offrefused (§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.
- Device
IdEvidence - Authenticated evidence that another installation uses this device id.
- Device
Only Error - 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.
- Device
Only Step - 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 ofall, is how far the whole call has come. - Device
State - What counted administrative slots did to a device id (E9). Later slots from a removed or replaced device are refused (§14.1, D6).
- Device
Stop - Why a device stopped for good (§14.1, §19.3).
- Directory
Creation Error - A store creation failure, with publication and rollback failures explicit.
- Drain
Outcome - Result of an app retry (
retry_uploads_now), or of one upload run. Individual failures stay inpending(). - Dropbox
Access - Dropbox fixes this access level on the app registration (§20.2).
- Dropbox
Clients - The app’s Dropbox registrations, with an explicit access choice when both exist.
- Dropbox
Location - Dropbox’s permanent creation choice, retained in settings and restore codes.
- Empty
S3Bucket Error - Why an S3 bucket was not emptied (api.md E14).
- Entry
Target - The target a proposed change can no longer affect.
- File
Error - A file operation’s cause, including whether replacement already happened.
- File
Missing Reason - Why a file can’t be read (§17.6).
- File
Name Error - A name that could escape its directory or alias a Windows device.
- File
Place - Where a file is (§17.2): in storage, or only on one device.
- File
Read Error - Reading a file failed with a cause the app can distinguish (E8).
- File
Source - An owned buffer or a reader whose stream coven consumes exactly once.
- File
Source Failure - The staging device cannot supply the file’s original bytes.
- File
Status - A file’s current availability (E8).
- Fresh
Change Outcome - How an admin change an app’s write journaled ended, for the kinds
CreateCircleandReplaceMemberKeys, ascoven_operations.outcomeholds 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). - Identity
Error - Initializing this device’s member identity failed (E11).
- IfUnsent
- What
delete_storedoes with writes and files not yet uploaded. - Incremental
Vacuum - How many free pages an incremental vacuum gives back.
- Invite
Access - How the invited person reaches the store’s provider.
- Invite
Admits - 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. - Invite
Lifetime - How long an invite stays open after it is made, by the inviting device’s clock (§13.2).
- Invite
Outcome - How an invite ended, the kind
Invite, ascoven_operations.outcomeholds it (§11.4, §13.2):coven_operationslists an invite only once a sharing refusal ends it. Its approval’s binding is an operation of its own, of the kindApproveJoin. - Invite
Stage - 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.
- Journal
Size Limit - How large the WAL file may stay after a checkpoint resets it.
- KeyError
- A failure unlocking, keeping or forgetting keys or host secrets (E11).
- Last
Pass - How the last pass that reached storage, or failed trying, ended (E5), as
coven_sync_status.last_passholds 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. - Listed
Outcome - 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. - Listed
Store - A store on this device as the listing found it (E1).
- Live
Query Cause - Why this run was requested; the first run answers the initial request.
- Load
Step - 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.
- Local
Failure - A local invariant or resource failure; immediate calls retain the native cause.
- Lock
Mode - Whether other holders may share the lock.
- Lost
- Values retained when a cell loses or a row is removed.
- Material
Error - A key or serialized secret violates its representation.
- Member
Access - An account to share with, or the id of a member’s S3 key.
- Member
Role - A member’s role in the store (§10).
- Memory
Request - Each attempted native call in the in-memory provider, before fault injection. This provider has one page per listing and no implicit metadata lookups.
- Merge
Error - Invalid input to the pure merge; no partially changed state is returned.
- Migration
Error - The application migration run could not complete.
- Move
File - A file of this device, on it only, to move to the cloud (§17.3, E3).
- Network
Watch Error - 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.
- OAuth
Access - The access requested by one sign-in and retained with its credentials.
- OAuth
Error - Sign-in failures distinguish cancellation, invalid redirects and provider refusal.
- Object
Checksum - Full-content checksums and multipart composites have different comparison rules.
- OldWrites
- What a breaking migration does with received late old-version writes.
- Open
Step - 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.
- Operation
Kind - The purpose of an unfinished operation, including maintenance.
- Operation
Rejection - Why the current applied state refuses an administrative operation.
- Page
Size - A database page size: a power of two from 512 bytes to 64 KiB.
- Pass
Failure - Why a pass, or the connection attempt that begins one, failed: how it
ended (
LastPass, E5). - Pending
Reason - A typed current condition, never an error’s display string.
- Pending
Subject - 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).
- Provider
Access Action - The provider’s intended sharing change.
- Provider
Sign Out - How a removed device’s member cuts off its provider access (§14.2, E9).
- Read
Only - A read-only handle: it reads synced rows and keeps its own file cache, and nothing else (E1).
- Read
Only Open Error - Opening a read-only store or its saved file-storage connection failed.
- Recorded
Invite Stage - Where an invite a test records is, as
coven_invites.stagenames it. - Recorded
Joiner - 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.
- Relative
Path Error - 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).
- Removal
Rule - A rule responsible for a removed row.
- Replaced
By - 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.
- Required
Update - 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.
- Reset
Reason - Why this installation can’t send under its keys or id, as
NeedsResetnames it (§19.3, §12.3). - Retained
Access Reason - The provider’s reason that a grant was retained.
- Retry
- What can permit another attempt; no attempt count determines it.
- Retry
Effect - What the person’s retry would do if made now (E5), as
coven_retry_effectholds it: run a pass, or be answered at once without one. An app offers a retry only while it isPass; the status says why it is not. - Retry
Outcome - What the first sync pass after the person’s retry came to (E5).
- RowAuthorization
Failure - Why a member’s row change was refused (§9.6).
- RowIdentity
- How independently inserted rows choose their identity (§9.2).
- S3Bucket
Versioning - The bucket’s versioning state, read through the service’s XML API (§20.7).
- S3Checksums
- How returned checksums are read.
- S3Copy
Condition - The destination condition on a publishing copy.
- S3Copy
Publication - Which publications proceed by a conditional copy of a reserved temporary (§20.6).
- S3Listing
- The listing protocol.
- S3Multipart
Timestamp - What a native multipart object’s
Last-Modifieddates. - S3Probe
- A behavior detection probes.
- S3Profile
- An S3 location’s behaviors: a catalogued service’s, or its own.
- S3Profile
Name - An S3 service whose catalogued profile a location names (§20.7). Self-hosted services have arbitrary endpoints, so no hostname identifies them.
- S3Response
Headers - Which response headers carry metadata, generation and hashes.
- S3Revision
- Where a replaceable object’s revision comes from.
- S3Signing
- Request authentication.
- S3Single
Put - The create-once condition on a single PUT.
- Saved
Restore Entry - One store’s saved entry, as listing found it (§13.1).
- Schema
Error - A schema rule checked on open and after migrating (§9, §15.1).
- Secure
Delete - Whether deleted content is overwritten.
- Settings
Error - Missing, damaged or unreadable store settings remain distinct errors.
- Setup
Cancellation - What cancelling storage setup did (E5).
- Sharing
Refusal - 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.
- Snapshot
Error - Snapshots or their gap writes could not be loaded into this database.
- Sqlite
Error - Enum listing possible errors from rusqlite.
- Status
Failure - What stopped a pass as a whole, as
LastPasskeeps it: aSyncFailurewithout the error objects, whose text it holds beside it (E5). - Storage
Check - The provider operation checked before setup commits anything (E5).
- Storage
Check Error - A provider or S3 settings check refused the location (§20.7, §20.8).
- Storage
Config - The store’s location; credentials are kept separately in key custody.
- Storage
Error - A storage error preserves its cause without converting it into text.
- Storage
Failure - Failures the app can distinguish and act on (Appendix F.5).
- Storage
Setup Error - A failed setup commits no local storage settings or credentials.
- Storage
Setup Outcome - How a storage setup ended, the kind
StorageSetup, ascoven_operations.outcomeholds it (§11.4, §11.6). - Storage
Setup Step - 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
Loadingis one unit, done when it ends. Setup can be cancelled untilCreatingStoreorRecordingAccessbegins, its point of no return (§11.6). - Store
Change - Every admin operation listed in §10, including store creation.
- Store
Creation Error - Creating a store failed, with publication and rollback made explicit (E1).
- Store
Deletion Error - Deleting the local store stopped at a step the caller may retry (E1).
- Store
KeyState - Whether this device’s custody holds opened store keys.
- Store
KeyUnlock Error - Opening this member’s sealed store keys failed.
- Store
List Error - A failure listing the stores. A store that can’t be read is not one: it
is listed as
ListedStore::Unreadable. - Store
Lock Error - A store in use is distinct from a filesystem failure.
- Sync
Activity - What Syncing is doing, as
Syncingnames 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. - Sync
Cause - What names a state: the last pass, or the first pending record, in the
order they arose, that names it, with the cause
coven_pendingkeeps. - Sync
Error - A synchronization request failed; its durable queue, if any, remains retryable.
- Sync
Failure - A sync step stopped as a whole (E5).
- Sync
State - The sync state (§19.1). With several candidates, the first of
Removed,NeedsReset,UpdateNeeded,SignedOut,NoAccess,FolderMissing,ClockWrong,StorageFull,OfflineWithUnsentChanges,Offline,Failed,Syncing,WaitingToSync,Syncedshows;NotSyncedcomes before them all.coven_sync_state.detailholds it as JSON, which this type reads. - Sync
Wait - What waiting to sync waits for, as
WaitingToSyncnames 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). - Temp
Store - Where temporary tables and indices are kept.
- Temporary
Directory Error - Why the folder for temporary tables could not be named (E1).
- Transfer
Change - A change to one file’s progress, or every file’s.
- Transfer
End - 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.
- Undo
Cause - Why an operation was undone (§11.6).
- Unfinished
- Work on a store that must finish before it opens (E1).
- Unreadable
Saved Code - Why a saved entry can’t be restored from. Listing shows it, with its store id, so the person can forget it (§13.1).
- Upload
Phase - 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.
- Upload
Wait - What a queued upload waits for, the first that holds (§17.9).
- UseAccess
KeyError - Why
use_access_keyfailed (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.
- Wall
Timer Error - A clock couldn’t wait for a wall-clock time (§13.2): the system refused its timer, or the clock has none.
- Write
Cutoff - Why a lower slot permanently excludes an original write.
- Write
Permission - 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.
- Write
Wait - 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).
- Files
Mode - 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:
WriterorReadOnly. - OAuth
Presenter - 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).
- Storage
Connector - 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::ToSqlConversionFailureif the conversion fails. - Write
Failure - 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:
DbErrorfor 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
dirthis process has open. - copy_
tree - Copy the tree at
fromintoto, makingtoand 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 callsjoin_with_invite. Refuses the code as that call would:WrongKindfor a restore or pairing code,Invalidfor 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 callsjoin_with_pairing. Refuses the code as that call would:WrongKindfor a restore or invite code,Invalidfor 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::OtherFilesbefore anything is removed. The first failure stops it; calling again finishes. Retained versions in a versioned bucket stay. It uses the app’sclockandids, the ones given toCovenBuilder::clockandCovenBuilder::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, onconnectionas a store ends it withoutcome:coven_operationslists the outcome until the app acknowledges it (§11.4). An outcome not in the outcome type of the operation’s kind fails withInvariant, 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.
nameis the name the new person typed when the invite admits a new person, andNonewhen it admits a member’s new keys, as the invite’sInviteInfo::admitssays; the other fails withCodeError::WrongJoinerbefore anything changes.circle_namenames 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, orresume_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).controlcancels 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 withBootstrapError::JoinRequestSentand keeps it, as dropping does. Once the join finds its admission it publishes the store, a cancel notwithstanding, then loads it, reportingLoading; a failure while it loads returnsBootstrapError::Publishedwith the open handle (§13.2). A store whose unfinished installation holds a restore’s record is refused withStoreLockError::BootstrapPendingbefore 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 (Nonewhen the pairing ended before its handover opened). A restore’s rules hold from its record on; before it, cancelling throughcontrol, 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, withdeviceas this device’s id, ascoven_database::test_utils::make_readable_objectssays. The sync state function is sync’s own, as every store registers it. - open_
files_ under - Every file under
dirthis 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_bytesholds 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_bytesrecorded. Bytes it never gives fail withPathBytesError: 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_textof 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
leaseuntil it ends (§17.3). - record_
change - Journal
changeonconnection, wheremake_readable_objectsmade coven’s objects, as the app’s write journals it, so thatcoven_operationslists it as running. Returns its operation. - record_
connected_ storage - Record on
connection, wheremake_readable_objectsmade coven’s objects, thatlocationis the store’s storage and this device holds its credentials, as opening a connected store records it. Until a test does,coven_sync_stateshows not synced, as for a store with no storage (§19.1). - record_
invite - Journal
inviteonconnection, wheremake_readable_objectsmade coven’s objects, as a store journals an invite at its stage, so thatcoven_invitesshows it. Returns the invite’s operation. - record_
last_ pass - Save
passonconnection, wheremake_readable_objectsmade coven’s objects, as how the last pass ended, as a store’s loop writes it when a pass ends, so thatcoven_sync_status.last_passholds it andcoven_sync_statecomputes its state from it beside the pending records the test saves withrecord_pending(§19.1). - record_
pending - Save
recordonconnection, wheremake_readable_objectsmade coven’s objects, as a store saves a pending record, so thatcoven_pendingshows it (§19.1). - record_
user_ file - Record on
connection, wheremake_readable_objectsmade coven’s objects, the original atpath, last modified atmodified_atand holdingbytes, asfile’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_filesthen lists it. - refuse_
invite - End the invite
inviteonconnectionas a store ends one that the provider refused to share withaccountforrefusal, a reason only a person can fix:coven_operationslists it as refused, and it leavescoven_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::BootstrapPendingbefore 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
storein place fromcodeneeds,Noneon S3 and CloudKit, read before any sign-in: the app signs in with it, then callsCovenBuilder::restore_device. Refuses the code as that call would:WrongKindfor an invite or pairing code,WrongStorefor another store’s restore code,Invalidfor 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_untilandcoven_sync_status.last_syncedhold it. One the clock can’t name isDamagedDatabase(§19.3). - unix_
seconds_ and_ nanos - A time as
coven_user_fileslists a modification time, inmodified_secondsandmodified_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::AfterReplacereports that new bytes are visible but directory syncing failed. Windows requires the POSIX replacement support described byAtomicFile::replace.
Type Aliases§
- Clock
Ref - A shared wall clock, supplied when the store opens.
- Coven
Result - A store call’s result, retaining its typed cause.
- IdSource
Ref - A shared source of new ids.
- Memory
Storage - 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.
Faultscan lose part/completion replies or expire pending sessions without losing published objects. - Operation
Error - An operation failure retains the same typed causes as an ordinary sync call.
- Sqlite
Result - A typedef of the result returned by many methods.