Module files 

Files on disk: the store layout, directory, settings and exclusive lock.

Structs

AtomicFile

One named file capability. It reads, creates, replaces and removes bytes without exposing a path. Replacement atomically installs a complete version.

BootstrapStore

An unpublished store at its permanent path, protected by a bootstrap lease. Dropping preserves resumable work; cancel removes it after its database closes. Publication removes the marker without moving any open files.

CacheWriteLock

A held lock on the cache’s range writes: shared by a write in progress, exclusive while opening finds abandoned ones. Dropping it unlocks.

ClosedStoreLock

The writer lock, held while a closed store is read without opening it: holding it shows that no handle runs the store’s sync. Registered in this process as closing from the start, so an open waits for its release. Dropping it unlocks.

CopyFolder

The folder the person picked, open for the copies one call makes.

CopyPlan

What one call makes below the folder: the folders that don’t exist yet, each before the folders inside it, and each file’s path, in the order of the relative paths.

CopyWriter

A copy being written under its temporary name. Dropping it leaves the bytes for the caller’s recorded cleanup.

DeviceReset

A replacement of this installation, not a membership removal (E5).

DirectoryBytes

What a store’s directory holds, in file sizes.

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.

FileReader

An open read-only file. Renaming or unlinking its path never redirects reads. Reads return what’s on disk, as the platform’s own positioned reads do.

FileWriter

An unpublished file’s open writer. Its OS handle and path stay private. Dropping it leaves the named bytes for the caller’s recorded cleanup. The shared store lock lasts until its handle and any cancelled I/O finish, and, for a file finished into a batch, until the batch’s flush ends.

FlushBatch

Files written for one commit, each synced as it finished, whose folders and drive cache are flushed together by FlushBatch::flush. The commit that records them takes the Flushed it returns, so nothing commits ahead of its bytes reaching the drive.

Flushed

A batch’s files reached the drive: what a commit recording them takes.

MadeFolder

A folder coven made for copies in a folder the person picked, as its record reads back (§17.3). It is made only where coven reads that record.

ObservedFile

Facts captured while reading one original; validation never rereads its bytes.

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.

RecordedCopy

A copy coven recorded writing in a folder the person picked, as its record reads back (§17.3): its bytes still at their temporary name, or placed at its path with the size and modification time they had there. It is made only where coven reads that record.

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.

ReplacementRecord

The durable record of a replacement past its point of no return: from just before the fresh device registers until it is published (§19.3).

ReplacementStore

A replacement of the installation in a published store’s directory. It holds the store’s bootstrap lease, and its writer lock until the new installation is in place. Dropping it keeps its work for the next call.

StagedName

Where a staged copy lies among the store’s app-provided files: in the folder its staging made, under its own name, recorded as <folder>/<copy> (Appendix C.3).

StoreClosingGuard

Marks an owning scope as closing on drop, without retaining its lock. Share an Arc of this guard across clones of that owner. A distinct owner scope can use closing_guard; ending either scope marks the instance.

StoreDeletionLock

Exclusive access to the writer, readers and bootstrap, authorizing deletion. Holding the bootstrap lock keeps every restore, join and replacement of the store out, including a reset_device or restore_device that holds only that lock between the steps of an unfinished swap (§19.3), and lets deletion remove its lock file too.

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.

StoreDirectories

The stores under app_dir, one directory each (E1).

StoreLock

An exclusive writer lock. Dropping it unlocks and closes the OS handle. Readers use a separate shared lock so they can coexist with the writer.

StoreReadLock

A shared lock that prevents deletion while a reader holds store files open.

StoreSettings

The settings written when creating, restoring or joining a store (E1). Storage settings belong to coven-storage’s own named file.

TemporaryFolder

The folder an app names for SQLite’s temporary tables (§21.2), outside coven’s directories. It is made where the app’s call names it.

UserOriginal

A user’s original: a file outside coven’s directories, at the path the app named for it, which coven reads and never changes (§17.3). It is made where the app’s call hands the path in, or where coven reads back the path it recorded.

WriterFolder

One area’s folder, held for a run of files made in it: the store’s read lock, taken once, and the folder’s resolved path, shared by every writer made here. The lock lasts until the last of those writers, and any batch one finished into, lets go of it.

Enums

BootstrapDirectoryError

Filesystem failures while reserving, publishing or cancelling a new device.

CopyPathError

Why a copy can’t go where the app named.

DirectoryCreationError

A store creation failure, with publication and rollback failures explicit.

FileArea

The two places coven keeps file bytes inside a store (E1).

FileError

A file operation’s cause, including whether replacement already happened.

FileNameError

A name that could escape its directory or alias a Windows device.

IfUnsent

What delete_store does with writes and files not yet uploaded.

LockMode

Whether other holders may share the lock.

ObservationError

A missing or changed original is distinct from an operating-system failure.

RelativePathError

Why names can’t be a RelativePath.

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.

ReplacementPhase

How far a recorded replacement has come (§19.3).

SettingsError

Missing, damaged or unreadable store settings remain distinct errors.

StagingFolderError

Why a staging’s folder could not be made.

StoreFile

One file owned by a crate, beside the database and store settings. The enum reserves the name so a caller cannot replace the database or settings.

StoreLockError

A store in use is distinct from a filesystem failure.

WriterError

Why a store’s file could not be created for writing: the store’s read lock, which the writer holds, or the file itself.

Traits

StoreDirAccess

Crate-to-crate operations for coven’s owners; not re-exported by the app API.

StoreLockProbe

Probes the OS writer lock without waiting, for lifetime assertions in tests. Production opens take the lock through StoreDirAccess.

Functions

assert_no_open_files_under

Panic naming every file under dir this process has open.

bootstrap_lock

The bootstrap lock file of the store at directory, which a test waits on to know an open finds the store’s bootstrap closing and waits for it.

cache_writes_lock

The cache-write lock file of the store at store, which a test waits on to know a range write or an open waits for it.

copy_tree

Copy the tree at from into to, making to and every folder below it, as restoring a backup of an installation does.

copy_tree_keeping

Copy the tree at from into to, as copy_tree does, with only the files whose name keep accepts.

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_bytes_text

The text that shows a path from its recorded bytes, as SQL’s coven_path_text gives it: valid UTF-8 as it is, and each byte that isn’t as \x and two uppercase hex digits. Caf\xE9.flac shows a Latin-1 name. A backslash already in the name stays as it is, so a name spelled Caf\xE9.flac shows the same: the text can’t be turned back into the path, and nothing opens a file by it.

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.

read_existing

The complete file at path, which must exist, for a test reading back bytes it saved with replace.

settle_files

Remove what unfinished writes left at the top of the store lock holds for writing (Appendix C.3), and the joining keys a published store still holds when the join that published it stopped before deleting them (§13.4), then give every folder and file the class its layout gives the store’s files, as directory names it, unless the store’s record shows they were last given it (E1). Blocks while it walks the store.

verify_lock

Check that lock protects exactly the store at directory.

when_reached

Told once file work reaches path: about to open it, or finding its lock held and about to wait for it.

windows_device

Whether base, a name’s part before its first . without trailing spaces, names a Windows device: Windows opens the device for it, with any extension on some versions, and in any ASCII case. ¹, ² and ³ count as digits.

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.

writer_lock

The writer lock file of the store at directory, which a test waits on (when_reached) to know an open finds the store’s writer closing and waits for it.

Type Aliases

FlushHook

Run where a batch’s flush has returned, in tests; an error from it fails the flush as the drive’s would.