Skip to main content

coven_database/
file_database_copies.rs

1//! The records behind making cloud files device-only (§17.3): who may, the
2//! copies a call writes into the person's folder, recorded before any of
3//! their bytes exist, the write switching the call's files to them, and the
4//! removal of what a failing call made.
5
6use super::{BytesWriting, FileDatabase, StoreDatabase};
7use crate::sqlite::StoreSql;
8use crate::{DbError, DeviceOnlyCopy, FileRef};
9use coven_foundation::locks::lock_unpoisoned;
10use coven_foundation::task::{BugSinkRef, CarriesBug, TaskFailed};
11use coven_foundation::{
12    files::{Flushed, ObservedFile},
13    id_source::FileId,
14};
15use sqlive::rusqlite::params;
16use std::path::{Path, PathBuf};
17use std::sync::{Arc, Mutex};
18
19/// One copy a call to make files device-only writes (§17.3): its path, the
20/// temporary name in the same folder its bytes are written under, and the
21/// folders the call makes on its path.
22#[derive(Clone, Debug, PartialEq, Eq)]
23pub struct FolderCopy {
24    /// Where the copy goes.
25    pub path: PathBuf,
26    /// The name its bytes are written under until they are whole and synced.
27    pub temporary: PathBuf,
28    /// The folders the call makes that hold it, outermost first.
29    pub folders: Vec<PathBuf>,
30}
31
32impl FileDatabase {
33    /// Each file as its record stands, once this device may make it
34    /// device-only (§17.3): in the cloud, of a user namespace, in an
35    /// audience this device's member is in, and referenced by no row this
36    /// device's member may not change: a row of an `owner_only` table another
37    /// member created, or, unless the member is an admin, a row of an
38    /// `admin_only` table. Read in one committed
39    /// state; the write switching the files checks again.
40    pub async fn device_only_files(&self, files: Vec<FileId>) -> Result<Vec<FileRef>, DbError> {
41        self.database
42            .call(move |inner| {
43                inner.access.with_committed(|db, call| {
44                    files
45                        .iter()
46                        .map(|file| {
47                            crate::file_write::permitted(
48                                db,
49                                call,
50                                &inner.access.write_schema,
51                                inner.access.device,
52                                *file,
53                            )
54                            .and_then(FileRef::of)
55                        })
56                        .collect()
57                })
58            })
59            .await
60    }
61
62    /// Record the copies one call writes, before any of their folders or
63    /// bytes exist (`StoreDatabase::record_copies`). A path another call is
64    /// writing a copy at is `CopyPathTaken`; the returned reservation keeps
65    /// the copies from other writes' removals while it is held.
66    pub async fn record_copies(&self, copies: Vec<FolderCopy>) -> Result<CopyReservation, DbError> {
67        self.database.record_copies(copies).await
68    }
69
70    /// The call's own mkdir made `folder`: it is the call's to remove, once
71    /// empty. A folder that was there already is never marked.
72    pub async fn made_folder(&self, folder: &Path) -> Result<(), DbError> {
73        self.database.made_folder(folder).await
74    }
75
76    /// A copy is whole and synced at its path, renamed there from its
77    /// temporary name, with the size and modification time `observed` read.
78    pub async fn place_copy(&self, observed: &ObservedFile) -> Result<(), DbError> {
79        self.database.place_copy(observed).await
80    }
81
82    /// The copies a call placed, ready for the write that switches their
83    /// files to them (§17.3). It takes the flush of the batch the copies
84    /// were written in: they are on the drive before the commit that records
85    /// them (Appendix C.3).
86    pub fn prepared_device_only(
87        &self,
88        mut reservation: CopyReservation,
89        copies: Vec<DeviceOnlyCopy>,
90        _flushed: Flushed,
91    ) -> Result<PreparedDeviceOnly, DbError> {
92        // The copies stay reserved, now for the prepared call, which holds
93        // nothing close or a reopen waits for.
94        let _writing = reservation.writing.take();
95        let database = &self.database;
96        Ok(PreparedDeviceOnly { database: database.clone(), reservation, copies })
97    }
98
99    /// Remove what a failing call made: the copies at `paths` it left
100    /// unswitched, if they are as it left them, and the folders it made for
101    /// them, if they are empty. A failed removal keeps its record, and the
102    /// next open removes it.
103    pub async fn abandon_copies(&self, paths: Vec<PathBuf>) -> Result<(), DbError> {
104        let paths = paths
105            .iter()
106            .map(|path| text(path).map(str::to_owned))
107            .collect::<Result<Vec<_>, _>>()?;
108        self.database.abandon_copies(paths).await
109    }
110}
111
112impl StoreDatabase {
113    /// Record the copies one call writes, before any of their folders or
114    /// bytes exist, so a failure or a crash leaves nothing unrecorded. A path
115    /// another call is writing a copy at is `CopyPathTaken`. While the
116    /// returned reservation is held, no other write's removal takes the
117    /// copies; once it drops without the call's switch, as when the call's
118    /// future is dropped, the next write removes them (Appendix C.3). Until
119    /// the copies are prepared or it drops, closing the store waits for it,
120    /// and so does a reopen once the last handle drops.
121    pub(crate) async fn record_copies(
122        &self,
123        copies: Vec<FolderCopy>,
124    ) -> Result<CopyReservation, DbError> {
125        let paths = copies
126            .iter()
127            .map(|copy| text(&copy.path).map(str::to_owned))
128            .collect::<Result<Vec<_>, _>>()?;
129        let writing = BytesWriting::of(self).await;
130        self.call(move |inner| {
131            inner.access.with_writer(|writer, _| {
132                writer.transaction(|db: &StoreSql| {
133                    for copy in &copies {
134                        let path = text(&copy.path)?;
135                        if db.execute(
136                            "INSERT INTO _coven_copies(path,temporary,state) VALUES(?1,?2,'writing')
137                             ON CONFLICT(path) DO NOTHING",
138                            params![path, text(&copy.temporary)?],
139                        )? != 1
140                        {
141                            return Err(DbError::CopyPathTaken {
142                                path: copy.path.clone(),
143                            });
144                        }
145                        for folder in &copy.folders {
146                            db.execute(
147                                "INSERT INTO _coven_copy_folders(folder,copy) VALUES(?1,?2)",
148                                params![text(folder)?, path],
149                            )?;
150                        }
151                    }
152                    Ok(())
153                })?;
154                // Registered under the writer, so no write's removal
155                // runs between the records and the registration.
156                lock_unpoisoned(&inner.copying).extend(paths.iter().cloned());
157                Ok::<_, DbError>(())
158            })?;
159            Ok(CopyReservation {
160                names: Arc::new(CopyNames {
161                    copying: inner.copying.clone(),
162                    paths: Mutex::new(paths),
163                }),
164                writing: Some(Arc::new(writing)),
165            })
166        })
167        .await
168    }
169
170    /// The call's own mkdir made `folder`: it is the call's to remove, once
171    /// empty. A folder that was there already is never marked.
172    pub(crate) async fn made_folder(&self, folder: &Path) -> Result<(), DbError> {
173        let folder = text(folder)?.to_owned();
174        self.call(move |inner| {
175            inner.access.with_writer(|writer, _| {
176                writer.transaction(|db: &StoreSql| {
177                    db.execute("UPDATE _coven_copy_folders SET made=1 WHERE folder=?1", [&folder])?;
178                    Ok(())
179                })
180            })
181        })
182        .await
183    }
184
185    /// A copy is whole and synced at its path, renamed there from its
186    /// temporary name, with the size and modification time `observed` read.
187    pub(crate) async fn place_copy(&self, observed: &ObservedFile) -> Result<(), DbError> {
188        let path = text(observed.path())?.to_owned();
189        let size = crate::sqlite::integer("file size", observed.size())?;
190        let modified_at = crate::user_file::encode_time(observed.modified_at());
191        self.call(move |inner| {
192            inner.access.with_writer(|writer, _| {
193                writer.transaction(|db: &StoreSql| {
194                    if db.execute(
195                        "UPDATE _coven_copies SET state='placed',size=?2,modified_at=?3
196                         WHERE path=?1 AND state='writing'",
197                        params![path, size, modified_at],
198                    )? != 1
199                    {
200                        return Err(DbError::Invariant {
201                            what: "a copy placed is one its call is writing",
202                        });
203                    }
204                    Ok(())
205                })
206            })
207        })
208        .await
209    }
210
211    /// Remove what a failing call made: the copies at `paths` it left
212    /// unswitched, if they are as it left them, and the folders it made for
213    /// them, if they are empty, once the writer is free. A failed removal
214    /// keeps its record, and the next open removes it.
215    pub(crate) async fn abandon_copies(&self, paths: Vec<String>) -> Result<(), DbError> {
216        self.call(move |inner| {
217            let chosen = inner.access.with_writer(|writer, call| {
218                Ok::<_, DbError>(crate::file_removals::choose_copies(writer, call, &paths))
219            })?;
220            inner.finish_removals(Ok::<_, DbError>(()), chosen)
221        })
222        .await
223    }
224}
225
226/// Cloud files downloaded to copies in the person's folder, ready for one
227/// write to make them device-only here (§17.3, E8). It holds nothing close
228/// waits for. Committed by no write, its copies stay reserved while it is
229/// held, and the next write or open removes them once it drops; `abandon`
230/// removes them at once.
231pub struct PreparedDeviceOnly {
232    database: StoreDatabase,
233    reservation: CopyReservation,
234    copies: Vec<DeviceOnlyCopy>,
235}
236
237impl PreparedDeviceOnly {
238    /// The copies' paths, as the store reserving them records them.
239    pub(crate) fn paths(&self) -> Vec<String> {
240        lock_unpoisoned(&self.reservation.names.paths).clone()
241    }
242
243    /// The switches, and the copies' paths, for the write making them;
244    /// the reservation's release is the write's from here.
245    pub(crate) fn take(mut self) -> (Vec<DeviceOnlyCopy>, Vec<String>) {
246        let paths = std::mem::take(&mut *lock_unpoisoned(&self.reservation.names.paths));
247        (std::mem::take(&mut self.copies), paths)
248    }
249
250    /// Remove the copies, and the folders made for them, now, instead of
251    /// at the next write or open (§17.3). A failed removal keeps its record,
252    /// and the next open removes it.
253    pub async fn abandon(self) -> Result<(), DbError> {
254        let paths = self.paths();
255        let database = self.database.clone();
256        drop(self);
257        database.abandon_copies(paths).await
258    }
259}
260
261impl std::fmt::Debug for PreparedDeviceOnly {
262    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
263        f.debug_struct("PreparedDeviceOnly")
264            .field("copies", &self.copies.len())
265            .finish_non_exhaustive()
266    }
267}
268
269/// The copies one call to make files device-only is writing, which no other
270/// write's removal takes while it is held or a step it runs is under way.
271/// Once both end, whatever became of the call, the next write removes those
272/// its switch didn't keep.
273pub struct CopyReservation {
274    // The names go before the store the writing holds can close.
275    names: Arc<CopyNames>,
276    /// Held while the copies are written, until they are prepared.
277    writing: Option<Arc<BytesWriting>>,
278}
279
280impl CopyReservation {
281    /// Run `work`, a step of the call named `operation` that makes a name in
282    /// the person's folder, as its own task, holding the call's copies, so
283    /// it runs to its end with its record though the call is dropped
284    /// meanwhile: until it ends, no write's removal takes the call's copies,
285    /// and closing the store waits for it (§17.3). Its panic comes back to a
286    /// caller still waiting, and goes to `bugs` once none is (E15).
287    pub async fn run_step<T: Send + 'static, E: CarriesBug + Send + 'static>(
288        &self,
289        operation: &'static str,
290        bugs: BugSinkRef,
291        work: impl std::future::Future<Output = Result<T, E>> + Send + 'static,
292    ) -> Result<Result<T, E>, TaskFailed> {
293        // The names go before the store the writing holds can close.
294        let held = (self.names.clone(), self.writing.clone());
295        let stepped = coven_foundation::task::spawn_completing(operation, bugs, async move {
296            // Declared first, so it goes last as a panic unwinds the work.
297            let held = held;
298            // A value comes back with the hold, so whatever it keeps open,
299            // such as a copy's file, closes before the hold goes, also when
300            // no caller waits for it any more.
301            work.await.map(|value| (value, held))
302        })
303        .await?;
304        Ok(stepped.map(|(value, _held)| value))
305    }
306}
307
308/// The copies one call is writing, kept out of removals until the last of
309/// its reservation and the steps it runs drops.
310struct CopyNames {
311    /// The copies the store that recorded them keeps out of removals; a
312    /// closed store's records stay for its next open.
313    copying: Arc<Mutex<std::collections::BTreeSet<String>>>,
314    /// Until a write takes them to release once it has decided.
315    paths: Mutex<Vec<String>>,
316}
317
318impl Drop for CopyNames {
319    fn drop(&mut self) {
320        crate::database::release_copies(&self.copying, &lock_unpoisoned(&self.paths));
321    }
322}
323
324/// The call's copy at `path` is placed and its file switched to it: the
325/// copy is an original this device records (§17.3).
326pub(crate) fn keep(db: &StoreSql, path: &str) -> Result<(), DbError> {
327    db.execute("UPDATE _coven_copies SET state='kept' WHERE path=?1", [path])?;
328    Ok(())
329}
330
331/// The kept copy at the original's `path` lost its switch to another
332/// device's, unless another of this device's files is recorded there: it is
333/// recorded for removal (Appendix C.3).
334pub(crate) fn lose(db: &StoreSql, path: &[u8], file: FileId) -> Result<(), DbError> {
335    db.execute(
336        "UPDATE _coven_copies SET state='lost' WHERE path=CAST(?1 AS TEXT) AND state='kept'
337         AND NOT EXISTS(SELECT 1 FROM _coven_user_files WHERE path=?1 AND file!=?2)",
338        params![path, file],
339    )?;
340    Ok(())
341}
342
343/// The copy at `path`, recorded as `state`, is removed; its folder links go
344/// with it.
345pub(crate) fn forget(db: &StoreSql, path: &str, state: &str) -> Result<(), DbError> {
346    db.execute("DELETE FROM _coven_copies WHERE path=?1 AND state=?2", (path, state))?;
347    Ok(())
348}
349
350/// A path as coven records it: valid Unicode, as planning a copy checks.
351pub(crate) fn text(path: &Path) -> Result<&str, DbError> {
352    path.to_str().ok_or(DbError::Invariant { what: "a copy's path is valid Unicode" })
353}
354
355#[cfg(test)]
356#[path = "file_database_copies_tests.rs"]
357pub(crate) mod tests;