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(©.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(©.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(©.temporary)?],
139 )? != 1
140 {
141 return Err(DbError::CopyPathTaken {
142 path: copy.path.clone(),
143 });
144 }
145 for folder in ©.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;