ic_host_fs/durable/

mod.rs

//! Durable filesystem publication and regular descriptor locks.
//!
//! Responsibility: own durable publication and explicitly in-place synchronized writes.
//! 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`].

#[cfg(unix)]
pub mod tree;

mod directory;
mod lock_wait;
pub use directory::{
    DirectoryCommitError, DirectoryCommitOutcome, DirectoryCommitStep, DirectoryCreationError,
    admit_directory, commit_existing_directory_with, create_private_directory,
};
pub use lock_wait::{
    SharedFileLock, lock_exclusive, lock_exclusive_with_wait, lock_shared, try_lock_exclusive,
    unlock,
};
#[cfg(unix)]
mod retained;
#[cfg(unix)]
pub use retained::{create_retained_at, publish_retained_at};
mod named;
pub use named::{NamedWriteError, write_named_with};
#[cfg(unix)]
mod export;
#[cfg(unix)]
pub use export::{NonAliasingWriteError, validate_non_aliasing, write_non_aliasing};
#[cfg(unix)]
mod symlink;
#[cfg(unix)]
pub use symlink::publish_symlink_with;
mod verified_copy;
pub use verified_copy::copy_verified;
mod stream;
#[cfg(unix)]
pub use stream::write_at_validated_with;
pub use stream::{
    PublicationMode, WriteOptions, write_existing_parent_validated_with, write_validated_with,
    write_with,
};

#[cfg(test)]
mod tests;

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

/// A no-follow regular-file lock could not be acquired.
#[derive(Debug, thiserror::Error)]
pub enum RegularFileLockError {
    /// The opened entry is not a regular file.
    #[error("lock target is not a regular file")]
    NotRegular,
    /// The filesystem operation failed.
    #[error("regular file lock I/O failed")]
    Io(#[source] io::Error),
    /// Durable lock-file creation failed, retaining publication and cleanup evidence.
    #[error("durable lock-file creation failed")]
    Publication(#[source] NamedWriteError<io::Error>),
    #[cfg(not(unix))]
    /// This operation is unsupported on the selected host.
    #[error("regular file locking is unsupported")]
    UnsupportedPlatform,
}

/// Preserve native I/O identity or retain the complete admission/publication cause.
///
/// Publication failures are wrapped intact with [`io::ErrorKind::Other`]; inspect
/// the contained [`RegularFileLockError`] before deciding whether to retry.
impl From<RegularFileLockError> for io::Error {
    fn from(error: RegularFileLockError) -> Self {
        match error {
            RegularFileLockError::Io(source) => source,
            other @ RegularFileLockError::NotRegular => Self::other(other),
            other @ RegularFileLockError::Publication(_) => Self::other(other),
            #[cfg(not(unix))]
            other @ RegularFileLockError::UnsupportedPlatform => Self::other(other),
        }
    }
}

/// Durably publish complete bytes with explicit mode and staging permissions.
///
/// Missing parent directories are created and durably linked before the file
/// is published. Uses the same engine and caller obligations as [`write_with`].
/// Serialization must complete before calling this helper. `options` selects
/// replace/create-only publication and permission bits reduced by the umask.
///
/// # Errors
/// Retains write, cleanup and filesystem failures in [`NamedWriteError`], including
/// the distinct after-publication state when the complete output is already visible.
/// Create-only mode refuses an occupied destination; invalid permissions refuse
/// before parent creation. Reconcile after-publication errors before retrying.
pub fn write_bytes(
    path: &Path,
    options: WriteOptions,
    bytes: &[u8],
) -> Result<(), NamedWriteError<io::Error>> {
    write_with(path, options, |file| std::io::Write::write_all(file, bytes))
}

/// Durably copy a caller-selected stream into one named output.
///
/// Reads from the reader's current position. Caller-owned admission, byte limits
/// and deadlines remain outside this operation. `permissions` selects exact
/// output permissions when supplied; otherwise `options` and umask apply.
/// Explicit permissions are applied after copying so writes do not clear them.
/// Publication, parent creation, interruption cleanup and after-publication
/// errors have the same contract as [`write_with`]. This adds no input-path policy.
///
/// # Errors
/// Retains read/write, explicit permission and publication failures in
/// [`NamedWriteError`]. Before-publication failure preserves an existing output;
/// after-publication sync failure means the complete copy is already visible.
pub fn copy_from<R: io::Read>(
    source: &mut R,
    destination: &Path,
    options: WriteOptions,
    permissions: Option<fs::Permissions>,
) -> Result<u64, NamedWriteError<io::Error>> {
    write_with(destination, options, |sink| {
        let copied = io::copy(source, sink)?;
        if let Some(permissions) = permissions {
            sink.set_permissions(permissions)?;
        }
        Ok(copied)
    })
}

/// Durably create missing owner-only parent directories without publishing a file.
///
/// New directories use mode `0700`, reduced by the process umask. Existing
/// directories retain their permissions. Every new directory and its parent link
/// are synchronized before this returns. Callers retain root confinement and
/// exclusion of concurrent namespace mutation; symlink path components reject.
/// Supply a physical path when an ancestor alias is intentionally selected.
/// Parent-directory (`..`) components reject before any directory is created.
///
/// # Errors
/// Rejects a non-directory or symlink component, a parent-directory component,
/// unsupported host or failed creation/sync.
pub fn prepare_private_parents(parent: &Path) -> io::Result<()> {
    #[cfg(any(target_os = "linux", target_os = "android", target_vendor = "apple"))]
    {
        supported::prepare_private_parents(parent)
    }
    #[cfg(not(any(target_os = "linux", target_os = "android", target_vendor = "apple")))]
    {
        let _ = parent;
        Err(io::Error::new(
            io::ErrorKind::Unsupported,
            "durable private parent creation is unsupported",
        ))
    }
}

/// Open an unlocked regular no-follow lock file, durably creating missing parents
/// and the file first. Existing file bytes are preserved.
///
/// The returned read/write descriptor is close-on-exec. No lock is acquired:
/// callers choose shared/exclusive acquisition, wait timing, callbacks and unlock
/// lifetime. It composes with [`lock_exclusive_with_wait`]. Descriptor clones
/// share kernel lock ownership; explicit unlock and final-close policy remain
/// caller-owned.
///
/// Callers own trusted parent paths and namespace stability. Only the final
/// component is opened without following symlinks; this is not root confinement.
/// Admission does not bound filesystem creation, open or sync latency.
/// Existing entries are admitted without staging or syncing another file, so
/// their parent need not be writable. Missing entries use durable creation once;
/// a competing creator is admitted through the same checks. Removal during
/// admission can return a native not-found error rather than retrying indefinitely.
///
/// # Errors
/// Returns typed file admission, creation, sync or unsupported-host failures.
pub fn open_regular_lock_file_with_parents(path: &Path) -> Result<fs::File, RegularFileLockError> {
    #[cfg(unix)]
    {
        let metadata = match fs::symlink_metadata(path) {
            Ok(metadata) => metadata,
            Err(source) if source.kind() == io::ErrorKind::NotFound => {
                match write_bytes(
                    path,
                    WriteOptions {
                        mode: PublicationMode::CreateNew,
                        permissions: 0o666,
                    },
                    &[],
                ) {
                    Ok(()) => {}
                    Err(NamedWriteError::BeforePublication {
                        source,
                        cleanup_error: None,
                    }) if source.kind() == io::ErrorKind::AlreadyExists => {}
                    Err(source) => return Err(RegularFileLockError::Publication(source)),
                }
                fs::symlink_metadata(path).map_err(RegularFileLockError::Io)?
            }
            Err(source) => return Err(RegularFileLockError::Io(source)),
        };
        if !metadata.file_type().is_file() {
            return Err(RegularFileLockError::NotRegular);
        }

        open_regular_lock_descriptor(path, None)
    }

    #[cfg(not(unix))]
    {
        let _ = path;
        Err(RegularFileLockError::UnsupportedPlatform)
    }
}

/// Open an unlocked regular no-follow sidecar in an existing parent directory.
///
/// A missing file is created read/write with mode `0o600` before umask. Missing
/// parents are never created. Existing bytes, inode and permissions are preserved;
/// existing files are not required to have private permissions. The returned
/// descriptor is close-on-exec. No lock is acquired; callers choose acquisition,
/// contention handling and descriptor lifetime (including clones and inheritance).
///
/// Creation is a direct open, without publication staging or durability syncs.
/// The sidecar may remain after a later admission or lock failure. Callers own
/// trusted parents and namespace stability: only the final component is opened
/// without following symlinks. This is not root confinement or a wall-clock bound.
///
/// # Errors
/// Returns [`RegularFileLockError::NotRegular`] for observed special entries,
/// or the original I/O cause for open/metadata failures (including missing parents
/// and a symlink encountered during open). Unsupported hosts are rejected.
pub fn open_private_regular_lock_file(path: &Path) -> Result<fs::File, RegularFileLockError> {
    #[cfg(unix)]
    {
        match fs::symlink_metadata(path) {
            Ok(metadata) if metadata.file_type().is_file() => {}
            Ok(_) => return Err(RegularFileLockError::NotRegular),
            Err(source) if source.kind() == io::ErrorKind::NotFound => {}
            Err(source) => return Err(RegularFileLockError::Io(source)),
        }
        open_regular_lock_descriptor(path, Some(rustix::fs::Mode::RUSR | rustix::fs::Mode::WUSR))
    }
    #[cfg(not(unix))]
    {
        let _ = path;
        Err(RegularFileLockError::UnsupportedPlatform)
    }
}

/// Open an existing regular no-follow sidecar without creating it or its parents.
///
/// The returned read/write descriptor is close-on-exec and unlocked. Existing
/// bytes, permissions and inode are preserved. A missing entry returns the
/// native not-found error; a known special entry returns `NotRegular`.
/// The caller owns trusted parents, stable namespace and lock acquisition.
///
/// # Errors
/// Returns typed entry admission, native open/metadata or unsupported-host errors.
pub fn open_existing_regular_lock_file(path: &Path) -> Result<fs::File, RegularFileLockError> {
    #[cfg(unix)]
    {
        let metadata = fs::symlink_metadata(path).map_err(RegularFileLockError::Io)?;
        if !metadata.file_type().is_file() {
            return Err(RegularFileLockError::NotRegular);
        }
        open_regular_lock_descriptor(path, None)
    }
    #[cfg(not(unix))]
    {
        let _ = path;
        Err(RegularFileLockError::UnsupportedPlatform)
    }
}

#[cfg(unix)]
fn open_regular_lock_descriptor(
    path: &Path,
    create_permissions: Option<rustix::fs::Mode>,
) -> Result<fs::File, RegularFileLockError> {
    use rustix::fs::{FileType, Mode, OFlags, fstat, open};

    // Path checks reject known special entries; descriptor admission still owns
    // safety if the final entry changes between observations.
    let mut flags = OFlags::RDWR | OFlags::NOFOLLOW | OFlags::NONBLOCK | OFlags::CLOEXEC;
    if create_permissions.is_some() {
        flags |= OFlags::CREATE;
    }
    let fd = open(path, flags, create_permissions.unwrap_or(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);
    }
    Ok(fs::File::from(fd))
}

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

#[cfg(any(target_os = "linux", target_os = "android", target_vendor = "apple"))]
mod supported {
    use super::{NamedWriteError, PublicationMode, WriteOptions};
    use crate::identity::FileIdentity;

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

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

    use std::os::unix::fs::DirBuilderExt;

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

    pub(super) enum WriterCustody {
        Writable,
        ReadOnly,
    }

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

    #[cfg(test)]
    pub(super) fn commit_with_hook(
        path: &Path,
        bytes: &[u8],
        options: WriteOptions,
        before: impl FnMut(FileCommitStep, &Path) -> io::Result<()>,
    ) -> Result<(), NamedWriteError<io::Error>> {
        commit_path_with_options(
            path,
            options,
            |_, file| std::io::Write::write_all(file, bytes),
            (WriterCustody::Writable, |_, ()| Ok(())),
            before,
        )
    }

    pub(super) fn commit_path_with_options<T, E>(
        path: &Path,
        options: WriteOptions,
        produce: impl FnOnce(&Path, &mut fs::File) -> Result<T, E>,
        admission: (WriterCustody, impl FnOnce(&Path, &T) -> Result<(), E>),
        mut before: impl FnMut(FileCommitStep, &Path) -> io::Result<()>,
    ) -> Result<T, NamedWriteError<E>> {
        let options = (
            options.mode,
            native_permissions(options.permissions).map_err(NamedWriteError::before)?,
        );
        let (parent, file_name) = split_target(path).map_err(NamedWriteError::before)?;
        create_parent_hierarchy(parent, &mut before, false).map_err(NamedWriteError::before)?;
        let parent_fd = open_directory(parent).map_err(NamedWriteError::before)?;
        commit_at_with_hook(
            parent_fd.as_fd(),
            Some(parent),
            file_name,
            options,
            produce,
            admission,
            before,
        )
    }

    pub(super) fn commit_at_with_hook<T, E>(
        parent_fd: BorrowedFd<'_>,
        parent_path: Option<&Path>,
        file_name: &OsStr,
        (mode, permissions): (PublicationMode, Mode),
        produce: impl FnOnce(&Path, &mut fs::File) -> Result<T, E>,
        admission: (WriterCustody, impl FnOnce(&Path, &T) -> Result<(), E>),
        mut before: impl FnMut(FileCommitStep, &Path) -> io::Result<()>,
    ) -> Result<T, NamedWriteError<E>> {
        validate_file_name(file_name).map_err(NamedWriteError::before)?;
        let metadata = unix_fs::fstat(parent_fd)
            .map_err(|error| NamedWriteError::before(errno_to_io(error)))?;
        if unix_fs::FileType::from_raw_mode(metadata.st_mode) != unix_fs::FileType::Directory {
            return Err(NamedWriteError::before(io::Error::from(
                io::ErrorKind::NotADirectory,
            )));
        }
        // Descriptor-only calls use relative names solely for hook diagnostics.
        // All filesystem operations below use the held directory descriptor.
        let parent = parent_path.unwrap_or_else(|| Path::new(""));
        let path = parent.join(file_name);
        let (temp_name, temp_path, mut temp_file) =
            create_sibling_temp(&parent_fd, parent, file_name, permissions, &mut before)
                .map_err(NamedWriteError::before)?;

        // Keep unused callbacks and the produced value alive through cleanup,
        // just as when each failure returned directly from this function.
        let mut produce = Some(produce);
        let (writer_custody, admit) = admission;
        let mut admit = Some(admit);
        let mut value = None;
        let published = (|| {
            before(FileCommitStep::TemporaryFileWrite, &temp_path)
                .map_err(NamedWriteError::before)?;
            value = Some(
                produce.take().expect("producer runs once")(&temp_path, &mut temp_file).map_err(
                    |source| NamedWriteError::Producer {
                        source,
                        cleanup_error: None,
                    },
                )?,
            );
            before(FileCommitStep::TemporaryFileSync, &temp_path)
                .map_err(NamedWriteError::before)?;
            verify_staging(&parent_fd, parent_path, &temp_name, &temp_file)
                .map_err(NamedWriteError::before)?;
            temp_file.sync_all().map_err(NamedWriteError::before)?;
            let admit = admit.take().expect("admission runs once");
            if matches!(writer_custody, WriterCustody::ReadOnly) {
                let read_only = retain_read_only(&parent_fd, parent_path, &temp_name, &temp_file)
                    .map_err(NamedWriteError::before)?;
                drop(std::mem::replace(&mut temp_file, read_only));
            }
            admit(&temp_path, value.as_ref().expect("production succeeded")).map_err(|source| {
                NamedWriteError::Producer {
                    source,
                    cleanup_error: None,
                }
            })?;
            before(FileCommitStep::Publication, &path).map_err(NamedWriteError::before)?;
            // Keep the descriptor alive through rename so its identity cannot
            // be recycled after a producer unlinks or replaces the pathname.
            verify_staging(&parent_fd, parent_path, &temp_name, &temp_file)
                .map_err(NamedWriteError::before)?;
            match mode {
                PublicationMode::Replace => {
                    unix_fs::renameat(parent_fd, &temp_name, parent_fd, file_name)
                        .map_err(|error| NamedWriteError::before(errno_to_io(error)))
                }
                PublicationMode::CreateNew => {
                    publish_create_new(&parent_fd, &temp_name, file_name, &temp_file)
                }
            }?;
            Ok(())
        })();
        published.map_err(|mut error| {
            // Only ordinary prepublication failures remove the still-owned stage.
            // Publication/cleanup uncertainty must retain its original evidence.
            if let NamedWriteError::Producer { cleanup_error, .. }
            | NamedWriteError::BeforePublication { cleanup_error, .. } = &mut error
            {
                *cleanup_error = remove_owned_temp(&parent_fd, &temp_name, &temp_file).err();
            }
            error
        })?;
        let value = value.expect("publication requires successful production");

        before(FileCommitStep::FinalParentSync, parent)
            .map_err(|source| NamedWriteError::AfterPublication { source })?;
        unix_fs::fsync(parent_fd).map_err(|error| NamedWriteError::AfterPublication {
            source: errno_to_io(error),
        })?;
        Ok(value)
    }

    pub(super) fn native_permissions(permissions: u32) -> io::Result<Mode> {
        validate_permissions(permissions)?;
        // Darwin's mode_t is u16; retain checked narrowing after admission.
        #[cfg(target_vendor = "apple")]
        let permissions = u16::try_from(permissions).map_err(|_| {
            io::Error::new(io::ErrorKind::InvalidInput, "invalid file permission bits")
        })?;
        Ok(Mode::from_raw_mode(permissions))
    }

    fn retain_read_only(
        parent_fd: &impl AsFd,
        parent_path: Option<&Path>,
        name: &OsStr,
        original: &fs::File,
    ) -> io::Result<fs::File> {
        let read_only = fs::File::from(
            unix_fs::openat(
                parent_fd,
                name,
                OFlags::RDONLY | OFlags::NOFOLLOW | OFlags::NONBLOCK | OFlags::CLOEXEC,
                Mode::empty(),
            )
            .map_err(errno_to_io)?,
        );
        // Both descriptors remain open until identity is verified, preventing reuse.
        let held = unix_fs::fstat(original).map_err(errno_to_io)?;
        let reopened = unix_fs::fstat(&read_only).map_err(errno_to_io)?;
        if !same_identity(&held, &reopened) {
            return Err(staging_identity_error());
        }
        verify_staging(parent_fd, parent_path, name, &read_only)?;
        Ok(read_only)
    }

    fn same_identity(left: &unix_fs::Stat, right: &unix_fs::Stat) -> bool {
        FileIdentity::from_stat(left) == FileIdentity::from_stat(right)
            && unix_fs::FileType::from_raw_mode(left.st_mode)
                == unix_fs::FileType::from_raw_mode(right.st_mode)
    }

    fn staging_identity_error() -> io::Error {
        io::Error::new(
            io::ErrorKind::InvalidData,
            "staging or parent identity changed",
        )
    }

    pub(super) fn verify_staging(
        parent_fd: &impl AsFd,
        parent: Option<&Path>,
        name: &OsStr,
        file: &fs::File,
    ) -> io::Result<()> {
        if let Some(parent) = parent {
            let held_parent = unix_fs::fstat(parent_fd).map_err(errno_to_io)?;
            let named_parent = unix_fs::statat(unix_fs::CWD, parent, AtFlags::SYMLINK_NOFOLLOW)
                .map_err(errno_to_io)?;
            if !same_identity(&held_parent, &named_parent) {
                return Err(staging_identity_error());
            }
        }
        let held = unix_fs::fstat(file).map_err(errno_to_io)?;
        let named =
            unix_fs::statat(parent_fd, name, AtFlags::SYMLINK_NOFOLLOW).map_err(errno_to_io)?;
        if !same_identity(&held, &named)
            || unix_fs::FileType::from_raw_mode(held.st_mode) != unix_fs::FileType::RegularFile
            || held.st_nlink != 1
            || named.st_nlink != 1
        {
            return Err(staging_identity_error());
        }
        Ok(())
    }

    fn remove_owned_temp(parent_fd: &impl AsFd, name: &OsStr, file: &fs::File) -> io::Result<()> {
        let named = match unix_fs::statat(parent_fd, name, AtFlags::SYMLINK_NOFOLLOW) {
            Ok(named) => named,
            Err(rustix::io::Errno::NOENT) => return Ok(()),
            Err(error) => return Err(errno_to_io(error)),
        };
        let held = unix_fs::fstat(file).map_err(errno_to_io)?;
        if !same_identity(&held, &named) {
            return Err(staging_identity_error());
        }
        unix_fs::unlinkat(parent_fd, name, AtFlags::empty()).map_err(errno_to_io)
    }

    pub(super) fn publish_create_new<E>(
        parent_fd: &impl AsFd,
        temp_name: &OsStr,
        file_name: &OsStr,
        temp_file: &fs::File,
    ) -> Result<(), NamedWriteError<E>> {
        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, || {
            remove_owned_temp(parent_fd, temp_name, temp_file)
        })
    }

    pub(super) fn finish_create_new_publication<E>(
        parent_fd: &impl AsFd,
        temp_name: &OsStr,
        file_name: &OsStr,
        renamed: rustix::io::Result<()>,
        cleanup: impl FnOnce() -> io::Result<()>,
    ) -> Result<(), NamedWriteError<E>> {
        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())
                    .map_err(|error| NamedWriteError::before(errno_to_io(error)))?;
                // Publication already happened. Never classify an unlink failure
                // as safe to retry, or silently retain the extra staging link.
                cleanup().map_err(|source| NamedWriteError::AfterPublication { source })
            }
            Err(error) => Err(NamedWriteError::before(errno_to_io(error))),
        }
    }

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

    pub(super) fn validate_target_path(path: &Path) -> io::Result<()> {
        let bytes = path.as_os_str().as_encoded_bytes();
        if bytes.contains(&0) {
            return Err(io::Error::new(
                io::ErrorKind::InvalidInput,
                "durable write target contains NUL",
            ));
        }
        // Path components and absolute() discard trailing directory requirements.
        // Refuse them before splitting or normalizing a file publication target.
        if bytes.ends_with(b"/") || bytes.ends_with(b"/.") {
            return Err(io::Error::new(
                io::ErrorKind::InvalidInput,
                "durable write target requires a directory",
            ));
        }
        Ok(())
    }

    pub(super) fn split_target(path: &Path) -> io::Result<(&Path, &OsStr)> {
        validate_target_path(path)?;
        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))
    }

    pub(super) fn validate_permissions(permissions: u32) -> io::Result<()> {
        if permissions & !0o777 != 0 {
            return Err(io::Error::new(
                io::ErrorKind::InvalidInput,
                "invalid file permission bits",
            ));
        }
        Ok(())
    }

    pub(super) fn validate_file_name(name: &OsStr) -> io::Result<()> {
        if name.is_empty()
            || name == "."
            || name == ".."
            || name
                .as_encoded_bytes()
                .iter()
                .any(|byte| matches!(byte, b'/' | 0))
        {
            return Err(io::Error::new(
                io::ErrorKind::InvalidInput,
                "expected one filename component",
            ));
        }
        Ok(())
    }

    pub(super) fn prepare_private_parents(parent: &Path) -> io::Result<()> {
        crate::path::validate_physical_directory_allow_missing(parent)?;
        create_parent_hierarchy(parent, &mut |_, _| Ok(()), true)
    }

    fn create_parent_hierarchy(
        parent: &Path,
        before: &mut impl FnMut(FileCommitStep, &Path) -> io::Result<()>,
        private: bool,
    ) -> 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)?;
            let creation = if private {
                fs::DirBuilder::new().mode(0o700).create(&directory)
            } else {
                fs::create_dir(&directory)
            };
            match creation {
                Ok(()) => {}
                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),
            }
            // A competing creator may stop after mkdir. Both paths must finish
            // persisting this formerly missing directory and its parent link.
            sync_created_directory(&directory, before)?;
        }
        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)
    }

    #[cfg(test)]
    fn remove_temp(parent_fd: &impl AsFd, temp_name: &OsStr) -> io::Result<()> {
        unix_fs::unlinkat(parent_fd, temp_name, AtFlags::empty()).map_err(errno_to_io)
    }

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