Skip to main content

coven_foundation/files/
directory.rs

1//! The paths and filesystem capabilities inside one store directory.
2
3use std::path::PathBuf;
4use std::sync::Arc;
5
6#[cfg(unix)]
7use crate::files::flush_batch::BatchFolder;
8use crate::files::protection::Protection;
9use crate::files::{
10    lock, settings, AtomicFile, CacheWriteLock, ClosedStoreLock, FileError, FileWriter, FlushBatch,
11    SettingsError, StoreDeletionLock, StoreLock, StoreLockError, StoreReadLock, StoreSettings,
12    WriterFolder,
13};
14use crate::id_source::StoreId;
15use crate::task::BugSinkRef;
16
17/// The store database file, also its name in a discarded device archive.
18pub(super) const DATABASE: &str = "store.db";
19
20/// One file owned by a crate, beside the database and store settings.
21/// The enum reserves the name so a caller cannot replace the database or settings.
22#[derive(Clone, Copy, Debug)]
23pub enum StoreFile {
24    /// coven-storage's provider settings, encoded and interpreted by that crate.
25    StorageSettings,
26    /// coven-crypto's passphrase-sealed store and circle keys (E1).
27    StoreKeys,
28    /// coven-crypto's passphrase-sealed member key pairs (E1).
29    MemberKeys,
30    /// Encrypted joining identity and fixed request, interpreted by coven-sync.
31    Bootstrap,
32}
33
34impl StoreFile {
35    /// The file's name in the store's directory.
36    pub(super) const fn name(self) -> &'static str {
37        match self {
38            Self::StorageSettings => "storage.json",
39            Self::StoreKeys => "store-keys.sealed",
40            Self::MemberKeys => "member-keys.sealed",
41            Self::Bootstrap => "bootstrap.sealed",
42        }
43    }
44}
45
46/// The two places coven keeps file bytes inside a store (E1).
47#[derive(Clone, Copy, Debug)]
48pub enum FileArea {
49    /// Coven's own copies of app-provided files, each staging's in a folder
50    /// of its own, and captured snapshots at the top (§17.1, Appendix C.3).
51    AppProvided,
52    /// The cache of uploaded files and chunks (§17.8).
53    Cache,
54}
55
56impl FileArea {
57    const ALL: [Self; 2] = [Self::AppProvided, Self::Cache];
58
59    /// The area's folder in the store's directory.
60    const fn name(self) -> &'static str {
61        match self {
62            Self::AppProvided => "files",
63            Self::Cache => "cache",
64        }
65    }
66}
67
68/// A portable single filename: ASCII letters, digits, `-`, `_` and interior
69/// dots, up to 255 bytes. Windows device names are refused on every platform.
70#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
71pub struct FileName(String);
72
73/// A name that could escape its directory or alias a Windows device.
74#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
75pub enum FileNameError {
76    /// The name is empty or exceeds a filesystem component's length.
77    #[error("file name must contain 1 to 255 bytes")]
78    Length,
79    /// The name contains a forbidden byte, starts with a dot or ends with one.
80    #[error("file name requires ASCII letters, digits, hyphens, underscores or interior dots")]
81    Character,
82    /// The name names a Windows device, even with an extension.
83    #[error("file name is reserved for a Windows device")]
84    Reserved,
85}
86
87impl FileName {
88    /// The validated filename, for recording an owned file in local metadata.
89    pub fn as_str(&self) -> &str {
90        &self.0
91    }
92
93    /// Validate a single filename before it is joined to an owned directory.
94    pub fn new(name: impl Into<String>) -> Result<Self, FileNameError> {
95        let name = name.into();
96        if name.is_empty() || name.len() > super::relative_path::NAME_LIMIT {
97            return Err(FileNameError::Length);
98        }
99        if name.starts_with('.')
100            || name.ends_with('.')
101            || !name.bytes().all(|b| b.is_ascii_alphanumeric() || b"-_.".contains(&b))
102        {
103            return Err(FileNameError::Character);
104        }
105        let stem = name.split('.').next().expect("a nonempty name has a stem");
106        if windows_reserved_names::windows_device(stem) {
107            return Err(FileNameError::Reserved);
108        }
109        Ok(Self(name))
110    }
111}
112
113/// Where a staged copy lies among the store's app-provided files: in the
114/// folder its staging made, under its own name, recorded as
115/// `<folder>/<copy>` (Appendix C.3).
116#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
117pub struct StagedName(String);
118
119impl StagedName {
120    /// The copy `name` in the staging's folder `folder`.
121    pub fn new(folder: &FileName, name: &FileName) -> Self {
122        Self(format!("{}/{}", folder.0, name.0))
123    }
124
125    /// A recorded name read back, when it is two portable names joined by
126    /// `/`.
127    pub fn parse(recorded: &str) -> Option<Self> {
128        let (folder, name) = recorded.split_once('/')?;
129        Some(Self::new(&FileName::new(folder).ok()?, &FileName::new(name).ok()?))
130    }
131
132    /// The name as records hold it.
133    pub fn as_str(&self) -> &str {
134        &self.0
135    }
136
137    /// The staging's folder.
138    pub fn folder(&self) -> FileName {
139        FileName(self.parts().0.to_owned())
140    }
141
142    /// The copy's own name in its staging's folder.
143    pub fn copy(&self) -> FileName {
144        FileName(self.parts().1.to_owned())
145    }
146
147    /// The staging's folder and the copy's name in it.
148    fn parts(&self) -> (&str, &str) {
149        self.0.split_once('/').expect("a staged name holds its folder")
150    }
151}
152
153/// Why a staging's folder could not be made.
154#[derive(Debug, thiserror::Error)]
155pub enum StagingFolderError {
156    /// A folder of that name is already there: the id source gave out the
157    /// name before.
158    #[error("staging folder {} is already there", .0.as_str())]
159    Taken(FileName),
160    /// The store could not be held, or the folder made.
161    #[error(transparent)]
162    Writer(#[from] WriterError),
163}
164
165/// One store's directory, owning the paths to its database, app-provided files,
166/// cache, settings and sibling locks. It never exposes the directory as a raw path.
167#[derive(Clone)]
168pub struct StoreDir {
169    path: PathBuf,
170    id: StoreId,
171    /// The bootstrap lock of the bootstrap that gave the directory out, which
172    /// opens the unpublished store while that bootstrap holds it.
173    bootstrap: Option<lock::LockInstance>,
174    /// The class its layout gives the store's files (E1).
175    protection: Protection,
176    /// Where a bug in the store's work that nobody waits for goes (E15).
177    bugs: BugSinkRef,
178}
179
180impl std::fmt::Debug for StoreDir {
181    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
182        f.debug_struct("StoreDir")
183            .field("path", &self.path)
184            .field("id", &self.id)
185            .field("bootstrap", &self.bootstrap)
186            .field("protection", &self.protection)
187            .finish_non_exhaustive()
188    }
189}
190
191impl StoreDir {
192    pub(crate) fn new(
193        path: PathBuf,
194        id: StoreId,
195        protection: Protection,
196        bugs: BugSinkRef,
197    ) -> Self {
198        Self { path, id, bootstrap: None, protection, bugs }
199    }
200
201    pub(super) fn bootstrapping(
202        path: PathBuf,
203        id: StoreId,
204        bootstrap: lock::LockInstance,
205        protection: Protection,
206        bugs: BugSinkRef,
207    ) -> Self {
208        Self { path, id, bootstrap: Some(bootstrap), protection, bugs }
209    }
210
211    /// Whether the store is still an unpublished installation: its marker is
212    /// there (§13.4).
213    pub fn is_unpublished(&self) -> Result<bool, FileError> {
214        super::bootstrap::is_pending(&self.path)
215    }
216
217    fn is_bootstrapping(&self) -> bool {
218        self.bootstrap
219            .is_some_and(|instance| lock::bootstrap_running(&self.path, self.id, instance))
220    }
221
222    /// An unfinished replacement's record refuses opens, from before its
223    /// fresh device registers until it is published; a marker alone belongs
224    /// to a first installation.
225    fn check_published(&self) -> Result<(), StoreLockError> {
226        if self.is_bootstrapping() {
227            return Ok(());
228        }
229        let unfinished =
230            super::device_reset::unfinished(&self.path, self.id).map_err(|error| match error {
231                SettingsError::File(error) => StoreLockError::from(error),
232                SettingsError::Bug(bug) => StoreLockError::Bug(bug),
233                error => FileError::at(
234                    "read the store's settings beside its replacement record",
235                    &self.path,
236                    std::io::Error::other(error),
237                )
238                .into(),
239            })?;
240        if let Some(record) = unfinished {
241            return Err(StoreLockError::ReplacementUnfinished { store: self.id, by: record.by });
242        }
243        if super::bootstrap::is_pending(&self.path)? {
244            return Err(StoreLockError::BootstrapPending(self.id));
245        }
246        Ok(())
247    }
248
249    /// The store identified by this directory.
250    pub fn id(&self) -> StoreId {
251        self.id
252    }
253
254    /// The folder of the store's file `area`, for a test that looks at the
255    /// files coven keeps there.
256    #[cfg(any(test, feature = "test-utils"))]
257    pub fn area_path(&self, area: FileArea) -> std::path::PathBuf {
258        self.path.join(area.name())
259    }
260
261    /// Whether any of the store's files are on disk: its directory, or the
262    /// directory under its deletion name that a deletion not yet finished
263    /// leaves, for a test of what a deletion removes.
264    #[cfg(any(test, feature = "test-utils"))]
265    pub fn files_exist(&self) -> bool {
266        self.path.exists() || lock::deletion_path(&self.path, self.id).exists()
267    }
268
269    /// Copy the closed store's directory into `to`, making `to` and every
270    /// folder below it, as a backup of the app's folder does. Panics on
271    /// failure. Close the store first: a copy of an open store's files is a
272    /// copy of a crash.
273    #[cfg(any(test, feature = "test-utils"))]
274    pub fn copy_files(&self, to: &std::path::Path) {
275        crate::files::copy_tree(&self.path, to);
276    }
277
278    /// Make the store's settings file unreadable, as a disk that wrote half
279    /// of it leaves it: listing the store then reports its settings as
280    /// unreadable. Panics on failure.
281    #[cfg(any(test, feature = "test-utils"))]
282    pub fn damage_settings(&self) {
283        std::fs::write(self.path.join(settings::SETTINGS_FILE), b"{").unwrap();
284    }
285
286    /// Make the store's storage settings file unreadable, as `damage_settings`
287    /// does the store's settings. Panics on failure.
288    #[cfg(any(test, feature = "test-utils"))]
289    pub fn damage_storage_settings(&self) {
290        std::fs::write(self.path.join(StoreFile::StorageSettings.name()), b"{not settings")
291            .unwrap();
292    }
293
294    /// Replace the closed store's directory with the copy at `from`, as
295    /// restoring a backup does: the files the store has now are removed first.
296    /// Panics on failure.
297    #[cfg(any(test, feature = "test-utils"))]
298    pub fn restore_files(&self, from: &std::path::Path) {
299        std::fs::remove_dir_all(&self.path).unwrap();
300        crate::files::copy_tree(from, &self.path);
301    }
302}
303
304/// The folder of the store's folder that holds a rebuild's store (§18.3).
305const REBUILD: &str = "rebuild";
306/// Where the folder `rebuild` moves as its removal begins.
307const REMOVING_REBUILD: &str = "removing-rebuild";
308
309pub(crate) fn initialize(
310    path: &std::path::Path,
311    settings: &StoreSettings,
312) -> Result<(), SettingsError> {
313    for area in FileArea::ALL {
314        let directory = path.join(area.name());
315        std::fs::create_dir(&directory).map_err(|source| {
316            crate::files::FileError::at("create store files directory", &directory, source)
317        })?;
318        #[cfg(unix)]
319        crate::files::atomic_file::sync_directory(&directory).map_err(|source| {
320            crate::files::FileError::at("sync store files directory", &directory, source)
321        })?;
322    }
323    settings::write(path, settings)
324}
325
326/// Why a store's file could not be created for writing: the store's read
327/// lock, which the writer holds, or the file itself.
328#[derive(Debug, thiserror::Error)]
329pub enum WriterError {
330    /// The store could not be held for the write.
331    #[error(transparent)]
332    Lock(#[from] StoreLockError),
333    /// Creating the file failed.
334    #[error(transparent)]
335    File(#[from] FileError),
336}
337
338/// Probes the OS writer lock without waiting, for lifetime assertions in
339/// tests. Production opens take the lock through `StoreDirAccess`.
340#[cfg(any(test, feature = "test-utils"))]
341pub trait StoreLockProbe {
342    /// Take the writer lock, refusing at once when it is held.
343    fn lock_exclusive(&self) -> Result<StoreLock, StoreLockError>;
344}
345
346#[cfg(any(test, feature = "test-utils"))]
347impl StoreLockProbe for StoreDir {
348    fn lock_exclusive(&self) -> Result<StoreLock, StoreLockError> {
349        let guard = lock::acquire(&self.path, self.id)?;
350        self.check_published()?;
351        Ok(guard)
352    }
353}
354
355/// Crate-to-crate operations for coven's owners; not re-exported by the app API.
356pub trait StoreDirAccess: Sized {
357    /// The database file's exact path for coven-database to open with SQLite.
358    /// Callers never append path components to it.
359    fn database_path(&self) -> PathBuf;
360    /// Retained remote input has its own SQLite owner: receiving bytes must not
361    /// wait for a transaction applying those bytes to the application database.
362    fn input_database_path(&self) -> PathBuf;
363    /// The database a breaking migration's per-audience check runs in, which
364    /// lives only for that check (§18.3).
365    fn audience_database_path(&self) -> PathBuf;
366    /// Remove that database's file and the files SQLite keeps beside it; one
367    /// that is absent is already removed.
368    fn remove_audience_database(&self) -> Result<(), FileError>;
369    /// The store a rebuild runs in (§18.3): a store of its own in the
370    /// folder `rebuild` of this store's folder, with this store's id and this
371    /// device's, the file areas empty and the class this layout gives the
372    /// store's files. A leftover from a crash goes first, once an instance of
373    /// it in this process has finished closing. The caller removes it with
374    /// [`Self::remove_rebuild_directory`].
375    fn rebuild_directory(
376        &self,
377    ) -> impl std::future::Future<Output = Result<Self, SettingsError>> + Send;
378    /// Remove the folder `rebuild` whole, with its locks; absent is removed.
379    fn remove_rebuild_directory(&self) -> Result<(), FileError>;
380    /// Move the folder `rebuild` aside, in one rename, so it leaves the
381    /// store's directory before coven deletes its files, after deleting what
382    /// an earlier removal left there. Returns whether there was one to move.
383    fn retire_rebuild_directory(&self) -> Result<bool, FileError>;
384    /// Move the folder `retire_rebuild_directory` moved aside back.
385    fn return_rebuild_directory(&self) -> Result<(), FileError>;
386    /// Delete the folder `retire_rebuild_directory` moved aside, whole. When
387    /// that folder is absent, the call does nothing and succeeds. The
388    /// database has no row for the files in that folder. Blocks while it
389    /// deletes the folder.
390    fn remove_retired_rebuild(&self) -> Result<(), FileError>;
391    /// The record of a replacement whose swap is under way (§19.3). A record
392    /// that remains only because publication was interrupted after removing
393    /// the bootstrap marker, with settings already naming the new device, is
394    /// not returned; the next replacement removes it. Reads only.
395    fn unfinished_replacement(&self) -> Result<Option<super::ReplacementRecord>, SettingsError>;
396    /// What the store's unfinished deletion does with unsent work, when this
397    /// device recorded that it is deleting the store and leaving it (E1).
398    /// Reads only.
399    fn unfinished_deletion(&self) -> Result<Option<super::IfUnsent>, FileError>;
400    /// Record that this device is deleting the store and leaving it, with
401    /// what the deletion does with unsent work, before it journals the
402    /// device's removal. The record goes with the directory.
403    fn record_deletion(&self, unsent: super::IfUnsent) -> Result<(), FileError>;
404    /// Remove the record of a deletion that ended before it journaled the
405    /// device's removal. An absent record succeeds.
406    fn forget_deletion(&self) -> Result<(), FileError>;
407    /// The name of each archive that a reset kept in the store's directory,
408    /// in order (§19.3).
409    fn discarded_devices(&self) -> Result<Vec<String>, FileError>;
410    /// The size of everything in the archive `name`. Blocks while it walks
411    /// the archive.
412    fn discarded_device_size(&self, name: &str) -> Result<u64, FileError>;
413    /// Move the archive `name` out of the store's directory, in one rename,
414    /// into the folder where coven deletes retired archives. Returns whether
415    /// it was there to move.
416    fn retire_discarded_device(&self, name: &str) -> Result<bool, FileError>;
417    /// Move the archive `name` back, as `retire_discarded_device` found it.
418    fn return_discarded_device(&self, name: &str) -> Result<(), FileError>;
419    /// Delete the folder that `retire_discarded_device` moved archives into,
420    /// then sync the store's directory. The database has no row for the archives in that folder,
421    /// so a removal that stops partway leaves the rest for the next call.
422    /// Blocks while it removes them.
423    fn remove_retired_devices(&self) -> Result<(), FileError>;
424    /// The settings written when this store was created, restored or joined.
425    /// Reading takes no lock; a read-only open uses it alongside a writer.
426    fn settings(&self) -> Result<StoreSettings, SettingsError>;
427    /// Where a bug in the store's work that nobody waits for goes (E15):
428    /// the app's own reporter, which its directories were given.
429    fn bugs(&self) -> &BugSinkRef;
430    /// Take the writer lock, awaiting release by a closing instance in this
431    /// process. A live instance or another process still refuses immediately.
432    fn lock_for_open(
433        &self,
434    ) -> impl std::future::Future<Output = Result<StoreLock, StoreLockError>> + Send;
435    /// Take the writer lock to read a closed store without opening it: a live
436    /// instance or another process refuses immediately, and an instance
437    /// closing in this process is waited for. Registered as closing, so an
438    /// open in this process waits for its release (api.md E1).
439    fn lock_closed(
440        &self,
441    ) -> impl std::future::Future<Output = Result<ClosedStoreLock, StoreLockError>> + Send;
442    /// Prevent deletion while reading, alongside other readers and the writer.
443    /// The guard must outlive every open file and database connection it protects.
444    fn lock_read_only(&self) -> Result<StoreReadLock, StoreLockError>;
445    /// Hold while a cache range recorded as being written gets its bytes
446    /// with no database writer held. Shared by such writes in every process;
447    /// `exclude_cache_writes` waits for all of them (Appendix C.3).
448    fn lock_cache_write(&self) -> Result<CacheWriteLock, FileError>;
449    /// Wait until no cache range is being written in any process and keep new
450    /// writes waiting, so a range still recorded as being written has no
451    /// live writer (Appendix C.3).
452    fn exclude_cache_writes(&self) -> Result<CacheWriteLock, FileError>;
453    /// Lock an existing store or a directory left by an interrupted deletion,
454    /// holding its writer, reader and bootstrap locks so that removal takes
455    /// every lock file named for the store. An absent store with leftover
456    /// locks can finish their removal on retry. A running restore, join or
457    /// replacement refuses with `StoreLockError::AlreadyOpen`. A store whose
458    /// replacement is unfinished is locked for deletion; an unfinished first
459    /// installation is refused with `StoreLockError::BootstrapPending`.
460    /// No directory is created by this call.
461    fn lock_for_deletion(&self) -> Result<Option<StoreDeletionLock>, StoreLockError>;
462    /// Wait until no instance of this store in this process is closing, as
463    /// `lock_for_open` does, so a deletion that follows is not refused by an
464    /// instance only finishing its close, a replacement's loading
465    /// installation in its hidden directory included. A live instance is not
466    /// waited for.
467    fn closed(&self) -> impl std::future::Future<Output = Result<(), FileError>> + Send;
468    /// Give a crate the capability for its reserved file, without exposing
469    /// the store path or letting it name any other top-level file.
470    fn owned_file(&self, file: StoreFile) -> AtomicFile;
471    /// The capability for one app-provided copy or cache entry. All path
472    /// construction stays here; the name cannot traverse directories.
473    fn file(&self, area: FileArea, name: &FileName) -> AtomicFile;
474    /// Create a named file in `area` for asynchronous streaming without
475    /// replacing anything. The writer holds the store's read lock until its
476    /// handle and any cancelled I/O finish, so the store can't be deleted
477    /// under it. The caller records the name first and removes partial bytes
478    /// after a failure.
479    fn create_writer(&self, area: FileArea, name: &FileName) -> Result<FileWriter, WriterError>;
480    /// Hold `area`'s folder for a run of files made in it: the store's read
481    /// lock is taken and the folder resolved once, for every writer
482    /// [`WriterFolder::create`] makes, each as `create_writer`'s does.
483    fn writer_folder(&self, area: FileArea) -> Result<WriterFolder, WriterError>;
484    /// The capability for one staged copy, in its staging's folder.
485    fn staged_file(&self, name: &StagedName) -> AtomicFile;
486    /// Make `folder` among the app-provided files for one staging's copies,
487    /// refusing one already there, and hold it as `writer_folder` holds an
488    /// area's folder. The app-provided files' folder now holds the new
489    /// folder, so `batch`'s flush syncs it too (Appendix C.3). The caller
490    /// records the copies' names first, which name the folder.
491    fn staging_folder(
492        &self,
493        folder: &FileName,
494        batch: &mut FlushBatch,
495    ) -> Result<WriterFolder, StagingFolderError>;
496    /// Remove a staged copy, then its staging's folder once nothing is in
497    /// it, syncing the folder that held each (Appendix C.3). An absent copy
498    /// or folder is gone.
499    fn remove_staged(&self, name: &StagedName) -> Result<(), FileError>;
500    /// Reopen a named file of `area` that an earlier writer left unfinished,
501    /// for appending after its first `length` bytes, which the caller
502    /// recorded as synced; anything past them is cut off. A file with fewer
503    /// bytes is refused. The writer holds the store's read lock as
504    /// `create_writer`'s does.
505    fn resume_writer(
506        &self,
507        area: FileArea,
508        name: &FileName,
509        length: u64,
510    ) -> Result<FileWriter, WriterError>;
511}
512
513/// Check that `lock` protects exactly the store at `directory`.
514pub fn verify_lock(directory: &StoreDir, lock: &StoreLock) -> Result<(), StoreLockError> {
515    lock.verify(&directory.path, directory.id)
516}
517
518/// Remove what unfinished writes left at the top of the store `lock` holds
519/// for writing (Appendix C.3), and the joining keys a published store still
520/// holds when the join that published it stopped before deleting them
521/// (§13.4), then give every folder and file the class its
522/// layout gives the store's files, as `directory` names it, unless the
523/// store's record shows they were last given it (E1). Blocks while it walks
524/// the store.
525pub fn settle_files(directory: &StoreDir, lock: &StoreLock) -> Result<(), FileError> {
526    super::atomic_file::remove_temporaries(lock.directory())?;
527    // A store still unpublished keeps them: its join resumes from them.
528    if !super::bootstrap::is_pending(lock.directory())?
529        && super::atomic_file::exists(
530            "inspect the joining keys",
531            &lock.directory().join(StoreFile::Bootstrap.name()),
532        )?
533    {
534        directory.owned_file(StoreFile::Bootstrap).remove_with_temporaries()?;
535    }
536    directory.protection.apply(lock.directory())
537}
538
539impl StoreDirAccess for StoreDir {
540    fn database_path(&self) -> PathBuf {
541        self.path.join(DATABASE)
542    }
543    fn input_database_path(&self) -> PathBuf {
544        self.path.join("inputs.db")
545    }
546    fn audience_database_path(&self) -> PathBuf {
547        self.path.join("audiences.db")
548    }
549    fn remove_audience_database(&self) -> Result<(), FileError> {
550        let path = self.audience_database_path();
551        for suffix in ["", "-wal", "-shm", "-journal"] {
552            let mut file = path.as_os_str().to_owned();
553            file.push(suffix);
554            match std::fs::remove_file(PathBuf::from(&file)) {
555                Err(source) if source.kind() != std::io::ErrorKind::NotFound => {
556                    return Err(FileError::at(
557                        "remove the audience database",
558                        &PathBuf::from(file),
559                        source,
560                    ));
561                }
562                _ => (),
563            }
564        }
565        Ok(())
566    }
567    async fn rebuild_directory(&self) -> Result<StoreDir, SettingsError> {
568        let settings = self.settings()?;
569        let scratch = self.path.join(REBUILD).join(self.id.to_string());
570        lock::closed(&scratch, self.id).await?;
571        self.remove_rebuild_directory()?;
572        let root = self.path.join(REBUILD);
573        for folder in [&root, &scratch] {
574            std::fs::create_dir(folder).map_err(|source| {
575                FileError::at("create the rebuild store's folder", folder, source)
576            })?;
577            self.protection.begin(folder)?;
578        }
579        initialize(&scratch, &settings)?;
580        Ok(StoreDir::new(scratch, self.id, self.protection, self.bugs.clone()))
581    }
582    fn remove_rebuild_directory(&self) -> Result<(), FileError> {
583        let root = self.path.join(REBUILD);
584        match std::fs::remove_dir_all(&root) {
585            Err(source) if source.kind() != std::io::ErrorKind::NotFound => {
586                Err(FileError::at("remove the rebuild store's folder", &root, source))
587            }
588            _ => Ok(()),
589        }
590    }
591    fn retire_rebuild_directory(&self) -> Result<bool, FileError> {
592        self.remove_retired_rebuild()?;
593        super::set_aside::move_aside(&self.path.join(REBUILD), &self.path.join(REMOVING_REBUILD))
594    }
595    fn return_rebuild_directory(&self) -> Result<(), FileError> {
596        super::set_aside::move_back(&self.path.join(REBUILD), &self.path.join(REMOVING_REBUILD))
597    }
598    fn remove_retired_rebuild(&self) -> Result<(), FileError> {
599        super::set_aside::delete(&self.path.join(REMOVING_REBUILD))
600    }
601    fn unfinished_replacement(&self) -> Result<Option<super::ReplacementRecord>, SettingsError> {
602        super::device_reset::unfinished(&self.path, self.id)
603    }
604    fn unfinished_deletion(&self) -> Result<Option<super::IfUnsent>, FileError> {
605        super::deletion::read(&self.path)
606    }
607    fn record_deletion(&self, unsent: super::IfUnsent) -> Result<(), FileError> {
608        super::deletion::record(&self.path, unsent)
609    }
610    fn forget_deletion(&self) -> Result<(), FileError> {
611        super::deletion::forget(&self.path)
612    }
613    fn discarded_devices(&self) -> Result<Vec<String>, FileError> {
614        super::device_reset::discarded_devices(&self.path)
615    }
616    fn discarded_device_size(&self, name: &str) -> Result<u64, FileError> {
617        super::device_reset::discarded_device_size(&self.path, name)
618    }
619    fn retire_discarded_device(&self, name: &str) -> Result<bool, FileError> {
620        super::device_reset::retire(&self.path, name)
621    }
622    fn return_discarded_device(&self, name: &str) -> Result<(), FileError> {
623        super::device_reset::unretire(&self.path, name)
624    }
625    fn remove_retired_devices(&self) -> Result<(), FileError> {
626        super::device_reset::remove_retired(&self.path)
627    }
628    fn settings(&self) -> Result<StoreSettings, SettingsError> {
629        settings::read(&self.path, self.id)
630    }
631    fn bugs(&self) -> &BugSinkRef {
632        &self.bugs
633    }
634    async fn lock_for_open(&self) -> Result<StoreLock, StoreLockError> {
635        let guard = lock::acquire_for_open(&self.path, self.id, &self.bugs).await?;
636        self.check_published()?;
637        Ok(guard)
638    }
639    async fn lock_closed(&self) -> Result<ClosedStoreLock, StoreLockError> {
640        let guard = lock::acquire_closed(&self.path, self.id, &self.bugs).await?;
641        self.check_published()?;
642        Ok(guard)
643    }
644    fn lock_read_only(&self) -> Result<StoreReadLock, StoreLockError> {
645        let guard = lock::acquire_reader(&self.path, self.id)?;
646        self.check_published()?;
647        Ok(guard)
648    }
649    fn lock_cache_write(&self) -> Result<CacheWriteLock, FileError> {
650        lock::cache_writes(&self.path, true)
651    }
652    fn exclude_cache_writes(&self) -> Result<CacheWriteLock, FileError> {
653        lock::cache_writes(&self.path, false)
654    }
655    fn lock_for_deletion(&self) -> Result<Option<StoreDeletionLock>, StoreLockError> {
656        let bootstrapping = self.is_bootstrapping();
657        let locked = lock::for_deletion(&self.path, self.id, None);
658        // A marker beside a replacement record belongs to a swap under way,
659        // which deletion removes whole: both installations, the record and
660        // the replacement's directory. Alone, it belongs to a first
661        // installation, which only its own call resumes or cancels, whether
662        // or not that call is running and holding the bootstrap lock.
663        if !bootstrapping
664            && matches!(locked, Ok(Some(_)) | Err(StoreLockError::AlreadyOpen(_)))
665            && super::device_reset::read(&self.path)?.is_none()
666            && super::bootstrap::is_pending(&self.path)?
667        {
668            return Err(StoreLockError::BootstrapPending(self.id));
669        }
670        locked
671    }
672    async fn closed(&self) -> Result<(), FileError> {
673        lock::closed(&self.path, self.id).await?;
674        // A replacement loads in a hidden directory of its own, a lock
675        // instance apart from the store's. Dropping the call that loads it
676        // releases the store's locks at once, but leaves the loading
677        // database to close as its last holders end, its files open until
678        // then.
679        lock::closed(&super::device_reset::loading(&self.path, self.id), self.id).await
680    }
681    fn owned_file(&self, file: StoreFile) -> AtomicFile {
682        AtomicFile::new(self.path.join(file.name()))
683    }
684    fn file(&self, area: FileArea, name: &FileName) -> AtomicFile {
685        AtomicFile::new(self.path.join(area.name()).join(&name.0))
686    }
687    fn create_writer(&self, area: FileArea, name: &FileName) -> Result<FileWriter, WriterError> {
688        Ok(self.writer_folder(area)?.create(name)?)
689    }
690    fn writer_folder(&self, area: FileArea) -> Result<WriterFolder, WriterError> {
691        let lock = self.lock_read_only()?;
692        Ok(WriterFolder::open(&self.path.join(area.name()), Arc::new(lock), self.bugs.clone())?)
693    }
694    fn resume_writer(
695        &self,
696        area: FileArea,
697        name: &FileName,
698        length: u64,
699    ) -> Result<FileWriter, WriterError> {
700        let lock = self.lock_read_only()?;
701        Ok(FileWriter::resume(&self.file(area, name), lock, self.bugs.clone(), length)?)
702    }
703    fn staged_file(&self, name: &StagedName) -> AtomicFile {
704        let (folder, copy) = name.parts();
705        AtomicFile::new(self.path.join(FileArea::AppProvided.name()).join(folder).join(copy))
706    }
707    fn staging_folder(
708        &self,
709        folder: &FileName,
710        #[cfg_attr(
711            not(unix),
712            expect(unused_variables, reason = "Windows writes a folder's entries through")
713        )]
714        batch: &mut FlushBatch,
715    ) -> Result<WriterFolder, StagingFolderError> {
716        let lock = Arc::new(self.lock_read_only().map_err(WriterError::from)?);
717        let files = self.path.join(FileArea::AppProvided.name());
718        let path = files.join(&folder.0);
719        match std::fs::create_dir(&path) {
720            Ok(()) => {}
721            Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
722                return Err(StagingFolderError::Taken(folder.clone()));
723            }
724            Err(source) => {
725                let error = FileError::at("create staging folder", &path, source);
726                return Err(WriterError::from(error).into());
727            }
728        }
729        #[cfg(unix)]
730        batch.add_folder(
731            BatchFolder::open(files.clone(), Some(lock.clone())).map_err(|source| {
732                WriterError::from(FileError::at("open folder", &files, source))
733            })?,
734        );
735        Ok(WriterFolder::open(&path, lock, self.bugs.clone()).map_err(WriterError::from)?)
736    }
737    fn remove_staged(&self, name: &StagedName) -> Result<(), FileError> {
738        let copy = self.staged_file(name);
739        copy.remove()?;
740        let (folder, _) = name.parts();
741        super::atomic_file::remove_empty_folder(
742            &self.path.join(FileArea::AppProvided.name()).join(folder),
743        )
744    }
745}
746
747#[cfg(test)]
748#[path = "directory_tests.rs"]
749mod tests;