coven_foundation/files/

folder_copy.rs

//! Copies coven writes into a folder the person picked, to make cloud files
//! device-only (§17.3): the folders and files a call needs, refusing paths
//! through a symbolic link; each file written under a temporary name in its
//! final folder and renamed once synced, its folder synced with the call's
//! batch (Appendix C.3); and the removal of what a call made,
//! which removes a copy only while it is as coven left it.
//!
//! The folder is opened once. On Unix every folder, copy and rename below it
//! is made relative to that open handle, one name at a time, never following
//! a symbolic link, so a folder swapped for a link after planning can't send
//! a write elsewhere. Windows has no such calls in the standard library, and
//! its writes go by path, each checked for links just before it.

#[cfg(windows)]
use super::atomic_file::{create_new, rename_new};
use super::atomic_file::{remove, sync_file};
#[cfg(unix)]
use super::flush_batch::BatchFolder;
use super::observed_file::observe_metadata;
use super::relative_path::local_name;
use super::{FileError, FlushBatch, ObservationError, ObservedFile, RelativePath};
use crate::task::BugSinkRef;
use std::collections::BTreeMap;
use std::fs;
use std::io::{self, Write};
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::SystemTime;

/// What one call makes below the folder: the folders that don't exist yet,
/// each before the folders inside it, and each file's path, in the order of
/// the relative paths.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CopyPlan {
    /// The folders to make, outermost first.
    pub folders: Vec<PathBuf>,
    /// Each file's path.
    pub files: Vec<PathBuf>,
}

/// Why a copy can't go where the app named.
#[derive(Debug, thiserror::Error)]
pub enum CopyPathError {
    /// The folder isn't an absolute path to a folder, or a path below it
    /// passes through something that isn't a folder.
    #[error("{} is not a folder", .0.display())]
    NotAFolder(PathBuf),
    /// A path below the folder passes through a symbolic link.
    #[error("{} is a symbolic link", .0.display())]
    Link(PathBuf),
    /// Something is at a file's path already.
    #[error("{} is taken", .0.display())]
    Exists(PathBuf),
    /// Two paths of the call are one path once each name is made valid
    /// (§17.3), as `Why?.flac` and `Why？.flac` are, or differ only in case
    /// or Unicode form, as `Album/Track.flac` and `album/track.flac` do. Many
    /// volumes, the default macOS and Windows ones among them, hold such
    /// names as one, so the second copy could never be placed. Each path is
    /// as the app named it, up to the name that clashes.
    #[error("{path} and {other} name one path")]
    Clash {
        /// The later path.
        path: RelativePath,
        /// The earlier path it clashes with.
        other: RelativePath,
    },
    /// The folder's path isn't valid Unicode, which coven records as text.
    #[error("{} is not valid Unicode", .0.display())]
    NotUnicode(PathBuf),
    /// Inspecting a path failed.
    #[error(transparent)]
    File(FileError),
    /// Inspecting the paths panicked on the blocking pool: a bug, which the
    /// caller reports (E15).
    #[error(transparent)]
    Bug(#[from] crate::task::Bug),
}

impl From<FileError> for CopyPathError {
    fn from(error: FileError) -> Self {
        match error {
            FileError::Bug(bug) => Self::Bug(bug),
            error => Self::File(error),
        }
    }
}

impl crate::task::CarriesBug for CopyPathError {
    fn bug(&self) -> Option<&crate::task::Bug> {
        match self {
            Self::Bug(bug) => Some(bug),
            Self::File(error) => error.bug(),
            _ => None,
        }
    }
}

/// The folder the person picked, open for the copies one call makes.
pub struct CopyFolder {
    path: PathBuf,
    #[cfg(unix)]
    handle: Arc<rustix::fd::OwnedFd>,
    /// Where a panic in work its caller stopped waiting for goes (E15).
    bugs: BugSinkRef,
}

impl CopyFolder {
    /// Open `folder`, an absolute path to a folder whose path is valid
    /// Unicode. The folder itself may be reached through a link: the person
    /// picked it. A panic in the copies' work whose caller stopped waiting
    /// goes to `bugs` (E15).
    pub async fn open(folder: PathBuf, bugs: BugSinkRef) -> Result<Self, CopyPathError> {
        let opened = bugs.clone();
        blocking("open folder", &opened, move || {
            if !folder.is_absolute() {
                return Err(CopyPathError::NotAFolder(folder));
            }
            if folder.to_str().is_none() {
                return Err(CopyPathError::NotUnicode(folder));
            }
            match fs::metadata(&folder) {
                Ok(metadata) if metadata.is_dir() => {}
                Ok(_) => return Err(CopyPathError::NotAFolder(folder)),
                Err(error) if error.kind() == io::ErrorKind::NotFound => {
                    return Err(CopyPathError::NotAFolder(folder))
                }
                Err(source) => return Err(FileError::at("inspect folder", &folder, source).into()),
            }
            #[cfg(unix)]
            {
                use rustix::fs::{Mode, OFlags};
                let handle = rustix::fs::open(
                    &folder,
                    OFlags::DIRECTORY | OFlags::RDONLY | OFlags::CLOEXEC,
                    Mode::empty(),
                )
                .map_err(|errno| FileError::at("open folder", &folder, errno.into()))?;
                Ok(Self { path: folder, handle: Arc::new(handle), bugs })
            }
            #[cfg(windows)]
            Ok(Self { path: folder, bugs })
        })
        .await
    }

    /// Plan the copies at `paths`, each name written as the one rule for
    /// every platform makes it (§17.3). Only what lies below the folder is
    /// checked for links.
    pub async fn plan(&self, paths: Vec<RelativePath>) -> Result<CopyPlan, CopyPathError> {
        let folder = self.path.clone();
        blocking("plan copies", &self.bugs, move || plan(&folder, &paths)).await
    }

    /// Make the folder at `path`, a path of a plan, and sync the folder
    /// holding it. True when this call made it; false when a folder was
    /// there already, made by someone else, which the call never removes.
    pub async fn create_folder(&self, path: PathBuf) -> Result<bool, FileError> {
        let folder = self.clone_handle();
        blocking("make folder", &self.bugs, move || folder.make_folder(&path)).await
    }

    /// Start a copy's bytes at `temporary`, a new file in its final folder.
    pub async fn create_copy(&self, temporary: PathBuf) -> Result<CopyWriter, FileError> {
        let folder = self.clone_handle();
        blocking("create copy", &self.bugs, move || folder.make_copy(temporary)).await
    }

    /// Observe the copy at `path`, a path below the folder, without reading
    /// its bytes: its size and modification time, for the original it
    /// becomes.
    pub async fn observe(&self, path: &Path) -> Result<ObservedFile, ObservationError> {
        self.names(path).map_err(|source| FileError::at("observe copy", path, source))?;
        observe_metadata(path).await
    }

    fn clone_handle(&self) -> CopyFolder {
        Self {
            path: self.path.clone(),
            #[cfg(unix)]
            handle: self.handle.clone(),
            bugs: self.bugs.clone(),
        }
    }

    /// The names below the folder leading to `path`.
    fn names<'a>(&self, path: &'a Path) -> io::Result<Vec<&'a std::ffi::OsStr>> {
        let names: Vec<_> = path
            .strip_prefix(&self.path)
            .map_err(|_outside| io::Error::new(io::ErrorKind::InvalidInput, "outside the folder"))?
            .iter()
            .collect();
        if names.is_empty() {
            return Err(io::Error::new(io::ErrorKind::InvalidInput, "the folder itself"));
        }
        Ok(names)
    }

    /// The folder holding `path`, opened one name at a time from the
    /// folder's handle without following a link, and `path`'s own name.
    #[cfg(unix)]
    fn parent<'a>(
        &self,
        path: &'a Path,
    ) -> io::Result<(Option<rustix::fd::OwnedFd>, &'a std::ffi::OsStr)> {
        use rustix::fd::AsFd;
        use rustix::fs::{Mode, OFlags};
        let names = self.names(path)?;
        let (last, folders) = names.split_last().expect("a path below the folder names something");
        let mut opened: Option<rustix::fd::OwnedFd> = None;
        for name in folders {
            let at = opened.as_ref().map_or(self.handle.as_fd(), |fd| fd.as_fd());
            opened = Some(rustix::fs::openat(
                at,
                *name,
                OFlags::DIRECTORY | OFlags::NOFOLLOW | OFlags::RDONLY | OFlags::CLOEXEC,
                Mode::empty(),
            )?);
        }
        Ok((opened, last))
    }

    #[cfg(unix)]
    fn make_folder(&self, path: &Path) -> Result<bool, FileError> {
        use rustix::fd::AsFd;
        use rustix::fs::{AtFlags, FileType, Mode};
        let at = |source: io::Error| FileError::at("create folder", path, source);
        let (opened, name) = self.parent(path).map_err(at)?;
        let parent = opened.as_ref().map_or(self.handle.as_fd(), |fd| fd.as_fd());
        match rustix::fs::mkdirat(parent, name, Mode::from(0o777)) {
            Ok(()) => {
                rustix::fs::fsync(parent).map_err(|errno| at(errno.into()))?;
                Ok(true)
            }
            Err(rustix::io::Errno::EXIST) => {
                let stat = rustix::fs::statat(parent, name, AtFlags::SYMLINK_NOFOLLOW)
                    .map_err(|errno| at(errno.into()))?;
                if FileType::from_raw_mode(stat.st_mode) == FileType::Directory {
                    Ok(false)
                } else {
                    Err(at(rustix::io::Errno::EXIST.into()))
                }
            }
            Err(errno) => Err(at(errno.into())),
        }
    }

    #[cfg(unix)]
    fn make_copy(&self, temporary: PathBuf) -> Result<CopyWriter, FileError> {
        use rustix::fd::AsFd;
        use rustix::fs::{Mode, OFlags};
        let at = |source: io::Error| FileError::at("create copy", &temporary, source);
        let (opened, name) = self.parent(&temporary).map_err(at)?;
        let parent = match opened {
            Some(opened) => opened,
            None => rustix::io::fcntl_dupfd_cloexec(self.handle.as_fd(), 0)
                .map_err(|errno| at(errno.into()))?,
        };
        let file = rustix::fs::openat(
            parent.as_fd(),
            name,
            OFlags::WRONLY | OFlags::CREATE | OFlags::EXCL | OFlags::NOFOLLOW | OFlags::CLOEXEC,
            Mode::from(0o666),
        )
        .map_err(|errno| at(errno.into()))?;
        let name = name.to_owned();
        Ok(CopyWriter {
            file: Arc::new(tokio::sync::Mutex::new(fs::File::from(file))),
            path: temporary,
            parent: Arc::new(parent),
            name,
            bugs: self.bugs.clone(),
        })
    }

    /// Each folder between this one and `path` must still be a folder, and
    /// not a link, just before a write by path.
    #[cfg(windows)]
    fn check_below(&self, path: &Path) -> io::Result<()> {
        let names = self.names(path)?;
        let mut below = self.path.clone();
        for name in &names[..names.len() - 1] {
            below.push(name);
            let metadata = fs::symlink_metadata(&below)?;
            if metadata.file_type().is_symlink() || !metadata.is_dir() {
                return Err(io::Error::new(io::ErrorKind::InvalidInput, "not a folder"));
            }
        }
        Ok(())
    }

    #[cfg(windows)]
    fn make_folder(&self, path: &Path) -> Result<bool, FileError> {
        let at = |source: io::Error| FileError::at("create folder", path, source);
        self.check_below(path).map_err(at)?;
        match fs::create_dir(path) {
            Ok(()) => Ok(true),
            Err(error) if error.kind() == io::ErrorKind::AlreadyExists => {
                let metadata = fs::symlink_metadata(path).map_err(at)?;
                if metadata.is_dir() && !metadata.file_type().is_symlink() {
                    Ok(false)
                } else {
                    Err(at(error))
                }
            }
            Err(error) => Err(at(error)),
        }
    }

    #[cfg(windows)]
    fn make_copy(&self, temporary: PathBuf) -> Result<CopyWriter, FileError> {
        let at = |source: io::Error| FileError::at("create copy", &temporary, source);
        self.check_below(&temporary).map_err(at)?;
        let file = create_new(&temporary).map_err(at)?;
        Ok(CopyWriter {
            file: Arc::new(tokio::sync::Mutex::new(file)),
            folder: self.clone_handle(),
            path: temporary,
            bugs: self.bugs.clone(),
        })
    }
}

fn plan(folder: &Path, paths: &[RelativePath]) -> Result<CopyPlan, CopyPathError> {
    if !folder.is_absolute() {
        return Err(CopyPathError::NotAFolder(folder.to_owned()));
    }
    if folder.to_str().is_none() {
        return Err(CopyPathError::NotUnicode(folder.to_owned()));
    }
    match fs::metadata(folder) {
        Ok(metadata) if metadata.is_dir() => {}
        Ok(_) => return Err(CopyPathError::NotAFolder(folder.to_owned())),
        Err(error) if error.kind() == io::ErrorKind::NotFound => {
            return Err(CopyPathError::NotAFolder(folder.to_owned()))
        }
        Err(source) => return Err(FileError::at("inspect folder", folder, source).into()),
    }
    let mut plan = CopyPlan { folders: Vec::new(), files: Vec::new() };
    // Each path the call names, folder or file, by the names coven writes
    // for it as a volume that ignores case and Unicode form compares them,
    // with the path as the app named it.
    let mut named: BTreeMap<Vec<String>, Named> = BTreeMap::new();
    for relative in paths {
        let names: Vec<&str> = relative.names().collect();
        let (last, folders) = names.split_last().expect("a relative path names something");
        let mut path = folder.to_path_buf();
        let mut key = Vec::new();
        for (index, name) in folders.iter().enumerate() {
            let local = local_name(name);
            key.push(one_name(&local));
            path.push(local);
            let here = relative.first(index + 1);
            match named.get(&key) {
                Some(Named::Folder(other)) if *other == here => continue,
                Some(Named::Folder(other) | Named::File(other)) => {
                    return Err(CopyPathError::Clash { path: here, other: other.clone() })
                }
                None => {}
            }
            named.insert(key.clone(), Named::Folder(here));
            match fs::symlink_metadata(&path) {
                Ok(metadata) if metadata.file_type().is_symlink() => {
                    return Err(CopyPathError::Link(path))
                }
                Ok(metadata) if metadata.is_dir() => {}
                Ok(_) => return Err(CopyPathError::NotAFolder(path)),
                Err(error) if error.kind() == io::ErrorKind::NotFound => {
                    plan.folders.push(path.clone());
                }
                Err(source) => return Err(FileError::at("inspect folder", &path, source).into()),
            }
        }
        let local = local_name(last);
        key.push(one_name(&local));
        path.push(local);
        if let Some(Named::Folder(other) | Named::File(other)) = named.get(&key) {
            return Err(CopyPathError::Clash { path: relative.clone(), other: other.clone() });
        }
        named.insert(key, Named::File(relative.clone()));
        match fs::symlink_metadata(&path) {
            Ok(_) => return Err(CopyPathError::Exists(path)),
            Err(error) if error.kind() == io::ErrorKind::NotFound => {}
            Err(source) => return Err(FileError::at("inspect file", &path, source).into()),
        }
        plan.files.push(path);
    }
    Ok(plan)
}

/// A path a plan names, as the app named it, as a folder on the way to a
/// file or as a file.
enum Named {
    Folder(RelativePath),
    File(RelativePath),
}

/// `name` as a volume that ignores case and Unicode form compares it: its
/// canonical decomposition, case-folded, decomposed again, as Unicode's
/// canonical caseless match does. Two names alike here are one name on such
/// a volume. A volume folding a few letters differently still refuses the
/// second copy's rename, which never replaces what is there.
fn one_name(name: &str) -> String {
    let decompose = icu_normalizer::DecomposingNormalizerBorrowed::new_nfd();
    let folded =
        icu_casemap::CaseMapperBorrowed::new().fold_string(&decompose.normalize(name)).into_owned();
    decompose.normalize(&folded).into_owned()
}

/// A copy being written under its temporary name. Dropping it leaves the
/// bytes for the caller's recorded cleanup.
pub struct CopyWriter {
    file: Arc<tokio::sync::Mutex<fs::File>>,
    path: PathBuf,
    /// The open folder holding the copy, which its rename is relative to.
    #[cfg(unix)]
    parent: Arc<rustix::fd::OwnedFd>,
    #[cfg(unix)]
    name: std::ffi::OsString,
    #[cfg(windows)]
    folder: CopyFolder,
    /// Where a panic in a write its caller stopped waiting for goes (E15).
    bugs: BugSinkRef,
}

impl CopyWriter {
    /// Append one bounded buffer, completing its disk write before returning.
    pub async fn append(&mut self, bytes: &[u8]) -> Result<(), FileError> {
        let bytes = bytes.to_vec();
        self.run("write copy", move |file| file.write_all(&bytes)).await
    }

    /// Sync the bytes, then rename them to `path`, where nothing may be, in
    /// the same folder, so the copy is whole under its final name or not
    /// there. The copy counts in `batch`, whose flush syncs the folder and
    /// makes the copy durable before the commit that records it.
    pub async fn publish(self, path: &Path, batch: &mut FlushBatch) -> Result<(), FileError> {
        self.run("sync copy", |file| sync_file(file)).await?;
        let to = path.to_owned();
        #[cfg(unix)]
        {
            let (parent, from) = (self.parent.clone(), self.name.clone());
            let folder = blocking("rename copy", &self.bugs, move || {
                use rustix::fs::RenameFlags;
                let (name, folder) = match (to.file_name(), to.parent()) {
                    (Some(name), Some(folder)) => (name, folder),
                    _ => {
                        return Err(FileError::at(
                            "rename copy",
                            &to,
                            io::Error::new(io::ErrorKind::InvalidInput, "file name required"),
                        ))
                    }
                };
                rustix::fs::renameat_with(&*parent, &from, &*parent, name, RenameFlags::NOREPLACE)
                    .map_err(|errno| FileError::at("rename copy", &to, errno.into()))?;
                BatchFolder::held(folder.to_owned(), parent, None)
                    .map_err(|source| FileError::at("inspect copy folder", &to, source))
            })
            .await?;
            batch.add(folder);
            Ok(())
        }
        #[cfg(windows)]
        {
            let (folder, from) = (self.folder.clone_handle(), self.path.clone());
            blocking("rename copy", &self.bugs, move || {
                folder
                    .check_below(&to)
                    .map_err(|source| FileError::at("rename copy", &to, source))?;
                rename_new(&from, &to).map_err(|source| FileError::at("rename copy", &to, source))
            })
            .await?;
            batch.add();
            Ok(())
        }
    }

    async fn run(
        &self,
        operation: &'static str,
        run: impl FnOnce(&mut fs::File) -> io::Result<()> + Send + 'static,
    ) -> Result<(), FileError> {
        // Acquire before spawning so later calls wait for cancelled work too.
        let mut file = self.file.clone().lock_owned().await;
        let path = self.path.clone();
        blocking(operation, &self.bugs, move || {
            run(&mut file).map_err(|source| FileError::at(operation, &path, source))
        })
        .await
    }
}

/// A copy coven recorded writing in a folder the person picked, as its
/// record reads back (§17.3): its bytes still at their temporary name, or
/// placed at its path with the size and modification time they had there.
/// It is made only where coven reads that record.
#[derive(Debug)]
pub struct RecordedCopy {
    path: PathBuf,
    placed: Option<(u64, SystemTime)>,
}

impl RecordedCopy {
    /// A copy still being written, at its temporary name `temporary`.
    pub fn writing(temporary: PathBuf) -> Self {
        Self { path: temporary, placed: None }
    }

    /// A copy placed at `path` with `size` and `modified_at`.
    pub fn placed(path: PathBuf, size: u64, modified_at: SystemTime) -> Self {
        Self { path, placed: Some((size, modified_at)) }
    }

    /// Remove the copy's bytes. A placed copy goes only if it still has the
    /// size and modification time coven recorded: one that changed since is
    /// the person's, and stays. Absent bytes are gone already.
    pub fn remove(&self) -> Result<(), FileError> {
        let Some((size, modified_at)) = self.placed else {
            return remove(&self.path);
        };
        let path = self.path.as_path();
        let metadata = match fs::symlink_metadata(path) {
            Ok(metadata) => metadata,
            Err(error) if error.kind() == io::ErrorKind::NotFound => {
                tracing::debug!(path = %path.display(), "copy is already absent");
                return Ok(());
            }
            Err(source) => return Err(FileError::at("inspect copy", path, source)),
        };
        let modified = metadata
            .modified()
            .map_err(|source| FileError::at("read modification time", path, source))?;
        if !metadata.is_file() || metadata.len() != size || modified != modified_at {
            tracing::debug!(path = %path.display(), "leaving a copy the person changed");
            return Ok(());
        }
        remove(path)
    }
}

/// A folder coven made for copies in a folder the person picked, as its
/// record reads back (§17.3). It is made only where coven reads that record.
#[derive(Debug)]
pub struct MadeFolder {
    path: PathBuf,
}

impl MadeFolder {
    /// The folder coven made at `path`.
    pub fn at(path: PathBuf) -> Self {
        Self { path }
    }

    /// Remove the folder if nothing is in it: a folder holding anything,
    /// the person's files included, stays. An absent one is gone.
    pub fn remove(&self) -> Result<(), FileError> {
        super::atomic_file::remove_empty_folder(&self.path)
    }
}

/// Run `run`, file work named `operation`, on the blocking pool; a panic in
/// it is `FileError::Bug`, and the pool dropping it unstarted
/// `FileError::Shutdown`. Once its caller stops waiting, its panic, or a bug
/// its error carries, goes to `bugs` (E15).
async fn blocking<T, E>(
    operation: &'static str,
    bugs: &BugSinkRef,
    run: impl FnOnce() -> Result<T, E> + Send + 'static,
) -> Result<T, E>
where
    T: Send + 'static,
    E: From<FileError> + crate::task::CarriesBug + Send + 'static,
{
    crate::task::blocking_completing(operation, bugs.clone(), run).await.map_err(FileError::from)?
}

#[cfg(test)]
#[path = "folder_copy_tests.rs"]
mod tests;