ic-host-process 0.7.0

//! Explicit child ownership and cleanup, without application lifecycle policy.
//!
//! Callers own executable admission, IO, readiness, cancellation and deadlines.
//! Group cleanup signals members of a newly created group; it cannot contain
//! processes that escape that group or prove completion of external effects.

#[cfg(target_os = "macos")]
mod macos;
#[cfg(test)]
mod tests;

use rustix::{
    io::Errno,
    process::{Pid, Signal, WaitId, WaitIdOptions, WaitIdStatus, kill_process_group, waitid},
};
use std::{
    fmt, io,
    os::unix::process::{CommandExt, ExitStatusExt},
    process::{Child, ChildStderr, ChildStdin, ChildStdout, Command, ExitStatus},
};

/// One exclusively owned child, normally spawned as a new process-group leader.
///
/// [`Self::spawn`] preserves the command's IO, environment and other settings,
/// replacing its process-group selection with a new group. It performs no
/// executable admission. The child must not change groups, and callers must
/// not independently reap it (including through a global SIGCHLD handler).
///
/// Ordinary waiting signals remaining group members before reaping the leader.
/// For a deliberate background handoff, [`Self::poll_exit`] observes without
/// releasing cleanup ownership, then [`Self::handoff`] reaps a successful leader
/// without signalling its group. The caller then owns the background lifetime.
/// Drop makes a best-effort kill/reap attempt, including during unwinding. Use
/// [`Self::terminate`] to observe cleanup failures. Cleanup is synchronous and
/// has no wall-clock bound; successful signalling is not proof that descendants
/// have exited or completed external effects. Only the direct child is reaped.
/// Group signalling can succeed for only some members when credentials differ.
pub struct OwnedChild {
    child: Child,
    group: bool,
    status: Option<ExitStatus>,
    owned: bool,
}

/// Failures observed during one explicit termination attempt.
///
/// Keep this separately from the caller's original cancellation/operation error.
/// If group signalling fails, direct-child kill and reaping are still attempted.
#[derive(Debug)]
pub struct CleanupError {
    /// Status retained if the direct child was reaped despite another failure.
    pub status: Option<ExitStatus>,
    /// Failure signalling the owned process group.
    pub group_error: Option<io::Error>,
    /// Failure killing the direct child (including fallback after group failure).
    pub kill_error: Option<io::Error>,
    /// Failure reaping the direct child.
    pub wait_error: Option<io::Error>,
}

impl fmt::Display for CleanupError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("child cleanup failed")?;
        for (operation, error) in [
            ("group signal", &self.group_error),
            ("child kill", &self.kill_error),
            ("child wait", &self.wait_error),
        ] {
            if let Some(error) = error {
                write!(f, "; {operation}: {error}")?;
            }
        }
        Ok(())
    }
}

impl std::error::Error for CleanupError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        self.group_error
            .as_ref()
            .or(self.kill_error.as_ref())
            .or(self.wait_error.as_ref())
            .map(|error| error as &dyn std::error::Error)
    }
}

impl OwnedChild {
    /// Spawn once in a new owned process group, preserving caller-configured IO.
    ///
    /// # Errors
    /// Returns the native spawn/setup failure. No retries are performed.
    pub fn spawn(command: &mut Command) -> io::Result<Self> {
        command.process_group(0);
        Self::spawn_inner(command, true)
    }

    pub(crate) fn spawn_direct(command: &mut Command) -> io::Result<Self> {
        Self::spawn_inner(command, false)
    }

    pub(crate) const fn is_owned(&self) -> bool {
        self.owned
    }

    fn spawn_inner(command: &mut Command, group: bool) -> io::Result<Self> {
        command.spawn().map(|child| Self {
            child,
            group,
            status: None,
            owned: true,
        })
    }

    /// Direct-child PID, for observation only; it can be reused after reaping.
    #[must_use]
    pub fn id(&self) -> u32 {
        self.child.id()
    }

    /// Take caller-configured piped stdin. Close it before waiting for EOF-driven children.
    pub const fn take_stdin(&mut self) -> Option<ChildStdin> {
        self.child.stdin.take()
    }

    /// Take caller-configured piped stdout; the caller owns draining and bounds.
    pub const fn take_stdout(&mut self) -> Option<ChildStdout> {
        self.child.stdout.take()
    }

    /// Take caller-configured piped stderr; the caller owns draining and bounds.
    pub const fn take_stderr(&mut self) -> Option<ChildStderr> {
        self.child.stderr.take()
    }

    /// Observe leader exit without signalling or reaping it.
    ///
    /// An exited leader stays reserved with `WNOWAIT`, so cancellation, failed IO
    /// admission and unwinding still clean its group. Repeated observations do
    /// not release ownership. After a completed wait/termination/handoff, returns
    /// the cached status. This status alone does not establish a handoff.
    ///
    /// Call [`Self::handoff`] only after admitting a successful background start.
    /// Otherwise use [`Self::wait`] or [`Self::terminate`] to clean and reap.
    /// # Errors
    /// Returns native inspection errors; external reaping invalidates ownership.
    pub fn poll_exit(&mut self) -> io::Result<Option<ExitStatus>> {
        if let Some(status) = self.status {
            return Ok(Some(status));
        }
        self.observe_exit(true)?
            .map(|status| {
                // Unix wait status encoding used by Linux and Darwin. waitid's
                // siginfo status is an exit code/signal, not an encoded wait status.
                let raw = if let Some(code) = status.exit_status() {
                    code << 8
                } else if let Some(signal) = status.terminating_signal() {
                    signal | if status.dumped() { 0x80 } else { 0 }
                } else {
                    return Err(io::Error::other("waitid returned a non-exit observation"));
                };
                Ok(ExitStatus::from_raw(raw))
            })
            .transpose()
    }

    /// Reap an already successful leader without signalling its remaining group.
    ///
    /// This is the explicit transfer point for a background lifetime. The caller
    /// must first admit its IO/result and arrange application-owned readiness,
    /// cancellation and stop/recovery. Zero exit does not prove those obligations.
    /// No PID/group handle is transferred: it could be reused after reaping.
    /// Subsequent wait/termination/Drop never signal the handed-off group.
    ///
    /// Use [`Self::poll_exit`] while draining IO and checking cancellation. A
    /// running or unsuccessful leader is refused without releasing ownership;
    /// use ordinary wait/termination for failed startup, keeping its original
    /// failure separate from any cleanup error. Drop still attempts cleanup.
    /// # Errors
    /// Returns `InvalidInput` for a running, unsuccessful or already-reaped
    /// leader, or native inspection/reap errors. Reap failures retain cleanup
    /// ownership unless it was lost externally.
    pub fn handoff(&mut self) -> io::Result<ExitStatus> {
        if !self.owned || !self.poll_exit()?.is_some_and(|status| status.success()) {
            return Err(io::Error::new(
                io::ErrorKind::InvalidInput,
                "handoff requires an owned, successfully exited leader",
            ));
        }
        self.reap()
    }

    /// Inspect exit without blocking on a running child; clean its group before reaping.
    ///
    /// Repeated successful calls return the cached status without signalling again.
    /// # Errors
    /// Returns native inspection, group-signal or reap errors. The leader remains
    /// reserved on a group-signal failure, so explicit cleanup can still be attempted.
    pub fn try_wait(&mut self) -> io::Result<Option<ExitStatus>> {
        if let Some(status) = self.status {
            return Ok(Some(status));
        }
        if !self.owned {
            return Err(Errno::CHILD.into());
        }
        if self.group {
            if self.observe_exit(true)?.is_none() {
                return Ok(None);
            }
            self.signal_group()?;
            self.reap().map(Some)
        } else {
            let result = retry_interrupted(|| self.child.try_wait());
            if let Ok(Some(status)) = result {
                self.status = Some(status);
                self.owned = false;
            }
            self.check_wait_ownership(&result);
            result
        }
    }

    /// Wait for natural leader exit, then clean its group and reap the leader.
    ///
    /// Close/drain caller-owned pipes as needed before waiting. No deadline or
    /// cancellation policy is installed; callers may use polling instead.
    /// # Errors
    /// Returns native inspection, group-signal or reap errors.
    pub fn wait(&mut self) -> io::Result<ExitStatus> {
        if let Some(status) = self.status {
            return Ok(status);
        }
        if self.group {
            self.observe_exit(false)?;
            self.signal_group()?;
        }
        self.reap()
    }

    /// Kill the owned group (or internal direct child), then reap the leader.
    ///
    /// Repeated calls after reaping return the cached status and never signal a
    /// reused PID. A prior group failure still matters even if reaping succeeded;
    /// later calls cannot recover group ownership and do not erase that evidence.
    /// # Errors
    /// Retains each failed cleanup step separately. Group failure triggers a
    /// direct-child kill fallback. Drop cannot report errors; call this explicitly
    /// when cleanup evidence matters.
    pub fn terminate(&mut self) -> Result<ExitStatus, CleanupError> {
        if let Some(status) = self.status {
            return Ok(status);
        }
        let group_error = if self.group {
            self.signal_group().err()
        } else {
            None
        };
        let kill_error = if self.owned && (!self.group || group_error.is_some()) {
            retry_interrupted(|| self.child.kill()).err()
        } else {
            None
        };
        let waited = self.reap();
        match waited {
            Ok(status) if group_error.is_none() && kill_error.is_none() => Ok(status),
            other => Err(CleanupError {
                status: self.status,
                group_error,
                kill_error,
                wait_error: other.err(),
            }),
        }
    }

    fn pid(&self) -> io::Result<Pid> {
        if !self.owned {
            return Err(Errno::CHILD.into());
        }
        Pid::from_raw(i32::try_from(self.id()).map_err(io::Error::other)?)
            .ok_or_else(|| io::Error::other("child PID is zero"))
    }

    fn observe_exit(&mut self, nonblocking: bool) -> io::Result<Option<WaitIdStatus>> {
        let pid = self.pid()?;
        // NOWAIT reserves the leader PID until cleanup or explicit handoff,
        // avoiding signals to an unrelated group after an early leader exit.
        let mut options = WaitIdOptions::EXITED | WaitIdOptions::NOWAIT;
        if nonblocking {
            options |= WaitIdOptions::NOHANG;
        }
        let result = retry_interrupted(|| waitid(WaitId::Pid(pid), options).map_err(Into::into));
        self.check_wait_ownership(&result);
        result
    }

    #[cfg_attr(
        not(target_os = "macos"),
        allow(
            clippy::needless_pass_by_ref_mut,
            reason = "Darwin inspects and may invalidate child ownership"
        )
    )]
    fn signal_group(&mut self) -> io::Result<()> {
        let pid = self.pid()?;
        match retry_interrupted(|| kill_process_group(pid, Signal::KILL).map_err(Into::into)) {
            Ok(()) => Ok(()),
            Err(error) if error.raw_os_error() == Some(Errno::SRCH.raw_os_error()) => Ok(()),
            #[cfg(target_os = "macos")]
            Err(error)
                if error.raw_os_error() == Some(Errno::PERM.raw_os_error())
                    && self.observe_exit(true)?.is_some()
                    && macos::sole_group_member(pid) =>
            {
                Ok(())
            }
            Err(error) => Err(error),
        }
    }

    fn reap(&mut self) -> io::Result<ExitStatus> {
        if !self.owned {
            return Err(Errno::CHILD.into());
        }
        let result = retry_interrupted(|| self.child.wait());
        if let Ok(status) = result {
            self.status = Some(status);
            self.owned = false;
        }
        self.check_wait_ownership(&result);
        result
    }

    fn check_wait_ownership<T>(&mut self, result: &io::Result<T>) {
        if result
            .as_ref()
            .is_err_and(|error| error.raw_os_error() == Some(Errno::CHILD.raw_os_error()))
        {
            // An external reaper violates exclusive ownership; never signal a
            // potentially reused PID after observing that ownership was lost.
            self.owned = false;
        }
    }
}

impl Drop for OwnedChild {
    fn drop(&mut self) {
        if self.owned {
            let _ = self.terminate();
        }
    }
}

fn retry_interrupted<T>(mut operation: impl FnMut() -> io::Result<T>) -> io::Result<T> {
    loop {
        match operation() {
            Err(error) if error.kind() == io::ErrorKind::Interrupted => {}
            result => return result,
        }
    }
}