ic-host-fs 0.4.0

//! Durable filesystem publication and exclusive descriptor locks.
//!
//! Responsibility: own atomic durable regular-file publication for host consumers.
//! Does not own: domain schemas or transitions, path selection, ephemeral protocol files, open
//! command-result descriptors, backup persistence, or multi-file transactions.
//! Boundary: writes own sibling staging, publication, cleanup and filesystem syncs
//! behind replace and create-new modes. Reads belong to [`crate::read`].

mod lock_wait;
pub use lock_wait::lock_exclusive_with_wait;

#[cfg(test)]
mod tests;

use std::{fmt, fs, io, path::Path};

/// A no-follow regular-file lock could not be acquired.
#[derive(Debug)]
pub enum RegularFileLockError {
    /// The opened entry is not a regular file.
    NotRegular,
    /// The filesystem operation failed.
    Io(io::Error),
    #[cfg(windows)]
    /// This operation is unsupported on the selected host.
    UnsupportedPlatform,
}

impl fmt::Display for RegularFileLockError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::NotRegular => formatter.write_str("lock target is not a regular file"),
            Self::Io(_) => formatter.write_str("regular file lock I/O failed"),
            #[cfg(windows)]
            Self::UnsupportedPlatform => formatter.write_str("regular file locking is unsupported"),
        }
    }
}

impl std::error::Error for RegularFileLockError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Io(source) => Some(source),
            Self::NotRegular => None,
            #[cfg(windows)]
            Self::UnsupportedPlatform => None,
        }
    }
}

/// Preserve native I/O identity or retain the typed admission cause at an I/O boundary.
impl From<RegularFileLockError> for io::Error {
    fn from(error: RegularFileLockError) -> Self {
        match error {
            RegularFileLockError::Io(source) => source,
            other @ RegularFileLockError::NotRegular => Self::other(other),
            #[cfg(windows)]
            other @ RegularFileLockError::UnsupportedPlatform => Self::other(other),
        }
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum FileCommitMode {
    Replace,
    CreateNewWithParents,
    CreatePrivateWithParents,
}

/// Durably replace one file through atomic publication of complete bytes.
///
/// Missing parent directories are created and durably linked before the file
/// is published. Serialization must complete before calling this helper.
///
/// # Errors
/// Returns filesystem or sync failures, including sync failures after publication.
pub fn write_bytes(path: &Path, bytes: &[u8]) -> io::Result<()> {
    commit_bytes(path, bytes, FileCommitMode::Replace)
}

/// Stream one complete file into durable atomic replacement without buffering its contents.
///
/// The producer writes only to the owned sibling staging file. Its return value
/// is returned after file synchronization, rename and parent synchronization.
/// If the producer returns an error, the previous destination is preserved and
/// removal of owned staging is attempted. Panics or process interruption can
/// leave staging behind.
/// Missing parents are created and synchronized through the same path as
/// [`write_bytes`]. Producers own encoding, input/output limits and source admission.
///
/// This follows caller-selected parent paths; it does not confine a root or
/// commit several files together. Do not change the staging file's identity or
/// retain writable descriptor clones beyond the callback.
///
/// # Errors
/// Returns producer, filesystem, sync or unsupported-host errors. A sync failure
/// after rename can leave the new complete file visible: reconcile before retrying.
pub fn write_with<T>(
    path: &Path,
    write: impl FnOnce(&mut fs::File) -> io::Result<T>,
) -> io::Result<T> {
    #[cfg(any(target_os = "linux", target_os = "android", target_vendor = "apple"))]
    {
        supported::commit_with_writer_and_hook(path, FileCommitMode::Replace, write, |_, _| Ok(()))
    }
    #[cfg(not(any(target_os = "linux", target_os = "android", target_vendor = "apple")))]
    {
        let _ = (path, write);
        Err(io::Error::new(
            io::ErrorKind::Unsupported,
            "durable atomic file publication is unsupported",
        ))
    }
}

/// Durably create one file and its missing parent hierarchy without replacing
/// an existing destination.
///
/// # Errors
/// Returns filesystem or sync failures, including an existing destination or a
/// sync failure after publication.
pub fn create_new_bytes_with_parents(path: &Path, bytes: &[u8]) -> io::Result<()> {
    commit_bytes(path, bytes, FileCommitMode::CreateNewWithParents)
}

/// Create owner-only bytes atomically, without replacing an existing destination.
///
/// # Errors
/// Returns filesystem or sync failures, an existing destination, or unsupported
/// platform errors. Sync failure can occur after publication.
pub fn create_private_bytes_with_parents(path: &Path, bytes: &[u8]) -> io::Result<()> {
    commit_bytes(path, bytes, FileCommitMode::CreatePrivateWithParents)
}

/// Open and exclusively lock one durable regular no-follow file.
///
/// The lock file and missing parent hierarchy are durably created first. The
/// returned descriptor owns the kernel lock and is close-on-exec.
///
/// # Errors
/// Returns typed file admission, creation, sync or lock acquisition failures.
pub fn lock_regular_file_with_parents(path: &Path) -> Result<fs::File, RegularFileLockError> {
    open_regular_lock_file(path, |file| {
        #[cfg(not(windows))]
        rustix::fs::flock(file, rustix::fs::FlockOperation::LockExclusive)
            .map_err(errno_to_lock_error)?;
        Ok(())
    })
}

/// Acquire the same exclusive lock, reporting contention while preserving its lifetime.
///
/// Errors retain their admission category or original I/O cause, including a
/// failed progress callback. No callback or lock error is converted to text.
/// Consumers own diagnostic formatting and whether to retry.
///
/// # Errors
/// Returns file admission, creation, sync, lock acquisition or callback failures.
pub fn lock_file_with_progress(
    path: &Path,
    mut waiting: impl FnMut(&fs::File, std::time::Duration) -> io::Result<()>,
) -> Result<fs::File, RegularFileLockError> {
    let started = std::time::Instant::now();
    open_regular_lock_file(path, |file| {
        #[cfg(not(windows))]
        {
            let mut next_report = std::time::Duration::from_secs(1);
            lock_exclusive_with_wait(file, std::time::Duration::from_millis(100), |_| {
                let elapsed = started.elapsed();
                if elapsed >= next_report {
                    waiting(file, elapsed)?;
                    next_report = elapsed + std::time::Duration::from_secs(1);
                }
                Ok(())
            })
            .map_err(RegularFileLockError::Io)?;
        }
        Ok(())
    })
}

fn open_regular_lock_file(
    path: &Path,
    acquire: impl FnOnce(&fs::File) -> Result<(), RegularFileLockError>,
) -> Result<fs::File, RegularFileLockError> {
    match create_new_bytes_with_parents(path, &[]) {
        Ok(()) => {}
        Err(source) if source.kind() == io::ErrorKind::AlreadyExists => {}
        Err(source) => return Err(RegularFileLockError::Io(source)),
    }
    let metadata = fs::symlink_metadata(path).map_err(RegularFileLockError::Io)?;
    if !metadata.file_type().is_file() {
        return Err(RegularFileLockError::NotRegular);
    }

    #[cfg(not(windows))]
    {
        use rustix::{
            fd::OwnedFd,
            fs::{FileType, Mode, OFlags, fstat, open},
        };

        let fd: OwnedFd = open(
            path,
            OFlags::RDWR | OFlags::NOFOLLOW | OFlags::NONBLOCK | OFlags::CLOEXEC,
            Mode::empty(),
        )
        .map_err(errno_to_lock_error)?;
        let metadata = fstat(&fd).map_err(errno_to_lock_error)?;
        if FileType::from_raw_mode(metadata.st_mode) != FileType::RegularFile {
            return Err(RegularFileLockError::NotRegular);
        }
        let file = fs::File::from(fd);
        acquire(&file)?;
        Ok(file)
    }

    #[cfg(windows)]
    {
        Err(RegularFileLockError::UnsupportedPlatform)
    }
}

#[cfg(not(windows))]
fn errno_to_lock_error(source: rustix::io::Errno) -> RegularFileLockError {
    RegularFileLockError::Io(io::Error::from_raw_os_error(source.raw_os_error()))
}

fn commit_bytes(path: &Path, bytes: &[u8], mode: FileCommitMode) -> io::Result<()> {
    #[cfg(any(target_os = "linux", target_os = "android", target_vendor = "apple"))]
    {
        supported::commit_with_hook(path, bytes, mode, |_, _| Ok(()))
    }

    #[cfg(not(any(target_os = "linux", target_os = "android", target_vendor = "apple")))]
    {
        let _ = (path, bytes, mode);
        Err(io::Error::new(
            io::ErrorKind::Unsupported,
            format!(
                "durable atomic file publication is unsupported on platform {}",
                std::env::consts::OS
            ),
        ))
    }
}

#[cfg(any(target_os = "linux", target_os = "android", target_vendor = "apple"))]
mod supported {
    use super::FileCommitMode;

    use std::{
        ffi::{OsStr, OsString},
        fs,
        io::{self, Write},
        path::{Path, PathBuf},
        sync::atomic::{AtomicU64, Ordering},
    };

    use rustix::{
        fd::{AsFd, OwnedFd},
        fs::{self as unix_fs, AtFlags, Mode, OFlags, RenameFlags},
    };

    const TEMP_ATTEMPTS: usize = 64;
    static TEMP_SEQUENCE: AtomicU64 = AtomicU64::new(0);

    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
    pub(super) enum FileCommitStep {
        ParentDirectoryCreate,
        CreatedDirectorySync,
        CreatedDirectoryParentSync,
        TemporaryFileCreate,
        TemporaryFileWrite,
        TemporaryFileSync,
        Publication,
        FinalParentSync,
    }

    pub(super) fn commit_with_hook(
        path: &Path,
        bytes: &[u8],
        mode: FileCommitMode,
        before: impl FnMut(FileCommitStep, &Path) -> io::Result<()>,
    ) -> io::Result<()> {
        commit_with_writer_and_hook(path, mode, |file| file.write_all(bytes), before)
    }

    pub(super) fn commit_with_writer_and_hook<T>(
        path: &Path,
        mode: FileCommitMode,
        write: impl FnOnce(&mut fs::File) -> io::Result<T>,
        mut before: impl FnMut(FileCommitStep, &Path) -> io::Result<()>,
    ) -> io::Result<T> {
        let (parent, file_name) = split_target(path)?;
        create_parent_hierarchy(parent, &mut before)?;
        let parent_fd = open_directory(parent)?;
        let permissions = if mode == FileCommitMode::CreatePrivateWithParents {
            Mode::RUSR | Mode::WUSR
        } else {
            Mode::RUSR | Mode::WUSR | Mode::RGRP | Mode::WGRP | Mode::ROTH | Mode::WOTH
        };
        let (temp_name, temp_path, mut temp_file) =
            create_sibling_temp(&parent_fd, parent, file_name, permissions, &mut before)?;

        let staged = (|| {
            before(FileCommitStep::TemporaryFileWrite, &temp_path)?;
            let value = write(&mut temp_file)?;
            before(FileCommitStep::TemporaryFileSync, &temp_path)?;
            temp_file.sync_all()?;
            Ok(value)
        })();
        drop(temp_file);
        let value = match staged {
            Ok(value) => value,
            Err(error) => {
                remove_temp(&parent_fd, &temp_name);
                return Err(error);
            }
        };

        if let Err(error) = before(FileCommitStep::Publication, path) {
            remove_temp(&parent_fd, &temp_name);
            return Err(error);
        }
        let published = match mode {
            FileCommitMode::Replace => {
                unix_fs::renameat(&parent_fd, &temp_name, &parent_fd, file_name)
            }
            FileCommitMode::CreateNewWithParents | FileCommitMode::CreatePrivateWithParents => {
                publish_create_new(&parent_fd, &temp_name, file_name)
            }
        };
        if let Err(error) = published {
            remove_temp(&parent_fd, &temp_name);
            return Err(errno_to_io(error));
        }

        before(FileCommitStep::FinalParentSync, parent)?;
        unix_fs::fsync(&parent_fd).map_err(errno_to_io)?;
        Ok(value)
    }

    fn publish_create_new(
        parent_fd: &OwnedFd,
        temp_name: &OsStr,
        file_name: &OsStr,
    ) -> rustix::io::Result<()> {
        let renamed = unix_fs::renameat_with(
            parent_fd,
            temp_name,
            parent_fd,
            file_name,
            RenameFlags::NOREPLACE,
        );
        finish_create_new_publication(parent_fd, temp_name, file_name, renamed)
    }

    fn finish_create_new_publication(
        parent_fd: &OwnedFd,
        temp_name: &OsStr,
        file_name: &OsStr,
        renamed: rustix::io::Result<()>,
    ) -> rustix::io::Result<()> {
        match renamed {
            Ok(()) => Ok(()),
            Err(
                rustix::io::Errno::INVAL | rustix::io::Errno::NOSYS | rustix::io::Errno::OPNOTSUPP,
            ) => {
                unix_fs::linkat(parent_fd, temp_name, parent_fd, file_name, AtFlags::empty())?;
                remove_temp(parent_fd, temp_name);
                Ok(())
            }
            Err(error) => Err(error),
        }
    }

    #[cfg(test)]
    pub(super) fn publish_create_new_after_error(
        parent: &Path,
        temp_name: &OsStr,
        file_name: &OsStr,
        error: rustix::io::Errno,
    ) -> io::Result<()> {
        let parent_fd = open_directory(parent)?;
        finish_create_new_publication(&parent_fd, temp_name, file_name, Err(error))
            .map_err(errno_to_io)
    }

    fn split_target(path: &Path) -> io::Result<(&Path, &OsStr)> {
        let file_name = path.file_name().ok_or_else(|| {
            io::Error::new(
                io::ErrorKind::InvalidInput,
                format!("durable write target has no file name: {}", path.display()),
            )
        })?;
        let parent = path
            .parent()
            .filter(|parent| !parent.as_os_str().is_empty())
            .unwrap_or_else(|| Path::new("."));
        Ok((parent, file_name))
    }

    fn create_parent_hierarchy(
        parent: &Path,
        before: &mut impl FnMut(FileCommitStep, &Path) -> io::Result<()>,
    ) -> io::Result<()> {
        let mut missing = Vec::new();
        let mut current = parent;
        loop {
            match fs::symlink_metadata(current) {
                Ok(metadata) if metadata.is_dir() => break,
                Ok(_) => {
                    return Err(io::Error::new(
                        io::ErrorKind::NotADirectory,
                        format!("output parent is not a directory: {}", current.display()),
                    ));
                }
                Err(error) if error.kind() == io::ErrorKind::NotFound => {
                    missing.push(current.to_path_buf());
                    current = current
                        .parent()
                        .filter(|ancestor| !ancestor.as_os_str().is_empty())
                        .unwrap_or_else(|| Path::new("."));
                }
                Err(error) => return Err(error),
            }
        }

        for directory in missing.into_iter().rev() {
            before(FileCommitStep::ParentDirectoryCreate, &directory)?;
            match fs::create_dir(&directory) {
                Ok(()) => sync_created_directory(&directory, before)?,
                Err(error) if error.kind() == io::ErrorKind::AlreadyExists => {
                    if !fs::symlink_metadata(&directory)?.is_dir() {
                        return Err(io::Error::new(
                            io::ErrorKind::NotADirectory,
                            format!("output parent is not a directory: {}", directory.display()),
                        ));
                    }
                }
                Err(error) => return Err(error),
            }
        }
        Ok(())
    }

    fn sync_created_directory(
        directory: &Path,
        before: &mut impl FnMut(FileCommitStep, &Path) -> io::Result<()>,
    ) -> io::Result<()> {
        before(FileCommitStep::CreatedDirectorySync, directory)?;
        let directory_fd = open_directory(directory)?;
        unix_fs::fsync(&directory_fd).map_err(errno_to_io)?;

        let owner = directory
            .parent()
            .filter(|parent| !parent.as_os_str().is_empty())
            .unwrap_or_else(|| Path::new("."));
        before(FileCommitStep::CreatedDirectoryParentSync, owner)?;
        let owner_fd = open_directory(owner)?;
        unix_fs::fsync(&owner_fd).map_err(errno_to_io)
    }

    fn create_sibling_temp(
        parent_fd: &impl AsFd,
        parent: &Path,
        file_name: &OsStr,
        permissions: Mode,
        before: &mut impl FnMut(FileCommitStep, &Path) -> io::Result<()>,
    ) -> io::Result<(OsString, PathBuf, fs::File)> {
        for _ in 0..TEMP_ATTEMPTS {
            let sequence = TEMP_SEQUENCE.fetch_add(1, Ordering::Relaxed);
            let name = format!(".ic-host-tmp-{}-{sequence}", std::process::id());
            // Short names support NAME_MAX destinations. Never stage directly
            // into the selected output, including on case-insensitive hosts.
            if file_name
                .as_encoded_bytes()
                .eq_ignore_ascii_case(name.as_bytes())
            {
                continue;
            }
            let temp_name = OsString::from(name);
            let temp_path = parent.join(&temp_name);
            before(FileCommitStep::TemporaryFileCreate, &temp_path)?;
            match unix_fs::openat(
                parent_fd,
                &temp_name,
                OFlags::WRONLY | OFlags::CREATE | OFlags::EXCL | OFlags::CLOEXEC,
                permissions,
            ) {
                Ok(file) => return Ok((temp_name, temp_path, fs::File::from(file))),
                Err(error) if error == rustix::io::Errno::EXIST => {}
                Err(error) => return Err(errno_to_io(error)),
            }
        }

        Err(io::Error::new(
            io::ErrorKind::AlreadyExists,
            format!(
                "could not allocate a unique sibling temporary file for {}",
                parent.join(file_name).display()
            ),
        ))
    }

    fn open_directory(path: &Path) -> io::Result<OwnedFd> {
        unix_fs::open(
            path,
            OFlags::RDONLY | OFlags::DIRECTORY | OFlags::NOFOLLOW | OFlags::CLOEXEC,
            Mode::empty(),
        )
        .map_err(errno_to_io)
    }

    fn remove_temp(parent_fd: &impl AsFd, temp_name: &OsStr) {
        let _ = unix_fs::unlinkat(parent_fd, temp_name, AtFlags::empty());
    }

    fn errno_to_io(error: rustix::io::Errno) -> io::Error {
        io::Error::from_raw_os_error(error.raw_os_error())
    }
}