Skip to main content

coven_foundation/files/
layout.rs

1//! The stores under an app directory, and publication of a new device's store.
2
3use std::fs;
4use std::io;
5use std::path::PathBuf;
6
7#[cfg(any(test, feature = "in-memory-keychain"))]
8use crate::files::DirectoryCreationError;
9
10use crate::files::protection::Protection;
11use crate::files::{
12    settings, BootstrapDirectoryError, FileError, SettingsError, StoreDeletionLock, StoreDir,
13    StoreDirAccess, StoreLockError,
14};
15use crate::id_source::{IdSource, StoreId};
16use crate::task::BugSinkRef;
17
18/// A store directory as the listing found it, and whether its settings
19/// read (E1).
20#[derive(Debug)]
21pub struct ListedDirectory {
22    /// The store the directory's name gives.
23    pub id: StoreId,
24    /// Why its settings can't be read: missing, corrupt, another store's,
25    /// or not a regular file.
26    pub settings: Result<(), SettingsError>,
27}
28
29/// The stores under `app_dir`, one directory each (E1).
30#[cfg_attr(
31    not(feature = "test-utils"),
32    doc = r#"
33Directory-only creation is a test fixture.
34```compile_fail
35use coven_foundation::{files::StoreDirectories, id_source::{StoreId, UuidIds, IdSource}};
36let layout = StoreDirectories::new("stores".into(), std::sync::Arc::new(coven_foundation::task::LoggedBugs));
37let _ = layout.create_store_dir(StoreId(UuidIds.new_id()), &UuidIds);
38```"#
39)]
40#[derive(Clone)]
41pub struct StoreDirectories {
42    app_dir: PathBuf,
43    /// The class every store's files take, where the app chose one.
44    protection: Protection,
45    /// Where a bug in work nobody waits for goes, for every store here
46    /// (E15): the app's own reporter.
47    bugs: BugSinkRef,
48}
49
50impl std::fmt::Debug for StoreDirectories {
51    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
52        f.debug_struct("StoreDirectories")
53            .field("app_dir", &self.app_dir)
54            .field("protection", &self.protection)
55            .finish_non_exhaustive()
56    }
57}
58
59/// Which of the store directories a listing reads.
60#[derive(Clone, Copy, Debug, PartialEq, Eq)]
61enum Installations {
62    /// Published stores, including those whose replacement is unfinished.
63    Published,
64    /// Stores whose first installation on this device hasn't been published.
65    UnfinishedFirst,
66}
67
68impl StoreDirectories {
69    /// The stores under `app_dir`, one directory each (E1). The app creates
70    /// `app_dir`; coven creates directories only inside it. A bug in work
71    /// nobody waits for, in any of the stores, goes to `bugs` (E15).
72    pub fn new(app_dir: PathBuf, bugs: BugSinkRef) -> Self {
73        Self { app_dir, protection: Protection::none(), bugs }
74    }
75
76    /// Where a bug in work nobody waits for goes, for every store here
77    /// (E15).
78    pub fn bugs(&self) -> &BugSinkRef {
79        &self.bugs
80    }
81
82    /// Give the files of every store these directories create, restore,
83    /// join, replace or open for writing Apple's protection class
84    /// `protection` (E1). On a volume that keeps no classes each of those
85    /// fails before any file changes. Without it, files keep the class they
86    /// have, and new ones take their folder's.
87    #[cfg(target_vendor = "apple")]
88    pub fn file_protection(mut self, protection: crate::files::FileProtection) -> Self {
89        self.protection = Protection::new(protection);
90        self
91    }
92
93    /// The folder that holds one directory per store.
94    fn stores(&self) -> PathBuf {
95        self.app_dir.join("stores")
96    }
97
98    /// The store directories on this device, ordered by id (E1), including
99    /// those whose replacement is unfinished, but no unpublished first
100    /// installation, each with whether its settings read. Only directories
101    /// with a canonical UUID name are listed; the settings of one that don't
102    /// read (missing, corrupt, another store's, not a regular file) come back
103    /// as why, so the caller lists the store as unreadable instead of
104    /// losing it. Filesystem failures are errors.
105    pub async fn store_listing(&self) -> Result<Vec<ListedDirectory>, FileError> {
106        self.listed(Installations::Published).await
107    }
108
109    /// The stores whose first installation on this device is unfinished, a
110    /// restore or a join that hasn't loaded, ordered by id (§19.1). A store
111    /// whose replacement is unfinished is listed by `store_listing` instead.
112    /// One whose settings don't read fails the call with `Settings`: it is
113    /// neither resumable nor reclaimable until it is discarded.
114    pub async fn unfinished_first_installations(
115        &self,
116    ) -> Result<Vec<StoreId>, BootstrapDirectoryError> {
117        let mut stores = Vec::new();
118        for listed in self.listed(Installations::UnfinishedFirst).await? {
119            match listed.settings {
120                Ok(()) => stores.push(listed.id),
121                Err(SettingsError::File(error)) => return Err(error.into()),
122                Err(SettingsError::Bug(bug)) => return Err(bug.into()),
123                Err(source) => {
124                    return Err(BootstrapDirectoryError::Settings { store: listed.id, source })
125                }
126            }
127        }
128        Ok(stores)
129    }
130
131    /// The ids `store_listing` lists whose settings read.
132    #[cfg(test)]
133    pub(crate) async fn readable_store_ids(&self) -> Result<Vec<StoreId>, FileError> {
134        Ok(self
135            .store_listing()
136            .await?
137            .into_iter()
138            .filter_map(|listed| listed.settings.ok().map(|()| listed.id))
139            .collect())
140    }
141
142    /// Lock an unfinished first installation for deletion while no call holds
143    /// it: no restore or join, in this process or another, holds its
144    /// bootstrap lock, and one closing in this process has been waited for.
145    /// `None` when a call holds it, or it is no longer an unfinished first
146    /// installation: published, being replaced, or gone. Whether anything
147    /// still refers to it, a join's saved code or a restore's record, is for
148    /// the caller to read while it holds the lock, since no call can begin on
149    /// the installation meanwhile (§13.4, §11.6).
150    pub async fn lock_unfinished_first(
151        &self,
152        id: StoreId,
153    ) -> Result<Option<StoreDeletionLock>, BootstrapDirectoryError> {
154        self.store_dir(&id).closed().await?;
155        let path = self.stores().join(id.to_string());
156        crate::task::blocking_completing(
157            "lock an unfinished installation",
158            self.bugs.clone(),
159            move || {
160                let lock = match super::lock::for_deletion(&path, id, None) {
161                    Ok(Some(lock)) => lock,
162                    // A call holds it, or nothing of it is left.
163                    Ok(None) | Err(StoreLockError::AlreadyOpen(_)) => return Ok(None),
164                    Err(error) => return Err(BootstrapDirectoryError::from(error)),
165                };
166                let first = super::bootstrap::is_pending(&path)?
167                    && super::device_reset::read(&path)?.is_none();
168                Ok(first.then_some(lock))
169            },
170        )
171        .await
172        .map_err(FileError::from)?
173    }
174
175    /// The stores whose deletion from this device is recorded and
176    /// unfinished, ordered by id: a directory under its deletion name, or the
177    /// store's writer or reader lock file with no directory. A deletion's
178    /// first step renames the store's directory, so either is what a cut
179    /// deletion leaves (E1).
180    pub async fn recorded_deletions(&self) -> Result<Vec<StoreId>, FileError> {
181        let root = self.stores();
182        crate::task::blocking_completing("list recorded deletions", self.bugs.clone(), move || {
183            recorded_deletions(&root)
184        })
185        .await?
186    }
187
188    /// Whether the deletion of the store with `id` is recorded and
189    /// unfinished, as `recorded_deletions` reads it.
190    pub async fn deletion_recorded(&self, id: StoreId) -> Result<bool, FileError> {
191        let published = self.stores().join(id.to_string());
192        crate::task::blocking_completing(
193            "inspect a recorded deletion",
194            self.bugs.clone(),
195            move || deletion_recorded(&published, id),
196        )
197        .await?
198    }
199
200    async fn listed(
201        &self,
202        installations: Installations,
203    ) -> Result<Vec<ListedDirectory>, FileError> {
204        let layout = self.clone();
205        let bugs = self.bugs.clone();
206        crate::task::blocking_completing("list stores", bugs, move || {
207            layout.list_stores(installations)
208        })
209        .await?
210    }
211
212    fn list_stores(&self, installations: Installations) -> Result<Vec<ListedDirectory>, FileError> {
213        let root = self.stores();
214        let entries = match fs::read_dir(&root) {
215            Ok(entries) => entries,
216            Err(error) if error.kind() == io::ErrorKind::NotFound => {
217                tracing::debug!(path = %root.display(), "stores directory is absent");
218                return Ok(Vec::new());
219            }
220            Err(source) => return Err(FileError::at("list store directories", &root, source)),
221        };
222        let mut stores = Vec::new();
223        for entry in entries {
224            let entry = entry
225                .map_err(|source| FileError::at("read store directory entry", &root, source))?;
226            let path = entry.path();
227            if !entry
228                .file_type()
229                .map_err(|source| FileError::at("inspect store directory", &path, source))?
230                .is_dir()
231            {
232                tracing::debug!(path = %path.display(), "entry is not a store directory");
233                continue;
234            }
235            let name = entry.file_name();
236            let id = match name.to_str().map(crate::id_source::canonical_uuid) {
237                Some(Ok(id)) => StoreId(id),
238                _ => {
239                    tracing::debug!(path = %path.display(), "directory name is not a store id");
240                    continue;
241                }
242            };
243            // A first installation stays hidden from the stores until
244            // published; a store whose replacement is unfinished lists, so
245            // the app can finish it.
246            let first =
247                super::bootstrap::is_pending(&path)? && super::device_reset::read(&path)?.is_none();
248            if first != (installations == Installations::UnfinishedFirst) {
249                tracing::debug!(path = %path.display(), first, "store is not in this listing");
250                continue;
251            }
252            // A settings file that doesn't read lists its store with why; a
253            // file error or a bug fails the listing.
254            let settings = match settings::read(&path, id) {
255                Ok(_) => Ok(()),
256                Err(SettingsError::File(error)) => return Err(error),
257                Err(SettingsError::Bug(bug)) => return Err(FileError::Bug(bug)),
258                Err(error) => Err(error),
259            };
260            stores.push(ListedDirectory { id, settings });
261        }
262        stores.sort_by_key(|listed| listed.id);
263        Ok(stores)
264    }
265
266    /// The directory of the store with `id` (E1). This does not create it,
267    /// read settings, or acquire the writer's lock.
268    pub fn store_dir(&self, id: &StoreId) -> StoreDir {
269        StoreDir::new(self.stores().join(id.to_string()), *id, self.protection, self.bugs.clone())
270    }
271
272    /// Publish a directory fixture without initializing member custody.
273    #[cfg(any(test, feature = "in-memory-keychain"))]
274    pub fn create_store_dir(
275        &self,
276        id: StoreId,
277        ids: &dyn IdSource,
278    ) -> Result<StoreDir, DirectoryCreationError> {
279        crate::files::creation::create(
280            &self.stores(),
281            id,
282            ids,
283            false,
284            self.protection,
285            self.bugs.clone(),
286        )
287    }
288}
289
290/// Whether a deletion of the store whose published directory is `published`
291/// is recorded: its directory under the deletion name, or, with no directory
292/// at all, its writer or reader lock file.
293fn deletion_recorded(published: &std::path::Path, id: StoreId) -> Result<bool, FileError> {
294    use super::atomic_file::exists;
295    // Creation refuses an id while its deletion's remains are there, so a
296    // published directory has none beside it.
297    if exists("inspect a store", published)? {
298        return Ok(false);
299    }
300    if exists("inspect a store's deletion", &super::lock::deletion_path(published, id))? {
301        return Ok(true);
302    }
303    for path in super::lock::lock_paths(published, id) {
304        if exists("inspect a store's lock", &path)? {
305            return Ok(true);
306        }
307    }
308    Ok(false)
309}
310
311fn recorded_deletions(root: &std::path::Path) -> Result<Vec<StoreId>, FileError> {
312    let entries = match fs::read_dir(root) {
313        Ok(entries) => entries,
314        Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(Vec::new()),
315        Err(source) => return Err(FileError::at("list store directories", root, source)),
316    };
317    let mut named = std::collections::BTreeSet::new();
318    for entry in entries {
319        let entry =
320            entry.map_err(|source| FileError::at("read store directory entry", root, source))?;
321        let name = entry.file_name();
322        let Some(name) = name.to_str() else {
323            tracing::debug!(name = ?name, "entry name is not UTF-8, so no store's");
324            continue;
325        };
326        // The names a deletion leaves: `.coven-delete-<id>`, `.<id>.lock` and
327        // `.<id>.readers.lock`.
328        let id = name
329            .strip_prefix(".coven-delete-")
330            .or_else(|| name.strip_prefix('.').and_then(|rest| rest.strip_suffix(".readers.lock")))
331            .or_else(|| name.strip_prefix('.').and_then(|rest| rest.strip_suffix(".lock")));
332        if let Some(Ok(id)) = id.map(crate::id_source::canonical_uuid) {
333            named.insert(StoreId(id));
334        }
335    }
336    let mut recorded = Vec::new();
337    for id in named {
338        if deletion_recorded(&root.join(id.to_string()), id)? {
339            recorded.push(id);
340        }
341    }
342    Ok(recorded)
343}
344
345impl StoreDirectories {
346    /// Reserve a hidden, restartable new-device store. A second attempt for the
347    /// same id waits for a dropped bootstrap's remaining work to release its
348    /// locks; a live bootstrap still refuses it. Ordinary store listings exclude
349    /// it until `BootstrapStore::publish` succeeds.
350    pub async fn begin_bootstrap(
351        &self,
352        id: StoreId,
353        ids: &dyn IdSource,
354    ) -> Result<super::BootstrapStore, super::BootstrapDirectoryError> {
355        super::bootstrap::reserve_bootstrap_directory(
356            &self.stores(),
357            id,
358            ids,
359            self.protection,
360            self.bugs.clone(),
361        )
362        .await
363    }
364
365    /// Replace the installation of a published store, or continue a
366    /// replacement under way: hold the store's bootstrap and writer locks, so
367    /// no handle opens it meanwhile, and load the new installation in a
368    /// hidden directory inside the store's directory (§19.3). A recorded
369    /// replacement continues its load, and a swap under way finishes. One
370    /// that the other call began is refused with
371    /// `StoreLockError::ReplacementUnfinished`, changing nothing.
372    pub async fn begin_replacement(
373        &self,
374        id: StoreId,
375        by: super::ReplacedBy,
376        registration: super::Registration,
377        ids: &dyn IdSource,
378    ) -> Result<super::ReplacementStore, super::BootstrapDirectoryError> {
379        super::replacement::begin(
380            &self.stores(),
381            id,
382            by,
383            registration,
384            ids,
385            self.protection,
386            self.bugs.clone(),
387        )
388        .await
389    }
390}
391
392#[cfg(test)]
393#[path = "layout_tests.rs"]
394mod tests;