Skip to main content

Crate coven_sync

Crate coven_sync 

Source
Expand description

The shared store sequence, durable operations, snapshots and file transfers.

Structs§

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).
ApprovalWaits
The wait between an approval’s checks, which a join and a pairing keep: its persisted delay, armed again after reopening, and any provider cooldown (§6.7).
Circle
A circle the local member belongs to (E12).
CircleMemberInfo
An active store member in a circle (E12).
CircleTerms
What the app says of the circle its joining person’s request makes: the admission will make it, with the person as its only member (§13.2).
CodeMetadata
Store, member and provider facts shared by every code kind.
ConnectionComing
A connection attempt’s mark on the file layer’s storage: while it lives, a connection is coming (§17.7).
Creation
What slot 1 sets up: the store, its first admin with her join facts, her first device, the first store key and the circles’ first keys ring holds.
CredentialKeychains
The keychain entries a credential change commits: this device’s provider credentials, and the person’s restore code and S3 key, saved for their next devices (§13.1).
CredentialRollback
Previous values of exactly the custody entries a credential commit changes. Setup and bootstrap retain this until their whole operation has committed.
DamagedObject
An object whose checks failed (§19.1).
DetectionRecord
One detection run’s record, as committed.
DeviceCredentials
This installation’s committed storage credentials. Every write of them goes through Self::write, so a refresh commits its replacement only while custody still holds the tokens the provider rejected.
DeviceInfo
One of a member’s device ids in the committed prefix (E9).
FileRangeStream
A borrowed stream of bounded authenticated plaintext buffers.
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.
Files
Owns storage, database file operations and the device’s file area (Appendix F.3), for the store’s writer or a read-only handle (Files<ReadOnly>), which only reads files and keeps its cache. The writer’s starts one commit-driven worker, for uploads and pins; no sync loop or timer is created. Call close before closing the database.
HeldIntervals
What the guards hold, as the owner of a wait reads it.
HolderDevice
An active device of a KeyHolder.
Invite
One of this device’s open invites (§13.2).
InviteExpiry
Ends this device’s invites as their lifetimes end, from the store’s opening until its handle closes. Dropping it stops the wakes too. A panic in it goes to the store’s bug sink and ends the wakes, as does a bug a write returns; the next open writes the expiries that passed.
InviteInfo
What an invite code tells before connecting: as typed or scanned, and as a join under way saved it (§13.2).
JoinPoll
An approval’s wait for its next poll: its persisted delay, armed again after reopening, any provider cooldown (§6.7), and the intervals the app holds (§13.2).
JoinRequest
A checked request, presented with the account from its local invitation.
JoiningIdentity
An unpublished member identity and its immutable request. The member id is the one the invite fixes; the keys are this device’s fresh pair. The only durable local copy is encrypted with the invite secret, bound to the complete code. No member keys or provider credentials enter final custody while waiting. One join holds it, from preparing or resuming the request until the join ends.
KeyHolder
A member of the store that holds a key a stopped device waits for: a copy of the key is sealed to the member’s current sealing key, so every device of the member with that pair opens it, and a device of the member that reads the key’s audience sends the copy on its next pass (§12.1).
MemberInfo
A live member and every device they registered (E9).
NetworkFollow
Follows one open store’s network watch from opening to closing: built as the store opens, already showing what the platform says, and closed before the database. It keeps the watch, whose platform registration ends with it.
NewCircle
A circle slot 1 makes, whose first key ring holds.
NewInvite
What the app asks an invite for: whom it admits, how they reach storage, and how long it stays open (§13.2).
OperationId
The local, never reused identity of an operation.
OperationSteps
The steps of the app’s write that journal an operation (§4, §11.1): checked against the state this device has applied, journaled with or without storage, and run by a later pass. One per writer handle.
PairingAsk
A request for a pairing and the pair it asks with.
PairingInfo
What a pairing code tells before connecting (§13.2).
Parks
The parks of one loop.
PassRequests
Requests a pass took when it began, answered when it ends. A pass that panicked, or was dropped, before answering them leaves them waiting again, for its owner’s ending to answer.
PendingRecord
One local first unmet condition, identified by its subject (§19.1, E5).
PinProgress
Verified cache coverage of requested files (§17.8, E8).
ProviderCheckPermit
A provider check’s object while permitted (SequenceState::permit_provider_check): removes it when dropped, a dropped future included.
QueuedUpload
One queued upload: what it is doing, and its committed progress.
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).
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.
RestoreCodes
Owns code generation and credential changes for one open handle, for its whole lifetime: connected or not, one change runs at a time, and a read waits for the change in flight. A change that needs the connection takes its sequence owner as an argument. Closing waits for updates holding the lock, even when their app futures were dropped.
RetryAnswer
Resolves when the first sync pass after a retry request ends (E5). Dropping it leaves the retry in place.
RetryWaits
One installation’s retry schedule. Construct when the store opens and inject the same owner into operations, file transfers, the sync loop and every provider connection.
SavedName
The store’s name as this device has it, and the slot that set it: 1 for creation, otherwise the rename’s. Of two names, the later slot’s is newer.
SequenceState
Shared state of this open installation. It carries no time-based permission.
SequenceSync
Owns sequence progress. App commits use the database independently; every publisher shares this owner’s serialization and actual blocked state.
SessionSignIn
A sign-in held for this session only, until setup or bootstrap publishes it to device custody: with the store, or for a join once it saves its invite code. It then refreshes there (§13.2, §20.2).
SetupJournal
One storage setup’s journal row, as its owner last committed it.
SyncLoop
Control of one serialized pass loop. Commands survive caller cancellation. It publishes its activity to the owner’s SequenceState.
SyncOften
The intervals apps hold, each with how many guards hold it.
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.
TransferLimits
Limits shared by the open store’s transfer consumers (E5).
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.

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.
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.
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.
ConnectionRetry
What permits this connection to attempt another pass. Time is held by RetryWaits. A failure that waits for something other than time holds every pass, and keeps what the status showed for it.
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.
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).
DrainOutcome
Result of an app retry (retry_uploads_now), or of one upload run. Individual failures stay in pending().
EntryTarget
The target a proposed change can no longer affect.
FileMissingReason
Why a file can’t be read (§17.6).
FileReadError
Reading a file failed with a cause the app can distinguish (E8).
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).
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).
JoinOutcome
The joining member’s outcome after checking storage (§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.
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.
LocalFailure
A local invariant or resource failure; immediate calls retain the native cause.
NetworkOwner
An owner of waits that acts on reports.
OperationKind
The purpose of an unfinished operation, including maintenance.
OperationRejection
Why the current applied state refuses an administrative operation.
PairingCheck
What a check of the request’s path finds.
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.
Prerequisite
A fact required before processing can continue.
ProviderAccessAction
The provider’s intended sharing change.
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.
Removal
Why a device is not in the store, and won’t be again (§13.2, §14.1).
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).
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).
SequenceStatus
Current sync activity. Reaching the read end says nothing about pending files.
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).
StorageSetupOutcome
How a storage setup ended, the kind StorageSetup, as coven_operations.outcome holds it (§11.4, §11.6).
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).
UndoCause
Why an operation was undone (§11.6).
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).
WriteCutoff
Why a lower slot permanently excludes an original write.

Traits§

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.

Functions§

admitting
The admission of member with keys that a join request would make, for a test that admits a member without a join: the circle it makes, named name, and the member’s own copy of its key.
change_operation
The journal row of change as the app’s write journals it, and the kind coven_operations lists it under, for a test that journals it outside a store (api.md E4).
commit_credentials
Commit device credentials and, on Apple, the separate S3 key. Setup and bootstrap also supply the restore code with the store’s name, and remove any S3 entry when setting up an account provider. Replacing credentials supplies no code; OAuth refresh touches neither person entry. A failed write restores every prior value and returns any rollback failures with the original cause.
connection_failure
The last attempt is offline only when its network failure received no reply.
decide_creation
Seal slot 1, journal its exact bytes as this device’s attempt at it with the operation that sends it, and apply it, all in database. The store is not published yet, so no other device can claim slot 1 first; setup later sends these bytes (§10.3). The creator’s copy of each key slot 1 introduces rides in its clear prefix, as an admission’s copies do (§12.1). Applying slot 1 runs the app’s joining write for the creator’s device, as an admission’s application does for a joiner’s (§13.2).
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.
decode_restore_info
A restore code’s metadata, or WrongKind for an invite or pairing code and Invalid for one that doesn’t decode.
ended_for
Whether the request kept for code was recorded as ended (record_ending).
follow_name
Rewrite the entry’s name when name is newer, keeping the code the entry holds: only setup, joining, restoring, resetting and member-key replacement save a code over a readable one (§13.1). An absent entry stays absent, so a forgotten entry stays forgotten.
invite_operation
The journal row of invite, as make_invite journals an invite and later steps record its state: the invite made by device 1 for an account, with a fixed secret and an expiry in 2096, and the request as coven-format’s fixture request with invite’s id, member and joiner (api.md E4).
location_code
The restore code that names identity’s held pair and the store’s location, with no credentials (§13.1).
pairing_status
The status of pairing, from records, the journal’s pairing rows (operation_kind::PAIRING), which a one-shot read or a live query reads. None for a pairing this device never made or has forgotten (E10).
pairings_opened
Opening the store ends every pairing a closed handle or a crash left: no screen shows one now. Each is forgotten once its marker is in place, and one that had ended already is forgotten at once, all in one transaction (§13.2).
read_connection
Read the saved provider location and custody credentials without opening a database. Shared by normal sync, read-only file access and damaged-database recovery. Absence means storage is not configured on this installation.
read_invite_code
Decode an invitation for the joining side after validating provider admission.
read_location
The storage location recorded on this installation, with its labels, and whether custody holds credentials for it, as the sync state reads it (§19.1): as a store opens, and as its closed status is read (api.md E1).
read_pairing_code
Decode a pairing code for the new device after validating provider admission.
read_restore_code
Decode a restore code for bootstrap, preserving a valid wrong-kind distinction. Its storage part has already been validated.
read_saved_code
Read a saved entry for store, and its code’s location.
record_connected_outside_store
Write that location is recorded on connection, a test’s connection outside any store, with this device holding its credentials, as record_opened writes it.
record_ending
Record that the join with code ends without a store, before anything it kept is deleted: a call that stops part way through the deletion finds the record and finishes it without connecting. Nothing saved is nothing to record.
record_location
Write whether a storage location is recorded here and its credentials held, with the location and its labels, as setup, a change of credentials, a connection’s new label or releasing a connection finds it; finished, for setup, is when it read the store to its end. A failure fails the store’s handle with its cause.
record_opened
Write, as the store opens, whether a storage location is recorded here and its credentials held, with the location and its labels, and that no pass moves; finished, for a store joining or restoring read to its end, is when (E5). A failure fails the store’s handle with its cause.
registration_journaled
Whether this installation’s registration is journaled and has not ended: its claim may still land, or has landed and not yet been applied. A restore that ends without its store, its device absent from the history it applied, reads this before it removes its installation (§13.1, §11.6).
removal_journaled
Whether this installation’s removal of device, its own, is journaled and has not ended: its claim may still land, or has landed and not yet been applied. A deletion that leaves the store reads this to learn whether it has passed its point of no return (E1, §11.6).
replacement_code
The code a device with the store open saves in place of an unreadable entry (§13.1), or None when it holds no current code: the store has no location or identity, custody holds no member pair, the member was removed, or another device replaced the keys this device holds.
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.
sealed_join_request
The request as it is stored at path: sealed with the invite secret’s request key and signed by the pair it names (§13.2).
sync_functions
_coven_sync_state and _coven_upload_phase, the functions coven_sync_state and coven_upload_phases call, for the database to register on every connection: the state and each upload’s phase computed in this crate’s Rust code, so that it stays the one definition the Lean model checks while an app’s screen reads them in SQL (§17.9, §19.1).
sync_status
The sync state and when sync last finished, as coven_sync_state shows them in one committed snapshot (§19.1).
test_joining_circle
The circle a join request of member with the sealing key sealing would make in store, named “Circle” at base zero, for a test that seals a request itself.

Type Aliases§

OperationError
An operation failure retains the same typed causes as an ordinary sync call.
StorageCommit
Credential and settings commit performed after remote setup has succeeded.
StorageRollback
Compensation retained until setup has committed its keys and applied origin.