ic-host-fs 0.20.0

//! Durable filesystem publication and regular 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 directory;
mod lock_wait;
pub use directory::{DirectoryCreationError, admit_directory, create_private_directory};
pub use lock_wait::{lock_exclusive, lock_exclusive_with_wait, lock_shared, 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};
mod stream;
pub use stream::{PublicationMode, WriteOptions, write_validated_with, write_with};
#[cfg(unix)]
pub use stream::{write_at_validated_with, write_at_with};

#[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),
    /// Durable lock-file creation failed, retaining publication and cleanup evidence.
    Publication(NamedWriteError<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"),
            Self::Publication(_) => formatter.write_str("durable lock-file creation 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::Publication(source) => Some(source),
            Self::NotRegular => None,
            #[cfg(windows)]
            Self::UnsupportedPlatform => None,
        }
    }
}

/// 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(windows)]
            other @ RegularFileLockError::UnsupportedPlatform => Self::other(other),
        }
    }
}

const REPLACE_OPTIONS: WriteOptions = WriteOptions {
    mode: PublicationMode::Replace,
    permissions: 0o666,
};
const CREATE_NEW_OPTIONS: WriteOptions = WriteOptions {
    mode: PublicationMode::CreateNew,
    permissions: 0o666,
};
const CREATE_PRIVATE_OPTIONS: WriteOptions = WriteOptions {
    mode: PublicationMode::CreateNew,
    permissions: 0o600,
};

/// 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
/// Retains write, cleanup and filesystem failures in [`NamedWriteError`], including
/// the distinct after-publication state when the complete output is already visible.
pub fn write_bytes(path: &Path, bytes: &[u8]) -> Result<(), NamedWriteError<io::Error>> {
    commit_bytes(path, bytes, REPLACE_OPTIONS)
}

/// Durably create one file and its missing parent hierarchy without replacing
/// an existing destination.
///
/// # Errors
/// Retains write, cleanup and filesystem failures in [`NamedWriteError`]. An existing
/// destination is a before-publication `AlreadyExists`; a final sync failure is
/// after-publication. Reconcile the latter before retrying.
pub fn create_new_bytes_with_parents(
    path: &Path,
    bytes: &[u8],
) -> Result<(), NamedWriteError<io::Error>> {
    commit_bytes(path, bytes, CREATE_NEW_OPTIONS)
}

/// Create owner-only bytes atomically, without replacing an existing destination.
///
/// # Errors
/// Retains write, cleanup and filesystem failures in [`NamedWriteError`], including
/// an existing destination or unsupported host before publication, and a final
/// sync failure after publication. Reconcile the latter before retrying.
pub fn create_private_bytes_with_parents(
    path: &Path,
    bytes: &[u8],
) -> Result<(), NamedWriteError<io::Error>> {
    commit_bytes(path, bytes, CREATE_PRIVATE_OPTIONS)
}

/// 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 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> {
    let file = open_regular_lock_file_with_parents(path)?;
    #[cfg(not(windows))]
    rustix::fs::flock(&file, rustix::fs::FlockOperation::LockExclusive)
        .map_err(errno_to_lock_error)?;
    Ok(file)
}

/// Open a durable regular no-follow lock file and attempt exclusive acquisition once.
///
/// Uses the same parent creation and file admission as
/// [`lock_regular_file_with_parents`], preserving existing file contents.
/// Contention returns [`RegularFileLockError::Io`] with [`io::ErrorKind::WouldBlock`]
/// immediately; there is no polling, retry or progress callback. The returned
/// close-on-exec descriptor holds the lock until unlocked or closed.
///
/// Callers own trusted parents, namespace stability and contention policy.
/// Nonblocking acquisition does not bound filesystem open, creation or sync latency.
///
/// # Errors
/// Returns typed admission, creation, sync or native lock errors, including contention.
pub fn try_lock_regular_file_with_parents(path: &Path) -> Result<fs::File, RegularFileLockError> {
    let file = open_regular_lock_file_with_parents(path)?;
    #[cfg(not(windows))]
    rustix::fs::flock(&file, rustix::fs::FlockOperation::NonBlockingLockExclusive)
        .map_err(errno_to_lock_error)?;
    Ok(file)
}

/// 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> {
    let metadata = match fs::symlink_metadata(path) {
        Ok(metadata) => metadata,
        Err(source) if source.kind() == io::ErrorKind::NotFound => {
            match create_new_bytes_with_parents(path, &[]) {
                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);
    }

    #[cfg(not(windows))]
    {
        open_regular_lock_descriptor(path, None)
    }

    #[cfg(windows)]
    {
        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(not(windows))]
    {
        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(windows)]
    {
        let _ = path;
        Err(RegularFileLockError::UnsupportedPlatform)
    }
}

#[cfg(not(windows))]
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(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],
    options: WriteOptions,
) -> Result<(), NamedWriteError<io::Error>> {
    write_with(path, options, |file| std::io::Write::write_all(file, bytes))
}

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

    use std::{
        ffi::{OsStr, OsString},
        fs, io,
        path::{Component, 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);

    #[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),
            None::<(bool, fn(&Path, &()) -> io::Result<()>)>,
            before,
        )
    }

    pub(super) fn commit_path_with_options<T, E>(
        path: &Path,
        options: WriteOptions,
        produce: impl FnOnce(&Path, &mut fs::File) -> Result<T, E>,
        admit: Option<(bool, impl FnOnce(&Path, &T) -> Result<(), E>)>,
        mut before: impl FnMut(FileCommitStep, &Path) -> io::Result<()>,
    ) -> Result<T, NamedWriteError<E>> {
        validate_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,
            admit,
            before,
        )
    }

    pub(super) fn commit_at_with_hook<T, E>(
        parent_fd: BorrowedFd<'_>,
        parent_path: Option<&Path>,
        file_name: &OsStr,
        options: WriteOptions,
        produce: impl FnOnce(&Path, &mut fs::File) -> Result<T, E>,
        mut admit: Option<(bool, impl FnOnce(&Path, &T) -> Result<(), E>)>,
        mut before: impl FnMut(FileCommitStep, &Path) -> io::Result<()>,
    ) -> Result<T, NamedWriteError<E>> {
        validate_permissions(options.permissions).map_err(NamedWriteError::before)?;
        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 permissions =
            native_permissions(options.permissions).map_err(NamedWriteError::before)?;
        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 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)?;
            if let Some((close_writer, admit)) = admit.take() {
                if close_writer {
                    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 options.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 {
        left.st_dev == right.st_dev
            && left.st_ino == right.st_ino
            && 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(())
    }

    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<()> {
        let mut component_path = PathBuf::new();
        for component in parent.components() {
            if component == Component::ParentDir {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidInput,
                    "private parent path may not contain '..'",
                ));
            }
            component_path.push(component.as_os_str());
            match fs::symlink_metadata(&component_path) {
                Ok(metadata) if metadata.is_dir() => {}
                Ok(_) => {
                    return Err(io::Error::new(
                        io::ErrorKind::NotADirectory,
                        format!(
                            "output parent is not a directory: {}",
                            component_path.display()
                        ),
                    ));
                }
                Err(error) if error.kind() == io::ErrorKind::NotFound => {}
                Err(error) => return Err(error),
            }
        }
        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())
    }
}