Skip to main content

coven_foundation/files/
bootstrap.rs

1//! Hidden stores retain interrupted bootstrap work until explicit retry or
2//! cancellation, or until a listing reclaims one nothing refers to.
3
4use super::{
5    atomic_file::exists, creation, device_reset, lock, protection::Protection,
6    DirectoryCreationError, FileError, SettingsError, StoreDir, StoreLockError,
7};
8use crate::files::StoreDirAccess;
9use crate::id_source::{IdSource, StoreId};
10use crate::locks::lock_unpoisoned;
11use std::{
12    fs, io,
13    path::{Path, PathBuf},
14    sync::Mutex,
15};
16
17/// Filesystem failures while reserving, publishing or cancelling a new device.
18#[derive(Debug, thiserror::Error)]
19pub enum BootstrapDirectoryError {
20    /// A store already exists or preparing its directory failed.
21    #[error(transparent)]
22    Create(#[from] DirectoryCreationError),
23    /// Another bootstrap or an open database prevents this operation.
24    #[error(transparent)]
25    Lock(StoreLockError),
26    /// A filesystem operation failed.
27    #[error(transparent)]
28    File(FileError),
29    /// An unfinished first installation's settings can't be read: missing,
30    /// corrupt, another store's, or not a regular file. Nothing of it can be
31    /// resumed or listed until the person discards it.
32    #[error("store {store}: {source}")]
33    Settings {
34        /// The installation's store.
35        store: StoreId,
36        /// Why its settings can't be read.
37        source: SettingsError,
38    },
39    /// The work panicked on the blocking pool: a bug, which the caller
40    /// reports (E15).
41    #[error(transparent)]
42    Bug(#[from] crate::task::Bug),
43}
44
45impl From<StoreLockError> for BootstrapDirectoryError {
46    fn from(error: StoreLockError) -> Self {
47        match error {
48            StoreLockError::Bug(bug) => Self::Bug(bug),
49            error => Self::Lock(error),
50        }
51    }
52}
53
54impl From<FileError> for BootstrapDirectoryError {
55    fn from(error: FileError) -> Self {
56        match error {
57            FileError::Bug(bug) => Self::Bug(bug),
58            error => Self::File(error),
59        }
60    }
61}
62
63impl crate::task::CarriesBug for BootstrapDirectoryError {
64    fn bug(&self) -> Option<&crate::task::Bug> {
65        match self {
66            Self::Bug(bug) => Some(bug),
67            Self::File(error) => error.bug(),
68            Self::Create(creation) => creation.bug(),
69            Self::Lock(error) => error.bug(),
70            Self::Settings { source, .. } => source.bug(),
71        }
72    }
73}
74
75impl BootstrapDirectoryError {
76    /// The protected file the lock refused, when the device is locked and
77    /// the store's chosen class keeps its files closed (api.md E1).
78    pub fn device_locked(&self) -> Option<&std::path::Path> {
79        let file = match self {
80            Self::File(file) => file,
81            Self::Create(creation) => creation.file()?,
82            Self::Lock(_) | Self::Settings { .. } | Self::Bug(_) => return None,
83        };
84        match file {
85            FileError::DeviceLocked { path } => Some(path),
86            _ => None,
87        }
88    }
89
90    /// The store is already visible, and only syncing its parent directory
91    /// failed.
92    pub fn published_unsynced(&self) -> bool {
93        matches!(self, Self::Create(DirectoryCreationError::Published { .. }))
94    }
95}
96
97/// An unpublished store at its permanent path, protected by a bootstrap lease.
98/// Dropping preserves resumable work; `cancel` removes it after its database
99/// closes. Publication removes the marker without moving any open files.
100pub struct BootstrapStore {
101    // Drops before the lease: the store's locks are closing before the
102    // bootstrap lock is released, so a call resuming the store waits for a
103    // writer the bootstrap's database may still hold.
104    _closing: lock::StoreClosingGuard,
105    path: PathBuf,
106    id: StoreId,
107    lease: BootstrapLease,
108    protection: Protection,
109    bugs: crate::task::BugSinkRef,
110    /// Whether the directory was there before this call: an earlier call's
111    /// installation, not a new one.
112    resumed: bool,
113}
114
115/// The bootstrap lock, which the bootstrap or replacement that took it holds
116/// alone until it publishes, cancels or is dropped. Its directories name the
117/// lock's instance and open the unpublished store only while it holds it.
118#[derive(Debug)]
119pub(super) struct BootstrapLease {
120    held: Mutex<Option<lock::RegisteredLock>>,
121    instance: lock::LockInstance,
122}
123
124impl BootstrapLease {
125    pub(super) fn new(lock: lock::RegisteredLock) -> Self {
126        Self { instance: lock.instance(), held: Mutex::new(Some(lock)) }
127    }
128
129    pub(super) fn instance(&self) -> lock::LockInstance {
130        self.instance
131    }
132
133    pub(super) fn release(&self) {
134        lock_unpoisoned(&self.held).take();
135    }
136}
137
138impl BootstrapStore {
139    /// The unpublished directory, which opens the store while this bootstrap
140    /// holds its lock.
141    pub fn directory(&self) -> StoreDir {
142        StoreDir::bootstrapping(
143            self.path.clone(),
144            self.id,
145            self.lease.instance(),
146            self.protection,
147            self.bugs.clone(),
148        )
149    }
150
151    /// Whether the installation was left by an earlier call, rather than made
152    /// by this one.
153    pub fn resumed(&self) -> bool {
154        self.resumed
155    }
156
157    /// Publish the loaded, open store by removing its durable marker.
158    /// After a `Create(Published { .. })` error it is already visible.
159    pub fn publish(&self) -> Result<(), BootstrapDirectoryError> {
160        let _reader = self.directory().lock_read_only()?;
161        let published = |source: io::Error| -> BootstrapDirectoryError {
162            DirectoryCreationError::Published { id: self.id, source }.into()
163        };
164        let result = remove_marker(&self.path, published);
165        self.lease.release();
166        result
167    }
168
169    /// Whether the store is published: its marker is gone. After a panic
170    /// in a publication, this says how far it got.
171    pub fn is_published(&self) -> Result<bool, FileError> {
172        Ok(!is_pending(&self.path)?)
173    }
174
175    /// Remove unpublished data and locks after all database work has closed.
176    /// An absent directory succeeds; a published store cannot be cancelled.
177    pub fn cancel(&self) -> Result<(), BootstrapDirectoryError> {
178        let mut held = lock_unpoisoned(&self.lease.held);
179        let guard = self.lock_for_deletion(&mut held)?;
180        if exists("inspect bootstrap path", &self.path)? && !is_pending(&self.path)? {
181            return Err(DirectoryCreationError::AlreadyExists(self.id).into());
182        }
183        if let Some(guard) = guard {
184            guard.remove_directory()?;
185        }
186        held.take();
187        Ok(())
188    }
189
190    /// Lock the store for deletion, handing the deletion the bootstrap lock
191    /// `held` while this bootstrap holds it. Once it has published, the
192    /// deletion takes the lock itself, as any deletion does.
193    fn lock_for_deletion(
194        &self,
195        held: &mut Option<lock::RegisteredLock>,
196    ) -> Result<Option<super::StoreDeletionLock>, StoreLockError> {
197        if held.is_some() {
198            lock::for_deletion(&self.path, self.id, Some(held))
199        } else {
200            self.directory().lock_for_deletion()
201        }
202    }
203}
204
205/// The file whose presence keeps a store unpublished.
206pub(super) const MARKER: &str = ".coven-bootstrap";
207
208pub(super) fn marker(directory: &Path) -> PathBuf {
209    directory.join(MARKER)
210}
211
212/// Remove the marker; only a failure syncing its directory leaves the store
213/// visible, which `published` reports.
214pub(super) fn remove_marker(
215    directory: &Path,
216    published: impl Fn(io::Error) -> BootstrapDirectoryError,
217) -> Result<(), BootstrapDirectoryError> {
218    match super::atomic_file::remove(&marker(directory)) {
219        // Directory removal retains the IO error from syncing its parent.
220        Ok(()) => Ok(()),
221        Err(FileError::AfterRemove { source, .. }) => Err(published(
222            *source.downcast::<io::Error>().expect("directory removal retains its IO cause"),
223        )),
224        Err(error) => Err(error.into()),
225    }
226}
227
228pub(super) fn is_pending(directory: &Path) -> Result<bool, FileError> {
229    exists("inspect bootstrap path", &marker(directory))
230}
231
232pub(super) async fn reserve_bootstrap_directory(
233    root: &Path,
234    id: StoreId,
235    ids: &dyn IdSource,
236    protection: Protection,
237    bugs: crate::task::BugSinkRef,
238) -> Result<BootstrapStore, BootstrapDirectoryError> {
239    creation::create_directory(root)
240        .map_err(|source| FileError::at("create bootstrap layout", root, source))?;
241    let root = fs::canonicalize(root)
242        .map_err(|source| FileError::at("resolve bootstrap layout", root, source))?;
243    let path = root.join(id.to_string());
244    let lock = lock::acquire_bootstrap(&path, id, &bugs).await?;
245    let closing = lock.closing_guard();
246    let lease = BootstrapLease::new(lock);
247    let resumed = exists("inspect bootstrap path", &path)?;
248    if !resumed {
249        creation::create(&root, id, ids, true, protection, bugs.clone())?;
250    }
251    let metadata = fs::symlink_metadata(&path)
252        .map_err(|source| FileError::at("inspect unpublished store", &path, source))?;
253    if !metadata.is_dir() {
254        return Err(FileError::at(
255            "inspect unpublished store",
256            &path,
257            io::Error::new(io::ErrorKind::InvalidInput, "unpublished store is not a directory"),
258        )
259        .into());
260    }
261    // A published or interrupted installation may still have a live writer,
262    // including one in another process. Refuse it before inspecting its data.
263    let _writer = lock::acquire_for_open(&path, id, &bugs).await?;
264    // A store in the middle of a swap is finished by the call that began it.
265    if let Some(record) =
266        device_reset::unfinished(&path, id).map_err(DirectoryCreationError::Settings)?
267    {
268        return Err(StoreLockError::ReplacementUnfinished { store: id, by: record.by }.into());
269    }
270    if !is_pending(&path)? {
271        return Err(DirectoryCreationError::AlreadyExists(id).into());
272    }
273    // Neither lock's holder is writing: a dropped call's saves ran inside it.
274    super::atomic_file::remove_temporaries(&path)?;
275    // A resumed installation may have been made with another class (E1).
276    protection.apply(&path)?;
277    let store = BootstrapStore { _closing: closing, path, id, lease, protection, bugs, resumed };
278    store.directory().settings().map_err(DirectoryCreationError::Settings)?;
279    Ok(store)
280}
281
282#[cfg(test)]
283#[path = "bootstrap_tests.rs"]
284mod tests;