Skip to main content

coven_sync/
file_device_only.rs

1//! Preparing cloud files to be made device-only on this device (§17.3):
2//! download each to the path the app names under the folder the person
3//! picked, reporting how far the downloads have come, for the write that
4//! switches them all to this device. A prepare that fails leaves nothing
5//! behind.
6
7use crate::files::Files;
8use crate::FileReadError;
9use coven_database::{
10    CopyReservation, DbError, DeviceOnlyCopy, FileHasher, FilePlace, FileRef, FolderCopy,
11    PreparedDeviceOnly,
12};
13use coven_foundation::{
14    files::{CopyFolder, CopyPathError, FileError, FileLease, FlushBatch, Flushed, RelativePath},
15    id_source::FileId,
16    progress::{Progress, ProgressReport},
17};
18use std::path::{Path, PathBuf};
19use std::sync::Arc;
20use tokio::sync::watch;
21
22/// A step of preparing files to be made device-only (§17.3, E8), which a
23/// host draws a bar for: one step for each file downloaded, in order. Done
24/// and total count the file's bytes; done plus `before`, out of `all`, is how
25/// far the whole call has come.
26#[derive(Clone, Copy, Debug, PartialEq, Eq)]
27pub enum DeviceOnlyStep {
28    /// Downloading one file to its copy.
29    Downloading {
30        /// The file.
31        file: FileId,
32        /// The bytes of the files downloaded before it.
33        before: u64,
34        /// The bytes of every file the call downloads.
35        all: u64,
36    },
37}
38
39/// Why no file of a call was made device-only (E8). Whatever the call made
40/// is removed before it returns, or, if removing it failed too, at the next
41/// open.
42#[derive(Debug, thiserror::Error)]
43pub enum DeviceOnlyError {
44    /// The call names one file twice.
45    #[error("file {file} is named twice")]
46    RepeatedFile {
47        /// The file.
48        file: FileId,
49    },
50    /// A copy can't go where the app named it.
51    #[error(transparent)]
52    Path(CopyPathError),
53    /// This device may not make a file device-only, or the write switching
54    /// them failed: no record of the file here (`FileAbsent`), as for a
55    /// file of a circle this member was never in; one not in the cloud
56    /// (`NotInCloud`); an app file (`NamespaceKind`); a file of a circle
57    /// this member has left (`NotInCircle`); another member's row of an
58    /// `owner_only` table referencing it (`NotOwner`); or, for a member who
59    /// isn't an admin, a row of an `admin_only` table referencing it
60    /// (`NotAdmin`).
61    #[error(transparent)]
62    Database(DbError),
63    /// Downloading a file failed.
64    #[error("downloading file {file} failed: {error}")]
65    Download {
66        /// The file.
67        file: FileId,
68        /// The read's failure.
69        #[source]
70        error: FileReadError,
71    },
72    /// Writing a folder or a copy failed.
73    #[error(transparent)]
74    Disk(FileError),
75    /// The app cancelled the call before its files switched.
76    #[error("cancelled")]
77    Cancelled,
78    /// Removing what the call made failed too. What stays is recorded, and
79    /// the next open removes it.
80    #[error("{error}; removing the copies failed: {cleanup}")]
81    Cleanup {
82        /// The call's failure.
83        error: Box<DeviceOnlyError>,
84        /// The removal's.
85        #[source]
86        cleanup: DbError,
87    },
88    /// The call's work panicked: a bug, which the caller reports (E15).
89    #[error(transparent)]
90    Bug(#[from] coven_foundation::task::Bug),
91}
92
93impl From<CopyPathError> for DeviceOnlyError {
94    fn from(error: CopyPathError) -> Self {
95        match error {
96            CopyPathError::Bug(bug) => Self::Bug(bug),
97            error => Self::Path(error),
98        }
99    }
100}
101
102impl From<DbError> for DeviceOnlyError {
103    fn from(error: DbError) -> Self {
104        match error {
105            DbError::Bug(bug) => Self::Bug(bug),
106            error => Self::Database(error),
107        }
108    }
109}
110
111impl From<FileError> for DeviceOnlyError {
112    fn from(error: FileError) -> Self {
113        match error {
114            FileError::Bug(bug) => Self::Bug(bug),
115            error => Self::Disk(error),
116        }
117    }
118}
119
120impl coven_foundation::task::CarriesBug for DeviceOnlyError {
121    fn bug(&self) -> Option<&coven_foundation::task::Bug> {
122        match self {
123            Self::Bug(bug) => Some(bug),
124            Self::Path(error) => error.bug(),
125            Self::Database(error) => error.bug(),
126            Self::Download { error, .. } => error.bug(),
127            Self::Disk(error) => error.bug(),
128            Self::Cleanup { error, cleanup } => error.bug().or_else(|| cleanup.bug()),
129            Self::RepeatedFile { .. } | Self::Cancelled => None,
130        }
131    }
132}
133
134impl Files {
135    /// Download each cloud file to its path under `folder`, for one write
136    /// to switch them all to this device only, each copy becoming the
137    /// original this device records (§17.3). Each download checks the
138    /// file's content hash, and each copy is written under a temporary name
139    /// in its final folder and renamed once synced. Each name is written as
140    /// the one rule for every platform makes it, which keeps it inside the
141    /// folder. A path through a symbolic link below the folder, where
142    /// something is already, or naming what another path names once
143    /// written, case and Unicode form aside, is refused. `progress` hears
144    /// each file's download and how many of its bytes, and of the call's,
145    /// are down. Until it returns, `cancel` stops the call; a failure, a
146    /// panic in a download among them, or a cancel removes every copy and
147    /// folder the call made. The call waits once for a place of the app's
148    /// budget, before it holds anything, and reads each file's stream in it
149    /// in turn; its copy's writer is outside the budget (§17.3).
150    pub async fn prepare_device_only(
151        &self,
152        folder: &Path,
153        files: Vec<(FileId, RelativePath)>,
154        cancel: &watch::Receiver<bool>,
155        progress: watch::Sender<Option<Progress<DeviceOnlyStep>>>,
156    ) -> Result<PreparedDeviceOnly, DeviceOnlyError> {
157        self.inner.check_open()?;
158        // One wait for the place every file's stream takes in turn, before
159        // the call holds anything else; a cancel ends it.
160        let mut cancel = cancel.clone();
161        let lease = tokio::select! {
162            biased;
163            () = cancelled(&mut cancel) => return Err(DeviceOnlyError::Cancelled),
164            lease = self.inner.files.lease(1) => lease.expect("a budget has at least one place"),
165        };
166        let mut ids = Vec::new();
167        let mut paths = Vec::new();
168        for (file, path) in files {
169            if ids.contains(&file) {
170                return Err(DeviceOnlyError::RepeatedFile { file });
171            }
172            ids.push(file);
173            paths.push(path);
174        }
175        // Refused before any byte is downloaded; the write checks again.
176        let refs = self.inner.database.device_only_files(ids).await?;
177        let folder = Arc::new(
178            CopyFolder::open(folder.to_owned(), self.inner.database.bugs().clone()).await?,
179        );
180        let plan = folder.plan(paths).await?;
181        let copies: Vec<FolderCopy> = plan
182            .files
183            .iter()
184            .map(|path| FolderCopy {
185                path: path.clone(),
186                temporary: path
187                    .with_file_name(format!(".coven-{}.download", self.inner.ids.new_id())),
188                folders: plan
189                    .folders
190                    .iter()
191                    .filter(|folder| path.starts_with(folder))
192                    .cloned()
193                    .collect(),
194            })
195            .collect();
196        // Held until the call ends however it ends: dropping the call's
197        // future drops it too, and the next write removes what it made.
198        let reservation = self.inner.database.record_copies(copies.clone()).await?;
199        let mut report = ProgressReport::new(progress, self.inner.clock.clone());
200        // A panic in a download fails the call as any failure does, and
201        // what the call made goes before it returns (E15).
202        let downloaded = coven_foundation::task::caught(
203            "download files to make device-only",
204            download(
205                self,
206                &folder,
207                &reservation,
208                &plan.folders,
209                &refs,
210                &copies,
211                &lease,
212                &mut cancel,
213                &mut report,
214            ),
215        )
216        .await;
217        let error = match downloaded {
218            Ok(Ok((switches, flushed))) => {
219                return Ok(self.inner.database.prepared_device_only(
220                    reservation,
221                    switches,
222                    flushed,
223                )?)
224            }
225            Ok(Err(error)) => error,
226            Err(bug) => DeviceOnlyError::Bug(bug),
227        };
228        let made = copies.into_iter().map(|copy| copy.path).collect();
229        let abandoned = self.inner.database.abandon_copies(made).await;
230        drop(reservation);
231        match abandoned {
232            Ok(()) => Err(error),
233            Err(cleanup) => Err(DeviceOnlyError::Cleanup { error: Box::new(error), cleanup }),
234        }
235    }
236}
237
238/// Make the plan's folders, then download each file to its copy and
239/// place it, returning the switches the write makes and the flush of
240/// the copies' batch: their folders and the drive's cache, once for the
241/// call, so every copy is on the drive before the write records it
242/// (Appendix C.3). A cancel is heard while waiting for bytes and between
243/// steps, never inside one, so every name a step made is in its record
244/// when the call removes them. A step that makes a name or writes under one,
245/// a folder, a copy's file, an append to it, or its rename to its path, runs
246/// to its end with its record once started, holding the call's copies,
247/// though the call is dropped meanwhile: what it made is then in its record
248/// for the next write or open to remove, and no removal meets a file a step
249/// still holds open, which Windows would refuse. Between steps the call
250/// holds no file open but the copy's writer, which drops with the call.
251#[expect(clippy::too_many_arguments, reason = "the call's parts, each its own")]
252async fn download(
253    handle: &Files,
254    folder: &Arc<CopyFolder>,
255    reservation: &CopyReservation,
256    folders: &[PathBuf],
257    files: &[FileRef],
258    copies: &[FolderCopy],
259    lease: &FileLease,
260    cancel: &mut watch::Receiver<bool>,
261    report: &mut ProgressReport<DeviceOnlyStep>,
262) -> Result<(Vec<DeviceOnlyCopy>, Flushed), DeviceOnlyError> {
263    let bugs = handle.inner.database.bugs().clone();
264    for made in folders {
265        check(cancel)?;
266        let (owner, folder, made) = (handle.inner.clone(), folder.clone(), made.clone());
267        step(reservation, "make a folder for copies", &bugs, async move {
268            // A folder someone made since planning is theirs, and stays.
269            if folder.create_folder(made.clone()).await? {
270                owner.database.made_folder(&made).await?;
271            }
272            Ok(())
273        })
274        .await?;
275    }
276    let mut switches = Vec::new();
277    let mut batch = FlushBatch::new(handle.inner.database.bugs().clone());
278    let all = files.iter().map(FileRef::size).sum();
279    let mut before = 0;
280    for (file, copy) in files.iter().zip(copies) {
281        check(cancel)?;
282        report.begin(DeviceOnlyStep::Downloading { file: file.id(), before, all }, file.size());
283        let mut done = 0;
284        let download = |error| DeviceOnlyError::Download { file: file.id(), error };
285        let FilePlace::Cloud { location, .. } = file.place() else {
286            return Err(DbError::NotInCloud { file: file.id() }.into());
287        };
288        let location = location.clone();
289        let stream = handle.open_file_stream(file, lease).await.map_err(download)?;
290        let mut writer = {
291            let (folder, temporary) = (folder.clone(), copy.temporary.clone());
292            step(reservation, "create a copy", &bugs, async move {
293                Ok(folder.create_copy(temporary).await?)
294            })
295            .await?
296        };
297        // A whole read in order checks the content hash before its last
298        // bytes are handed over (§17.7). The bytes written are hashed as
299        // they go, for a later move of the copy to check against (§17.3).
300        let mut range = stream.read_range(0, file.size()).map_err(download)?;
301        let mut hashes = FileHasher::new();
302        loop {
303            let bytes = tokio::select! {
304                biased;
305                () = cancelled(cancel) => return Err(DeviceOnlyError::Cancelled),
306                bytes = range.next() => bytes.map_err(download)?,
307            };
308            let Some(bytes) = bytes else { break };
309            hashes.update(&bytes);
310            done += bytes.len() as u64;
311            writer = {
312                #[cfg(test)]
313                let owner = handle.inner.clone();
314                step(reservation, "append to a copy", &bugs, async move {
315                    writer.append(&bytes).await?;
316                    #[cfg(test)]
317                    owner.pass_device_only_gate(DeviceOnlyPoint::Appended).await;
318                    Ok(writer)
319                })
320                .await?
321            };
322            report.done(done);
323        }
324        before += file.size();
325        batch = {
326            let (owner, folder, path) = (handle.inner.clone(), folder.clone(), copy.path.clone());
327            step(reservation, "place a copy", &bugs, async move {
328                writer.publish(&path, &mut batch).await?;
329                #[cfg(test)]
330                owner.pass_device_only_gate(DeviceOnlyPoint::Renamed).await;
331                let observed = folder.observe(&path).await.map_err(DbError::from)?;
332                owner.database.place_copy(&observed).await?;
333                Ok(batch)
334            })
335            .await?
336        };
337        switches.push(DeviceOnlyCopy {
338            file: file.id(),
339            location,
340            path: copy.path.clone(),
341            hashes: hashes.finish(),
342        });
343    }
344    check(cancel)?;
345    Ok((switches, batch.flush().await?))
346}
347
348/// Where a test holds a device-only call (`FilesInner::device_only_gate`).
349#[cfg(test)]
350#[derive(Clone, Copy, Debug, PartialEq, Eq)]
351pub(crate) enum DeviceOnlyPoint {
352    /// A copy's bytes were just appended.
353    Appended,
354    /// A copy was renamed to its path and is not yet recorded placed.
355    Renamed,
356}
357
358/// A test's hold on a device-only call: where, the signal that it got
359/// there, and the resume it waits for.
360#[cfg(test)]
361pub(crate) type DeviceOnlyGate =
362    (DeviceOnlyPoint, tokio::sync::oneshot::Sender<()>, tokio::sync::oneshot::Receiver<()>);
363
364impl crate::files::FilesInner {
365    /// Wait at the gate a test set for `point`, if any, once there.
366    #[cfg(test)]
367    async fn pass_device_only_gate(&self, point: DeviceOnlyPoint) {
368        let gate = {
369            let mut gate = coven_foundation::locks::lock_unpoisoned(&self.device_only_gate);
370            if gate.as_ref().is_some_and(|(at, _, _)| *at == point) {
371                gate.take()
372            } else {
373                None
374            }
375        };
376        if let Some((_, reached, resume)) = gate {
377            reached.send(()).ok();
378            resume.await.ok();
379        }
380    }
381}
382
383/// Run `work`, a step of the call named `operation`, to its end with its
384/// record once started, holding the call's copies (`run_step`).
385async fn step<T: Send + 'static>(
386    reservation: &CopyReservation,
387    operation: &'static str,
388    bugs: &coven_foundation::task::BugSinkRef,
389    work: impl std::future::Future<Output = Result<T, DeviceOnlyError>> + Send + 'static,
390) -> Result<T, DeviceOnlyError> {
391    reservation.run_step(operation, bugs.clone(), work).await.map_err(FileError::from)?
392}
393
394fn check(cancel: &watch::Receiver<bool>) -> Result<(), DeviceOnlyError> {
395    if *cancel.borrow() {
396        Err(DeviceOnlyError::Cancelled)
397    } else {
398        Ok(())
399    }
400}
401
402/// Resolves once `cancel` says to stop; never, once its sender is gone.
403async fn cancelled(cancel: &mut watch::Receiver<bool>) {
404    loop {
405        if *cancel.borrow_and_update() {
406            return;
407        }
408        if cancel.changed().await.is_err() {
409            std::future::pending::<()>().await;
410        }
411    }
412}